User Guide | Aware IM

Aware IM

Version 8.8

User Guide

Aware IM 8.8 User Guide

CONTENTS

AWARE IM DOCUMENTATION STRUCTURE..................................................................................... 8

INTRODUCTION ................................................................................................................................ 9

AWARE IM CONCEPTS ................................................................................................................... 10

ASPECTS OF INFORMATION MANAGEMENT SYSTEM............................................................................... 11

BASIC CONCEPTS............................................................................................................................ 12

Business Objects as Carriers of Data .......................................................................................... 12

Business Rules as Carriers of Business Logic ............................................................................. 13

Processes as Links between User Interface and Business Logic ................................................... 14

Reference Attributes .................................................................................................................. 16

Business Space......................................................................................................................... 18

Business Object Groups............................................................................................................. 19

USER INTERFACE ............................................................................................................................ 21

Visual Perspective ..................................................................................................................... 22

Operations ................................................................................................................................ 23

DATA ENTRY AND EDITING ................................................................................................................ 24

Business Object Forms .............................................................................................................. 24

Form Sections................................................................................................................................................................... 26

Navigation Style ............................................................................................................................................................... 27

Form Operations .............................................................................................................................................................. 28

DATA STORAGE .............................................................................................................................. 28

DATA RETRIEVAL ............................................................................................................................ 31

Configuring Queries ................................................................................................................... 31

Queries that Require User Input.................................................................................................................................... 33

Running Queries in the Operation Mode...................................................................................... 34

Building Queries in the Operation Mode ...................................................................................... 35

Searching for Data using Forms.................................................................................................. 35

DATA PRESENTATION....................................................................................................................... 37

Standard Form of Query Results................................................................................................. 37

Custom Form of Query Results................................................................................................... 38

Business Object Presentation ........................................................................................................................................ 39

Hyperlinks.......................................................................................................................................................................... 41

Calendar Form of Query Results................................................................................................. 42

DATA PROCESSING.......................................................................................................................... 42

Rule Evaluation ......................................................................................................................... 43

Context............................................................................................................................................................................... 44

Action Execution............................................................................................................................................................... 46

Evaluation of Rule Collections ....................................................................................................................................... 49

Evaluation of Unordered Rule Collections ................................................................................................................... 50

Context of Rule Execution .............................................................................................................................................. 60

Evaluation of Rules Containing WAS CHANGED expressions ..................................................................................... 66

Initialization Rules ............................................................................................................................................................ 68

Summary of Rule Evaluation.......................................................................................................................................... 69

Rules and Transactions.............................................................................................................. 71

Long Operations............................................................................................................................................................... 72

Batch Operations ............................................................................................................................................................. 73

Process Failure Rules ..................................................................................................................................................... 74

Execution Log ........................................................................................................................... 76

Rule Debugger .......................................................................................................................... 79

Configuration of Rules................................................................................................................ 80

PRODUCTIVITY FEATURES ................................................................................................................ 80

Aware IM 8.8 User Guide

Access Control .......................................................................................................................... 80

Access Level..................................................................................................................................................................... 80

Predefined Access Levels .............................................................................................................................................. 82

Conditional Access .......................................................................................................................................................... 82

Login ........................................................................................................................................ 83

Handling Login and Logout Events ............................................................................................................................... 86

Working with Documents and Reports......................................................................................... 86

Document Management.................................................................................................................................................. 86

Document Generation ..................................................................................................................................................... 87

Reports .............................................................................................................................................................................. 90

User Defined Documents and Reports......................................................................................................................... 94

Communication with Other Systems ............................................................................................ 94

Intelligent Business Objects ........................................................................................................................................... 94

Requesting Services and Sending Notifications ......................................................................................................... 96

Integration with Stripe Payments................................................................................................. 96

Scheduling ................................................................................................................................ 96

E-mail Handling ......................................................................................................................... 96

Outgoing Email ................................................................................................................................................................. 97

Incoming Email ................................................................................................................................................................. 98

Export and Import ...................................................................................................................... 99

Export and Import in the Operation Mode.................................................................................................................. 101

Export and Import from Business Rules..................................................................................................................... 101

Exporting and Importing Relationships....................................................................................................................... 102

Setting Initial Values of the Application .......................................................................................103

Extending Aware IM ..................................................................................................................104

Performance Profiler .................................................................................................................105

CONFIGURATION PROCESS ..............................................................................................................105

Business Space Versions and Version Control ...........................................................................105

Productivity Features ................................................................................................................107

Testing Mode ...........................................................................................................................107

Working with Aware IM in Hosting Environment ..........................................................................108

Configuration Guidelines ...........................................................................................................109

Configuration steps ........................................................................................................................................................ 109

Configuration principles................................................................................................................................................. 112

CONFIGURING APPLICATIONS .....................................................................................................119

OVERVIEW OF THE CONFIGURATION TOOL..........................................................................................119

WORKING WITH BUSINESS SPACE VERSIONS ......................................................................................120

LIFECYCLE OF A BUSINESS SPACE VERSION .......................................................................................121

MAJOR AND MINOR VERSIONS..........................................................................................................122

Creating Minor Version..............................................................................................................122

Creating Major Version..............................................................................................................123

LOADING BUSINESS SPACE VERSION.................................................................................................123

UPDATING BUSINESS SPACE VERSION ...............................................................................................124

CHECKING VERSION INTEGRITY ........................................................................................................124

TESTING BUSINESS SPACE VERSION .................................................................................................125

Embedded Testing....................................................................................................................126

PUBLISHING BUSINESS SPACE VERSION ............................................................................................126

WORKING WITH A BUSINESS SPACE VERSION IN A MULTI-DEVELOPER MODE ...........................................128

DELETING BUSINESS SPACE VERSION ...............................................................................................128

VIEWING PROPERTIES AND HISTORY OF THE BUSINESS SPACE VERSION.................................................128

EXPORTING BUSINESS SPACE VERSION .............................................................................................130

IMPORTING BUSINESS SPACE VERSION..............................................................................................130

REFRESHING BUSINESS SPACE VERSION ...........................................................................................130

WORKING WITH CONFIGURATION ELEMENTS.......................................................................................131

Adding Elements ......................................................................................................................131

Editing/Viewing Elements ..........................................................................................................131

Aware IM 8.8 User Guide

Deleting Elements.....................................................................................................................132

Copying Elements.....................................................................................................................132

Pasting Elements......................................................................................................................132

FINDING WHERE ELEMENT IS USED ...................................................................................................133

ADDING/EDITING BUSINESS OBJECTS ................................................................................................134

Specifying General Properties ...................................................................................................134

Defining Forms .........................................................................................................................136

Adding/Editing Forms .................................................................................................................................................... 137

Form Properties.............................................................................................................................................................. 138

Adding/Editing Form Sections...................................................................................................................................... 146

Defining Form Section Layout...................................................................................................................................... 148

Adding Custom HTML forms ........................................................................................................................................ 161

Adding/Editing Panel Operations ................................................................................................................................ 161

Defining Presentations ..............................................................................................................165

Defining Intelligent Business Objects .........................................................................................166

ADDING/EDITING ATTRIBUTES ..........................................................................................................174

Common Properties ..................................................................................................................174

Setting Properties of Plain Text Attributes...................................................................................182

Setting Properties of Number Attributes......................................................................................184

Setting Properties of Date, Timestamp and Duration Attributes ....................................................187

Setting Properties of Reference Attributes ..................................................................................188

Configuring References ................................................................................................................................................ 189

Presentation Options for References.......................................................................................................................... 190

Diagram of Object Relationships ................................................................................................................................. 203

Setting Properties of Picture Attributes .......................................................................................207

Setting Properties of Document Attributes ..................................................................................210

Setting Properties of Shortcut Attributes .....................................................................................211

Setting Properties of Yes/No Attributes.......................................................................................212

ADDING/EDITING RULES ..................................................................................................................213

Working with Rule Collection .....................................................................................................213

Adding/Editing Individual Rules ................................................................................................................................... 215

Context Assistant......................................................................................................................219

ADDING/EDITING PROCESSES ..........................................................................................................221

Process Diagrams ....................................................................................................................224

ADDING/EDITING BUSINESS OBJECT GROUPS .....................................................................................226

ADDING/EDITING QUERIES ...............................................................................................................227

Displaying Query Results ..........................................................................................................230

Standard Grid ................................................................................................................................................................. 230

Custom Presentation ..................................................................................................................................................... 238

Calendar/Scheduler Presentation ............................................................................................................................... 244

Chart Presentation ......................................................................................................................................................... 249

Tree Presentation........................................................................................................................................................... 256

Gantt Presentation ......................................................................................................................................................... 257

Kanban Boards............................................................................................................................................................... 257

Displaying Query Results as a Timeline of Events................................................................................................... 258

Specifying Query Using Standard View ......................................................................................258

Specifying Query Using Textual View .........................................................................................260

ADDING/EDITING NOTIFICATIONS ......................................................................................................260

ADDING/EDITING DOCUMENT TEMPLATES ..........................................................................................261

ADDING/EDITING ACCESS LEVELS .....................................................................................................264

Working with Access Level Editor ..............................................................................................265

ADDING/EDITING VISUAL PERSPECTIVES ............................................................................................266

Working with Visual Perspective Editor.......................................................................................267

Defining Frame Properties.........................................................................................................270

Defining Tab Properties ................................................................................................................................................ 273

Defining Content Panel Properties.............................................................................................................................. 274

Defining Content Panel with HTML Content.............................................................................................................. 279

Defining Layout of Content Panels.............................................................................................................................. 282

Aware IM 8.8 User Guide

Setting Menu Properties ............................................................................................................297

Setting Menu Item Properties....................................................................................................................................... 301

MULTI-STEP PROCESSES.................................................................................................................308

FORM AND GRID STYLES .................................................................................................................309

CREATING APPLICATIONS IN DIFFERENT LANGUAGES ...........................................................................309

Adding/Editing Locales..............................................................................................................310

RIGHT-TO-LEFT SUPPORT ................................................................................................................312

ADDING/EDITING SERVICES .............................................................................................................312

SCHEDULING .................................................................................................................................314

ADDING/EDITING BUSINESS SPACES .................................................................................................316

SETTING OPTIONS FOR INCOMING E-MAIL HANDLING............................................................................317

HANDLING LOGIN EVENTS................................................................................................................319

HANDLING LOGOUT EVENTS.............................................................................................................320

SENDING OUTGOING E-MAIL ............................................................................................................321

HANDLING UNSENT E-MAIL ..............................................................................................................322

ADDING APPOINTMENT OBJECTS ......................................................................................................322

WORKING WITH DATA STORED IN EXISTING DATABASE TABLES OR LDAP ...............................................323

Defining Business Objects that Use Existing Database Tables.....................................................324

Defining Business Objects that Use Data from LDAP Server /Active Directory ..............................326

Using LDAP/Active Directory for Login .......................................................................................327

Bypassing Aware IM Login for Active Directory/LDAP Users ................................................................................. 328

LOGIN VIA SOCIAL MEDIA SITES AND OTHER APPLICATIONS.....................................................................329

IMPLEMENTING SINGLE SIGN-ON USING SAML PROTOCOL ....................................................................329

GENERATING DOCUMENTATION ........................................................................................................329

SHOW SYSTEM OBJECTS.................................................................................................................330

SEARCHING FOR ELEMENTS IN A BUSINESS SPACE VERSION .................................................................331

BACKING UP AND RESTORING OPERATIONAL DATA ..............................................................................332

MANAGING CONFIGURATION USERS ..................................................................................................333

WORKING ON THE SAME BUSINESS SPACE VERSION CONCURRENTLY (MULTI-DEVELOPER MODE)..............334

PROTECTING BUSINESS SPACE VERSION ...........................................................................................334

COMPARING BUSINESS SPACE VERSIONS ..........................................................................................335

LOGGING INTO THE OPERATION MODE ...............................................................................................335

RE-CONNECTING TO THE AWARE IM SERVER ......................................................................................335

UNDOING AND REDOING CHANGES....................................................................................................336

WORKING WITH REPORT/PRESENTATION DESIGNER ............................................................................336

Report/Presentation Bands........................................................................................................338

Adding Report/Presentation Elements ........................................................................................339

Editing Report/Presentation Elements ........................................................................................343

Selecting Elements ........................................................................................................................................................ 343

Scaling and Moving Elements...................................................................................................................................... 344

Deleting Elements .......................................................................................................................................................... 345

Copying and Pasting Elements.................................................................................................................................... 345

Changing Element Properties ...................................................................................................................................... 345

Using Toolbar to change Report/Presentation Elements ..............................................................357

Setting Report/Presentation Properties.......................................................................................358

Setting Band Properties ............................................................................................................359

Add/Delete Group Bands...........................................................................................................360

Adding/Deleting Custom Font ....................................................................................................360

Finding Design Element ............................................................................................................361

Aligning Elements .....................................................................................................................362

Positioning Elements in Band ....................................................................................................362

Changing Size of Elements .......................................................................................................362

Working with Charts ..................................................................................................................363

Previewing the Report ...............................................................................................................368

Miscellaneous Commands.........................................................................................................368

BUILDING RUNTIME EXECUTABLE ......................................................................................................370

Aware IM 8.8 User Guide

CONFIGURING APPLICATIONS FOR MOBILE DEVICES ............................................................................372

CREATING NATIVE MOBILE APPLICATIONS ..........................................................................................372

DETERMINING CURRENT LOCATION OF THE USER ................................................................................372

RULE LANGUAGE REFERENCE ....................................................................................................372

RULE............................................................................................................................................373

RULE CONDITION ...........................................................................................................................374

Comparison..............................................................................................................................375

String Expression .....................................................................................................................376

EXISTS Expression ..................................................................................................................376

IN Expression ...........................................................................................................................377

Range Expression ....................................................................................................................377

WAS CHANGED Expression .....................................................................................................378

IS UNDEFINED Expression.......................................................................................................379

IS NEW Expression ..................................................................................................................379

Negation ..................................................................................................................................379

CALCULATIONS ..............................................................................................................................380

Constants.................................................................................................................................380

Arithmetic Operations................................................................................................................380

Functions .................................................................................................................................381

Aggregate Calculation ...............................................................................................................381

ACTIONS .......................................................................................................................................382

Modify Attribute Action ..............................................................................................................383

INCREASE BY and REDUCE BY Actions ..................................................................................383

INSERT and REMOVE Actions..................................................................................................384

REPLACE Action ......................................................................................................................384

CREATE Action ........................................................................................................................384

DUPLICATE Action...................................................................................................................385

DELETE Action ........................................................................................................................386

CLEAN Action ..........................................................................................................................386

DELETE FILE Action ................................................................................................................387

COPY FILE Action ....................................................................................................................387

MAKE DIRECTORY Action .......................................................................................................387

SEND Action ............................................................................................................................387

REQUEST SERVICE Action......................................................................................................388

REPORT ERROR Action...........................................................................................................388

PROTECT Action .....................................................................................................................389

FIND Action..............................................................................................................................390

ENTER NEW Action .................................................................................................................392

EDIT Action ..............................................................................................................................393

VIEW Action .............................................................................................................................393

DISPLAY PERSPECTIVE Action ...............................................................................................393

DISPLAY LAYOUT Action .........................................................................................................394

DISPLAY DOCUMENT Action ...................................................................................................394

PRINT DOCUMENT Action .......................................................................................................395

EXPORT DOCUMENT Action....................................................................................................395

IMPORT DOCUMENT Action ....................................................................................................397

EXPORT action ........................................................................................................................397

IMPORT Action ........................................................................................................................398

SET Action ...............................................................................................................................399

UPDATE Action ........................................................................................................................400

IMPORT RELATIONSHIPS Action .............................................................................................401

DISPLAY MESSAGE Action ......................................................................................................401

DISPLAY QUESTION Action .....................................................................................................402

DISPLAY URL Action................................................................................................................402

PICK FROM Action ...................................................................................................................403

Aware IM 8.8 User Guide

DISPLAY Action .......................................................................................................................403

PRINT FORM Action.................................................................................................................404

EXECUTE PROGRAM Action....................................................................................................404

EXEC_SP Action ......................................................................................................................404

CONNECT TO EMAIL and DISCONNECT FROM EMAIL Actions................................................405

SAVE SCREEN Action..............................................................................................................405

RENAME DOCUMENT Action ...................................................................................................406

CLOSE TAB Action...................................................................................................................406

EXEC_STRING Action ..............................................................................................................406

EXEC_SQL Action ....................................................................................................................406

LOG2 Action.............................................................................................................................407

LOG2 CONTEXT Action............................................................................................................407

CLEAR CONTEXT Action .........................................................................................................407

COMMIT TRANSACTION Action ...............................................................................................407

MOBILE CAMERA SNAP INTO Action.......................................................................................407

MOBILE CAMERA GET INTO Action .........................................................................................408

MOBILE GET LOCATION INTO Action ......................................................................................408

MOBILE START LOCATION WATCH Action ..............................................................................408

MOBILE STOP LOCATION WATCH Action................................................................................409

MOBILE SUBSCRIBE Action.....................................................................................................409

MOBILE PUSH Action...............................................................................................................409

EXEC_SCRIPT Action ..............................................................................................................409

END_PROCESS Action ............................................................................................................410

SET PROGRESS Action ...........................................................................................................410

CLEAR OFFLINE DATA Action .................................................................................................410

ADD OFFLINE DATA Action......................................................................................................411

GO OFFLINE Action .................................................................................................................411

CREATE BUCKET action ..........................................................................................................411

Process Call Action...................................................................................................................411

FUNCTIONS ...................................................................................................................................412

Date and Time Functions ..........................................................................................................412

Text Functions ..........................................................................................................................423

Mathematical Functions ............................................................................................................428

Financial Functions ...................................................................................................................431

Miscellaneous Functions ...........................................................................................................432

GLOSSARY ....................................................................................................................................442

APPENDIX A. AWARE IM PROPERTY FILES ..................................................................................466

APPENDIX B. KNOWN BUGS AND LIMITATIONS...........................................................................469

APPENDIX C. NUMBER FORMAT IN JAVA PROGRAMMING LANGUAGE......................................472

APPENDIX D. LINKS TO AWARE IM OPERATIONS ........................................................................473

APPENDIX E. REGULAR EXPRESSIONS........................................................................................476

Summary of regular-expression constructs ............................................................................................................... 476

Aware IM 8.8 User Guide

Trademarks

Aware IM is a trademark of Awaresoft Pty Ltd.

Java is a trademark of Sun Microsystems.

Microsoft Windows, Microsoft Access, Microsoft SQL Server, Microsoft

Internet Explorer are trademarks of Microsoft Corporation.

MySQL is a trademark of MySQL AB.

Cloudscape is a trademark of IBM Corporation.

Netscape Navigator is a trademark of Netscape Communication Corp.

Aware IM Documentation Structure

Aware IM documentation consists of the following documents:

1. Aware IM Installation Guide

2. Aware IM Getting Started

3. Aware IM User Guide (this document)

4. Aware IM Rule Language Reference

5. Aware IM Programmer’s Reference

6. Aware IM How To

7. Aware IM for Mobile Devices

Aware IM Installation Guide contains instructions on the installation, deployment and

start-up of the Aware IM software.

Aware IM Getting Started contains a brief introduction into configuring and running

applications with Aware IM.

Aware IM User Guide is the main document in the set, which explains how to use Aware

IM software to configure powerful and flexible web applications.

Aware IM Rule Language Reference contains the description of the Aware IM Rule

Language used in business rules.

Aware IM Programmer’s Reference describes how to add programming extensions to

Aware IM.

Aware IM How To contains answers to some frequently asked questions and describes

how to perform certain common tasks in Aware IM.

Aware IM for Mobile Devices contains guidelines on how to develop Aware IM

Applications for mobile devices, such as iPhone, iPad, Android, Windows phone or

Blackberry.

Aware IM 8.8 User Guide

Introduction

Aware IM is a software tool that was created to help organizations address many of their

data processing needs. The main design goal for Aware IM was to substantially reduce

the technical complexity of managing information and give non-technical people much

greater control over the process. As a result the information management task becomes

easier, more intuitive, predictable, manageable, and ultimately less expensive.

With Aware IM one can automate the organization’s policies, procedures, guidelines,

checklists, document handling, form input validation, event registration, decision making,

e-mail notifications, data tracking, report generation, task scheduling, periodic

processing, information sharing, bulk data exchange, and many other tasks in a flexible

and cost-efficient manner. It can help to increase awareness, enforce standards,

improve quality control, lift compliance level, simplify communication, and save time and

efforts across the organization.

Aware IM is configurable information management software that can be adjusted by

users without special computer skills to manage their specific information. In a simple

intuitive way users can specify the information they want to manage and the rules on

how to process the information. Aware IM automatically performs all the technical work

required to manage information such as storage, retrieval, calculation, security, sharing,

presentation, communication, etc.

Aware IM works in two modes: the configuration mode and the operation mode. The

configuration mode allows the configurator, that is, a person configuring an information

management system, to specify the contents and behaviour of the system. Once the

definition work is finished the configurator makes the system operational. In the

operation mode Aware IM analyses the system configuration and manages the

information according to the instructions provided by the configurator. Regular users

access the system in the operation mode in the course of conducting their day-to-day

business activities.

The following picture illustrates the two modes of Aware IM:

Aware IM 8.8 User Guide

Configurator

Configurattion

Tool

Operation

Engine

Regular

User

Aware IM

Definition

Operation

Objects,

Processes,

Rules

Data,

Transactions

The configuration of an information system, as defined by the configurator, can be

exported out of Aware IM and saved in a file on a computer disk, just like any other

electronic document. Similarly, a configuration can be imported into Aware IM from a

file. This allows people to share configurations they create so that other people can

adapt existing configurations for their own needs or reuse some parts of such

configurations to incorporate into their own information systems.

Aware IM can be installed on a personal computer. If such a computer is a part of an

office computer network the people in the office can use the system from their

computers using a standard Internet browser. People outside of the office can also

access the system as long as the computer on which Aware IM is installed is connected

to the Internet. Alternatively Aware IM can be installed on a computer managed by an

Internet hosting service provider so that users can access the information system via the

Internet.

Aware IM Concepts

The following section describes how to use Aware IM to configure and operate

applications that manage business information. The section is divided into several parts.

The first part identifies the main generic aspects of essentially any information

management application, describes how these generic aspects can be implemented in

Aware IM and the specifics of the Aware IM approach to this implementation. The

Aware IM 8.8 User Guide

second part identifies other features that most applications are likely to require and

describes how they can be implemented in Aware IM. Finally the last part provides an

overview of the configuration process and lists the productivity features of the Aware IM

Configuration Tool that help configurators create flexible and powerful applications.

See also:

Aspects of Information Management System

Basic Concepts

User Interface

Data Entry and Editing

Data Storage

Data Retrieval

Data Presentation

Data Processing

Productivity Features

Configuration Process

Aspects of Information Management System

Aware IM is a software tool that allows creation of essentially any data management

system. Therefore by nature it is very generic. It is built on the assumption that most

data management applications have many common aspects such as:

- Data entry

- Data storage

- Data retrieval

- Data editing

- Data processing

- User Interface

Essentially any application would require some data to be entered and stored

somewhere (usually in a database), it would also require the data to be found, retrieved

and edited and it would offer some user interface to perform all these operations. Most

applications would also perform some processing of this data according to certain rules

(this is also often referred to as “business logic” of an application) – for example, car

insurance policies would need their premium to be calculated, banking applications

would need to calculate daily interest rates etc.

Apart from these main generic aspects most applications would also need to do the

following:

- Take care of security issues

- Manage documents

- Generate data reports

- Communicate with other software systems and hardware devices

Aware IM 8.8 User Guide

We will explain in detail how Aware IM deals with all these issues in the following

sections of the document.

See also:

Basic Concepts

User Interface

Data Entry and Editing

Data Storage

Data Retrieval

Data Presentation

Data Processing

Productivity Features

Basic Concepts

See:

Business Objects as Carriers of Data

Business Rules as Carriers of Business Logic

Processes as Links between User Interface and Business Logic

Business Space

Business Object Groups

Business Objects as Carriers of Data

In Aware IM the world of data management application consists of business objects.

Business objects encapsulate the data that needs to be entered, retrieved, edited and

processed.

In fact, there is no data in an Aware IM-configured system that exists outside of some

business object.

In a way this model very closely reflects the real world. Business objects exist in every

business - customers, accounts, orders, payments etc. The data that a business object

encapsulates is represented as attributes of a business object. For example, an order

may have the placement date, customer, line items, shipment address, shipment date,

shipment number, delivery instructions, order status, etc.

Attributes of a business object may be of different types – text, number, date, document

etc (see Adding/Editing Attributes for a complete list of attribute types).

One of the most important attribute types is a reference attribute type. Reference

attribute type (or simply reference) reflects the fact that business objects may be linked

Aware IM 8.8 User Guide

with other related objects. For example, an order may be linked to its order line items.

References are explained in detail in the Reference Attributes section.

Given that business objects encapsulate the data in a data management application, the

main aspects of the system related to data entry, storage, retrieval and processing boil

down to the following:

- Data entry is the process of entering of the attributes values of some business object

- Data storage is the storage of attribute values

- Data retrieval is finding instances of business object(s) that match a certain criteria

- Data editing is the process of changing values of of a business object’s attributes

- Data processing is using attribute values of business objects to create instances of

other business objects and/or modify the existing attribute values.

NOTE: In the Configuration Mode one can configure definitions of business objects

and their attributes. In the Operation Mode one can create actual objects filling their

attributes with specific data and linking them with other objects. While there is a single

definition describing a business object in the Configuration Mode, there may be many

instances in the Operation Mode representing the same business object. For example,

you can configure a Customer object and then create many instances of a Customer

objects in the Operation Mode, each representing a different customer. A formal way of

making the distinction between objects in the two modes is to refer to the configuration-

mode object as object definition and to the operation-mode objects as object instances.

This document uses the formal notation when it is necessary to avoid confusion between

the two modes. When it is clear which mode is being described, the term object is used.

Configuration of business objects is described in detail in the Adding/Editing Business

Objects section.

Business Rules as Carriers of Business Logic

In Aware IM data processing (or business logic) is encapsulated in business rules.

A rule specifies one or more actions that should be executed when the rule conditions

are met. Conditions are optional and if none are specified the actions are executed

unconditionally. In other words a rule states what should happen and when.

Here are some examples of rules:

1. If Account.Holder.Age < 16 Then

REPORT ERROR 'Account holder must be 16 years old or over'

2. LineItem.Total = LineItem.Price * LineItem.Quantity

3. If Reservation.Status WAS CHANGED TO 'Offered' Then SEND

ReservaitonOfferEmail TO Reservation.Member

Aware IM 8.8 User Guide

4. REQUEST SERVICE ProcessPayment OF PaymentProcessingSystem

5. If Fee.Status='Applied' Then PROTECT Fee.Amount FROM ALL

Actions of business rules can perform a variety of tasks. Most importantly they can

create and modify business objects, i.e. perform data processing. They can also perform

calculations, create or print documents, display information, exchange data with other

software, etc.

Evaluation of rules is triggered when certain events happen inside the system. Most

importantly rules are triggered when data is entered or edited or, in Aware IM terms,

when business objects are created or modified.

When a value of an attribute changes Aware IM considers all rules related to the object

and executes the actions of those rules for which the conditions are met. Note that

execution of actions may have a ripple effect because an action may change values of

other attributes which may in turn cause evaluation of other rules and so on. Aware IM

continues this process of rule evaluation until there are no more actions to execute. This

process is described in detail in the Rule Evaluation section.

There are also other events apart from the modification of a business object that may

trigger rule evaluation and action execution – a full list of these events is provided in the

Rule Evaluation section.

Configuration of business rules is explained in detail in Adding/Editing Rules, details of

rule conditions and actions syntax is provided in the Rule Language section and the

“Aware IM Rule Language Reference” document.

Processes as Links between User Interface and Business

Logic

As we said in the Business Rules as Carriers of Business Logic section business logic of

an application Aware IM is encapsulated in business rules, which get triggered

whenever business objects are created or modified. Let us now have a look at when

these creations and modifications take place.

The initial trigger that leads to the creation or modification of a business object is almost

always some external request to the system usually from a user who sends this request

via the system’s User Interface. The user can perform this request in two ways – she

can explicitly ask the system to create a new instance of a business object or edit an

existing instance. More often though a user asks the system to start a process, which

will then create or modify a business object(s).

Aware IM 8.8 User Guide

A process usually consists of actions that are executed in a pre-defined order. These

actions usually create business objects or find the existing business object and modify it.

As a result business rules are triggered. These rules may start a chain reaction of other

modifications, which take place until there are no more actions to execute. After data

processing has been completed the process usually communicates the results back to

the user.

Therefore a process represents a link between the User Interface and business rules – it

triggers business rules in response to the request from the User Interface by performing

initial creation or modification of a business object and then communicates the result

back to the User Interface. This is shown on the diagram below:

NOTE: Even though a process itself usually consists of rules it is not supposed to

implement any business logic other than triggering the initial change as described

above.

NOTE: A process may be started not just by the User Interface but also by other

forms of external requests – for example, a request from other software system through

a service (see Communication with Other Systems)

The illustration below shows the make up of a process transferring funds between two

accounts.

Note that the process is very small and is mainly concerned with allowing the user to

enter necessary details and presenting the results of the operation to the user. All the

business logic behind the funds transfer operation (such as checking whether there are

Aware IM 8.8 User Guide

sufficient funds in the source account, calculation of fees for the transfer operation etc) is

expressed in business rules related to the object FundsTransfer (they are not shown

here). Aware IM evaluates these rules as soon as the user enters the data for the

FundsTransfer object (between “Display funds transfer form” and “Check for transfer

success” operations).

Configuration of processes is discussed in detail in the Adding/Editing Processes

section.

Reference Attributes

Attributes that refer to other business objects are called reference attributes or simply

references. References represent relationships between business objects. For example,

the Account business object may contain a reference to a list of account transactions

(represented by the Transaction business object) or the Employee business object

may have a reference to the Company business object.

The relationships between objects represented by reference attributes may be of several

types:

- Relationships can be single or multiple

- Relationships can be matching or non-matching

- Relationships can be peer, parent or child.

Single and multiple relationships.

“Single” relationship indicates that a business object may only refer to a single instance

of another business object through this relationship (for example, the Employee object

may refer to only one instance of the Company object). “Multiple” relationship indicates

that a business object may refer to one or more instances of another business object

through this relationship (for example, the Account object may refer to multiple

instances of the Transaction object).

Matching and non-matching relationships

With matching relationships if an attribute of one business object refers to another

business object there is a reference attribute in this other object (matching attribute) that

refers to the first object. For example, if the Account object refers to the Transaction

object through an attribute with the name MyTransactions there may be a matching

attribute in the Transaction object called MyAccount that refers to the Account

object. This is shown on the picture below:

Aware IM 8.8 User Guide

Note that the MyTransactions attribute on the Account business object represents a

“multiple” relationship (account may have multiple transactions) whereas the matching

MyAccount attribute in the Transaction object represents a “single” relationship

(transactions belong only to one account). Generally speaking, any combinations of

single and multiple references are possible within the matching relationship.

Matching relationships are very convenient as far as navigation between objects is

concerned. In the example above once an instance of the Account object has been

added to a particular Transaction in the Operation Mode the added Account will

automatically have the Transaction in its list of transactions and vice versa – if an

instance of a Transaction has been added to the list of transactions on the Account,

the Account is also automatically attached to the Transaction. The corresponding

forms of both the Account and Transaction objects will automatically allow

navigation to the referred instances (unless presentation options are explicitly specified

not to allow this – see Presentation Options for References).

With non-matching relationships there are no matching attributes on the referred object.

Consequently if an instance of the second object is added to the first object in the

Operation Mode only the first object will know that it has references to the instance of

the second object – the instance of the second object will not know that some instance

of the first object refers to it. Thus navigation from the instance of the second object

directly to the instance of the first object will not be possible. Note that if the reference

attribute on the first object has no matching attribute in the second object it does not

mean that the second object may not refer to the first object at all through its own

reference (matching or non-matching). If such reference does exist it is a completely

different relationship. This is shown in the example below (FamilyMember object has a

non-matching single relationship to its Family and the Family object has independent

non-matching single relationship to the FamilyMember object – HeadOfFamily):

Peer, Parent and Child relationships

Peer relationships represent relationships when instances of both business objects

participating in the relationship can exist on their own. With parent (“owner”) and child

Aware IM 8.8 User Guide

(“owned”) relationship on the other hand, instances of the business object representing

the “child” part of the relationship cannot exist without the instance of its “parent”

business object. For example, the instance of a Transaction does not make sense if it

is not attached to some account, so we could say that the Account and Transaction

are related via a parent-child relationship where Account is parent and Transaction

is child.

The following applies for parent-child relationships:

1. If an instance of the parent business object is deleted instances of all “child” business

objects attached to the “parent” are automatically deleted as well

2. If an instance of a “child” object is removed from the instance of its “parent” object it

is automatically deleted.

The above behaviour saves the trouble of configuring rules to delete child instances

explicitly.

See also: Working with References in the Operation Mode.

Business Space

One can think of a business space as a place where Aware IM keeps both configuration

definitions of an application (such as business objects, processes, business rules etc)

and its operational data (data created by the end users of the application). Therefore,

business space encapsulates everything related to a data management system in a

business.

Business space is secure. Only the parties registered with the business space can get

access to the information in the business space, whether in the Configuration or the

Operation modes. Aware IM can manage multiple business spaces on the same

computer, but it keeps such business spaces completely separate from each other. It is

impossible to directly access operational data of one business space from another

business space

. When configuring multiple applications it is possible, however, to re-

use configuration information used in one business space and copy it into another

business space – see Copying Elements.

Since a business space is designed to cover all information management needs of an

organization, most users will only need to manage a single business space. However,

some users may need to maintain multiple business spaces, for example if they do it for,

or on behalf of, multiple unrelated organizations.

It is possible, however, to call services of one business space from another business space – see

Business Space as Intelligent Business Object.

Aware IM 8.8 User Guide

NOTE: Aware IM keeps configuration data completely separate from operational

data, which makes it very easy to provide a new version of the configuration data without

affecting the operational data.

Business Object Groups

Business object groups in Aware IM offer you a simple and convenient way to handle

similar yet different data.

Let us consider an application that registers client communication history, such as

meetings, phone calls, letters, e-mails, etc. A summary of the history should be

presented as a chronological list on the client form. The user should be able to see full

details of any list item on a separate form.

Some details are common across all communications, like the contact time, summary or

description. Other details are specific to a particular communication type, like the status

of an outgoing e-mail can be Sent or Unsent, and the user should be able to prepare

and send an e-mail, say by clicking a button. The status of an incoming e-mail can be

Read or Unread. Phone conversations do not have any status at all. Letters should have

a letter document attached to them, etc.

How would we represent communication details in our application? One way would be to

combine the details of all communication types in a single business object called, say,

Communications. The problem with the single business object is that depending on

the communication type we would have to hide non-applicable details and operations

from the data form or dynamically manipulate the values of the same attribute (like

Status for incoming and outgoing e-mails). Alternatively, we could make several forms

specific to each communication type. Then we would have to add some logic to all

places where a communication form is displayed, like from the history list on the client

form, to check the type and display an appropriate form. We would have to do the same

check in all other places where the user can navigate to the communication form, like in

a search result table.

Another way of going about it could be to create separate business objects for different

communication types, like Outgoing Emails, Incoming Emails, Outgoing

Letters, etc. Each of these objects would have its own data form. The trouble with

separate objects is that it would be very difficult (if not impossible) to show records from

separate objects in a single chronologically sorted list, say on a client form, or do a

search across multiple objects.

With the solution that Aware IM offers you would create separate business objects for

different communication types, like OutgoingEmail, IncomingEmail,

OutgoingLetter, then create a business object group, say, called Communication,

and include all the specific objects as its members. This is all it takes.

Aware IM 8.8 User Guide

Each member of a group usually contains attributes common to all other members. In

the example above the common attributes would be the date when the communication

was sent or received and the state of the communication. Each member would also

have some specific attributes not found in other group members, for example, telephone

number for telephone communication; e-mail address for e-mail communication etc.

Business object groups are treated in the same way as regular business objects - they

can be used in business rules, queries, document templates, and they also appear in the

list of available attribute types. So, we would simply add a multiple reference attribute

ContactHistory of type Communication to Client to display a list of

communication records on the client form. When the user clicks on an item in the list, a

form for the specific record will be automatically shown to the user.

Business object groups are useful in the following scenarios:

1. Business object groups can be used in queries to search the system for objects of

different types based on the criteria that use common attributes of the group – see

Data Retrieval.

2. Business object groups can be referred to by reference attributes as shown in the

above example – the ContactHistory attribute on the Client object refers to a

group rather than to a particular object.

3. Business object groups can be used in business rules – again in this case rules may

only use common attributes of the group. For example consider the following rules:

FIND Communication WHERE Communication.SentDate = CURRENT_DATE

Communication.State = 'SENT'

Here the second rule would set the value of the state attribute of any communication

object found by a query irrespective of its type.

TIP: If business rules attached to different members of a group are exactly the same

it is better to use group names in the rules rather than names of a particular group

member. In this case changes made to a rule attached to one member will be

automatically transferred to the equivalent rules attached to other members – see also

Adding/Editing Rules.

Configuration of business object groups is explained in the Adding/Editing Business

Object Groups section.

Aware IM 8.8 User Guide

User Interface

We can now explain in greater detail how the generic aspects of a data management

application are implemented in Aware IM. We will start with the User Interface.

Applications configured by Aware IM have HTML-based user interface that can be

viewed by any web browser such as Google Chrome, Internet Explorer or Firefox. After

a user logs into the system Aware IM displays the screen similar to the one shown

below (this shows screen layout for the CRM application):

In Aware IM the screen is divided into several areas:

- The optional area at the top is called the banner (not shown on the picture above)

- The leftmost area if defined may contains the menu of the system (as on the picture

above) or some other information

- The optional toolbar area at the top of the screen may have an additional menu (as

on the picture above)

- The main central area is called the main page and it contains a number of panels

showing data list and calendar (called content panels)

- The optional area at the bottom is called the status bar

The banner area at the top of the screen usually contains the logo of the system and

possibly some advertisements. The menu always contains the main operations that can

be performed by the user. The main page is the working area of the screen that displays

data forms, data search results etc. The status bar if present shows the name of the

currently logged in user and the name of the business space. You can also allocate

Aware IM 8.8 User Guide

special areas to the left, right and underneath the main page, that usually contain static

controls (like in the example above), news, advertisements etc.

Whether each of these areas (also called frames) will be shown as well as the contents

of each area can be specified in the application configuration. The following section

explains how this is done.

See also:

Visual Perspective

Operations

Visual Perspective

The Aware IM concept of the screen layout is called a visual perspective. The visual

perspective defines the look and feel of an application. Aware IM always generates the

default visual perspective, but in most cases configurators will change the default

perspective to provide their own layout.

Visual perspectives allow configurators to define the following:

- Names of menu items as well as operations that they invoke (see Operations)

- Frames that will be present

- Initial layout of the main page

- Layouts of each frame. You can display several pages (tabs) within a frame. A user

will be able to switch between pages. Each page can be further split up into several

content panels. Every content panel can show an HTML page or show the results of

a menu command (for example, run a query or a process).

- Color/font scheme (“theme”)

Configuration of a visual perspective is described in detail in the Adding/Editing Visual

Perspectives section.

It is possible to define several visual perspectives for an application and switch between

them when necessary. This may be useful if the application contains several relatively

independent functional areas that need to look different to the user and/or offer different

sets of menu operations. For example, there may be an area that provides management

of forums and another area that handles orders and purchases. Switching visual

perspectives is achieved by configuring a special type of a menu operation called

“Change Perspective” (see Setting Menu Item Properties) – when a user selects the

menu item of this type Aware IM shows the visual perspective configured for this menu

item.

Aware IM 8.8 User Guide

Operations

The screen layout would be rather worthless if it did not allow invoking operations. Most

operations are invoked from the main menu that is configured as part of a visual

perspective (see Visual Perspective).

The content of the main menu is entirely up to the configurator to define. The menu

consists of menu items that can be arranged in a hierarchical structure. Some menu

items (folder items) may only contain other items whereas other menu items (leaf items)

may actually perform a particular operation. Configurators define the name of the menu

item as well as the type of the operation that it invokes. There are a number of operation

types that Aware IM offers. Arguably the most important ones are those that initiate data

creation, editing, retrieval and processing. These are the following operation types:

Create Object

When a user selects a menu item of this type Aware IM shows the form that allows

entering attribute values of a new instance of the specified business object (see

Business Objects as Carriers of Data). When the user submits the form the new

instance of the object with the entered values is created (see Data Entry and Editing).

For example, the “New Account” menu item may be configured to create a new instance

of the Account business object.

Run Query

When a user selects a menu item of this type Aware IM runs the specified query and

shows the business objects found (see Data Retrieval and Data Presentation). For

example, the “Expired Policies” menu item may be configured to run a query that looks

for instances of a Policy business object with the value of State attribute equal to

“Expired”.

Start Process

When a user selects a menu item of this type Aware IM starts the specified process

(see Processes as Links between User Interface and Business Logic). For example, the

“Transfer Funds” menu item may be configured to start the “TransferFunds” process that

displays the appropriate form for the creation of FundsTransfer business object and

prints out the receipt after the object has been created (and the funds have been

transferred by the business rules attached to this object).

Other types of operations allow building a query dynamically, generating a report,

exporting and importing business objects etc. The complete list of operation types

supported by Aware IM via the main menu is available in the Setting Menu Item

Properties section.

NOTE: Operations of an application may be invoked not only from the main menu but

also from business object forms (see Form Caption and Form Operations), from the

standard query results screen (see Standard Form of Query Results) and from the

hyperlinks defined in business object presentations (see Hyperlinks).

Aware IM 8.8 User Guide

Data Entry and Editing

As described in the Business Objects as Carriers of Data section, data entry and editing

in Aware IM is achieved by creating and updating instances of business objects.

Instances of business objects can be created either explicitly by the user when she

selects a menu item of the “Create Object” type (see Operations) or by a process when

it executes the ENTER NEW action of the Rule Language

In both cases Aware IM displays a form that allows the user to enter values of the

attributes of the business object. When the user submits the form the new instance of

the business object is created (this triggers evaluation of business rules, if there are any,

attached to this business object – see Business Rules as Carriers of Business Logic). If

the form was displayed by the ENTER NEW action of a process, the process continues its

execution after the business rules attached to the object have been evaluated.

Editing of business object instances occurs either when a user presses the “Edit” button

on the query results screen (see Data Presentation) or when a process executes the

EDIT action of the Rule Language

. Again in both cases Aware IM displays a form that

allows a user to modify the values of the attributes of the business object. When the user

submits the form the existing instance of the business object is replaced with the

changed values (this triggers evaluation of business rules attached to this business

object – see Business Rules as Carriers of Business Logic). If the form was displayed by

the EDIT action from a process, the process continues its execution after the business

rules attached to the object have been evaluated.

See also:

Configuring Queries

Running Queries in the Operation Mode

Building Queries in the Operation Mode

Searching for Data using Forms

Configuring Queries

Queries can be defined at the configuration stage - a user can run such pre-configured

queries in the Operation Mode. Pre-configured queries can also be referenced by rules

(see FIND action).

When defining a query the configurator has to indicate the business object, (or business

object group) the instances of which the query will be searching. Then the configurator

has to indicate the conditions of search – only those instances of the business object

that have attribute values matching the specified conditions will be retrieved by the query

(if conditions are not specified all instances of the business object will be retrieved). For

example, if a query is to retrieve accounts of John Smith, the query has to include a

condition that compares the value of the OwnerName attribute with ‘John Smith’:

FIND Account WHERE Account.OwnerName = 'John Smith'

One can define multiple conditions for a query – the conditions may be linked with the

AND or OR keywords.

Note that query conditions allow specifying not only attributes of the business object that

the query will be searching, but also attributes of the related objects. For example, if

Aware IM 8.8 User Guide

account owner is a Customer object related to the Account object via the Owner

reference attribute, the above query could be specified as follows:

FIND Account WHERE Account.Owner.Name = 'John Smith'

It is also possible to indicate attributes of objects related to the related objects, for

example, Account.Owner.Company.Name. There is no limit on the level of nesting of

the related objects.

The configurator may indicate that instances of a business object found by a query

should be sorted by a particular attribute(s) in a particular order and also indicate how

these instances should be displayed in the Operation Mode – see Data Presentation.

Configuration of queries is described in more detail in the Adding/Editing Queries

section.

NOTE: If a query searches for instances of business objects belonging to a business

object group, the conditions of the query may only use attributes common to all

members of the group (see Business Object Groups). When the results of such a query

are presented to the user the presentation is only allowed to show common attributes of

the group (see Data Presentation).

Aware IM 8.8 User Guide

NOTE: It is possible to define a query with conditions that use attributes of a business

object that the query is not searching for (they are also called dynamically resolved

attributes or simply dynamic attributes). Consider the following query as an example:

FIND Account WHERE Account.OwnerName = Customer.Name

The business object Customer used in a query condition is not the object that the query

is searching for. Aware IM replaces references to such attributes with the actual values

at run time – just before the search is performed. For example, if the value of the Name

attribute of the Customer object is ‘John Smith’ the actual query performed by Aware IM

is:

FIND Account WHERE Account.OwnerName = 'John Smith'

Where does Aware IM find the instance of the Customer object and what happens if

there are no instances of this object or if there are more than one instance? The answer

to the first part of the question is that the instance is taken from the Context (this is

explained in the Other Usages of Context section); the answer to the second part is that

if Aware IM cannot find the instance of the object in the Context it logs a run-time error

and the query is not run. The queries using dynamic attributes should only be used in

situations where such attributes can be unambiguously resolved.

See also Queries that Require User Input

Queries that Require User Input

Quite often a value that a query should use in its conditions must be entered by a user at

run time rather than pre-configured. For example, consider a query that finds the

owner’s accounts after the owner’s name has been entered by the user. Aware IM

allows configuring such a query – the configurator will need to specify the business

object that the query should be looking for as well as the attributes and criteria

participating in the query condition(s). However, instead of specifying a particular value

of the attribute(s) in the condition(s) the configurator will need to indicate that the value

should be entered at run time. When the user runs such a query in the Operation Mode

Aware IM automatically generates a form where the user enters the required value(s) (in

the above example - the name of the owner that the query will be looking for). After the

required value has been entered Aware IM performs the search and displays the

results.

A query may require several values to be specified by the user (for example, a query

that finds accounts of owners with the names that start with the specified value and with

balances that are greater than the specified amount). In this case Aware IM generates a

form that prompts for the values of every attribute that requires input from the user.

Aware IM 8.8 User Guide

It is possible to mix conditions that check for pre-configured values with conditions that

require input from the user within a single query.

NOTE: If the user does not provide any value, the corresponding condition is not

considered at all when the search is performed. For example, if the user does not

provide a value of the owner’s name in a query that looks for accounts of the specified

owners, the query will find all existing accounts. If the user does not provide the value of

the account balance in a query that looks for the accounts of the specified owners with

balances greater than the specified amount, but provides the name of the owner the

query will find the accounts of the specified owner. If the user provides the balance

amount but not the owner’s name, the accounts with a balance greater than the

specified amount will be found. Finally, if the user does not provide values for both the

owner’s name and the balance all existing accounts will be found. This capability may be

quite useful in those types of searches where users only enter values for those criteria

that they are interested in.

Running Queries in the Operation Mode

Usually the user would run a query by selecting an item of the “Run Query” type from the

main menu, provided that such an item has been configured in the visual perspective –

see Operations. The user may not even realize that selecting a particular menu item will

run a pre-configured query. For example, the configurator can define a query that finds

accounts with balances larger than a certain amount and configure a menu item in a

visual perspective called “Large Balances”. When the user selects this menu item in the

Operation Mode the system will display the accounts with a large balance as expected

and the user would not even be aware of the invocation of a query mechanism behind

the scenes.

Note that as explained in Operations a query can also be implicitly invoked from the

hyperlink of the business object presentation (see Hyperlinks) or from a business object

form (see Form Caption and Form Operations). Again in both cases the user may not be

aware of the existence of queries in the system.

There is also another way of running queries in the Operation Mode – that is, selecting a

menu item of the “Search Objects” type (provided that one has been configured). An

operation of this type shows the screen where the user can select a specific query that

she wants to run from a list of all queries configured in the system. Note that since the

user selects a particular query from a list of all available queries she should be well

aware of the existence of queries in the system. Normally an operation of this type

should be used by system administrators only.

Aware IM 8.8 User Guide

Building Queries in the Operation Mode

In certain systems it may be necessary for the users to build and run their own queries

rather than run pre-configured queries. The functionality of building queries dynamically

in the Operation Mode is available from operations of the “Manage Queries” and “Run

User Defined Queries” types – see Operations.

The process of building a query in the Operation Mode is divided into several steps. For

each step Aware IM shows the appropriate screen. It is possible to move forward and

backwards between the steps. The parameters of a query that need to be specified

during these steps are very similar to those specified when a query is defined in the

Configuration Mode – see Adding/Editing Queries. After all steps have been

accomplished the built query is run and the found instances of the business objects are

displayed.

Note that the query built in this way does not become part of the system configuration –

however, it is accessible to end users of the system. Usually a system administrator

would build such queries before other users start working with the system.

Searching for Data using Forms

Another way of retrieving data in the Operation Mode is using forms to search for

business objects (see Business Object Forms). The idea is that the user is presented

with a blank form of a business object. She can enter values in any field of the form, and

when the form is submitted Aware IM will search for instances of this business object

using the entered data. To do this Aware IM automatically builds and runs a query.

When building a query Aware IM constructs a query condition for every value entered by

a user and connects them using the “AND” operator. Blank fields are ignored.

For example, let’s say we have a Customer business object with the following

attributes: FirstName, LastName, DOB, Address and TelephoneNo. If the user

enters “John” in the “FirstName” field of the form and “Smith” in the “LastName” field

Aware IM will find all customers with the first name “John” and the last name “Smith”.

It is also possible for a more advanced user to enter not only simple values into the

fields of a form but also expressions. The following table lists all possible keywords that

can be entered into a field:

Keyword

Aware IM search behaviour

Literal value (string,

number, date,

timestamp)

For Plain Text attributes Aware IM will search for objects

the attribute values of which contain the specified value;

for all other attribute types – that are equal to the specified

value

All objects with attribute values less than the specified

value, for example: “<5”

Aware IM 8.8 User Guide

All objects with attribute values greater than the specified

value, for example: “>5”

All objects with attribute values less or equal than the

specified value, for example: “<=5”

All objects with attribute values greater or equal than the

specified value, for example: “>=5”

All objects with attribute values not equal to the specified

value, for example: “<>5”

All objects with attribute values equal to the specified

value, for example: “=’John Smith’”

CONTAINS

All objects with attribute values that contain the specified

value, for example: “CONTAINS 25”

STARTSWITH

All objects with attribute values that starts with the

specified value, for example: “STARTSWITH ‘John’”

ENDSWITH

All objects with attribute values that ends with the

specified value, for example: “ENDSWITH ‘ith’”

BETWEEN, AND

All objects with attribute values that are in the specified

range, for example “BETWEEN 5 AND 10”

AND

Both conditions are included, for example “<5 AND >20”

Either of the conditions is included, for example “<5 OR

>20”

NOTE: If the user enters data into the field of a reference attribute Aware IM will

search through the related instances.

To configure an operation that will invoke a search using forms as explained above the

configurator has to tick the “Using form” checkbox on the query property editor – see

Adding/Editing Queries.

NOTE: When you use form-based queries it is also possible to specify query

conditions when defining a query. These conditions will be used as extra conditions and

will be automatically added to the query after the user enters data into the query form.

Advantages and disadvantages of using form-based search versus defining

queries that require user input.

If you want users to be able to enter their search criteria dynamically at run time, you

have two configuration options at your disposal – configure queries requiring user input

or using business object forms to search for data. Which one is better? There are

advantages and disadvantages of using either method:

- Using forms often requires less configuration effort, as you don’t need to configure a

query (in some cases, however, you may want to configure a special form)

Aware IM 8.8 User Guide

- Using forms may be more flexible as it offers a large number of attributes to the user

to search by. However, it may be confusing to some users as some of the attributes

may not be relevant to a particular search.

- Forms offers the power of expressions to advanced users, however, for users who

do not want or cannot use expressions it is better to offer a simple way of entering a

value only.

- Even though forms allow entering expressions, not all queries can be expressed with

forms.

Data Presentation

After data has been retrieved from the system it needs to be presented to the user so

that she can inspect and modify it if necessary. As explained in the Data Retrieval

section data is retrieved by a query. The following section describes how Aware IM

presents instances of business objects found by a query to the user. (Data may also be

presented by generating a document or report – see Working with Documents and

Reports)

Business object instances found by a query may be presented in a standard or custom

manner. Unless the configurator defines the query to use a presentation of the business

object to display its results, the results of the query execution are displayed in the

standard manner. This is explained in more detail in the following sections.

See:

Standard Form of Query Results

Custom Form of Query Results

Calendar Form of Query Results

Standard Form of Query Results

The standard form of query results is generated by Aware IM automatically. The

standard form displays query results as a table. Every instance of a business object

occupies a row in this table. Columns of the table display values of certain attributes of

the business object. This is illustrated on the picture below:

Aware IM 8.8 User Guide

The attributes shown in the columns are specified when a query is configured. If they are

not defined, Aware IM picks attributes to display at random.

The rightmost columns of every row in the table show the operations that can be

performed with an instance represented by the row (in the above example there is the

“Edit” and “Delete” operations). When defining a query it is possible to configure which

operations will be available – see Adding/Editing Queries.

The leftmost column of every row in the table may have a checkbox that allows selecting

multiple instances of a business object to perform operations with.

If the number of instances found by a query is large only a limited number of these

instances is displayed on one page (this number is 20 by default and can also be

specified when a query is configured). To navigate between pages a user can press one

of the navigation buttons located in the bottom left corner of the list and traverse to the

start or end of the list and to the previous or next page or go directly to a particular page.

Clicking on a particular column allows sorting the list by the value of the column.

Custom Form of Query Results

The custom form of query results shows instances of a business object found by a query

according to a custom HTML template or a presentation defined for this business object.

This may be useful if the configurator wants to provide a more customized layout of the

query results than the one offered by the standard form and/or include different visual

effects not supported by the standard layout, such as foreground or background images.

Aware IM 8.8 User Guide

On the picture above each instance of the Customer object is represented by an HTML

fragment that shows the Name, Title and Photo attributes of the customer.

See:

Business Object Presentation

Hyperlinks

Business Object Presentation

Presentation of a business object is defined as part of the business object configuration

(see Defining Presentations) and is designated to display the results of a particular

query in a non-standard fashion (see Custom Form of Query Results). The layout of a

presentation is created using the Report/Presentation Designer in the Configuration

Tool. The following picture shows an example of a presentation defined for a business

object Product.

Aware IM 8.8 User Guide

If such a presentation is designated to display results of a query that finds all available

products, running such a query in the Operation Mode will produce the following:

The presentation layout consists of different sections called bands. Each band has its

own purpose in the generation of the final output. Each band may contain design

elements. There are several types of design elements, such as static texts, tags,

images, rectangles, lines, conditional elements and sub-presentations. Probably the

most frequently used design element is the tag element, which may refer to attributes of

a business object and also contain arithmetic expressions with these attributes. Most of

these elements are explained in detail in Working with Documents and Reports.

The Report/Presentation Designer is a powerful tool that allows creating flexible and

comprehensive layouts for reports and presentations. Some of the functionality of the

Report/Presentation Designer may be familiar to those who used to work with report

Aware IM 8.8 User Guide

generators before (such as, for example, Crystal Reports). In a way a presentation is

similar to a report (see Working with Documents and Reports) in that it allows providing

a title and summary, break the data into groups, display headers and footers for each

group etc. Unlike reports presentations may include hyperlinks that invoke different

operations – start processes, run queries, view other presentations etc – see Hyperlinks.

Presentations can be displayed not only from the query results screen but also from

operations invoked on a business object form (see Form Caption and Form Operations),

from hyperlinks of some other presentation (see Hyperlinks) and from processes (using

the VIEW action). In all these cases there is an instance of a business object, which

owns the presentation that is being viewed. If the presentation is viewed from a business

object form this instance is the instance of the object that the form displays; if it is viewed

from a hyperlink this is the instance of the object that the hyperlink is associated with. If

a presentation is viewed from a process this is the instance of the object in the Context.

Also in all these cases only a single instance of a business object is displayed by a

presentation unlike the situation when a presentation shows query results where in most

cases multiple instances are displayed. When designing the layout of a presentation it is

important to remember whether the presentation will be used to display a single or

multiple instances of a business object. Some presentations should only be used to

display query results (i.e. showing multiple instances) while others should only be used

from forms, hyperlinks or processes (i.e. showing single instances).

Hyperlinks

Hyperlinks invoke operations from a presentation. They are defined using the

Report/Presentation Designer as part of the presentation layout (see Setting Hyperlink

Properties).

Hyperlinks can be optionally attached to text, tag and image design elements. When

defining a hyperlink the configurator has to specify the type of operation that the

hyperlink invokes if clicked on by the user in the Operation Mode. These operations can

start a process, run a query, display a form or presentation of a business object or

navigate to a particular URL. The full list of operation types is described in the Setting

Hyperlink Properties section.

In the Operation Mode a hyperlink is most often associated with a particular instance of

a business object. If a presentation where the hyperlink is defined shows one instance of

a business object (see Business Object Presentation) this is the instance that the

hyperlink is associated with. If the presentation shows multiple instances and the

hyperlink is defined in the Details band of the presentation there will be as many

hyperlinks as there are instances of the business object – each hyperlink will be

associated with its own instance.

When an operation that a hyperlink invokes starts, the instance of a business object that

the hyperlink is associated with becomes available as context for this operation. If the

operation starts a process this instance may be used by rules of the process (process

Aware IM 8.8 User Guide

input); if the operation runs a query this instance may be used by the query for attributes

resolved dynamically (see Configuring Queries); if the operation displays the form for

editing this instance is the one that gets edited.

Calendar Form of Query Results

Calendar form of query results can be used to show business objects of the

Appointment type in a calendar style layout (see picture below).

Users can switch between different calendar views (daily, weekly, monthly etc), create

and modify appointments, set priority of appointments. See also Adding Appointment

Objects.

Data Processing

As explained in the Business Rules as Carriers of Business Logic section in Aware IM

data processing logic (or business logic) is configurable and centralized. It is expressed

in the form of business rules rather than in a more traditional programming or scripting

language. Implementation of this business logic is based on the fact that business rules

get evaluated and their actions are executed as soon as the rule conditions are met.

Aware IM 8.8 User Guide

This section explains in detail how this happens – how rule conditions are evaluated and

what happens when rule actions are triggered.

See also:

Rule Evaluation

Rules and Transactions

Execution Log

Rule Debugger

Configuration of Rules

Rule Evaluation

In Aware IM rules are evaluated if either of the following happens:

- An instance of a business object is created (provided that there are rules attached to

this business object)

- Value of an attribute of a business object instance is modified (provided that there

are rules attached to this business object)

- A process implemented by rules is started

- Aware IM receives a notification (provided that there are rules associated with this

event)

- A notification is created (provided that there are rules associated with this event)

- Scheduling rules are triggered by a timer event – see Scheduling

So what exactly do we mean by saying that “rules are evaluated”? Essentially this

means that Aware IM starts checking whether rule conditions are met and if so begins

execution of the corresponding actions. Before we explain how this happens for a

number of rules, let us have a look first at the evaluation of a single rule.

See also:

Context

Action Execution

Evaluation of Rule Collections

Evaluation of Unordered Rule Collections

Context of Rule Execution

Evaluation of Rules Containing WAS CHANGED Expressions

Initialization Rules

Summary of Rule Execution

Aware IM 8.8 User Guide

Context

When evaluating a rule Aware IM checks if rule conditions are met and if so executes

the action specified by the rule

Let us consider the following rule as an example (taken from an application that

manages car insurance policies – the rule itself may or may not be very realistic, but it

does not matter for the purposes of this example):

IF Driver.Age > 70 Then INCREASE Policy.Excess BY 100

According to this rule the system is supposed to evaluate whether the age of the driver

is greater than 70 and if so, increase the excess of the policy by 100 dollars. The

question is – which driver and which policy? The system may have details about

thousands of drivers and thousands of policies in its database – so, which ones are we

talking about? If you ask a businessperson this question, she will probably answer

something along the lines of “Of course, I know what I am talking about – the driver here

is the person who has asked for a quote and the policy is the policy we are calculating

for her”. Judging from this imaginary but quite possible answer, one can draw a

conclusion that a businessperson always has a certain context in mind when she talks

about business rules. In the example above this context is the fact that someone asked

for a quote already - the business rule is therefore evaluated within this context and so

“the driver” and “the policy” have a very specific meaning.

The concept of Context therefore is the key to rule evaluation and action execution –

when deciding which instances of the business objects to consider when checking rule

conditions and executing actions, Aware IM looks for such instances in the Context (with

one exception that we will consider later). The Context can be regarded as a special

place within Aware IM where it keeps “relevant” instances of the business objects and

notifications. Still the question is how this Context is formed – how does Aware IM know

which instances are relevant and which ones are not?

There are certain formal events within Aware IM that affect the contents of the Context.

The full list of such events is described in the Data Processing section. Here we only

mention two of them:

- If an instance of a business object is created by the ENTER NEW or CREATE actions,

it is placed in the Context.

- If rules attached to a business object are being evaluated the instance of the

business object, for which rules are being evaluated, is placed in the Context.

Strictly speaking this is not necessarily true. For un-ordered rule collections an action is not executed

immediately but is placed on the agenda first. An action on the agenda may or may not be executed – see

Evaluation of Unordered Rule Collections. In this section, however, we will assume for simplicity that

actions are always executed

Aware IM 8.8 User Guide

Now let us go back to our rule – to get a full picture of what is going on when it is being

evaluated we must consider what was happening before and restore the context of rule

evaluation. We assume here that the software calculates the details of the requested

policy after someone has asked for a quote. It is therefore quite reasonable to assume

that there is some process that displays the form with the driver’s details to be filled out

by a user and after the form has been filled out calculates the details of the policy. The

rules of the process might look something like this:

ENTER NEW Driver

CREATE Policy

We assume here that the Driver and the Policy business objects are defined and

that the Policy business object has our rule attached to it as well as other rules that

calculate all the details of the policy. The first action displays the form of the Driver

business object on the user’s screen. As soon as the user enters all the details the

instance of the Driver object is created and is placed in the Context (if there are any

rules attached to the Driver object they are evaluated as well). Then the instance of

the Policy object is created and placed in the Context and the rules attached to the

Policy business object (including our rule) are evaluated. Therefore when our rule is

being evaluated the appropriate instances of the Driver and Policy business objects

will have been already made available in the Context and the system uses the values of

the attributes of these objects to check the rule conditions and execute actions. By the

time the system finishes the creation of the Policy object all the details of the policy will

have been calculated!

More detailed information about the Context is given in the Context of Rule Execution

section.

Aggregate Operations

In the Context section we have mentioned that there is one exception to the fact that

Aware IM looks for instances of the business objects to work with in the Context. This

exception applies to aggregate operations. Aggregate operations are those rule

expressions that start with keywords EXISTS, COUNT, SUM, MIN, MAX, AVG (see

EXISTS Expression and Aggregate Calculations). When such an expression is

encountered Aware IM always looks at all data available in the database and considers

all instances in the database that match the conditions of the aggregate operation, not

only instances in the Context. For example,

IF EXISTS Policy WHERE Policy.Excess > 1000 Then DoSomething

Here Aware IM looks at all existing policies in the database to find out if there is any

policy with excess greater than one thousand dollars.

Aware IM 8.8 User Guide

Let us now have a look at what happens when the conditions of a rule have been met

and the corresponding action(s) are triggered. See Action Execution.

Action Execution

Before an action triggered by a rule is executed the system’s data is assumed to be in a

stable state. The “data” here means the entire collection of data available– all instances

of all business objects stored in the database or in some other storage media known to

Aware IM. A stable state means that all the data is consistent and nothing is happening

– the state of the system is “fixed” at this moment in time

An action may disturb the stable state of the system by doing one of the following:

- Creating a new instance of some business object

- Modifying the existing instance of some business object

After the disturbance occurs Aware IM starts checking if there are rules defined

anywhere in the system that react to the creation or modification of the business object

instance. If that is the case Aware IM starts evaluation of such rules. These rules in turn

may create or modify other instances of business objects and cause other disturbances

and so on – thus starting a chain reaction that stops only when there are no rules to

evaluate any more, in which case the system moves to a stable state again (but this

state is different from the previous state as the the data is probably different).

We said above that if there are rules anywhere in the system that react to the creation or

modification of the business object instance, they are evaluated. What does “anywhere

in the system” mean here? It means the following:

1. Rules attached to a business object the instance of which has been created or

modified.

2. Rules attached to other business objects that refer to the business object instance

that has been created or modified.

The first set of rules has already been mentioned before – whenever a new instance of a

business object is being created or the existing instance is being modified, and there are

rules attached to this business object, they are evaluated. In the example of the previous

section rules attached to the Driver business object are evaluated after the form has

been filled out (this is when the instance of the Driver object is created in the system).

Rules attached to the Policy business object are evaluated immediately after the

This may not be true if the action was triggered in the middle of the evaluation of an un-ordered

collection of rules – see Evaluation of Unordered Rule Collections. In this section, however, we will

assume for simplicity that the state of the system is always stable prior to the execution of an action.

This does not apply to the instance of a business object the rules of which are already being evaluated

as part of an un-ordered collection of rules - see Evaluation of Unordered Rule Collections. We will ignore

this case for purposes of the current discussion.

Aware IM 8.8 User Guide

CREATE action creates a new instance of the Policy object. Let us suppose now that

we modify our process to add an action that sets the state of the policy after it has been

created, so the process now looks like this:

ENTER NEW Driver

CREATE Policy

Policy.State='Calculated'

The action in the third rule unconditionally modifies the attribute of the Policy object –

this causes the rules attached to the Policy object to be evaluated again.

The second set of rules (those rules that refer to the instance of the business object that

has been created or modified) is called cross-reference rules. An explanation of what

these are, are given in the Cross-reference Rules section.

Cross-reference Rules

Cross-reference rules are rules that refer to a particular instance of a business object

through the reference attribute of another object. For example, let us assume that our

Policy business object has a reference attribute declared – this reference is to the

Driver for which the policy is made. Let us assume that the name of this attribute is

MyDriver. Our age rule should now be written like this:

IF Policy.MyDriver.Age > 70 Then INCREASE Policy.Excess BY 100

We should also make modifications to the process that enters the details of the driver

and calculates the policy to initialize the MyDriver attribute of the Policy object

appropriately:

ENTER NEW Driver

CREATE Policy WITH Policy.MyDriver=Driver

The age rule written in the above form refers to the instance of the Driver object

through the reference of the Policy object (Policy.MyDriver.Age). This rule

therefore is a cross-reference rule.

Cross-reference rules are evaluated whenever the instance of the object they refer to is

changed. Consider what happens if a policy for some driver has been calculated but

then the user realizes that she had made a mistake and entered the wrong age of the

driver. She brings up a form for the driver and changes the value of the Age attribute.

Let us see what happens when the changes are submitted. The particular instance of a

Driver object is modified and therefore if there are any rules attached to the Driver

object they are evaluated. Let us assume for simplicity that there are no such rules.

There is however a rule that refers to the Driver object – this is our age rule. Aware IM

automatically finds the instance of the Policy object that refers to the instance of the

Aware IM 8.8 User Guide

modified Driver object and starts evaluating the cross-reference rule. Thus the system

guarantees that the excess is correctly calculated no matter where the change that

affects its calculation happens! If the age value entered first was 70 and the correct age

is 71 then the excess will be re-calculated as soon as the correct age of 71 is submitted.

Note that Aware IM will re-calculate cross-reference rules only for those instances of

business objects that refer to the modified instances – in our example, only the Policy

instance that refers to the modified Driver object will be re-calculated; all other policies

will not be considered.

There is a flag in the Configuration Tool that allows you to explicitly turn off the cross-

reference rule mechanism for a particular rule (see Advanced Rule Options). When this

flag is turned off for a rule the rule is never recognized as a cross-reference rule, so if

any attributes referred to by this rule are modified the rule is not evaluated. Turning off

this flag may be useful if evaluation of a cross-reference rule as a result of an attribute

change leads to modification of a large number of business object instances. For

example, let us say that our Policy object refers to a StampDuty object in a rule that

calculates commission of the policy:

Policy.Commission = Policy.Value/20 + Policy.StampDuty.Rate/100

If rate of the StampDuty object changes this change will cause re-calculation of all

policies in the system through the above rule, which is normally interpreted as a cross-

reference rule. If there are a large number of policies in the system their re-calculation

may take up significant time. You may want to warn the user about the effect of such

change or even defer the execution of the change until nighttime. In this case you would

like to configure a process that would control the changes to critical attributes of the

system and turn off automatic recognition of cross-reference rules.

Other Points Related to Action Execution

There are also a couple of other interesting points worth mentioning when describing

execution of actions.

a) When a reference attribute of some object is modified and this reference attribute

has matching attribute on the referred object, the referred object is modified as well

and its rules (if any) are evaluated (see Reference Attributes for the explanation of

what matching attribute is).

For example, let us assume that the Policy object has a reference to the Driver

object like in the previous example. Let us also assume that this attribute has a matching

reference on the Driver object called MyPolicies, which refers to all the policies of a

driver. The relationships between objects are illustrated in the following diagram:

Aware IM 8.8 User Guide

Let us also assume that there is a rule somewhere that sets the reference of some

instance of the Policy object to some instance of the Driver object:

Policy.MyDriver=Driver

This action modifies the instance of the Policy object and so any rules attached to the

Policy are evaluated. This is not the only thing that happens, however. Because the

MyDriver attribute of the Policy object has a matching attribute in the Driver object

(MyPolicies), the instance of the Driver object that is set into the Policy is

modified as well – the instance of the Policy object appears in its list of policies.

Consequently if there are any rules attached to the Driver object they are evaluated as

well.

b) The rules that check whether the existing member has been changed in a list are

considered to be cross-reference rules.

Let us assume hypothetically that the Driver object has the attribute TotalExcess

that is supposed to store the cumulative excess across all policies of a particular driver.

Consider the following rule attached to the Driver object, which re-calculates the value

of total premium whenever one of its policies changes in any way:

IF Policy FROM Driver.MyPolicies WAS CHANGED Then

Driver.TotalPremium = SUM Policy.Excess WHERE Policy IN

Driver.MyPolicies

Even though there is no attribute of some business object that is referred to through a

reference of another business object in this rule, the rule is still considered to be a cross-

reference rule. So if a user modifies attributes of some Policy object the rules of the

related instance of the Driver object are automatically evaluated as well and the total

premium is re-calculated.

Evaluation of Rule Collections

We had a look at how Aware IM identifies instances of the business objects to work with

and also what happens when actions are executed. Let us now look in more detail at

how rules are evaluated. In the Rule Evaluation section we have provided the list of

events that trigger rule evaluation. When any of these events occur there is a number of

rules that are considered for evaluation – if a process has been started these are the

Aware IM 8.8 User Guide

rules that implement the process, if an instance of a business object is created or

modified, these are the rules attached to the business object and so on. We will call

these sets of rules rule collections.

Rule collections can be ordered or un-ordered. Ordered rule collections are evaluated

one-by-one in exactly the same order that they appear in the rule collection. The only

example of an ordered rule collection is a process implemented by rules, which has the

“Maintain rule order” flag turned on – see Adding/Editing Processes. When such a

process is started its first rule is evaluated and the actions are executed if rule conditions

are met. If actions create any instances of the business objects they are placed in the

Context as described in the Context section. If actions create or modify instances of

business objects the rules attached to these business objects (if there are any) are

evaluated, cross-reference rules (if there are any) get evaluated as well – as described

in Action Execution. When action(s) of the first rule finish their execution, the second rule

of the ordered rule collection of the process is examined – its conditions are evaluated

and if they are met the corresponding actions are executed. This cycle is repeated until

the last rule in the collection has been evaluated.

Evaluation of un-ordered rule collection is very different. So different in fact that an entire

section in this document is dedicated to the evaluation of un-ordered rule collections.

See Evaluation of Unordered Rule Collections.

Evaluation of Unordered Rule Collections

Evaluation of an un-ordered rule collection in Aware IM is implemented by a rule engine,

so the terminology used in this section will probably be familiar to those who used to

work with rule-based systems before and knows the theory behind the algorithms

employed by rule engines.

See also:

Overview of Rule Engine Framework

Example of Rule Engine Execution

“While” Semantics

Did it Change?

Rule Priorities

Overview of the Rule Engine Framework

Most rule collections in Aware IM are un-ordered, such as rule collections attached to

business objects and notifications as well as processes that have the “Maintain rule

order” flag turned off. From the name of the rule collection it is clear that the order of

rules in the collection does not matter. So how does the rule engine in Aware IM decide

which rules to evaluate first, second and so on?

Aware IM 8.8 User Guide

The answer is that when the rule engine starts evaluating an un-ordered rule collection it

evaluates all rules of the collection at once. Actions for those rules for which conditions

have been met are stored in a separate container called the agenda. The fact that there

are actions on the agenda does not mean that all these actions are immediately

executed – the actions are waiting until they are taken off the agenda and are executed.

Actions are stored on the agenda in blocks. Action block corresponds to exactly one rule

that triggers the actions of the block in the first place. Usually an action block contains

just one action, however, if a rule triggers several actions the block contains several

actions.

So what happens after all rules have been evaluated and placed on the agenda? The

first action block is taken off the agenda and is executed. Which action block is first? The

answer to this question is undefined. It is impossible to predict which action block will be

executed first - the action block is taken off the agenda at random

What happens next? The actions of the first block randomly taken off the agenda are

executed. What happens during execution of such actions is described in Action

Execution. The only difference is that if the un-ordered rule collection represents rules

attached to a business object and the actions modify some attribute of the same

business object, then the entire collection of rules does not get re-executed again, since

it is already being executed.

After the first action block has finished execution the rule engine starts to re-evaluate

conditions of the rules, since the actions could have changed the state of the system

(represented by values of attributes of business objects that are in the rule engine

terminology called facts). Note that only those rules that depend on the facts changed by

the action(s) are re-evaluated. The agenda is reviewed as well – those action blocks that

represent rules with the conditions that no longer hold are removed from the agenda and

the new action blocks representing rules for which the conditions hold are placed on the

agenda.

After the agenda has been re-structured another action block is randomly taken off the

agenda and executed. The cycle is repeated until there are no more action blocks on the

agenda.

This algorithm can be summarized by the following flowchart:

In fact the order is random only for action blocks that have equal priority – see priorities later in this

section. In the current discussion we assume for simplicity that the order is completely random.

Aware IM 8.8 User Guide

Example of Rule Engine Execution

To better illustrate how the rule engine works let us consider the following example.

Suppose that our Policy object has the following rules defined (again it does not

matter whether this example is very realistic):

1. Rule 1 (initialization of State attribute):

IF Policy.State IS UNDEFINED Then Policy.State = 'NEW'

2. Rule 2 (initialization of Excess):

IF Policy.Excess IS UNDEFINED Then Policy.Excess = 0

Aware IM 8.8 User Guide

3. Rule 3 (calculation of excess for young drivers)

IF Policy.State = 'NEW' AND Policy.MyDriver.Age < 70 Then

Policy.Excess = 100

4. Rule 4 (calculation of excess for elderly drivers)

IF Policy.State = 'NEW' AND Policy.MyDriver.Age >= 70 Then

Policy.Excess = 200

5. Rule 5 (calculation of final state)

IF Policy.Excess > 0 Then Policy.State = 'CALCULATED'

Let us assume that an instance of the Policy object is being created, Policy is

initialized with a reference to the Driver, whose age is 30 and all other attributes of

the Policy object are initially undefined. Now let us see what happens when the rule

engine starts evaluating the rules for this new instance of the Policy object.

Scenario 1:

Step 1: all rules are evaluated. The conditions are met for Rule 1 (State is initially

undefined) and Rule 2 (Excess is initially undefined) only. Conditions of Rule 3 and

Rule 4 are not met because the State is not ‘NEW’; conditions of Rule 5 are not met

because the Excess is undefined. The agenda is formed and it initially contains

actions blocks of Rule 1 and Rule 2 (each action block has one action):

Agenda:

- Policy.State = 'New' (from Rule 1)

- Policy.Excess = 0 (from Rule 2)

Step 2: an action block is randomly taken off the agenda. Let us assume that it is the

action block from Rule 2. After it is executed the value of Excess attribute becomes 0.

The agenda now only has the action block from Rule 1.

Agenda:

- Policy.State = 'New' (from Rule 1)

Step 3: Rules that depend on the changed attribute Excess are re-evaluated. Rule 2

and Rule 5 only depend on the value of Excess attribute (Rule 3 and Rule 4 set this

value but do not depend on it). The conditions of Rule 2 and Rule 5 are re-evaluated.

Both conditions are not met (Excess is defined and equal to 0). Therefore their actions

are not placed on the agenda. Existing agenda is reviewed as well – its only action is

from Rule 1, which does not depend on the changed attribute and so is left intact. The

agenda therefore still has one action block from Rule 1.

Agenda:

Aware IM 8.8 User Guide

- Policy.State = 'New' (from Rule 1)

Step 4: an action block is randomly taken off the agenda. There is only one action

block on the agenda so it is executed. The value of the State attribute becomes

‘NEW’

Agenda: (empty)

Step 5: Rules that depend on the changed attribute are re-evaluated. Rule 1, Rule 3

and Rule 4 depend on the value of the State attribute, so their conditions are re-

evaluated. Only conditions of Rule 3 are met because the State is now defined and

the age of the driver is 30. So the action of Rule 3 is placed on the agenda.

Agenda:

- Policy.Excess = 100 (from Rule 3)

Step 6: the only action block is taken off the agenda and is executed. The value of

excess becomes 100.

Agenda: (empty)

Step 7: The conditions of Rule 2 and Rule 5 that depend on the Excess attribute are

re-evaluated. The condition of Rule 5 is met and the corresponding action is placed on

the agenda.

Agenda:

- Policy.State = 'CALCULATED' (from Rule 5)

Step 8: the only action block is taken off the agenda and is executed. The value of

state is now CALCULATED.

Agenda: (empty)

Step 9: The conditions of Rule 1, Rule 3 and Rule 4 that depend on the State

attribute are re-evaluated. Neither condition is met; nothing is placed on the agenda.

Agenda: (empty)

Step 10: The agenda is empty; the algorithm finishes. The value of Excess is 100, the

value of State is CALCULATED

Agenda: (empty)

Let us see now what would happen if a different action block was taken off the agenda

at Step 2.

Scenario 2:

Step 1 is the same as before.

Aware IM 8.8 User Guide

Step 1: all rules are evaluated. The conditions are met for Rule 1 (State is initially

undefined) and Rule 2 (Excess is initially undefined) only. The agenda has the

corresponding actions

Agenda:

- Policy.State = 'New' (from Rule 1)

- Policy.Excess = 0 (from Rule 2)

Now we take the action from Rule 1 off the agenda.

Step 2: The action block from Rule 1 is taken off the agenda. It is executed and the

value of State attribute becomes ‘NEW’. The agenda now only has the action block

from Rule 2.

Agenda:

- Policy.Excess = 0 (from Rule 2)

Step 3: The conditions of Rule 1, Rule 3 and Rule 4 are re-evaluated because they

depend on the value of the changed attribute State. The condition of Rule 3 only is

met (state is ‘NEW’ and driver age is 30) so its action is placed on the agenda. The

agenda is reviewed as well – the rule of its existing action block does not depend on

the State attribute and so the action is left intact. The agenda now has 2 actions.

Agenda:

- Policy.Excess = 0 (from Rule 2)

- Policy.Excess = 100 (from Rule 3)

Step 4: an action block is randomly taken off the agenda. Let us assume that it is the

action block from Rule 3. After it is executed the value of the Excess attribute

becomes 100. The agenda now only has the action block from Rule 2.

Agenda:

- Policy.Excess = 0 (from Rule 2)

Step 5: The conditions of Rule 2 and Rule 5 are re-evaluated because they depend on

the value of the changed attribute Excess. The condition of Rule 5 only is met so its

action (Policy.State = 'CALCULATED') is placed on the agenda. The existing

action on the agenda is reviewed as well. The action comes from Rule 2 that depends

on the changed attribute so the condition is re-evaluated – it no longer holds

(Policy.Excess is no longer undefined as its value is now 100)! This means that the

action is removed from the agenda! Therefore the only action that remains on the

agenda is the action from Rule 5.

Agenda:

- Policy.State = 'CALCULATED' (from Rule 5)

Further steps are equivalent to steps 8, 9 and 10 in the previous scenario. At the end of

the algorithm we will also have the value of State=’CALCULATED’ and the value of

Excess=100.

Aware IM 8.8 User Guide

Finally let us consider what would have happened if a different action was taken off the

agenda at step 4 of the second scenario.

Scenario 3:

The first 3 steps are the same:

Step 1: all rules are evaluated. The conditions are met for Rule 1 (State is initially

undefined) and Rule 2 (Excess is initially undefined) only. The agenda has the

corresponding actions

Agenda:

- Policy.State = 'New' (from Rule 1)

- Policy.Excess = 0 (from Rule 2)

Step 2: The action block from Rule 1 is taken off the agenda. After it is executed the

value of the State attribute becomes ‘NEW’. The agenda now only has the action

block from Rule 2.

Agenda:

- Policy.Excess = 0 (from Rule 2)

Step 3: The conditions of Rule 1, Rule 3 and Rule 4 get re-evaluated because they

depend on the value of the changed attribute State. The condition of Rule 3 only is

met (state is ‘NEW’ and driver age is 30) so its action is placed on the agenda. The

agenda is reviewed as well – the rule of its action does not depend on the State

attribute and so the action is left intact. So the agenda now has 2 actions.

Agenda:

- Policy.Excess = 0 (from Rule 2)

- Policy.Excess = 100 (from Rule 3)

Now we take the action from Rule 2 off the agenda.

Step 4: The action block from Rule 2 is taken off the agenda. After it is executed the

value of the Excess attribute becomes 0. The agenda now only has action block from

Rule 3.

Agenda:

- Policy.Excess = 100 (from Rule 3)

Step 5: The conditions of Rule 2 and Rule 5 are re-evaluated because these rules

depend on the changed attribute Excess. The conditions of neither rule are met

(Excess is defined and is equal to 0). The existing action on the agenda is reviewed

as well – its rule depends on the changed attribute, but its conditions still hold, so the

action remains on the agenda.

Agenda:

- Policy.Excess = 100 (from Rule 3)

Aware IM 8.8 User Guide

Step 6: the only action block is taken off the agenda and is executed. The value of

Excess is now 100.

Agenda: (empty)

Step 7: The conditions of Rule 2 and Rule 5 are re-evaluated because they depend on

the value of the changed attribute Excess. The condition of Rule 5 only is met so its

action is placed on the agenda.

Agenda:

- Policy.State = 'CALCULATED' (from Rule 5)

Further steps are equivalent to steps 8, 9 and 10 of the scenario 1. At the end of the

algorithm we get the value of State=’CALCULATED’ and the value of Excess=100

again.

Interestingly, no matter in which order we take the actions off the agenda the end result

is the same! This is only possible, though, if every single rule in the un-ordered collection

of rules is self-contained (independent of how and when other rules are evaluated) and

consistent (makes sense from the business point of view) and this is what business rules

are supposed to be! This is worth stressing again – business rules must be self-

contained and consistent!

“While” Semantics

Normally when the rule engine finishes execution of an action it starts re-evaluating rules

that depend on changed facts only. However, generally speaking, it must also re-

evaluate conditions of the rule that triggered the last action irrespective of whether the

rule depends on the changed facts or not. The rationale behind this is that if conditions

of a rule are met its actions must be executed. There is no guarantee that the action that

has just been executed had changed anything that could have affected its conditions, so

the engine must evaluate the rule again

This behaviour means that the same rule may be evaluated over and over again

provided that its conditions still hold. Thus a rule may encapsulate the semantics of the

“while” statement – instead of defining a rule as “IF something is true then do something”

we might as well define it as “WHILE something is true then do something”.

The only problem with the above behaviour is that the subtlety of the “while” semantics

is easy to overlook. Anyone defining business rules must be very careful as the incorrect

usage of rules may cause infinite loops (the rule engine will eventually time out and

abort if an infinite loop does occur). Consider the following rule:

There is a guarantee that conditions of other rules, which do not depend on changed facts and which

actions are not on the agenda, do not hold (otherwise they would have been on the agenda) – this is the

reason the algorithm does not consider them after execution of an action.

Aware IM 8.8 User Guide

IF Glass.State <> 'FULL' Then INCREASE Glass.WaterLevel BY 10

The rule is supposed to add some water to a glass if it is not full already. If we only have

this single rule defined for a Glass object and we evaluate it for a glass with the State

attribute not FULL initially, the rule will keep executing the INCREASE action until the

engine times out. However, if we add the following rule to the Glass object everything

will be fine:

IF Glass.WaterLevel = 100 Then Glass.State = 'FULL'

Aware IM supports a special flag that makes it possible to turn off the “while” semantics

behaviour for a rule (see Advanced Rule Options). If this flag is turned off the rule engine

will not evaluate the rule that triggered the execution of the last action block taken off the

agenda (unless the conditions of the rule depend on the values of attributes that the

action of the rule changes). For example, if the flag for the rule

IF Glass.State <> 'FULL' Then INCREASE Glass.WaterLevel BY 10

is turned off, the rule will be evaluated initially and its action will be executed (jf state is

not FULL), but it will not be executed immediately again. Other actions (if there are any)

will get executed and if those actions do not change the value of the State attribute our

rule will not be re-evaluated again. However, if our rule were written like this:

IF Glass.WaterLevel <> 100 Then INCREASE Glass.WaterLevel BY 10

it would be re-evaluated repeatedly after the execution of the INCREASE action

irrespective of the value of the “while semantics” flag. This is because the INCREASE

action changes the value of the WaterLevel attribute and the rule condition depends

on this value.

Did it Change?

The subtle issue described in this section is related to a stage in the rule engine

algorithm where it detects which rules depend on the changes made by the previously

executed action. The subtle point here is that even though the action has been executed

it may not have changed the state of the system, even if it had attempted to modify the

value of some attribute. This happens, for example, if an action sets the value of the

attribute that is equal to its current value. This situation is considered to be a non-event

from the rule engine point of view and the rule engine simply ignores the fact that the

action has been executed. Consequently it does not re-evaluate the rules and review the

existing agenda even for a rule that triggered the last action.

This behaviour helps to avoid infinite loops in certain rules even if they support “while”

semantics. Consider the following rule, for example:

Aware IM 8.8 User Guide

If Policy.Driver.Age > 70 Then Policy.Excess = 200

If a rule supports the semantics of a “while” statement (see While Semantics) the rule

can be interpreted as “while driver’s age is greater than 70 set excess to 200”. The

driver’s age will never change here and so we might think that this rule would cause an

infinite loop. This does not happen, however. After the action has been executed for the

first time and the new value has been set to 200, all subsequent executions of the action

would not change the value of the attribute and so the rule is not evaluated again.

NOTE: the rule engine will not execute unconditional rules over and over again if the

action keeps changing the value of some attribute, since such action guarantees to

cause infinite loop. For example, the following rule with no conditions:

INCREASE Policy.Excess BY 100

will only be executed once.

Rule Priorities

When describing the rule engine algorithm in the Overview of the Rule Engine

Framework section we said that action blocks are taken off the agenda at random. This

is not quite true - the order of action blocks on the agenda is not completely random, but

arranged according to rule priorities. The higher the priority of the rule corresponding to

the action block the sooner it will be executed. The rule engine guarantees that action

blocks corresponding to rules with higher priority are always executed before action

blocks corresponding to rules with lower priority – whatever actions exist on the agenda

are sorted according to the priorities of their rules and are taken off the agenda in that

order.

It is important to stress, though, that if priorities of the rules are the same, the order of

the corresponding action blocks is random. Most often action blocks on the agenda

correspond to rules that have the same priority – that is why we ignored rule priorities

when describing the rule engine algorithm.

So when are priorities important? First of all, when we are dealing with rules that invoke

actions that do not modify the value of some attribute, but call predefined system

operations, such as REPORT ERROR, SEND etc. By default Aware IM assigns lower

priorities to such rules than the priorities of rules invoking actions that modify attributes.

The rationale is that unlike modification of an attribute, the predefined system operations

are one-off actions that usually have drastic effects that cannot be undone. For example,

the REPORT ERROR action immediately aborts the execution of the rule engine without

giving it a chance to change anything (unless process failure rules are defined).

Consider the following rules:

Aware IM 8.8 User Guide

Rule 1: If Policy.State IS UNDEFINED Then REPORT ERROR 'State must

always be defined'

Rule 2: If Policy.State IS UNDEFINED Then Policy.State = 'NEW'

If priorities of these rules were equal there is a chance that Rule1 is executed before

Rule 2. If this happened the engine would be immediately aborted without being able to

change the value of the Policy.State to NEW and by doing so avoid execution of Rule

1. This does not happen as Aware IM assigns lower priority to Rule 1 than to Rule 2 or

any other “modify attribute” rule. Therefore validation rules like Rule 1 are only evaluated

after the values of all attributes have “stabilized”.

Another type of rule that is prioritised by Aware IM by default is a rule that has an action,

which generates documents from document templates (see Document Generation).

Again documents should only be generated after values of all attributes have stabilized

and so such a rule has low priority.

It is relatively rare that someone might need to prioritize rules explicitly. One such need

may arise from the necessity to specify the default action to be taken if all else fails. For

example, there may be a situation when we enumerate possible options and take action

in each case: “If condition1 then do something”; “If condition2 then do something else”;

“If condition 3 then do something else again” and so on. Finally we may want to take a

default action that is executed if neither of the conditions holds. We could write a rule

that would negate all the conditions: “If NOT condition1 and NOT condition2 and NOT

condition3 … then take default action”. If there are many conditions it may be quite

tedious and impractical to negate them all. An alternative would be to assign lower

priority to the rule that takes the default action compared to the rules that check

conditions.

Context of Rule Execution

In the Context section we have introduced the concept of Context and explained where

Aware IM looks for instances of business objects and notifications while evaluating

rules. This section provides more details about the Context; in particular, it explains how

and when the Context is formed.

See also:

How Context is Formed

Instances Prefixes

Other Usages of Context

How Context is Formed

The Context is used by Aware IM to resolve values of attributes of business objects

during evaluation of rule collections (both ordered and un-ordered – see Evaluation of

Rule Collections). It is important to emphasize that each rule collection has its own

Aware IM 8.8 User Guide

Context; there is no single Context that is shared by all rule collections. For example, let

us suppose that we are executing a rule collection representing rules of a process. This

rule collection has a Context associated with it (let us not worry for now how it was

formed). If some action modifies the value of an attribute of some business object

Aware IM starts evaluating the rules attached to this business object. Before doing so it

assigns a new Context to this collection of rules (again let us not worry for now what

gets written into this Context). Once the rules attached to the business object finish

execution, the Context associated with the rule collection is discarded and Aware IM

continues evaluation of the process rules. Now, if some action of these rules starts

another process Aware IM assigns another Context and starts evaluating the rules of a

sub-process. When the sub-process finishes Aware IM discards the Context and returns

to the evaluation of the rules of the original process.

Let us now have a look at what gets written into the Context and when. The contents of

the Context is changed under the following scenarios:

1. Instances of the business objects found by the FIND and PICK FROM actions are

written into the Context of the rule collection that invokes these actions

For example, let us look at the following process:

FIND Driver WHERE Driver.Name = 'John Smith'

Driver.Age = 40

The first rule in this process finds the driver with the name John Smith. If such an

instance is found it is written into the Context.

2. Instances of business objects or notifications created by the CREATE or ENTER NEW

actions are written into the Context of the rule collection that invokes the actions.

The following example is similar to the previous one:

CREATE Driver WITH Driver.Name = 'John Smith'

Driver.Age = 40

3. When Aware IM starts evaluating the rules attached to a business object the

instance of the business object is written into the Context. The instance is either

taken from the parent Context (such as when an instance of a business object is

modified by a process) or is provided by the external request (such as when a user

changes attribute values on the business object form and submits the changes to the

system).

If an un-ordered collection is executing the instances are written into the Context of the action block - see

Note 3 later in this section.

Aware IM 8.8 User Guide

In the process from the first scenario the second rule modifies the attribute of the driver’s

instance found by the previous rule. If the Driver object has rules attached to it Aware

IM assigns a new Context to these rules, writes the instance of the Driver from the

process Context into the new Context and starts evaluating rules of the Driver object.

4. When Aware IM starts executing a process the instances of the business objects

representing process input are written into the Context. The instances are taken from

the parent Context.

For example, consider the following process:

FIND Policy WHERE Policy.MyDriver.Name = 'John Smith'

CalculatePremium

Here we assume that CalculatePremium process that calculates the premium of the

policy has the Policy object declared as its input. The first rule finds the policy

belonging to John Smith and writes it into the Context of the main process. Then Aware

IM creates a new Context for the CalculatePremium process, writes the instance of

the Policy from the main process’s Context into the new Context and starts evaluating

rules of the CalculatePremium process.

5. When a new instance of a business object or notification is created by the CREATE

action Aware IM writes the contents of the parent Context into the new Context

which is created when rules attached to the business object or notification are

evaluated.

In other words the Context of the parent rule collection is available when a new business

object or notification are being created. For example consider the following process,

FIND Policy WHERE Policy.ExpiryDate < CURRENT_DATE

CREATE ExpiryEmail

SEND ExpiryEmail TO Policy.Driver

The first rule of the process finds the expired policy and puts the found instance into the

Context of the process. The second rule of the process creates the notification

ExpiryEmail and evaluates any rules attached to the creation of this notification

The new Context is assigned to these rules, but now not only the created notification is

written into this Context but the entire contents of the existing Context is written into the

new Context as well. Therefore in this example Policy instance is available to any

initialization rules of the notification. The created notification is also written into the

original Context (as a result of creation), so in this particular case both Contexts have

identical contents.

In this example the CREATE rule is actually unnecessary. The SEND action would automatically create

the notification if it has not been created already.

Aware IM 8.8 User Guide

NOTE: The following instances of business objects are always accessible to rules

directly – there is no need to find them using the FIND action, as they are always

implicitly present in any Context:

a. An instance of a business object representing logged in user (must be a member of

the SystemUsers group) – this instance can be referred to using LoggedIn prefix

(see Instance Prefixes), for example LoggedInLibraryMember where

LibraryMember is a business object belonging to the SystemUsers group.

b. Instances of intelligent business objects with Business or System intelligence

types. There are always only single instances of such business objects in the

system, so they can always be unambiguously resolved.

c. An instance of the SystemSettings object.

NOTE: If there are multiple instances of the same business object in the Context any

action that operates on such a business object operates on all instances of the object

present in the Context. For example, in the scenario 1 above which describes the

modification of the Driver object found by the FIND action, if the action finds several

instances of the Driver object all these instances are written into the Context.

Consequently the action that modifies the Age attribute modifies every single instance of

the Driver object found by the FIND action. Similarly in scenario 5 if there are several

expired policies the email is sent to owners of each policy.

NOTE: When rules of an un-ordered rule collection are executed (see Evaluation of

Unordered Rule Collection) instances of business objects and notifications created by

the CREATE or ENTER NEW actions or found by the FIND or PICK FROM actions are not

written into the Context of the un-ordered rule collection. Instead these instances are

made available only within the action block that contains the FIND (PICK FROM) or

CREATE (ENTER NEW) actions. This means, for example, that it is quite meaningless

to attach rules to a business object, which have single FIND action. However, having an

action block that finds some object and then does something with the found instance

within this block may be quite meaningful.

Instance Prefixes

Normally rules do not distinguish between instances of the same business object.

Instances are resolved from the Context and if there is more than one instance of the

object in the Context the action is applied to all such instances.

However, in certain relatively rare circumstances it may be necessary to distinguish

between instances of the same business object stored in the Context. In these cases

special instance prefixes added to the attribute path just before the name of the

business object can be used.

Aware IM 8.8 User Guide

Consider, for example, the following rule attached to a business object SystemUser,

which checks that there is only one instance of the SystemUser with the specified login

name in the system:

If EXISTS SystemUser WHERE (SystemUser.LoginName =

ThisSystemUser.LoginName) Then REPORT ERROR 'User with this name

already exists'.

Here the This prefix added to the name of the business object

(ThisSystemUser.LoginName) indicates the SystemUser instance located in the

Context as opposed to the SystemUser instances in the rest of the system, which are

searched by the aggregate operation.

There are several special prefixes that are used in the Rule Language to distinguish

between instances of business objects in the Context:

- This

- That

- Other

- LoggedIn

- Added

- Removed

- Changed

- Failed

This prefix indicates the first instance of an object that has been added to the Context

by any of the scenarios described in the How Context is Formed section.

That prefix indicates the second instance of an object added to the Context. Usually it is

the instance found by the FIND or PICK FROM action or created by the CREATE or

ENTER NEW actions. For example, consider the process that has the following rules

defined:

1. FIND Policy WHERE Policy.MyDriver.Name='John Smith'

2. If ThisPolicy.Excess > ThatPolicy.Excess Then…

Let us assume that the above process has the Policy object as its input. When this

process is executed the instance of the Policy object being the input of the process is

put in the Context first. This instance may be referred to by the This prefix. The first rule

of the process finds another instance of the Policy object (the one belonging to John

Smith). The result is put into the Context as well. As John Smith’s policy is the second

instance of the Policy object in the Context it will have the That prefix, so the second

rule will compare the excess of the process input instance with the excess of John

Smith’s policy.

Aware IM 8.8 User Guide

If the FIND rule found more than one instance of the Policy object, then these

instances could be referred to with the Other prefix – so we could refer to the initial

policy as ThisPolicy and to all other policies as OtherPolicy.

The LoggedIn prefix can be used in conjunction with the name of the business object

that is using the system (member of the SystemUser group) to refer to the instance of

the currently logged in user. For example,

If LoggedInAssociate.LoginName='john' Then DoSomething.

Added, Removed and Changed prefixes are used in conjunction with WAS CHANGED

expression, which tracks changes in the list – see Evaluation of Rules Containing WAS

CHANGED Expressions.

The Failed prefix is used to indicate the object that caused a failure in process failure

rules – see Process Failure Rules.

Other Usages of Context

Aware IM uses the Context not only when rules are executed. It is also used in the

following situations:

- When queries using dynamic attributes are run (see Configuring Queries)

- When documents and presentations are generated (see Document Generation)

Queries using dynamic attributes may be invoked either from form operations in the user

interface or from hyperlinks in presentations or from rules (see FIND action). When a

query is invoked from a form operation the instance of the business object displayed by

the form is written into the Context and used if the query refers to the attributes of this

object dynamically. Similarly if a query is invoked from a hyperlink in a presentation the

instance of the object that the hyperlink is associated with is written into the Context and

used if the query refers to attributes of this object dynamically. If a query is invoked from

rules the dynamic attributes are resolved from the Context of the currently executing rule

collection – see How Context is Formed.

NOTE: a query using dynamic attributes may not be invoked from a menu item (see

Operations) as there is no Context when the menu item is selected. If this happens run

time error occurs.

When documents or presentations are generated attribute values referenced by tags

inside documents or tags and conditional elements inside reports or presentations are

resolved from the Context. The following scenarios are possible:

1. A document with the data source property set to “Determined at Run-time” is

generated in the Operation Mode using an operation of the “Create Document” type

Aware IM 8.8 User Guide

(see Setting Menu Item Properties) after a user selects one or more instances of the

business object on the Query Results screen. In this case selected instances of the

business object are written into the Context and used when the document is

generated.

2. A document with the data source determined by some query is generated in the

Operation Mode using the operation of the “Create Document” type. In this case the

query is run before the document is generated and the instances of a business object

found by the query are written into the Context and used when the document is

generated.

3. A document is generated in the Operation Mode by invoking the operation of the

“Create Document” type from the form of a business object (see Form Caption and

Form Operations). In this case the instance of the business object being displayed by

the form is written into the Context and used when the document is generated.

4. A document with the data source property set to “Determined at Run-time” is

generated from rules (for example, when some attribute is being initialized to some

document template – see Document Generation). In this case the document uses the

Context of the currently executing rule collection.

5. A document with the data source determined by some query is generated from rules

as in the previous scenario. In this case the query is run before the document is

generated and a separate Context is formed. This Context contains the results of the

query execution as well as any contents of the Context of the currently executing rule

collection. The resulting Context is used when the document is generated.

6. A presentation of some business object is generated to display the instances of a

business object found by a query (see Business Object Presentation). In this case

the instances found by the query are written into the Context and used when the

presentation is generated.

7. A presentation is generated from a form operation or from a hyperlink located on

some other presentation. In this case the instance of a business object that the form

is displaying or that the hyperlink is associated with is written into the Context and

used when the presentation is generated.

8. Sub-report or sub-presentation is generated as part of the generation of the master

report or presentation (see Document Generation). In this case a query associated

with the sub-report or sub-presentation is run first and then a special Context is

formed. This Context contains the results of the query and the current instance of the

business object in the master report for which the sub-report is generated. (Note that

the query associated with the sub-report or sub-presentation may use this instance

for attributes resolved dynamically). This Context is used when the sub-report or sub-

presentation are generated.

Evaluation of Rules Containing WAS CHANGED expressions

Evaluation of rule conditions containing WAS CHANGED expressions (and also

expressions that track changes in the list – WAS ADDED TO, WAS REMOVED FROM, WAS

CHANGED FROM – see WAS CHANGED Expression) is somewhat different from

evaluation of other expressions. Whereas most expressions check the absolute value of

Aware IM 8.8 User Guide

an attribute (such as “If Driver.Age > 70”), WAS CHANGED expressions check the

relative value of the attribute – that is, the current value of the attribute compared to the

old value of the attribute. The question is which value is considered to be “old”? Similarly

if an expression checks whether some element has been added to a list, the question is

– added when?

Before answering this question we must explain the meaning of the term last stable

version of a business object instance. The last stable version is the version of the

business object instance that is stored in the system and no rule processing of the rules

attached to the object is occurring. When an instance of the business object is modified

and rules attached to this business object start to be evaluated the instance of the

business object is considered to be in an unstable state. When rule evaluation and

action execution for the instance of the business object finish the instance of the object

moves to a stable state again. Any new modification to the business object instance

from the outside (for example, by a user or by a process) will cause rule evaluation and

action execution to occur again and move the object back to the unstable state.

Now we can answer the question which value Aware IM considers to be “old” when

evaluating WAS CHANGED expressions. The “old” value is the value corresponding to the

last stable version of the business object instance. For example, consider the following

rule:

If OLD_VALUE(Policy.State) = 'CALCULATED' AND Policy.State WAS

CHANGED Then REPORT ERROR 'Cannot change state of the policy once

it is calculated'

OLD_VALUE here is the function that returns the value of the attribute corresponding to

the last stable version. Let us assume that the value of the State attribute currently

stored in the system is CALCULATED. Let us assume that a user brings up a policy form

and changes the value of the State attribute to NEW. When the changes to the policy

are submitted Aware IM starts evaluating the policy rules. When evaluating the rule

above it will compare the value of the last stable version of the State attribute

(CALCULATED) with the current value (NEW) and trigger the REPORT ERROR action.

Note that WAS CHANGED expression will return true each time it is evaluated provided

that the current value is different from the value of the last stable version. So in our

example if a rule above is evaluated again as a result of execution of other actions it will

still return TRUE. It will keep returning TRUE while rules are being evaluated for the

instance of the business object.

Once rule evaluation finishes the instance of the business object moves to the stable

state again. Consider the following rules on the Policy object:

1.IF Policy.State WAS CHANGED Then DoSomething

2.IF Policy.MyDriver.Age > 70 Then Policy.Premium = 200

3.IF Policy.Premium = 200 Then Policy.State='BIG PREMIUM'

Aware IM 8.8 User Guide

Let us assume that there is a policy for a driver aged 45, the value of Premium is 100

and the policy state is NORMAL PREMIUM. If a user changes the age of the driver to 50,

neither of the actions of the three rules will be triggered (the value of the State attribute

for the current and last stable versions are the same and the age is still less than 70).

Now, if the user changes the age of the driver to 75 (again without changing the state of

the policy) the following will happen after the initial evaluation of rules:

a. Condition of Rule 1 will not hold because the current state is equal to the state of

the last stable version

b. Condition of Rule 2 will hold and so its action will be placed on the agenda

c. Condition of Rule 2 will not hold initially because premium is still 100

After the premium is changed to 200 by the action of Rule 2 the action of Rule 3 will be

triggered. This action will change the value of the State attribute to BIG PREMIUM.

This will cause the conditions of Rule 1 to be evaluated. Now, the current value of the

State attribute will be different from the value of the last stable version and

DoSomething will be triggered. After that the policy instance will move to the stable

state again so the “stable” value of the State attribute becomes BIG PREMIUM. If now

the user changes the driver’s age to 80 the action of the first rule will not be triggered.

Evaluation of list tracking expressions is quite similar – they compare the condition of the

list in the last stable version of the business object with the current condition.

Initialization Rules

The Rule Evaluation section enumerates all occasions when rules are evaluated in

Aware IM. There is one other occasion not mentioned in this section albeit this occasion

has a rather secondary nature compared to the ones described before.

When the user brings up a form to create a new instance of a business object (this may

happen as a result of the user selecting a menu item of the “Create Object” type or as a

result of the execution of the ENTER NEW action in some process), before the form is

displayed the rules attached to the business object are evaluated and the appropriate

actions are executed. The objective of rule evaluation is to initialize the attributes with

their initial values. Because of this not all rules attached to the object are evaluated -

only the initialization rules.

By default the system considers the following rules to be initialization rules:

1. Unconditional rules that set attribute values, for example

Policy.State = 'NEW'

Aware IM 8.8 User Guide

2. Rules that check whether a value is undefined and if so initialize this value, for

example

IF Policy.Excess IS UNDEFINED Then Policy.Excess = 0

It is also possible to explicitly specify whether the rule will or will not be used during

initialization - see Advanced Rule Options.

All other rules are ignored at the initialization stage. However, when the form is

submitted with the values entered by the user (who could have changed the initial

values) all rules are evaluated as usual.

Summary of Rule Evaluation

The following section provides a brief summary of what has been described in the

previous sections regarding rule evaluation and action execution in Aware IM.

1. Rules are evaluated when the following happens:

- An instance of a business object is created (provided that there are rules attached

to this business object)

- Value of an attribute of a business object instance is modified (provided that there

are rules attached to this business object)

- A process implemented by rules is started

- Aware IM receives notification (provided that there are rules associated with this

event)

- Notification is created (provided that there are rules associated with this event)

- Scheduling rules are triggered by a timer event

- Values of attributes of business objects are taken from the Context except for

aggregate operations such as EXISTS. When aggregate operations are

evaluated Aware IM looks at all data available in the system – see Aggregate

Operations.

2. The following events change the contents of the Context (see How Context is

Formed):

- Business objects found or selected by the FIND or PICK FROM actions are

written into the Context of an ordered rule collection or into the Context of the

currently executing action block of an un-ordered rule collection.

- Business objects and notifications created by the CREATE and ENTER NEW

actions are written into the Context of an ordered rule collection or into the

Context of the currently executing action block of an un-ordered rule collection.

- Before a rule collection attached to a business object is evaluated the instance of

the business object for which evaluation occurs is written into the Context.

Aware IM 8.8 User Guide

- Before a rule collection attached to a notification event (creation or receiving) is

evaluated the instance of the notification for which evaluation occurs is written

into the Context.

- Instances of business objects representing process input are written into the

Context prior to execution of the process.

3. Whenever a change to the system state occurs as a result of the creation of a new

instance of a business object or notification or modification of the existing instance,

Aware IM starts evaluation of the appropriate set of rules, i.e.

- Rules attached to a business object, an instance of which has been created or

modified.

- Rules attached to other business objects that refer to the business object

instance that has been created or modified (cross-reference rules).

4. Cross-reference rules are rules attached to some business object that also refer to

some other object via a reference attribute or check whether an existing element in a

list has been changed – see Cross-reference Rules.

5. When a reference attribute of some object is modified and this reference attribute

has matching attribute on the referred object, the referred object is modified as well

and its rules (if any) are evaluated.

6. Rule collections can be ordered and un-ordered. Ordered rule collections are

evaluated one-by-one in exactly the same order that they appear in the rule

collection. Un-ordered rule collections are evaluated by the rule engine using a

special algorithm – see Evaluation of Rule Collections.

7. The rule engine works as follows (see Overview of Rule Engine Framework):

- Initially all rules of the un-ordered rule collection are evaluated and the initial

agenda is formed.

- The first action block is taken off the agenda. The block is taken off according to

its priority. If priorities of actions blocks on the agenda are equal the block is

taken off at random.

- The actions of the action block are executed. The changes to the system facts

occur.

- Rules that depend on the changed facts are re-evaluated. The remaining actions

on the agenda are also reviewed to check if the conditions that triggered them are

still valid. The new agenda is formed.

- Another action block is taken off the agenda and executed. The process is

repeated until there are no more actions on the agenda.

8. Even though actions may be randomly taken off the agenda by the rule engine the

end result is the same provided that business rules are self-contained and

consistent.

Aware IM 8.8 User Guide

9. Rules may support “while semantics” in which case conditions of the rule that

triggered action execution will be repeatedly re-evaluated irrespective of whether rule

conditions depend on changed facts – see While Semantics.

10. Actions that assign an attribute value equal to the existing value do not cause re-

evaluation of rules, as the system’s state is not changed as a result of such an action

– see Did it Change?

11. Aware IM assigns default priorities to rules – actions that modify attribute have

highest priority; actions that call “system services” have lower priority and actions

that generate documents from templates have the lowest priority – see Rule

Priorities.

12. It is possible to distinguish between instances of the same business object by using

instance prefixes – see Instance Prefixes.

13. The last stable version is the version of a business object instance that is stored in

the system and no rule processing of the rules attached to the object is occurring.

The WAS CHANGED expressions compare the current value of an attribute (or the

current state of a list) with the value of the last stable version – see Evaluation of

Rules Containing WAS CHANGED expressions.

14. Initialization rules are rules that set attribute values either unconditionally or after

checking whether the value is undefined. Such rules are executed before a form for

the new instance of a business object is displayed – see Initialization Rules.

Rules and Transactions

In Aware IM data processing may occur under the following scenarios:

1. An external request has been issued to the system, which triggered rule evaluation

(see Rule Evaluation). This external request may have been issued either from the

User Interface or from an external software system.

2. A notification has been received by Aware IM, which triggered rule evaluation.

3. A timer event triggered scheduled processes to start executing (see Scheduling).

The following section describes how Aware IM handles database transactions when

processing data under the above scenarios (transactions are described in the Data

Storage section).

With scenarios 1 and 3 data processing occurs within a context of a single transaction.

This means that if something goes wrong all changes that have been done by any of the

rules between the start of the external request (or when the scheduled process started)

and the error are discarded (transaction is rolled back).

Aware IM 8.8 User Guide

What can go wrong? First of all a transaction is rolled back if any of the rules issues the

REPORT ERROR action. This action indicates an unrecoverable operation error so the

current transaction is immediately rolled back and any prior changes are discarded

. A

transaction is also rolled back in case of an internal error.

With scenario 2 the behaviour of the system is slightly different. The rules attached to a

notification event are considered to be independent and are executed within separate

database transactions, so if one rule fails anywhere it does not affect other rules

attached to the notification – their changes are committed provided that these changes

themselves did not cause errors.

See also:

Long Operations

Batch Operations

Process Failure Rules

Long Operations

An action executed by a rule may start an operation that takes a long time to complete.

For example, an action may request a service from some other system (see

Communication with Other Systems) and the other system may take minutes, days or

months to implement the request. Or an action may start an operation in the user

interface and wait for the input from a user (there is a number of such actions in the Rule

Language – see Rule Language Reference). Again it may take a user minutes or hours

to provide this input.

Aware IM seamlessly supports operations that take a long time to complete. If a reply

has not been delivered to Aware IM within a certain time frame the current request that

started the long operation is suspended. This means that Aware IM stores the current

state of the external request that started rule execution in the first place in the database

and continues with other tasks. As soon as a reply has been received (no matter how

long it took to receive the reply) Aware IM restores the state of the request and resumes

execution of rules as if no long operation has taken place. While Aware IM is waiting for

the reply the request is considered to be “active” – it is possible to look at the list of all

active processes in the system by selecting the menu item of the “Active Processes”

type in the Operation Mode (see Setting Menu Item Properties).

When an action requests a service of another system Aware IM waits for a reply for one

minute before it suspends the current request. After that it waits for the reply indefinitely

(unless the request is cancelled by the user from the Active Processes screen).

Transaction is not rolled back if process failure rules are defined for a process that started rule

evaluation in the first place – see Process Failure Rules.

Aware IM 8.8 User Guide

When an action starts an operation of the user interface the request is suspended

immediately. If a reply from the user has not been received within half an hour (this is

the default value which can be changed in the system’s property file – see Appendix A)

the request is automatically cancelled.

When a request is suspended Aware IM commits the current database transaction.

When a reply is received a new transaction is started. This means that if an error occurs

after the reply has been received only changes since the request has been resumed are

rolled back. Any changes before the request was suspended remain committed. This

behaviour means that it is generally not a good idea to perform any changes to the

system prior to the execution of a potentially long operation, such as invocation of a user

interface operation – all user interface operations need to be executed first and then the

data collected from a user should be used to perform changes to the system.

Batch Operations

When Aware IM executes the FIND action it runs a query and finds instances of

business objects that match the conditions of the query. The instances found are written

into the Context (see How Context is Formed) and any further actions operate with the

found instances. If the number of found instances is large enough further operations

happen in batches. This means that instead of operating on all instances at once further

actions operate only on a subset of instances (a batch). When the query is run for the

first time the first batch is returned. After all actions finish their execution the query is run

again and the next batch is returned. Action execution continues until no more batches

are returned by the query. At each iteration after actions finish execution of the current

batch the database transaction is committed.

For example, consider the following process consisting of two rules:

Rule 1: FIND Account WHERE Account.Balance < 100

Rule 2: Account.State = 'CLOSED'

The first rule runs a query that finds all accounts with balances less than 100. The

second rule changes the state of found accounts. If the number of accounts found by the

query is larger than the batch size the query will initially return only the first batch and

the second rule will change the states only of the first batch. After the second rule

finishes processing the first batch the transaction is committed (so the changes to the

first batch are not rolled back if an error occurs when processing any subsequent

batches). After committing the first batch the rule 1 is executed again and the query

returns the second batch. This process continues until the query returns the last batch.

The size of the batch is 1000 by default, but the default value may be overridden by

specifying the size explicitly in the FIND action.

Aware IM 8.8 User Guide

Process Failure Rules

As explained in the previous sections when a rule issues the REPORT ERROR action the

execution of the current request is terminated and the current transaction is rolled back.

However, what about the situations when we do not want this to happen? Consider, for

example, the following scenario. We have a banking system and we want to define a

process that would be scheduled to run overnight to find all pending fund transfers and

execute them. Some of the fund transfers may fail (for example, there may be not

enough funds in the bank account from which the transfer is made). Our process may

look something like this:

1. FIND FundsTransfer WHERE FundsTransfer.State = 'READY'

2. FundsTransfer.State = 'APPLIED'

The first rule finds all the pending transfers and the second one executes them. Let us

assume that the FundsTransfer object has the following validation rule, which checks

that there are enough funds:

If FundsTransfer.State WAS CHANGED TO 'APPLIED' AND

FundsTransfer.Amount > FundsTranfer.FromAccount.Balance Then

REPORT ERROR 'Not enough funds in the account for transfer

operation'

If our process encounters a transfer with insufficient funds and tries to change its state to

‘APPLIED’ the above validation rule will be triggered. The problem is that this rule will

abort the current transaction and the entire process will be terminated. What we want,

though, is not to terminate the current process, but make the appropriate record about

the failed transfer and continue execution of the process. One way to solve the problem

would be to change the validation rule, so that instead of reporting an error it would set

the state of the transfer to “FAILED”, for example:

If FundsTransfer.State WAS CHANGED TO 'APPLIED' AND

FundsTransfer.Amount > FundsTranfer.FromAccount.Balance Then

FundsTransfer.State = 'Failed'

This solution may be valid in some situations; however, the main problem with it is that it

makes rules of the object dependent on the context in which the object is used. For

example, when setting the state to FAILED in the rule above we make an assumption

that the object will be used within the context of the scheduled process and this is the

reason why we are setting the state rather than reporting the error. What if the object is

used in other contexts – for example, a user sets the state of the transfer manually on

the object form?

The recommended solution to the above problem is to define process failure rules.

These rules may be attached to a process and they will be executed whenever the

process fails as a result of the execution of the REPORT ERROR action anywhere during

Aware IM 8.8 User Guide

the course of the process. Failure rules are supposed to perform corrective actions to

neutralize the effects of the failure. Most importantly, if failure rules are defined for a

process, execution of the process continues after failure and the current

transaction is not rolled back (unless failure rules themselves report an error). The

sequence is as follows:

1. A process starts executing

2. A failure occurs by rules of any object affected by the process issuing the REPORT

ERROR action.

3. If process failure rules are not defined, the execution of the current request is

terminated and the transaction is rolled back. If process failure rules are defined they

start executing and performing corrective actions.

4. Process execution continues as if there was no failure.

In our example we could define the failure rules as follows:

FailedFundsTransfer.State = 'FAILED'

FailedFundsTrasfer.FailureReason = ProcessError.Message

If we define process failure rules like shown above we can still leave the REPORT ERROR

action in the validation rule of the FundsTransfer object.

Note the usage of the special “Failed” prefix in front of the FundsTransfer object. This

prefix can be used to distinguish the instance of the FundsTransfer object that

caused the failure from all other instances of the FundsTransfer object (see also

Instance Prefixes). In fact, all objects that were involved in the failed operation are

placed in the Context and are accessible via the Failed prefix – for example, if in

response to changing its state to APPLIED the FundsTransfer object created or

modified another object, which created or modified yet another object the rules of which

issued the REPORT ERROR action, all these objects are written into the Context and are

available to process failure rules. If there can only be one instance of a particular object

it can also be accessed by the failure rules without the Failed prefix.

Note also the usage of a special predefined object called ProcessError. The instance of

this object is automatically created by the system for the process failure rules to use (it is

not available to any other rules). The attributes of this object are explained in the

following table:

Attribute name

Comments

Message

Error message issued by the REPORT ERROR action that

caused the failure

FailedObject

The name of the business object the rules of which issued

the REPORT ERROR action

FailedRuleName

The name of the rule that issued the REPORT ERROR action

Aware IM 8.8 User Guide

FailedRule

The text of the rule that issued the REPORT ERROR action

CurrentObject

The name of the business object used directly by the

process, the modification or creation of which ultimately

caused the REPORT ERROR action (can be UNDEFINED or

can be the same as FailedObject)

CurrentRuleName

The name of the rule inside the process that the process was

executing when the failure occurred.

CurrentRule

The text of the rule inside the process that the process was

executing when the failure occurred.

NOTE: Process failure rules are also executed if a process has been cancelled by the

user. For example, if a process calls ENTER NEW action the form of the object will be

shown to the user. If the user clicks on the Cancel button on the form, the process will

be cancelled and the failure rules (if any) will be activated. In this case no special

predefined object describing the failure is written into the context.

Execution Log

The results of rule evaluation and action execution are written into the execution log.

This log can be very useful when checking whether business rules behave as expected

(especially when testing new configuration – see Testing Mode).

The log record consists of the record timestamp, the name of the business space in

which the user that has issued the request operates and the name of the user. For

example,

2004-06-18 20:26:07,760 AIS#admin -Executing action

Associate.RegisteredOn=CURRENT_DATE from rules of object

Associate

Here the name of the business space is “AIS” and the name of the user is “admin”.

The execution log supports different levels of logging:

Rules only

This is the default level – only evaluation/execution results of rules attached to business

objects or used in processes are recorded in the log. Evaluation and execution results of

scheduling rules are not shown.

All server events except timer and SQL events

At this level the log contains records of all requests that the server receives. It also has

results of rule evaluation/execution (except scheduiling rules)

Aware IM 8.8 User Guide

All server events excluding SQL

This is the same as the previous level. Evaluation/execution of scheduling rules are also

included in the rule log

All server events including SQL

This is the most verbose level. This is the same as the previous level, but the rule log

also includes records of all SQL commands that Aware IM sends to the database.

The levels may be set up using the Aware IM Control Panel (Settings/Logging menu

item) or in the “logger.props” file located in the BIN directory of the Aware IM Server

installation.

When you run the Settings/Logging command you can also specify whether the system

will log any events into a log file or not. If you tick the corresponding checkbox the

system will store events of all applications running in the production mode in the file

AwareIM/bin/main.log, and it will store events of all applications running in the

testing mode in the file AwareIM/bin/test.log

Log Viewer

The execution log may be viewed using the Aware IM Control Panel. There are several

menu items that can view the log:

 View/Production Log menu item – opens the current log for all

applications running in the production mode

 View/Testing Log menu item – opens the current log for all

applications running in the testing mode

 File/Open Log File – opens the specified log file

Aware IM displays the log as a tree structure where every node represents a single log

record. The nodes of the tree are hierarchical – for example, all log records spawned by

an external request (such as a request to start a process or update an instance of a

business object) are children of the node representing the external request. This is

illustrated on the picture below:

Aware IM 8.8 User Guide

The picture shows execution of the DeleteTopic process – the corresponding nodes

are expanded to show all details of the log. Note also that the Log Viewer shows

different types of log records with different icons and colors. Using the Log Viewer one

can quickly browse through the log and delve into the details of a particular request only

when necessary.

Setting Logging Options

You can specify what each log record will contain by choosing the View/Log View

Options menu item. This menu item opens a dialog where you can specify whether

each record will contain timestamp, business space name and user name.You can also

filter the log and display only records that belong to the specified user in the specified

business space or to all users in the specified business space.

Traversing the log

It’s often useful to quickly traverse the log by only going through certain records,

skipping records that you are not interested in. To do this you need to specify which

records will be filtered out during traversal. This is done by selecting the Edit/Find

Log Record menu item. In this menu command you specify your filtering criteria and

then you traverse the log by pressing the F3 button. Each time you press this button the

system will display the next log record that meets your search criteria.

Aware IM 8.8 User Guide

The Edit/Find Log Record menu item opens a dialog where you can set the

following options:

By text of the log message

Only log records containing the specified text will be traversed.

By business space name

Only log records that belong to the specified business space (and optionally to the

specified user in this business space) will be traversed.

By message type

The following record types are supported:

 EXECUTING ACTION – these are records that indicate that an action of some

rule is about to be executed

 ADD ACTION TO THE AGENDA – these are records that indicate that the

conditions of a rule are satisfied and the actions of the rule are placed on the

agenda of the rule engine

 SQL – these are records that show SQL being sent to the database

 OTHER – all records that do not belong to any of the categories above

By reply to process

Only log records that are involved in the execution of the specified process are traversed

By time difference with previous

Only log records that have timestamp that is different from the timestamp of the previous

records by the specified amount or more are traversed. This can be very useful when

identifying performance bottlenecks in the system. For example, if you specify 30

seconds than you will immediately go to log records that show operation where

execution time was 30 seconds or more.

Rule Debugger

If your business rules do not perform as expected you may need to use special tools to

find out what’s wrong. One of such tools is the Rule Log that shows in detail what is

going on in the system. Another tool that can be extremely useful is the Rule Debugger.

The Rule Debugger is very similar to debuggers used to debug code, written in some

programming language. The idea is that you can set one or more “breakpoints” on the

lines of your code and the system “stops” when execution reaches the breakpoint. At

this point you can inspect the data – local and global variables and so on. You can then

continue one line at a time and see how your lines of code get executed.

In the Aware IM Rule Debugger you can set breakpoints on business rules wherever

those rules are used - for example, rules of a process, rules of a business object,

notification and so on. Whenever Aware IM executes these rules the system will stop

and show you the current Context, the stack and the log up to this point. You can set

Aware IM 8.8 User Guide

breakpoints not only on rules but on actions of the rules. The Rue Debugger is explained

in detail in this video tutorial.

Configuration of Rules

The configuration process for business rules is described in detail in the Adding/Editing

Rules section.

Productivity Features

In the previous sections we described in detail how Aware IM implements the generic

aspects of a data management application, such as data entry and editing, data storage,

data retrieval, data processing and the user interface (see Basic Concepts). In the

following section we will describe how Aware IM implements some other features that

most applications are likely to require.

See:

Access Control

Working with Documents and Reports

Communication with Other Systems

Scheduling

E-mail Handling

Export and Import

Extending Aware IM

Performance Profiler

Access Control

One of the issues that most applications have to deal with is security. A system has to

make sure that sensitive data is only available to those users who are authorized to view

and operate this data. The system therefore has to control access to this data. The

following section describes how access control issues are implemented in Aware IM.

See also:

Business Space Versions and Version Control

Productivity Features

Testing Mode

Working with Aware IM in Hosting Environment

Configuration Guidelines

Business Space Versions and Version Control

To configure an application is to configure a business space. At the end of the day it is

the business space that must contain all the configuration elements – business objects,

business rules, processes etc. The default business space is created during Aware IM

installation (see the “Aware IM Installation Guide”). This business space is usually the

one that represents the application.

Application configuration is not a trivial process – it involves detailed preparation as the

configurator has to collect and analyse requirements of the system and think how these

requirements are translated into business objects, business rules etc, and it usually

evolves over time as new requirements and new business rules appear or old

requirements are changed or become irrelevant.

To help manage changes of a business space Aware IM includes a built-in version

control mechanism. It allows configurators to make and test changes to a business

space without affecting the normal operation of the system. When a change to a

Aware IM 8.8 User Guide

business space needs to be made a new business space version must be created and

the change must be made in that version. Thus all elements of a configuration are

always contained within some business space version.

With the version control mechanism configurators can also keep track of changes made

to the application over time. For example, one can find out which rules and processes

were in effect at a particular date and time or what specific information was being

registered by the system by inspecting a particular business space version that was

current at that time.

Some business space versions are treated differently from others. This treatment is

based on their state – this is explained below.

Most business versions undergo the following lifecycle:

1. The version is created (either as a blank version or from some base version – see

Major and Minor Versions) in the NEW state. The configurator makes changes to the

version by creating or making modifications to the configuration elements, such as

business objects, business rules etc

2. Once the configurator is happy with the version she makes it available for testing and

the state of the version becomes UNDER TEST (see Testing Business Space

Version). At this moment the configurator can test the version in the Operation Mode

to verify that the changes work as expected. Aware IM keeps the version being

tested separately from the current operating version, so the testing is not going to

disrupt operation activities (see Testing Mode). If testing discovers that more

changes need to be made to the version the version is moved back to the NEW state

and step 2 is repeated.

3. Once the configurator is satisfied with the version she makes it operational (see

Publishing Business Space Version). Aware IM makes any necessary adjustments

and starts using the updated configuration information in the operation mode. The

state of the version becomes CURRENT.

4. When some other version is made operational the version becomes OBSOLETE. It

can be deleted or kept for historical purposes. It is also possible to return to the

obsolete version and make it operational again if for whatever reason the new

version has been proven not satisfactory.

See also Lifecycle of a Business Space Version.

Aware IM 8.8 User Guide

Productivity Features

Aware IM offers a number of productivity features that help configurators work with

business space versions:

- A business space version can be exported to, or imported from a file, so that

configurations can be shared (see Exporting Business Space Version and Importing

Business Space Version). This makes it possible to prepare configuration templates

for others to use.

- A business space version in the CURRENT or UNDER TEST state must be consistent,

i.e. it must not have invalid rules, references to non-existent business objects etc.

Aware IM performs rigorous checks of the validity of the version’s elements before

the version is made operational or made available for testing. This process is called

integrity checking – see Checking Version Integrity.

- On configurator’s request Aware IM can generate documentation for a particular

version. This documentation has the names, properties and descriptions of all

elements in the version (business objects, business rules, processes etc) in the

format that can be easily viewed or printed. The documentation is an entirely

separate structure and no access to Aware IM software is required to view it. The

documentation can be used for reference and/or audit purposes. See also

Generating Documentation.

Testing Mode

As described in the Business Space Versions and Version Control section a business

space version can be put under test to verify that the version works as expected before

making the version operational.

To test the business space version the configurator has to log into the system in the

Operation Mode using the URL described in the Login section. The screen displayed by

Aware IM includes the “Testing Mode” check box – this checkbox needs to be ticked to

indicate that Aware IM should operate in the testing mode.

Using the application in the Operation Testing Mode is very similar to using the

application in the regular Operation Mode. The main difference is that the operation data

created when the application works in the Operation Testing Mode is stored in a

completely separate database, so that the main data of the system is not affected by any

operations performed in the testing mode. There are also some other relatively minor

differences that are summarized below:

1. Users with the “Guest” access level (see Predefined Access Levels) cannot log into

the system in the testing mode. If one wants to test the “Guest” access level while

working in the testing mode the following can be done:

a. Log in as administrator into the testing mode as described above.

Aware IM 8.8 User Guide

b. Create a new instance of the RegularUser object and set the value of its

AccessLevel attribute to ‘Guest’

c. Logout and login as the newly created user.

2. Menu item of the “Login” type will attempt to login the user into the regular mode, not

the testing mode.

3. Menu item of the “Register User” type: when the user completes registration the

system automatically logs in the user into the regular mode of the same business

space using the newly entered login name and password.

4. If a business space version is configured to process incoming e-mails (see E-mail

Handling) it will periodically check the specified mailbox on the mail server, whether

in the regular or testing mode. Therefore, if there is an operational version in the

regular mode and the one in the testing mode that are both configured to receive e-

mails from the same source they will compete for incoming e-mails. As a result new

incoming e-mails can end up in either regular or testing version. To avoid this

situation, change the version to be put under test to use an alternative mailbox.

5. It is not possible to save newly built queries in the testing mode (see Building

Queries in the Operation Mode).

Working with Aware IM in Hosting Environment

The main components of the Aware IM software are the Aware IM Server and the

Configuration Tool. Aware IM Server is the core component of the software that stores

configuration and operational data and executes processes and business rules, whereas

the Configuration Tool provides the functionality that allows configurators to define

business objects, processes, business rules and other elements of an application.

Normally the Configuration Tool works in tandem with the Aware IM Server – the

changes to the configuration data performed in the Configuration Tool are stored on the

Aware IM Server and vice versa – the Configuration Tool obtains the initial configuration

data from the Aware IM Server (see also Configuration Process). This makes it possible

to store and update the configuration information in one repository managed by the

Aware IM Server.

Aware IM allows users to access their business space in the Operation Mode from any

location via the Internet using a standard Web browser. This requires the Aware IM

Server to be installed on a computer that has a permanent connection to the Internet

with sufficient speed and bandwidth. The users who do not have a suitable Internet

connection can run the Aware IM Server on a remote computer managed by an Internet

hosting service provider (this set-up is called a hosting environment – see also “Aware

IM Installation Guide”). Users who only need to access their application within a single

location do not need a hosting environment.

In the hosting environment the Configuration Tool is unable to work with the Aware IM

Server directly. However, one can prepare and test configurations on the local machine

Aware IM 8.8 User Guide

and then export the configuration into a BSV file. Once saved to a file the configuration

information can then be uploaded to the remote Aware IM Server from the user interface

of the Operation Mode.

In order to upload the configuration file to the Aware IM Server the system has to be

configured to include the menu item of the “Publish Business Space Version” type (see

Setting Menu Item Properties). When the user selects this menu item in the Operation

Mode Aware IM displays a form where the user can specify the configuration file and

provide the description of the changes. When the user submits the form the version is

uploaded to the Aware IM Server and becomes operational (at this point Aware IM also

performs the usual checks of the version to make sure that it is consistent – see

Checking Version Integrity).

A few other features that can be very helpful for users that need to operate with the

remote Aware IM Server can also be configured:

- Operation of the “List Business Space Versions” type shows all business space

versions available on the server in the Operation Mode. One can view the properties

of the versions and delete them if necessary. This is like having a bit of functionality

of the Configuration Tool in the Operation Mode

- Operation of the “Create Business Space” type allows creating a new business

space in the Operation Mode. The functionality is equivalent to the similar

functionality in the Configuration Tool. A system of an Internet host may include this

operation to allow their users to create their own business space and work in it.

Configuration Guidelines

See:

Configuration steps

Configuration principles

Configuration steps

This section describes the recommended sequence in which configuration elements

should be defined when configuring a new application.

See:

Business objects

Business object rules

Processes

User interface

Business objects

Business objects are the central elements of any Aware IM-based application. None of

the other elements would be of any use without business objects. It is therefore

Aware IM 8.8 User Guide

important to start working on an application by configuring objects of the business

environment for which the application is being created.

Which objects need to be configured depends entirely on the nature of the business.

You can, therefore, start by identifying the business elements that people deal with as

part of their day-to-day activities.

See section Business Objects as Carriers of Data for general description of business

objects. See section Configuration principles for recommendations on configuring

business objects and object groups.

Business object rules

Once you have created your business objects you can start attaching rules to the

objects. All data processing in Aware IM is done by object rules. Such rules can find,

create or delete objects, perform initialisation, validation and calculation operations,

communicate with other software systems or people, etc.

Rules are found everywhere in a business environment. You need to identify the rules

that are applicable to your application and attach them to the appropriate objects. Some

rules may be well-known and easy to spot. For example:

- No account can be open for a person under 16 years old.

- Once a transaction is approved its amount cannot be changed.

- If an item is not returned to the library by due date a reminder e-mail is sent to the

borrower.

Other rules can be found by inspecting processes and procedures performed by people

in the course of their day-to-day activities. You would need to break these procedures

into steps and configure each step as one or more rules attached to one or more

business objects.

To configure effective object rules it is essential to understand how rules work in

Aware IM. See section Business Rules as Carriers of Business Logic for introduction

into object rules, Data Processing for detailed explanation of rule processing,

Configuration principles on important guidelines on configuring object rules.

Processes

Now, that you have the business objects and object rules that handle information

processing, you can add processes to provide a convenient way of making and handling

incoming requests for information or operations. See section Processes as Links

between User Interface and Business Logic for details on the purpose and use of

processes.

To make it easier for the users to perform an operation that applies to a particular object

you can configure a process that takes that particular object as its input. For example, a

Aware IM 8.8 User Guide

transaction approval operation can be configured as a process ApproveTransaction

that takes Transaction object as its input and contains the following two rules:

– Transaction.State=’Approved’

– DISPLAY MESSAGE ‘Transaction has been completed’

Processes with a single object as their input will be available for users to start on the

corresponding object forms. Therefore, rather than having to manually change the state

of a pending transaction and submit the form, the authorized user can simply choose

process ApproveTransaction on the transaction object form.

You can also define processes with no input objects, which are useful for creating new

objects or performing other operations that do not require selecting a particular single

object upfront. Such processes can be made available to the users as operations via the

main menu of the system. For example, an account opening process could be

configured as follows:

– ENTER NEW Account

– PRINT DOCUMENT AccountOpeningLetter

– VIEW Account

Remember that processes should not be configured to process information. This is a job

for object rules – see Configuration principles for more details.

User interface

When you configure a new application Aware IM provides the default interface for the

users of the application. This includes the main menu with a set of generic operations

allowing the users to search for business objects in the system, create new objects or

documents and perform some other actions. For each of the business objects you

configure Aware IM generates the default object form to allow the users to edit the

object. There are several steps you can take to enhance and fine-tune the user access

to the system.

First, inspect the auto-generated object forms. With very little effort you can adjust the

forms by selecting the attributes to appear on forms. For complex objects with many

attributes you can split the form into several sections and select the attributes for each of

the sections. If you have configured processes to start operations that are applicable to

particular objects, such operations will be available on the object form for the users to

start, making the system easier for people to use.

The main menu of the system the users see when they log into the system can also be

easily customized. You can hide the generic actions from the menu and add specific

operations such as finding customers, creating accounts, registering members, etc. To

initiate such specific operations you can define queries looking for particular objects

matching the search criteria entered by the users. You can also attach to the menu the

Aware IM 8.8 User Guide

no-input processes, as described in the previous section, to let the user perform

operations.

If you want the object information to appear differently to users of different categories

you can define additional access levels and specify the information and operations

available to users of each level. Aware IM will adjust object forms and the main menu

accordingly. In addition, you can configure different object forms and different visual

perspectives, which include the main menu and other visual settings, for different access

levels. This gives you more options of controlling the way the users work with the

system.

Configuration principles

This section contains several key recommendations on configuring Aware IM

applications. The rationale behind these recommendations is to help creating

applications that have fewer elements, easier to understand and, most critically, easier

to maintain. People familiar with development of data management applications may find

some of the recommendations familiar and obvious. Certain things, however, are done

differently in Aware IM compared to traditional development tools. This is why reading

these guidelines would be beneficial for experienced developers as well.

The recommendations of this section describe the general principles of configuring

applications.

Business objects represent elements of business environment

Business object groups unite dissimilar objects

Object rules perform all information processing

Object rules are self-contained

Object rules are attached to the right objects

Business objects represent elements of business environment

It is very important that each object you configure represents some real element of the

business, not just an arbitrary collection of data. Systems having objects with unclear

purpose and processing logic are difficult to operate and maintain.

Examples of legitimate business objects, commonly found in many business

organizations, could be customers (clients, members, etc.), accounts (contracts,

policies, etc.), orders, fees, payments, etc. They would have attributes and rules clearly

identifiable from day-to-day business activities.

Business object groups unite dissimilar objects

Use a business object group only when the objects in the group cannot be configured as

a single object. Unnecessarily creating several similar objects will lead to duplicating of

configuration information such as attributes and rules. Whenever the configuration of

one of such objects needs to be changed, other similar objects are likely to require the

same change.

Aware IM 8.8 User Guide

You need to configure business elements of similar nature as separate objects, as

opposed to a single object, when:

- Attributes of one of the objects are not applicable to other objects and should not be

displayed on an object form for the other objects.

- Different processing logic applies to different objects. There would be too many rules

for one object and they would become too complicated because of the differences.

For example, different forms of customer communication such as email, telephone call,

fax or traditional letter, have to be configured as separate objects because of the

different way the message information is stored and presented to the user. Withdrawal

and deposit transactions, while both being financial transactions applicable to accounts,

have to be configured separately because of different processing rules that apply to the

transactions.

When objects differ only to a minor extent the difference may be covered by an attribute

in a single object. For example, a library catalogue may contain items of different types

such as books, videos, CDs, etc. Other attributes such as title, author, description, or

catalogue number would be identical. Therefore, a single LibraryItem object may be

configured that has an additional attribute representing the item type.

Object rules perform all information processing

All essential processing logic in the system should be specified as individual rules

attached to applicable objects, not processes. There are two important reasons for this

principle.

Reason 1. There may be many scenarios causing a change to an object. If the

processing logic is spread across various scenarios, any change to the logic needs to be

propagated throughout the scenarios. With the object rules approach, for each object

you specify all rules that make sense from that particular object point of view. None of

these rules are duplicated anywhere else in the system.

For example, Aware IM will automatically evaluate the following validation rule on

account whether a new holder is linked to the account, or the existing holder’s age is

changed:

If Account.Holder.Age < 16

Then REPORT ERROR ‘Account holder must be 16 years old or

over’

Reason 2. Object rules are independent from each other and therefore allow configuring

each step in multi-step procedures separately from other steps. A really complex

procedure would be difficult to configure as a single process because of multiple

conditional, parallel or overlapping steps it may contain.

Aware IM 8.8 User Guide

Let us consider an example of a withdrawal transaction, which requires an approval by

an authorised person if the withdrawal amount exceeds 5000. Before the transaction is

approved all necessary validation checks should be made. After the approval the

account balance should be updated accordingly.

We will first demonstrate how this procedure can be implemented by object rules. We

configure WithdrawalTransaction object with its State attribute initialised to ‘New’.

We then attach a pre-approval validation rule to the object:

If WithdrawalTransaction.State = ‘New’ AND

WithdrawalTransaction.Account.Balance <

ABS(WithdrawalTransaction.Amount)

Then REPORT ERROR ‘Insufficient funds on account’

In a similar manner we could attach all other validation rules as necessary. Next, we

need to see if the transaction can be approved automatically, which is done by attaching

the following rule to WithdrawalTransaction:

If WithdrawalTransaction.State = ‘New’ AND

ABS(WithdrawalTransaction.Amount) < 5000

Then WithdrawalTransaction.State = ‘Approved’

If the transaction amount is larger the transaction will wait for manual approval (or

rejection) by an authorized person. The manual approval will change its state to

‘Approved’ signalling the start of the second step in the processing of the transaction,

namely the updating of the account balance. This can be done by attaching the following

rule to Account object (note that Transaction here is a name of object group that

has WithdrawalTransaction as well as objects for other transaction types as its

members):

Account.Balance = SUM Transaction.Amount WHERE

(Transaction IN Account.Transactions AND

Transaction.State = ‘Approved’)

Let us now see how the same procedure could be configured using processes, a more

traditional approach, which is not recommended for use in Aware IM. We would need

two processes. The first is called EnterTransaction and contains the following

sequential rules:

– ENTER NEW WithdrawalTransaction WITH

WithdrawalTransaction.Account = Account

– If ABS(WithdrawalTransaction.Amount) < 5000 Then

WithdrawalTransaction.State = ‘Approved’

REDUCE Account.Balance BY

ABS(WithdrawalTransaction.Amount)

Aware IM 8.8 User Guide

The second process is called ApproveTransaction and used by an authorised

person to complete pending transactions. It contains the following rules:

– WithdrawalTransaction.State = ‘Approved’

– REDUCE Account.Balance BY

ABS(WithdrawalTransaction.Amount)

What is wrong with these processes? Several things:

1. The rule updating the account balance is duplicated in both processes. All other

similar processes, configured to handle other transaction types, would also have to

include a step updating the account balance. Compare this with the object rules

approach where there is only one rule on the Account object that updates the

balance whenever a new transaction is applied.

2. Transaction processing logic is entangled with the user interface step that allows the

user to enter the transaction details. If the transaction needed to be created without

the user input, for example as a part of a funds transfer transaction, the validation

and calculation rules would have to be duplicated in the transfer process.

3. If the logic of updating account balance needs to be changed, the change would

need to be propagated throughout all the processes configured in the system that

update account balance.

Object rules are self-contained

Each individual rule attached to an object should be self-explanatory and independent of

other rules. In other words, it should include all necessary conditions to clearly specify

when the rule action should be executed. There are two important reasons for this

principle.

Reason 1. If specific conditions for the rule action are not defined, the action can be

executed at the wrong time leading to the wrong results.

Reason 2. A rule cannot depend on execution of actions of other rules since the order in

which object rules are executed is not defined.

For example, the following rule initialises the account address with a default value. Once

the address is given the rule action will not be executed again:

If Account.Address IS UNDEFINED

Then Account.Address = Account.Holder.Address

If we removed the condition the rule would execute every time the Account object is

changed, thereby overwriting the address manually entered by the user.

In another example the rule below ensures that the transaction amount cannot be

changed once the transaction is completed. If the condition were removed the system

would not allow changing the amount at any time, including the initial entry of the

transaction details:

Aware IM 8.8 User Guide

If Transaction.State = ‘Approved’

Then PROTECT Transaction.Amount FROM ALL

Let us consider yet another example in which the final action is determined by several

possibly dependent events or facts. There may be a requirement to notify the library

member when an item the member reserved is returned to the library. If the e-mail

address of the member is known the member is notified by e-mail, otherwise a letter is

posted to the member. These requirements are implemented in Aware IM by two self-

contained and independent rules attached to the Reservation object:

Rule 1:

If Reservation.Status WAS CHANGED TO ‘Offered’

AND Reservation.Member.EmailAddress IS DEFINED

Then SEND ReservaitonOfferEmail TO Reservation.Member

Rule 2:

If Reservation.Status WAS CHANGED TO ‘Offered’

AND Reservation.Member.EmailAddress IS UNDEFINED

Then PRINT DOCUMENT ReservaitonLetter

Object rules are attached to the right objects

A rule attached to an object should specify the logic that applies to that object, not other

objects. In particular, a rule that modifies an attribute of an object should be attached to

the object to which the attribute belongs. There are two important reasons for this

principle.

Reason 1. The right rule attached to the wrong object will lead to the wrong results.

Reason 2. When you need to make a change to an object configuration you will see all

relevant rules in one place. You will not need to search through the system to see what

other object rules can make a change to the object and when. This may also help

reducing the number of similar rules, which will further simplify the system.

Let us illustrate this principle with examples. Consider a validation rule that a person

must be 16 or over to be an account holder. This rule should be attached to the

Account object and can be specified as follows:

If Account.Holder.Age < 16

Then REPORT ERROR ‘Account holder must be 16 years old or

over’

However, the same rule attached to the Person object would have a very different

meaning:

If Person.Age < 16

Aware IM 8.8 User Guide

Then REPORT ERROR ‘Account holder must be 16 years old or

over’

This is because the latter rule would essentially state that no person under 16 can be

registered in the system, whether to be an account holder or for any other purpose.

While this may very well be another business rule on its own right, it is definitely not

what the original rule was meant to specify.

As for the object-modifying rules, consider an example when an account balance is

updated following a financial transaction applied to the account. A rule on the

transaction could update the account balance:

If Transaction.State WAS CHANGED TO ‘Approved’

Then INCREASE Transaction.Account.Balance BY

Transaction.Amount

Now suppose that there are a number of transactions in the system, each represented

by a separate object. The above rule would have to be configured, essentially

duplicated, for each specific transaction object. The correct way of updating the account

balance, and also a safer one, would be for the account to update its own balance

following the addition of a new transaction. This is done by attaching the following rule to

Account object:

Account.Balance = SUM Transaction.Amount WHERE

(Transaction IN Account.Transactions AND

Transaction.State = ‘Approved’)

Note that Aware IM will execute the above rule whenever any of the account details

change, including the transaction list, or the state of a transaction, that is already in the

list, changes. We can be more specific and state that the balance should be updated

only when the transaction list changes (i.e. a new transaction is added), but not when

other account details change. Then we would need to add a corresponding condition to

the above rule:

If Account.Transactions WAS CHANGED

Then Account.Balance = SUM FinancialTransaction.Amount WHERE

(FinancialTransaction IN Account.Transactions AND

FinancialTransaction.State = ‘Approved’)

In this case, however, we should also remember to update the balance when a pending

transaction is approved, which can be done by adding the following rule to Account:

If Transaction FROM Account.Transactions WAS CHANGED

AND ChangedTransaction.State WAS CHANGED TO ‘Approved’

Then Account.Balance = SUM FinancialTransaction.Amount WHERE

(FinancialTransaction IN Account.Transactions AND

Aware IM 8.8 User Guide

FinancialTransaction.State = ‘Approved’)

Aware IM 8.8 User Guide

Configuring Applications

Overview of the Configuration Tool

Applications are configured in the Configuration Tool. The screen area of the

Configuration Tool is divided into several regions:

 Elements Tree (red)

 Working Area. (orange)

 Main Element Properties (green)

 Selection Properties (blue)

 Additional Windows (yellow)

The Elements Tree contains the configured elements presented as a hierarchical tree

structure. Right clicking on a tree node brings up a pop-up menu specific to the selected

element. Most elements provide the New and Open commands in their pop-up menus

that allow adding new elements or editing the existing ones. Once the user selects the

New or Open command from a pop-up menu the editor corresponding to the selected

element appears in the Working Area. The user can then enter properties of the new

element or change properties of the existing element using the controls of the editor.

You can also edit an existing element by double clicking on it.

It is possible to enter/edit properties of several elements at the same time – the editors

are displayed as different tabs and it is possible to switch between editors by clicking on

the corresponding tab. See also Adding Element, Editing Element.

The “Main Element Properties window” contains a list of properties of the element being

edited – for example, a business object. The “Selection Properties” window shows the

properties of the selected sub-element that belongs to the main element. For example,

an attribute of the business object being edited.

The “Additional Windows” area contains some other windows – for example, results of

search and a list of integrity problems of the business space version.

Note that most windows can be moved around the screen, so that the user can re-

arrange them the way it suits him/her.

The screen of the Configuration Tool also contains the main menu and the toolbar that

allows performing frequently used operations.

Aware IM 8.8 User Guide

Configuration elements of an application are contained in business space versions;

business space versions exist in a business space. After the initial installation the

Configuration Tool contains one business space with two business space versions

(which have some pre-defined elements). One of these versions is in the NEW state and

is ready for modifications. Configuration work usually begins with configuring business

space-specific elements in this version – see Working with Business Space Versions.

Working with Business Space Versions

Business objects, rules, processes and other elements of the system belong to a

business space. A business space may have a number of business space versions,

each containing different versions of the elements that you configure. The following

section explains the life cycle of a business space version and the steps required to

create and edit the version.

Lifecycle of a Business Space Version

Creating Minor Version

Creating Major Version

Updating Business Space Version

Loading Business Space Version

Aware IM 8.8 User Guide

Checking Version Integrity

Testing Business Space Version

Publishing Business Space Version

Deleting Business Space Version

Viewing Version Properties and History

Exporting Business Space Version

Importing Business Space Version

Lifecycle of a Business Space Version

As work on the configuration of the application evolves the business space version

undergoes certain stages in its lifecycle.

Business space version in the NEW state.

When a business space version is initially created its state is always NEW. A version in a

NEW state may not be deployed for the end users nor can it be tested. It exists purely as

the working version of the configurator. The Configuration Tool displays the business

version in the NEW state in green. Once the configurator is happy with the contents of the

version she can make the version available for testing (or even publish it straight away,

although publishing without testing is strongly discouraged) – see Testing Business

Space Version.

Business space version in the UNDER TEST state.

Once the version has been made available for testing its state becomes UNDER TEST. A

version in this state can be tested by the configurator in the Operation Mode (see

Testing Mode). The purpose of testing is to ascertain that the configured system works

as expected. The operation data created during testing is stored in a separate database

and does not affect operation data of the end users. There may only be one business

space version in the UNDER TEST state in a business space – if there is already a

version in the UNDER TEST state it will move back to the NEW state after a new version

has been made available for testing.The Configuration Tool displays business space

versions in the UNDER TEST state in pink.

Business space version in the CURRENT state.

If the configurator finds some problems with the version during testing, she can start

editing the version under test (which moves the version to the NEW state) or create a

new minor or major version (see Creating Minor Version and Creating Major Version)

from the version being tested, correct errors in this new version and then make the new

version available for further testing. Once the configurator is finally happy with the

version she can publish (deploy) it so that it can be used by the end users (see

Publishing Business Space Version). When the version is published its state becomes

CURRENT. There may only be one version in the CURRENT state in a business space. If

there is already a CURRENT version it is moved to the OBSOLETE state after the new

version has been published.

Aware IM 8.8 User Guide

Once the version has been published it may not be changed by anyone. If further

changes to the version are required a new major or minor version may be created from

the current version and the changes may be introduced in this new version.

The Configuration Tool displays business space versions in the CURRENT state in black.

Business space version in the OBSOLETE state.

A business space version currently used by the end users is made obsolete when the

configurator publishes a new version. The new version moves to the CURRENT state and

the previously used version is moved to the OBSOLETE state. A version in this state may

not be modified, however, it can be published again (if for whatever reason the

configurator decides to go back to the old version). It is also possible to create a new

minor or major version from the OBSOLETE version and then make changes to the new

version (see Creating Minor Version and Creating Major Version). The Configuration

Tool displays a version in the OBSOLETE state in grey.

Business space version in the IN DEVELOPMENT state.

A version in this state indicates that the business space is running in a multi-

developer mode when several developers are working on the same business space

version concurrently. For more details about the multi-developer mode please watch the

Milti-Developer Mode video tutorial. The Configuration Tool displays business space

versions in the IN DEVELOPMENT state in orange.

Major and Minor Versions

Each business space version has a number associated with it that uniquely identifies the

version within a business space. This number has the format “n.m” where “n” is the

number identifying the major version and “m” is the number identifying the minor version.

Major versions usually represent big steps forward compared to the previous version,

whereas minor versions usually contain small modifications to the previous version. This

is, however, entirely up to the configurator to decide whether the new version will be

major or minor.

Creating Minor Version

Creating Major Version

Creating Minor Version

A new minor version is always created from some existing base version. When a new

minor version is created the entire contents of the base version is copied into the new

version and the new version is assigned a new number being an increment of the

maximum minor version number used already. The new version is created in the NEW

state – see Lifecycle of a Business Space Version.

Aware IM 8.8 User Guide

To create a new minor version:

1. Click on the base version in the Elements Tree to select it.

2. Select “Version/New Minor Version” in the menu or right click to bring up the pop-up

menu and select “New Minor Version”. The new version must appear in the Elements

Tree.

3. The Configuration Tool will bring up a dialog where you can enter any comments

about the new version being created and the press the OK button. Alternatively press

the Cancel button if you do not want to enter any comments.

Creating Major Version

A new major version can either be created from some existing base version or from a

blank version. When a new major version is created from a base version the entire

contents of the base version is copied into the new version. When a new version is

created from a blank version the version only contains pre-defined elements (such as

the RegularUser business object) and nothing else. The number of a major version

assigned to a new version is the increment of the maximum version number used

already. The new version is created in the NEW state – see Lifecycle of a Business

Space Version.

To create a new major version from the existing version:

1. Select “Version/New Major Version” in the menu or right click on the base version in

the Elements Tree to bring up the pop-up menu and select New Major Version. The

new version will appear in the Elements Tree.

2. The Configuration Tool will bring up a dialog where you can enter any comments

about the new version being created and the press the OK button. Alternatively press

the Cancel button if you do not want to enter any comments.

Loading Business Space Version

When the Configuration Tool starts up it does not load the contents of some versions for

efficiency reasons. When such versions are displayed in the Elements Tree the tree only

shows version number and state – there is no little “plus” sign next to the version to

indicate that the contents of the version have been loaded from the server. If you want to

view and/or change the elements of such a version you have to load its contents from

the server.

To load a business space version:

1. Click on the node displaying version number and state in the Elements Tree to select

it.

Aware IM 8.8 User Guide

2. Select “Version/Load Version” in the menu or right click to bring up the pop-up menu

and select “Load Version”. Once the version is loaded a little “plus” sign is displayed

next to its node in the Elements Tree. You can now expand the node and

view/change its contents.

Updating Business Space Version

Any changes to a business space version have to be saved to the Aware IM server. If

you do not update the version data on the server your configuration changes will be lost

when you close the Configuration Tool (unless you export the version to a file and then

import it back next time you start the Configuration Tool – see Exporting Business Space

Version and Importing Business Space Version).

To update the version:

1. Click on the version you want to update in the Elements Tree to select it

2. Select “Version/Update” in the menu or right click to bring up the pop-up menu and

select “Update”.

Checking Version Integrity

A business space version being published or made available for testing must be

consistent, i.e. must not have invalid rules, references to non-existent business objects

etc. The Configuration Tool performs rigorous checks of the validity of the version’s

elements when they are being created and/or edited. However, such checks are not

made when significant modifications to the version elements are taking place and

elements are being deleted and replaced. In this scenario it is easy to overlook a

reference to an obsolete element.

To make sure that the version is consistent the Configuration Tool always checks the

integrity of the version when it is being published or made available for testing. The

Configuration Tool will not allow publishing or testing an inconsistent version. If a version

is inconsistent the Configuration Tool displays a list of the version’s problems and does

not proceed with publishing or testing. It is also possible at any time to check the

integrity of the version irrespective of the state it is in.

To check version integrity:

1. Click on the version that you want to check in the Elements Tree to select it.

2. Select “Version/Check Integrity” in the menu or right click to bring up the pop-up

menu and select “Check Integrity”. A list of the problems from the last time you ran

the integrity check will be shown in the “Problems” window (the list is empty if

integrity is being checked for the first time).

Aware IM 8.8 User Guide

If a version has integrity problems the Configuration Tool will display a list where each

entry in the list contains the description of the problem. You can double click on the entry

to bring up the editor that will allow you to fix the problem.

TIP: If a problem is inside a report or presentation the integrity checker will tell you

which report or presentation has a problem but it will not take you directly to the

problem. You can open the report or presentation manually and find the offending

element using the Find Design Element feature of the Report/Presentation Designer –

see Find Design Element.

Testing Business Space Version

Once you are happy with your changes to the business space version you can make the

version available for testing. You may need to test the version in order to make sure that

your business rules and processes work as expected, presentations and reports look

good etc. It is recommended that you always test your version prior to publishing it for

the end users. Once the version has been made available for testing its state changes to

UNDER TEST, and you can now try creating instances of different business objects from

this version, run processes, reports etc in the Operation Mode (see Testing Mode).

Instances of objects created during testing are stored in a separate database so the

operational data of the end users is not affected by any testing activity – see also

Lifecycle of a Business Space Version.

To make a version available for testing:

1. Click on the version you want to test in the Elements Tree to select it (make sure that

the version is loaded – see Loading Business Space Version).

2. Select “Version/Put under Test” in the menu or right click to bring up the pop-up

menu and select “Put under Test”.

3. If you already have a version in this business space in the UNDER TEST state, you

will be offered a choice of whether to copy the operation data from the existing test

version or create the test version with no operational data at all. If you already had

some test instances of business objects from the previous rounds of testing it may be

helpful to use the same instances during the new round. Once you select the

required option the version will be moved to the UNDER TEST state (this may take

some time) and displayed in pink.

If your business space version has already been in the UNDER TEST state before

Aware IM will display a dialog asking you whether to perform integrity checking of the

version and whether to use the existing data for testing or clear the testing data. If you

are going through many testing cycles during development and put version in and out of

testing many times then constantly answering the questions of this dialog can be

tedious. To avoid the dialog and to get Aware IM to use the default values (no integrity

Aware IM 8.8 User Guide

checking and using the existing data for testing) you can use the “Put under Test

(quickly)” command available in the main menu or in the popup menu instead of the “Put

under Test” command. You can also use the Ctrl+Q shortcut to make it even quicker.

Embedded Testing

“Embedded testing” allows you to test your business space version not in the standalone

browser but in the browser embedded in the Configuration Tool. A separate tab in the

Working Area of the screen is opened and the default browser is started inside this

window. An advantage of using embedded testing is that you can not only test the

version in the UNDER TEST state but you can also test the version you are currently

editing (which is in the NEW state) provided that this version is based on some version in

the UNDER TEST state.

The rationale for embedded testing is to free the developer from constantly putting the

version under test and then editing it again in order to make further changes. With

embedded testing you can perform changes to the version and test it in the embedded

browser straight away. You can have the embedded browser open and once you make

your changes you can continue working with the browser, which should automatically

pick up the changes you made

Not all changes, however, are allowed if you want to continue working with the

embedded browser. If you make changes that affect the database structure (such as,

add, delete or rename an attribute of a business object) or if you make changes to a

document template you won’t be able to continue with the embedded browser – it will

automatically close and you will have to put your version under test and start a new

testing session.

To start embedded testing select the version you want to test (it can be in the UNDER

TEST state or in the NEW state) and then select “Version/Start Embedded Browser” in

the menu or right click and select “Start Embedded Browser” from a popup menu. This

will open the embedded browser for the selected version in a separate window. If you

already have this browser open you can just switch to this window and the browser will

automatically pick up your changes.

Publishing Business Space Version

Once a business space version has been tested and you are happy with how your

business rules and processes work, the business space version can be published.

Publishing business space version makes it available to the end users. The version is

moved into the CURRENT state – see also Lifecycle of a Business Space Version.

Aware IM 8.8 User Guide

If you already have a version in the CURRENT state it is recommended that you publish

the new version when no one is using the old version in the Operation Mode. Aware IM

will not proceed with publishing of the new version until there is no user activity with the

old version, so if the old version is being heavily used Aware IM will keep waiting until

there is a break in the old version usage. Once the new version has been published any

current users of the old version will not be able to use the old version any more – they

will be advised to log out and log into the new version.

It is also highly recommended that you back up your existing operation data

before publishing the version – see Backing up Operation Data.

Publishing business space version is a complicated process – in particular, if any new

business objects have been defined in the version being published or definitions of the

existing business objects have been changed, Aware IM will build and/or alter the

corresponding database tables.

CAUTION: If there is already operational data created by the end users while working

with the previous versions, publishing a new version may destroy this data if changes to

the business object in the new version are such that it is not possible to preserve the

existing data – for example, if a definition of a business object has been deleted, all

instances of the business object are lost. Similarly if some attribute of a business object

has been deleted, the existing data corresponding to this attribute is lost. Aware IM does

everything it can to preserve the existing data whenever possible (for example, when an

attribute type is changed) and the Configuration Tool warns the user immediately if the

configurator’s changes lead to any loss of data – see also Adding/Editing Business

Objects.

To publish a business space version:

1. Make sure that the version you want to publish is loaded – see Loading Business

Space Version.

2. Click on the business space version you want to publish in the Elements Tree to

select it (the version must be in either the UNDER TEST, OBSOLETE or NEW state)

3. Select the “Version/Publish” command in the menu or right click to bring up the pop-

up menu and select “Publish”. The version will be moved to the CURRENT state (this

may take some time) and displayed in black.

NOTE: before a version is moved to the CURRENT state the integrity checking of the

version is performed. If the version has any integrity problems it will not be published,

instead the list of integrity problems will be displayed – see Checking Version Integrity.

Aware IM 8.8 User Guide

Working with a Business Space Version in a Multi-Developer

Mode

Several developers can work on the same business space version concurrently (this is

called a “multi-developer mode”). In this mode developers lock (check-out) those

elements of the version that they are working on (business objects, queries, processes

etc). To make changes to the version they have to check-in their changes. To start the

multi-developer mode a system administrator has to “put a business space version in

development”. To do this:

1. Click on the business space version you want to put in development in the Elements

Tree to select it

2. Select the “Version/Put In Development” command from the menu or right click to

bring up the pop-up menu and select “Put In Development”.

For more details about the multi-developer mode please watch the Milti-Developer Mode

video tutorial.

Deleting Business Space Version

To delete a business space version:

1. Click on the business space version you want to publish in the Elements Tree to

select it

2. Select the “Edit/Delete” command from the menu or right click to bring up the pop-up

menu and select “Delete”.

NOTE: a business space version in the CURRENT state cannot be deleted.

CAUTION: Deleting a business space version is not an undoable operation; so once

deleted the business space version cannot be recovered. Make sure that you only delete

those versions that you no longer need.

Viewing Properties and History of the Business Space

Version

To view business space version properties and history of changes:

1. Double click on the business space version you want to view in the Elements Tree to

edit it.

2. The Working Area of the screen will show the details of the selected version:

a. The name of the business space to which the version belongs.

Aware IM 8.8 User Guide

b. The state of the version.

c. Version number.

d. The description of the version.

The “History of Changes” section will show what has been done to the version before. In

particular:

a. When a version has been created.

b. When a version has been updated on the server.

c. When a version state has been changed.

d. When a version has been imported.

The Properties window will show other properties of the business space version:

 Application Title - this title will be used in the <title> HTML tag of the application.

 Timeout Page – a page that the system will display when a browser session times

out. If not specified the default one will be used

 Incoming Emails – whether the version handles incoming emails (see Incoming

Emails for details)

 Login options – how the system will handle login. See Login Options for more

details.

 Login page – this defines properties of the default login page. You can specify the

title of the page, the image displayed at the top of the page (if any), the text that

prompts user to sign up (if any) and the link to handle “forgotten password”

functionality (if any).

 Default date/time formats – this property defines default formats for attributes of

the Date and Timestamp types. New attributes of these types will be created with

the specified formats by default. Here it is also possible to change existing

attributes of the Date and Timestamp types to the specified formats.

 Page Margins – this property defines default page margins to be applied to pages

with dynamic content.

 Database scripts - in most cases there is no need for you to worry about

database scripts, as Aware IM will take care of the database issues for you. In

some cases, however, you may want to add custom database scripts to your

application. Usually you may want to do this if you implement a query using a

stored procedure (see the EXEC_SP action) or if you implement your own

indexing of the database tables automatically created by Aware IM. Saving a

database script with the business space version saves you the trouble of applying

these scripts manually every time you install your Aware IM application on your

customer’s site, as Aware IM will automatically run the scripts when the business

space version is published for the first time.

 Password protection – whether a configurator needs to specify a password to

look at the configuration of the version

 Push notification – whether the version supported push notifications for mobile

devices – see the “Mobile Applications” document for more details.

Aware IM 8.8 User Guide

Exporting Business Space Version

A business space version may be saved to a file to be later imported back (see

Importing Business Space Version) or uploaded to the Aware IM server in the Operation

Mode.

To export a business space version:

1. Click on the business space version you want to view in the Elements Tree to select

it.

2. Select the “Version/Export” command in the menu or right click to bring up the pop-

up menu and select ”Export”. The Configuration Tool will display the File Selection

Dialog.

3. Select the file you want the version to be written to or type in the name of the file and

click OK.

Importing Business Space Version

To import a business space version from a file:

1. Click on the business space version you want to import into in the Elements Tree to

select it (the version must be in the NEW state)

2. Select the “Version/Import” command in the menu or right click to bring up the pop-

up menu and select “Import”. The Configuration Tool will display the File Selection

Dialog.

3. Select the file you want the version to be read from or type in the name of the file and

click OK. The current contents of the business space version will be replaced with

the contents of the version read from the file.

Refreshing Business Space Version

If several configurators are working with the business space versions at the same time it

may be necessary to upload the current contents of the business space and/or business

space version from the Aware IM server to see the new changes to the versions

performed by other configurators.

To refresh a business space version:

1. Click on the business space version you want to refresh in the Elements Tree to

select it

2. Select the “Version/Refresh” command in the menu or right click to bring up the pop-

up menu and select “Refresh”. The current contents of the business space version

will be uploaded from the server and displayed in the Elements Tree.

Aware IM 8.8 User Guide

Working with Configuration Elements

Business space version elements are added/edited using property editors specific to the

element being added/edited. However, certain editing principles described in the

following sections are common to all configuration elements.

Adding Elements

Editing/Viewing Elements

Deleting Elements

Copying Elements

Pasting Elements

Adding Elements

To add a new configuration element of any type:

1. Click on a node in the Elements Tree that represents the collection of elements of the

required type – for example, to add a new process click on Processes; to add a new

business object click on Business Objects (the version that you are adding to must

be in the NEW state– see Lifecycle of a Business Space Version)

2. Select the “File/New” command from the menu or right click to bring up the pop-up

menu and select “New”. The editor appropriate to the given type of element will be

displayed in the Working Area of the screen.

3. Specify properties specific to the element being added in the editor and/or in the

properties of the element and its sub-elements. When finished press the Save button

in the toolbar (or select File/Save from the menu) to save the new element in the

business space version or close the editor tab to discard the changes.

Editing/Viewing Elements

To edit an existing configuration element of any type just double click on the element in

the tree. Alternatively do the following:

1. Click on the element’s node in the Elements Tree to select it.

2. Select the “File/Open” command in the menu or right click to bring up the pop-up

menu and select “Open”.

The editor appropriate to the given type of element will be displayed in the Working Area

of the screen. Modify properties specific to the element being edited inside the editor

and/or in the properties windows for the main element and its sub-elements. When

finished press the Save button in the toolbar (or select the “File/Save command from the

Aware IM 8.8 User Guide

menu) to save the changes to the element in the business space version. Close the

editor tab to discard the changes.

Deleting Elements

To delete an element of any type:

1. Click on the element’s node in the Elements Tree to select it (the element must

belong to a business space version in the NEW state – see Lifecycle of a Business

Space Version)

2. Select the “Edit/Delete” command in the menu or right click to bring up the pop-up

menu and select “Delete”.

NOTE: Certain elements of a business space version may not be deleted. This

applies to those elements that are added to the business space version automatically

and are required for the business space version to operate correctly. Examples of such

elements are the RegularUser business object and the SystemUsers business

objects group. An attempt to delete such an element will result in an error message.

Copying Elements

Elements of a business space version may be copied within a single business space

version, between business space versions of the same business space or between

business versions of different business spaces. Only compatible elements may be

copied – for example it is possible to copy an attribute into a business object or

notification but it is not possible to copy an attribute into a process or rule.

To copy an element to the clipboard:

1. Click on the element’s node in the Elements Tree to select it

2. Select “Edit/Copy” in the menu or right click to bring up the pop-up menu and select

“Copy”.

Pasting Elements

Elements of a business space version may be copied within a single business space

version, between business space versions of the same business space or between

business versions of different business spaces. Only compatible elements may be

copied – for example it is possible to copy an attribute into the business object or

notification but it is not possible to copy an attribute into a process or rule.

To paste an element which has been previously copied into the clipboard:

Aware IM 8.8 User Guide

1. Click on a node in the Elements Tree that represents the element into which the

element in the clipboard is being pasted – for example, to paste a process click on

Processes; to paste an attribute into a business object select the business object.

The business space version where an element is being pasted must be in the NEW

state – see Lifecycle of a Business Space Version

2. Select the “Edit/Paste” command in the menu or right click to bring up the pop-up

menu and select “Paste”. Pasted element will appear in the Elements Tree.

NOTE: If an element with the same name already exists in the business space

version Aware IM will change the name of the pasted element so that it is unique (you

can later change this name to whatever you want) – for example, if a business object

with the name Account is pasted into the version which already has a business object

named Account, the name of the pasted object will become Account1 (or Account2

if Account1 exists as well).

NOTE: If a rule is being pasted the Configuration Tool may inspect the contents of the

rule and offer to rename certain identifiers used in a rule. For example, if the following

rule is pasted into the rule collection attached to the Account business object:

Account1.Balance = 100

The Configuration Tool will detect the usage of the identifier Account1 possibly

inconsistent with the name of the owner of the rule collection (Account) and offer to

rename Account1 to Account (see also Adding/Editing Rules).

Finding where Element is Used

To find out where a particular element is used in a business space version:

1. Select the node of the element in the tree

2. Select “Edit/Find References” in the menu or right click and select “Find References”

Aware IM will will list all elements of the business space version that refer to the

selected element in the Search Window. For example, if you have a menu item defined

in a visual perspective that starts a process and you selected this process to check

where it is used, the menu item that starts the process will be listed in the window.

Note that this command will not search everything – it will not search scripts and HTML,

for example. To search absolutely everything in a business space version, use the

Search Version command.

Aware IM 8.8 User Guide

Adding/Editing Business Objects

The following section describes how to work with the editor of business objects when

adding a new business object or editing the existing one. Business objects are described

in the Business Objects as Carriers of Data section.

Specifying General Properties

Defining Forms

Defining Presentations

Defining Intelligent Business Objects

Specifying General Properties

The editor of business objects has several tabs – Attributes, Forms, Update Rules,

Delete Rules and Presentations. The Property window contains the following properties:

Name

Specify the name of the business object uniquely identifying it within the business space

version. The following restrictions apply:

a) The name must start with a character (not digit) or underscore symbol. All other

symbols in the name must be either characters (including underscore symbol) or

digits. No spaces or special symbols are allowed.

b) The name must be unique among the names of other business objects, business

object groups and notifications.

c) The name must not start with one of the instance prefixes – This, That, Added,

Removed, LoggedIn, Changed or Failed.

d) The name must not be one of the reserved names – File, Day, Question,

EmailSender, ReceivedEmail, IncomingEmail.

e) The name must not coincide with the name of the basic attribute types – Number,

Date, Duration, Timestamp, Shortcut, Document or Picture.

Description

Specify any text that describes what the business object is for, the business concept that

it represents, how it is used etc. Any description if defined is included into the generated

documentation for the business space version – see Generating Documentation. To

provide the description for the business object, click on the Menu button in the top right

corner of the screen and select “Business object description”.

See also:

Adding/Editing Forms

Form Properties

Adding/Editing Forms

There must be at least one form defined for a business object. When a new business

object is being defined the Configuration Tool creates the default form automatically.

You can add new forms and/or edit the default one.

Add

To add a new form switch to the “Forms” tab and click on the icon at the top of the

Forms table. There are two types of forms you can create – Aware IM-managed forms

and custom HTML forms. Aware IM-managed forms are fully managed by Aware IM –

you can customize the appearance of such forms using the Form Designer. Raw HTML

forms are created outside of Aware IM using any 3

party HTML editors, They are then

imported into Aware IM and input fields of these forms are mapped to the attributes of

the business object where the form belongs. For more details about custom HTML forms

watch the Custom HTML Forms video tutorial. All further discussion in this and

subsequent sections will apply to AwareIM-managed forms.

Enter the name of the new form and the form entry will be displayed in the table. You

can now define properties of the new form in the Selection Properties window – see

Form Properties.

Edit/View

To edit/view an existing form select the form in the Forms table and the properties of the

selected form will be displayed in the Selection Properties window. You can edit these

properties – see Form Properties. You can also expand the form entry and edit the form

sections of the form – see Adding/Editing Form Sections.

Aware IM 8.8 User Guide

Delete

To delete an existing form select the form in the Forms table and press the icon at the

top of the Forms table.

Preview

To see how the form will look like in the browser use “form preview”. The preview of the

selected form in the embedded browser is displayed underneath the forms table. All

changes to the form will be automatically shown in the embedded preview. To turn the

embedded preview on/off click on the icon at the top of the forms table. To set

preview settings (such as the “theme” and font size) click on the icon. To see how the

preview will look in the standalone browser click on the icon.

Apply Style

Clicking the icon allows the user to apply a particular presentation style to the form.

For more details about styles see Form and Grid Styles section.

Form Properties

To change properties of a form of a business object:

1. Begin adding or editing the business object – see Adding Element and Editing

Element.

2. Click on the “Forms” tab at the bottom of the screen. Select the form you want to edit.

The properties of the form will be displayed in the Selection Properties window. The

following properties can be defined:

Name

Specify the name of the form. Can be any text including space symbols. The name must

be unique among other form names of the business object.

Description

Specify the description of the form. Can be any text including space symbols.

Width

Specify the width of the form in pixels. If you leave this value blank (default) the form will

occupy all the available width of the screen

Height

Specify the height of the form in pixels. If you leave this value blank (default) the form

will automatically calculate its height based on its contents. In this case no vertical scroll

bar will be displayed. If you specify a particular height of the form the vertical scroll bar

may be displayed if the content of the form does not fit the specified height.

Aware IM 8.8 User Guide

Stretch to bottom of screen

When this checkbox is ticked height of the form will be calculated automatically to make

sure that the bottom of the form aligns with the bottom of the screen.

Panel Header

Select this property to define how the header of the form will look like. The following

options are available:

Aware IM 8.8 User Guide

Default Header / Custom Header/No Header

Aware IM can either display a default header, a custom header or no header at all. The

default header includes a special area at the top of the form that may optionally contain

the caption of the form, the icon and “tools” (form operations specifically designated for

this area) – see the form below.

The orange area at the top represents the default form header that contains default icon,

default caption and default “tool operations”

To define a custom header, specify HTML of the header. It will be displayed at the top of

the form. The form below shows custom header with the following simple HTML:

<span style='font-family:Arial;font-size:18px;color:orange;padding:15px'>REGULAR

USER</span>

For forms with “wizard” navigation you can also select the “Show Wizard Steps” radio

button. If this radio button is selected the panel header will only display the “stepper”

widget and nothing else – see the Navigation Type property of the form.

Aware IM 8.8 User Guide

Default Caption

Select this radio button if you want Aware IM to use the default caption – for forms with

one form section it is the caption of the form section; for forms with multiple form section

it is the name of the business object.

Use This Caption

Select this radio button to display the specified text as caption.

No Caption

Select this radio button if you do not want the caption of the form to be displayed.

Put caption in the application toolbar at the top

You want want to save real estate by displaying caption of the form inside the

application toolbar (one must be defined in the Top Bar area of the corresponding visual

perspective). In this case you can turn the header of the form off completely but still

display its caption. This option is especially useful if a form is displayed on mobile

phones where screen real estate is limited.

Icon, No Icon, Default Icon

Select these radio options to display or hide the icon inside the header area of the form.

Show Caption/Show Icon

Tick these checkboxes to show caption or icon in the default header.

Aware IM 8.8 User Guide

NOTE:. Even if the caption/icon are not shown in the default header you may define

them, so that they are displayed as the caption or icon of the tab where the form is

displayed (if a form is displayed on a tab of a visual perspective)

Mobile Style Header

If this option is selected a special CSS style is assigned to the default header – the

caption is displayed with large bold letters in the middle of the header. This style is

useful when the form is displayed on mobile phones.

Panel can be collapsed/expanded

If this option is selected the “tools” displayed in the header include an icon to collapse or

expand the form

Panel is initially expanded

This option can only be used if “Panel can be collapsed expanded” option is selected. If

this option is selected the form is initially displayed in a collapsed state.

Use automatic

The following options specify the times at which Aware IM will use the form in the

Operation Mode (see Defining Forms).

a. Tick the “Object creation” checkbox if you want the form to be used when new

instances of the business object are created.

b. Tick the “Object editing” checkbox if you want the form to be used when existing

instances of the business object are edited/viewed

c. Tick the “User registration” checkbox if you want the form to be used when the end

users register themselves with the system (if your system supports this feature).

d. Click on the “Access levels” property if you want the form to be used only when the

user creating or editing an instance of the business object has a particular access

level(s). By default a form is used by users of all access levels. You can exclude

certain access levels by selecting them in the left list box and using the Right arrow

button to move the selected access levels into the right list box.

NOTE: Among all forms defined for the business object there must be at least one

that is used when creating new instances of the object and at least one that is used

when editing instances of the business object (could be the same form). Also there must

not be an access level that does not have creation or editing form defined for it,

otherwise Aware IM will not know which form to use when the user with this access level

creates or edits an instance of the business object.

NOTE: The default form created by Aware IM automatically for a new business object

is intended for both creation and editing and covers all access levels (you can change

this if you like).

Aware IM 8.8 User Guide

NOTE: Some forms may be created only to be used by the ENTER NEW or EDIT

actions in a particular process. You can uncheck the “automatic usage” check box for

such forms, as Aware IM will not be using these forms automatically.

Navigation Type

The navigation type of form sections in a form determines how form sections are

navigated in the Operation Mode (this is relevant, of course, if a form has more than one

form section). There are two types of the navigation style – tabs and wizard.

With “tabs” the order of form sections in the form is undefined – the user can navigate

between form sections at random choosing any form section after the current one (this is

like working with the tabbed dialog). The names of the existing form sections are

displayed above the form and the name of the currently displayed form section is

highlighted. The user can click on the name of the form section to navigate directly to

this section – see also the picture shown in Form Sections.

With wizard-like navigation the order of form sections is strictly defined. The user can

only navigate to the next or previous form section in the defined order. The currently

displayed form section contains the Next and Previous buttons that brings the user to

the next or previous form section. For wizard forms it is also possible to display a special

widget that shows where in the sequence the user currently is – see below:

Aware IM 8.8 User Guide

To display the widget select the Show Wizard Steps radio button in the Panel Header of

the form - see panel header for object forms

NOTE: there is an alternative way of implementing wizard forms in Aware IM – see

Multi-step Processes.

Aware IM 8.8 User Guide

Tab reordering

Tick this checkbox if the user is allowed to change the order of the tabs(form sections)

defined by the configurator. The user will then be able to save the new order of tabs.

Mobile tabs

Tick this checkbox if the tabs of the form are to be displayed using a “mobile” style – the

tabs are then bigger than usual and the icon is displayed above the text

Tabbar position

Select whether the tabbar will be displayed at the top, bottom, left side or right side of

the form

Centre Align Form

Tick this checkbox if you want the form to be displayed in the centre of the screen

(otherwise the form will be left-aligned).

Autosave

Normally when the user closes or abandons a form without saving his changes the

system automatically asks whether the user wants to save the changes. Tick this box to

suppress this prompt – in this case the form will be automatically saved without asking

the user. There will also be a Cancel button that allows user to close the form without

saving the changes.

Display Mask

Tick this checkbox if you want to see the “Executing…” message every time the changes

of the user are committed to the server – either when the changes are “auto-saved” (see

the paragraph above) or when dynamic rule execution happens (see Advanced Rule

Options).

Button Aligment

By default Save and Close buttons are displayed center-aligned. You can select different

alignment here.

Panel Operations

This option allows you to define operations that you can do with the instance of a

business object while the form is being edited or viewed in the Operation Mode. See

Adding/Editing Panel Operations for details.

Aware IM 8.8 User Guide

Form Auto Refresh Settings

Select this option from the menu if you want to specify how the form refreshes itself

when some operation in the system has been done. By default Aware IM will

automatically refresh the form when the form is saved or when a process is started from

the form itself. Sometimes it may be necessary to refresh the form when other

processes are executed or other forms are saved. You can specify such processes and

objects in the Auto Refresh dialog.

Form panel resizing

Select this option from the menu to allow/disallow the user to resize the form at run time

and/or specify size constraints. The Resizing Options dialog will be displayed. Tick the

“Resize Width” checkbox to allow user to change width of the form; tick the “Resize

Height” checkbox to allow user to change the height. If you tick the “Allow User to

Save/Restore Current Size” checkbox user will be able to save the current settings of

width and height, so that the form is displayed again with the saved width and height

when the user logs in again (note, that the settings are maintained by Aware IM per

user). The user will also be able to restore the form to the configured settings.

CSS Style and CSS class

Here you can also assign CSS style and/or class to the form. You may want to do this if

you want to customise the appearance of the form. See the “How to use CSS” section in

the How To Guide for more details.

Responsiveness

Select this option from the menu to make the form “responsive” to changes of the screen

size. For more details please watch the video tutorial.

Tour

The “Tour” feature allows configurators to add explanation to the elements of the form,

so that the user can understand the screen better. The explanation of the element is

displayed to the user at the bottom of the screen with the marker pointing to the element

of the screen being displayed. The user can jump between the elements of the screen

and Aware IM automatically scrolls to the element being explained and displays the

marker for the element. For more details about tours see the “How to use the Screen

Tour feature” in the How To Guide.

Scripts

For users who are familiar with Javascript this dialog allows specifying additional

parameters when forms are initialized and displayed. See Programmers Reference

Guide for more details.

Adding/Editing Form Sections

To add or edit a form section:

Aware IM 8.8 User Guide

1. Begin adding or editing a business object – see Adding Element and Editing

Element.

2. Select the Forms tab and then select the form that owns the form section.

3. To add a form section click on the icon at the top of the forms table. In the dialog

that appears select the “New section” radio button and specify the name of the new

section. Click OK on the dialog and the new entry for the form section will be

displayed underneath the form. Select this entry and edit the form section properties

in the Selection Propertes window.

4. To edit a form section expand the form that owns the section and select the form

section to edit. Its properties will be displayed in the Selection Properties window.

The following properties can be specified:

Name

Specify the name of the form section. The name may contain any characters including

spaces. The name must be unique among the names of other form sections in the form.

Description

Specify the description of the form section.

Caption

Specify the caption of the form section. By default it is the name of the business object

that owns the form.

Icon

Specify the icon that will be displayed inside the tab representing the section in the

Operation Mode (only for sections with random navigation order).

Specify a unique ID of the section. This ID can be used in the Tour feature.

Not present when

You can specify that under a certain condition the form section should not be displayed.

If the specified condition holds true the tab showing the section will not be displayed or

(for wizard-style navigation) the section will be skipped during navigation. When

specifying conditions you can only use attributes of the object whose form the section

belongs to.

TIP: To use attributes of the referred instances in conditions define shortcut attributes

that refer to the required attributes (see Reference Attributes and Setting Properties of

Shortcut Attributes) and use shortcuts instead of reference attributes.

Aware IM 8.8 User Guide

Tour

This is the similar to the Tour property of a form, except that the tour element is meant to

explain what the form section is for.

Badge

Click on this property to display a “badge” for the tab representing the form section. A

badge is a little icon on top of the tab usually showing a number (for example, a number

of unread messages for the current user). This number is constantly refreshed – it can

be changed by the rules and the number will then be displayed, When specifying badge

properties you have to define an expression for the number (or text) displayed on the

badge. You can then specify the background color of the badge as well as the refresh

rate and tooltip.

Scripts

For users who are familiar with Javascript this dialog allows specifying additional

parameters when form sections are initialized and displayed. See Programmers

Reference Guide for more details.

Defining Form Section Layout

To define the layout of a form section, double click on the form section entry on the

Forms tab of a business object (or click on the icon at the top of the table. The Form

Section designer for the selection section is then displayed in a separate window.

The layout of the section represents a table consisting of rows and columns. Each cell in

this table represents an attribute (sometimes several attributes) or it can contain an

HTML or be empty. By default the table has a single column so the attributes are laid out

in a top-down fashion.

The Form Section Designer has two modes – the Preview mode and the Table Layout

mode. In the Preview mode the changes you make to the layout of the form section are

immediately displayed in the embedded browser, so that you can immediately see how

the form will look like in the browser. A form is represented by a table consisting of cells.

Each cell contains specific information – either an attribute or several attributes or HTML

or a Google Map. In the Table Layout mode the cells are represented by an entry in the

table (see the picture below). In the Preview mode cells are harder to see but you can

still notice small dividing lines between them. You switch between modes by clicking on

the and icons at the top of the editor.

The pictures below show a particular form section in the Table Layout mode and

Preview mode respectively:

Aware IM 8.8 User Guide

Most of the time you will be working in the Preview mode so that you can immediately

see how the form looks in the browser. But sometimes selecting the cells you want to

work with is difficult in the Preview mode, so in this case you can switch to the Table

Layout mode, perform the changes and switch back to the preview mode. Note also that

you can always see how the form section looks like in the standalone browser by

clicking on the icon.

Specifying which attributes will be shown on the form

You can control which attributes will be shown on the form section by including them into

the layout. If the form section is the only section of the form Aware IM automatically

Aware IM 8.8 User Guide

includes all attributes of the business object into the form section and lays them out in

the top-down fashion. If you do not want the form section to show all attributes you can

delete the corresponding cell by clicking on the cell and pressing the icon at the top of

the editor.

If the form section is not the only one in the form you have to specify which attributes will

be shown. To do this:

1. Click on the icon at the top editor

2. In the dialog that appears tick the attributes you want to insert and click OK

Alternatively you can drag and drop a particular attribute by selecting it from a panel of

available attributes on the right of the form.

The rows representing the attributes will appear in the form section. You can change the

order of the attributes by clicking on the Up and Down icons in the toolbar of the editor.

Cell Properties

By default each attribute on the auto-generated form section will be displayed according

to the presentation information specified for the attribute (see Adding/Editing Attributes).

It is possible, however, to override the default presentation of the attribute when it is

displayed on a particular form section. To do this, click on the cell that contains the

attribute and the cell properties will be displayed in the Selection Properties window. You

can then specify the presentation properties of the attribute as described in the

Adding/Editing Attributes section. If it’s an HTML or a Google Map cell, the Selection

Properties window will display the properties specific to the type of the cell.

Multiple columns

Each attribute in the resulting form is displayed according to the presentation information

defined for the attribute – see Adding/Editing Attributes. The default top-down fashion of

laying out attributes can be easily changed so that the form section contains more than

one column. To do this:

1. Click on the icon in the toolbar of the editor.

2. A blank column will be added to the form.

3. Click on the cell representing the attribute you want to display in a different column.

Drag and drop the cell to the new column

The pictures above show an example of a multi-column form section:

Column properties

To select a column rather than an individual cell depress the SHIFT key and click on any

cell that belongs to the column you want to select. Alternatively toggle “column selection”

mode by clicking on the icon and then click on the column you want to select. The

column is highlighted and its properties are displayed in the Selection Properties

window. You can specify the following properties:

Aware IM 8.8 User Guide

Column Width

Specify percentage of the overall width occupied by the column. If you have two

columns like on the picture above the default value for the width of each column is 50%,

which means that each column will occupy equal share of the total width of the form

section. You can make a particular column wider or narrower.

Label Alignment

You can specify how labels of the controlled are aligned relative to the control itself.

Labels can be placed on the left of the column (left aligned or right-aligned) – see the

Item Type form above. Or labels can be placed above controls as in the Contact Note

form above.

Label Width

This setting is relevant only when labels are placed to the left of the control and defines

the width of the label column. Width can be specified as an absolute value or

percentage. Percentage is especially useful for forms displayed on mobile phones.

Width of input control

Usually width of the input control is specified in the Presentation properties of the

corresponding attribute. However, you can override the value in the control by selecting

“Width in percentage” or “Entire width less” radio buttons. The former is used when label

width is specified in percent. In this case the control occupies the rest. If you select the

“Entire width of the column less” radio button all controls of the column will occupy the

entire width of the column less specified value in pixels or percent.

Note that columns can be swapped by dragging a selected column on the column that

you want to swap the selected column with.

Aware IM 8.8 User Guide

Merging and splitting cells

It is possible to define cells that span across several columns. Only an attribute cell can

span rows like this and it can only be merged with empty cells. You can see In the

Appointment form above that the Subject, Description and StaffResponsible attributes

span across two columns. To achieve this we need to merge the corresponding cells.

First we need to select the leftmost non-empty cell that should be merged. Note that the

Merge icon becomes enabled. We click on the icon and the two cells are merged.

Note that a separate column is formed and we can now define properties of this column.

To split a cell that has been merged before select the cell and click on the icon.

Displaying reference tables

If you put a reference attribute represented by a table into a layout cell the reference

table will be displayed as part of the form section – see how the Items attribute is

displayed in the Item Type form below:

Aware IM 8.8 User Guide

Here the “Items” attribute is put into its own cell. It is also possible to display references

in tabs at the bottom of the form section as shown on the Contact Note form below – see

In Reply To, Replies and Alert tabs.

Aware IM 8.8 User Guide

Here “ReplyTo”, “Replies” and “Alerts” attributes (all are references) are each displayed

in their own tab. To achieve this effect one has to place reference attributes into the

same cell. This should be done in the Table Layout mode. To do this select the cell with

one reference attribute and drag it to the cell with another reference attribute.

Alternatively, select the cell with the reference attribute and click on the “Attribute name”

property in the Selection Property window. Then tick other reference attributes in the

dialog that comes up to indicate that these reference attributes should be added to the

cell.

Putting cells inside group boxes

You can enclose a group of logically related cells into a named group box:

Aware IM 8.8 User Guide

To insert a group box:

1. Click on the icon (or alternatively drag and drop the Start Separator element from

the palette of available elements on the right of the form).

2. In the dialog that appears specify the title of the group box, for example “Library

Details” and click OK.

3. Using the Up and Down arrows move the separator row to the required place.

If you click on the separator row you can define the following properties of the group

box:

Title

The title of the group box

Aware IM 8.8 User Guide

Width and Height

Width and height of the group box in pixels. If left blank Aware IM will calculate these

automatically

Collapsible

If you tick this box Aware IM will display a control that will allow users to collapse the

group box to save space – see the little triangle next to the Library Details text above.

CSS style

Specify the CSS style of the group box.

CSS class

CSS class of the group-box. This class has to be defined in the custom CSS file of the

application.

Aware IM 8.8 User Guide

Collapsed initially

If you tick this box the group box will be collapsed initially when the form is displayed. On

the picture above the “Outgoing email” and “Incoming emal” group boxes are initially

collapsed

NOTE: At the moment you can only define group boxes located beneath each other,

you cannot define group boxes located next to each other.

Not present when

It is possible to include a group box conditionally. Here you can specify a condtion when

the group box will not be included. If left blank the group box will always be included.

Adding HTML

Using Form Section Designer you can also add arbitrary HTML to your forms. For

example, you may want to add some static images or add a descriptive and text. To add

HTML to your form:

1. Click on the drop down next to the icon of the Form Designer toolbar icon (or

alternatively drag and drop the HTML element from the palette of available elements

on the right of the form).

2. Select “HTML row from the drop down menu.

3. The HTML dialog will come up. Add HTML to be placed into the form cell

NOTE: If you refer to images in your HTML place the image files into some

subdirectory of the web application directory of the web server. For the default Windows

installation of Aware IM this directory could be

c:\AwareIM\Tomcat\webapps\AwareIM\myimages.

Here is an example of a form that uses an HTML cell:

Aware IM 8.8 User Guide

Note the explanation with the greay background at the top of the form has the following

HTML:

<div style="border: solid 1px gray;PADDING: 8px; BACKGROUND-COLOR: lavender;

TEXT-ALIGN: justify; LINE-HEIGHT:1.2em">

Click on an item in the list to see more details on a separate form.

Use buttons in the caption of the table to filter the list.

</div>

You can refer to the attributes of the object whose form is being displayed. For example,

NOTE: You can embed video in your form if you refer to the document attribute

representing a video in your HTML cell – see How To document for more details.

Adding buttons/links to forms

To add buttons or hyperlinks to your form:

1. Click on the drop down menu next to the icon of the Form Designer toolbar icon

(or alternatively drag and drop the Buttons element from the palette of available

elements on the right of the form).

2. Select “Button/Link Row” from the drop down menu.

3. The dialog will be displayed where you can define operations that your buttons will

perform – one button per operation. See Adding/Editing Panel Operations. The

Operation dialog has a checkbox that specifies whether to generate a hyperlink

rather than a button.

Aware IM 8.8 User Guide

You can also add buttons when you specify HTML for the HTML row (see the previous

section). To do this clicki on the “Add Button” button displayed on the dialog where you

specify the HTML code. You can then specify the operation that will be performed when

the user clicks on the button. The button itself will be styled according to the currently

used theme. Note that Aware IM will generate a special HTML element representing the

button. You do not need to understand what this element contains, but the button will be

properly generated at run time. If you want change the parameters of the button you

have to re-create it – you cannot edit it.

Alternatively, you can provide an HTML hyperlink using one of the Javascript operations,

for example:

<a href=”#” onclick=”AwareApp.startProcessFromForm (‘My process’,

‘main’, this, true)>My Process </a>

Forms that use Google Maps

Using the Form Section Designer you can also get your forms to display Google Maps.

You would do this only if you want to show some address on a Google Map. The object

that owns the form must have an attribute that stores the complete address. Note that

you cannot display a Google map when you are creating an object. To add a Google

Map to your form:

4. Click on the drop down menu next to the icon of the Form Designer toolbar icon

(or alternatively drag and drop the Google Map element from the palette of available

elements on the right of the form).

5. Select “Google Map Row” from the drop down menu.

6. The dialog with Google Map properties will come up. Select the attribute that stores

the complete address that can be shown on a Google Map or an attribute that stores

a reference to a special MGeoLocation object that stores location latitude and

longitude (See Mobile Applications document for details about MGeoLocation)

7. Select other map properties and click OK.

NOTE: For details how to use the “Polygons” feature of the Google Map please

refer to the How To Guide.

NOTE: Some usages of Google Maps require you to create an account and

specify a special key. If you need to provide a key for your Google Maps account you

can do this in the predefined GoogleMapsKey attribute of the SystemSettings object.

Forms that use Gauge Chart

Using the Form Section Designer you can also get your forms to display a gauge chart.

This is useful when you want to show the value of a particular attribute as a gauge. To

do this you need to define a cell of the Gauge type. The steps for defining such a cell are

Aware IM 8.8 User Guide

similar to defining the Google Map cell. You also need to select an attribute whose value

will be displayed on the gauge chart and provide min. and max. values for the gauge

(either as fixed numbers of refer to values of some attributes).

Show preview of the form on phones and tablets

To see how the form looks on the phone click on the icon. To see how the form looks

on the table click on the icon.

Adding Custom HTML forms

Native Aware IM forms that you can create using embedded Form Designer are very

powerful and normally you don’t need to use any other forms. However, if you want to

use very specific styling which is difficult to achieve using native Aware IM forms, you

can create such forms outside of Aware IM using any HTML editor of your choice and

then import them into Aware IM mapping input fields in the HTML form to the attributes

of the business object that owns this form. Please watch the video tutorial, which

explains this process in great detail.

Adding/Editing Panel Operations

This section describes how you can define “context” operations that can be invoked from

the form. Note that this section is also relevant for queries – when the results of a query

are displayed users can perform operations relevant to the query. The buttons

representing operations are usually displayed in the toolbar at the top or bottom of the

form/query, but they can also be displayed in the “tools area” in the default panel header

(see “Panel Header”) or they can be temporarily added to the system menu. In the latter

case buttons for the form or query are added to the system menu when the form/query is

displayed and removed from the menu when the form/query is closed.

An instance of the object shown by the form is automatically added to the Context of the

operation. For a query the Context is formed when the user selects one or more records

shown by the query (provided that the operation is marked as Applicable to Multiple –

see below)

To add/edit panel operations to a form or query:

1. Begin adding or editing the business object or query – see Adding Element and

Editing Element. If editing a business object select the required form on the Forms

tab.

2. The properties of the selected form will be displayed in the Selection Properties

window, while the properties of the query will be displayed in the Element Properties

window.

3. Click on the “Panel Operations” property to bring up the “Panel Operations” dialog.

Aware IM 8.8 User Guide

Add/Edit

These buttons let you add/edit an operation to the form or query (see below for more

details)

Edit Toolbar

If an operation is located on one of the toolbars of the form or query this button allows

you to further edit the contents of the corresponding toolbar:

Add Separator

This button lets you define a “separator” to the toolbar – a vertical dividing line

separating groups of operations.

Add Text

You can add not only operations to your toolbar but also arbitrary text. You can use

HTML tags here and you can refer to the values of object attributes using tags.

Add Input Control

You can add text input elements or combo-boxes to your toolbar. When the user enters

data into the text box or makes a selection in the combo-box Aware IM will write the

entered value into the attribute of the object that you specify (it can either be the

SystemSettings object or the object representing the logged in user, or the “session”

object (a non-persistent object that has been marked as storing “session” values). Once

the value has been written into the attribute Aware IM will run the operation that you

specify. The operation can use the stored value and do something with it – run a query

or start a process, for example.

Add Folder

You can add a “folder” to your toolbar. A folder consists of operations that you can add

to this folder. At runtime Aware IM will show a “menu button” representing this folder. If

the user clicks on such a button a list of operations of the folder will pop down.

Right Aligner

When you add “right aligner” all operations, text, folders and separators added to the

toolbar after the right aligner will be aligned to the right of the menu. You can have only

one right aligner in the menu.

Delete/Change Order

Use these buttons to delete selected operations or change their order

Adding/Editing an operation

You can set the following properties when adding/editing an operation

Name

Specify the name of the operation. This name will be displayed in the menu. Any

identifier is allowed including HTML tags.

Aware IM 8.8 User Guide

Description

Specify the description of the operation. This description will be shown as a tooltip when

the user hovers the mouse over the text/icon representing the operation.

Location

Specify where the button of the operation will be located – as explained before you can

choose one of the toolbars around the form/query, “tools” area in the default header,

“bottom of the form” area (where Save and Close buttons are by default), or you can

choose to temporarily add operation button to one of the system menus.

Applicability condition

This option allows you to specify the condition(s) that must be satisfied in order for the

operation to appear on the form of the business object. For example, if you specified the

condition Loan.Status=’CURRENT’, the operation will appear only for loans with

current statuses. If condition is left blank the operation will always appear on the form.

The format of the condition must satisfy the format of the Rule Language condition (see

Rule Language).

Text Color

Allows specifying the color of the text displayed on the button (provided that the Display

Operation Name” is ticked)

Background Color

Allows specifying the background color of the button representing the operation

CSS class

You can assign custom CSS class to the button representing the operation. This can be

useful if you assign button colors in the CSS rather than explicitly. In this case changing

colors in the CSS will change them for all operationbuttons where the CSS class is used.

Display Image on the Button

If this box is ticked an icon will be displayed along with the name of the operation (if

“Display Operation Name” is ticked) to represent the operation. You can choose an icon

by specifying an icon file or referring to a CSS class. See “How to use icons fonts to

display an icon for a button” section in the How To Guide.

Display Operation Name on the Button

If this box is ticked the name of the operation will be displayed along with the icon (if

“Display Icon” is on) to represent the operation.

Operation Type and Parameters

The most common types of operations are described below:

Start Process

This operation type starts a process. When the Start Process operation type is selected

the Configuration Tool displays the combo box containing all processes defined in the

Aware IM 8.8 User Guide

business space version. Select the process you want started when the operation is

invoked. If the process has input then you may need to provide the value for this input.

Two scenarios are possible:

- If the object defined as the process input is the same as the owner of the form, you

don’t have to do anything, as the system will automatically provide the input when the

process starts.

- If the object defined as the process input is different from the owner of the form, you

must specify the input in the “Value” column of the “Process Input Table”. Click on

the appropriate cell in the “Value” column and enter the process input as the

reference attribute of the form owner. For example, let us assume that we are

creating a Forum management system where we have a Topic and a Forum

objects defined. The Topic object has a single reference attribute named MyForum

that refers to the Forum where the Topic belongs. Let us assume also that we are

editing the form of the Topic object and we want to define the operation that starts

the PostNewTopic process, which allows posting a new topic from the form of the

existing one. Let us assume that the PostNewTopic process requires Forum as its

input. When defining the operation we would define the operation type that starts the

PostNewTopic process and we would specify “Topic.MyForum” in the “Value”

column of the Process Input Table (note that Topic is the owner of the form we are

editing) as the process input.

Run Query

An operation of this type runs the specified query. When the “Run Query” operation type

is selected the Configuration Tool displays the combo box containing all queries defined

in the business space version. Select the query you want run when the operation is

invoked.

Create Document

An operation of this type generates a document from the specified document template or

report and displays the resulting document (see Document Generation). When the

Create Document operation type is selected the Configuration Tool displays the combo

box containing all document templates defined in the business space version. Select the

document template you want to generate the document from when the operation is

invoked. Alternatively you can let users choose the document at run-time from the list of

pre-configured document templates or user-defined documents.

Delete Object

An operation of this type deletes the instance of the business object being edited (a

warning is displayed before the object is deleted). This operation type has no

parameters.

Edit

An operation of this type allows editing a different form of the business object from the

one shown currently (if one is defined). Select the name of the form to be edited and the

form section to be displayed when editing starts.

Aware IM 8.8 User Guide

View

An operation of this type either shows the specified presentation of the business object

that owns the form (see Business Object Presentation) or shows a different form of the

business object. In the latter case the form being shown has all input controls disabled

so that a user cannot change attribute values. Select the presentation or form you want

to show when the operation is invoked.

Create Object

An operation of this type allows creating an instance of an object. Select the name of the

object to create and the form of the object to be used during creation.

Execute Javascript

An operation of this type executes the specified Javascript. This can be used by

advanced developers who are familiar with Javascript. One of the common uses of this

operation is integration of custom Cordova plugins for native mobile applications. This is

described in detail in the Programmer’s Reference Guide. When a script is executed the

following Javascript objects are available:

 parser (controller of the corresponding widget

 context – an array of objects containing objectName and objectId of the record

that the operation is for

Defining Presentations

Presentations are explained in the Business Object Presentation section.

Presentation layout is created in the Report/Presentations Designer – see Working with

Report/Presentation Designer.

Aware IM 8.8 User Guide

Add

1. To create a new presentation click on the Presentations tab in the business object

editor and click on the icon located at the top of the Presentations table. New

Presentation dialog will be displayed

2. Enter the name of the new presentation (the name must be unique among the

presentations of the business object) and optionally specify the description of the

presentation

3. Click OK and the entry for the new presentation will appear in the table of

presentations.

4. Click the Save button on the application toolbar (or select “File/Save” from the menu

to save changes to the business object.

5. Double click on the presentation entry to open the Report/Presentation Designer

where you can design the layout of the presentation - see Working with

Report/Presentation Designer.

Edit/View

Double click on the presentation entry in the table of presentations of the business

object. The Report/Presentation Designer will be displayed where you can change the

layout of the presentation - see Working with Report/Presentation Designer

Delete

1. Select the presentation you want to delete in the table of presentations of the

business object

2. Click on the icon located at the top of the table.

Export

Exporting a presentation may be useful if you want to reuse the layout of the

presentation in another presentation or report. To export the presentation layout open

the Report/Presentation Designer and export it from there see Working with

Report/Presentation Designer:

Import

Importing a presentation may be useful if you want to reuse the layout of the

presentation in another presentation or report. To import the presentation layout open

the Report/Presentation designer and use its import functionality - see Working with

Report/Presentation Designer

Defining Intelligent Business Objects

Intelligent business objects are described in the Intelligent Business Objects section.

In order to define an intelligent business object the configurator has to click on the

“Communication” property of a business object and define communication channels of

the object in the “Communication Channels” dialog that comes up.

Aware IM 8.8 User Guide

Aware IM supports the following types of communication channels out-of-the-box:

- E-mail channel – communication with an intelligent business object is via e-mail

- SOAP channel – communication with an intelligent business object is via Web

services mechanism which supports SOAP (Simple Object Access Protocol)

- URL channel – communication with an intelligent business object is via HTTP URL

(Unified Resource Locator)

- REST channel – communication with an intelligent business object is via a popular

REST protocol

In addition to the above pre-defined types it is possible to plug-in custom channel types

– see “Aware IM Programmer’s Reference”.

A particular object may expose several communication channels at once – when a

notification or service request are sent to the object it is possible to indicate which type

of channel the request or notification should be sent through (see SEND and REQUEST

SERVICE actions). Therefore the configurator has to indicate which channels the

intelligent business object exposes.

Every channel has certain properties specific to its type. To set the properties of a

channel tick the channel type in the “Communication Channels” dialog and define its

properties.

Setting Properties of the SOAP Channel

To set properties of the SOAP channel you need to provide settings to discover web

services offered through this channel. Discovering services is getting Aware IM to

automatically figure out which services are exposed by an intelligent object by sending a

special discovery request through the communication channel provided that the channel

supports the service discovery protocol.

To discover services press the Discover button next to the Services table. Discovered

services (if any) will be displayed in the Services table.

NOTE: Business objects declared as service input and reply are automatically added

to the business space version once you have saved the changes for the intelligent

business object you are defining or editing.

NOTE: If the service provider changes definitions of services the services may be re-

discovered in the same way as described above. The Configuration Tool will

automatically replace all services and business objects declared as service input and

replies with the new definitions.

Setting Properties of the E-mail Channel

The following properties should be specified:

Aware IM 8.8 User Guide

Outgoing mail host

The DNS name of your e-mail server that will send outgoing e-mails to the intelligent

business object.

“From” address

The e-mail address that your e-mails to the business object will have as the “from”

address. Note that the “from address” must be recognized by your email server, so it

must be registered on this server.

If your outgoing e-mail server requires that you log in select the “Login Required” option,

press the Details button and enter login credentials. Otherwise select the “No Login

Required” option.

NOTE: When an e-mail channel is defined for a business object the Configuration

Tool automatically adds the EmailAddress attribute to the business object. This

attribute can be used to set the e-mail address of a particular instance of the business

object in the Operation Mode. When the e-mail channel is removed from the business

object the EmailAddress attribute is automatically removed as well.

NOTE: If you select the “Use values from SystemSettings object” radio button the

system administrator will have to provide the values for the outgoing mail host, from

address and login details when the system is initialised – see Setting Initial Values of the

System.

Setting Properties of the URL Channel

Communication with an intelligent business object via the URL channel assumes that

Aware IM sends service requests to the specified URL. It is expected that when this

URL is called the browser will go to the web site of the service provider. When this web

site finishes its task it will return to the Aware IM-based application, A typical scenario

for the URL channel service is a payment system (such as PayPal) that collects credit

card details and returns to the web site of the merchant.

If services exposed by the business object require input (see Defining Services) the

attribute values of the business object instances representing service input will be

passed to the specified URL as request parameters. For example, if a service requires

the business object URLParameters that has Parameter1, Parameter2 and

Parameter3 attributes defined and the provider’s URL is www.provider.com the service

requests will be sent to the following address:

www.provider.com?Parameter1=value1&Parameter2=value2&Parameter3=value3

where value1, value2 and value3 are values of the Parameter1, Parameter2 and

Parameter3 attributes respectively.

Aware IM 8.8 User Guide

The following properties should be specified:

URL of the service provider

This is the URL where the requests will be sent. This property is mandatory.

Request parameter identifying the URL to return to if success

The service provider represented by the intelligent business object may expect that the

request contain the URL that the provider should return to in case of the successful

fulfilment of the service. Aware IM will take care of supplying the appropriate URL

provided that it knows the name of the request parameter that should contain this URL.

For example, if you specify “successURL” as a request parameter the service request

sent to the service provider will be:

www.provider.com?Parameter1=value1&Parameter2=value2&Parameter3=value3&succ

essURL=returnURL

where “returnURL” is the value that Aware IM will supply so that when the reply from the

provider is delivered via this URL Aware IM will know that the service has been

completed successfully. If this parameter is not specified Aware IM will assume that any

service request sent to the provider has been successfully completed without waiting for

any reply from the provider.

Request parameter identifying the URL to return to if a failure occurs

This is the same as the previous parameter except that the return URL indicates failure

rather than success. If this parameter is not specified Aware IM will either assume that

any service request sent to the provider has been successfully completed without

waiting for any reply from the provider (if success request parameter is also not

specified) or it will wait for the service reply from the provider and if the provider’s

service fails the service request will eventually time out (this scenario should be avoided

unless the provider’s service can never fail).

Setting Properties of the REST Channel

Communication through the REST channel involves sending an HTTP call to a particular

URL. Unlike the URL channel no user interface is involved in the call – the service

returns straight away and the execution of the rules continues. Services exposed by an

intelligent object through the REST channel can be discovered if the provider supplies a

file in an Open API format describing exposed services. They can also be added

manually as described below.

To discover services automatically click on the “Discover” button above the services

table. Then provide the URL of the file in the Open API format (with .json or .yaml

extension). Aware IM will automatically discover services exposed by the provider and

will display them. You can then select the services you will be using in your application.

Aware IM 8.8 User Guide

To add a service manually, click on the “Add” button above the services table. To edit

the service details click on the “Edit” button and to delete a service click on the Delete

button. You can also copy a service that you have already defined to use it as a basis for

another service. To do this select a service, click on the “Copy” button, then click on the

“Paste” button to create a duplicate of the service and then click on the “Edit” button to

modify it.

The following properties can be specified when adding/editing a service.

Name

Specify the name of the service. The name must be unique among other services of the

business object. The name must start with a character or underscore symbol and

contain characters, digits or underscore symbols. Spaces are not allowed in the name.

Description

The optional description of the service: what it does, how it is used etc.

Base URL

The URL to call when the service is requested. This URL should not include any URL

parameters. You can use tag expressions to refer to attributes of the objects in Context

here.

HTTP Verb

HTTP verb to use when the service is called – usually GET or POST

Parameters

Parameters of the service can be specified in different ways depending on what the

provider requires.

URL-encoded string

If a provider requires that parameters must be specified in the URL of the call, specify

them here. You can use tag expressions to refer to attributes of the objects in Context.

Aware IM 8.8 User Guide

Request Body

Use these values if parameters need to be encoded into the bodiy of the request. You

can define the details if you click on the Details dialog. A body of the request may

consist of several “parts” if parameters include binary content. Usually, though, the

request contains just one part. To specify the content of the part you either need to

provide the text string containing all parameters or refer to an attribute of some object in

Context or refer to the entire object.

If you specify a parameter string you next to specify “text/plain” as ContentType and

then provide the parameter string by selecting the “Use this String” radio button. The

string may refer to attributes of the objects in Context in tag expressions.

The value of the parameter may also be stored in an attribute of some object in Context

in which case you should select the “Take From Context” radio button and then select

the name of the object and attribute that holds the parameter. You also need to specify

the correct Content Type of the value stored in the attribute.

If you select the “Take From Context” radio button, specify the object, but do not specify

the attribute Aware IM will automatically convert the entire instance of the object either

into JSON or XML representation (depending on whether the Content Type is specified

as “application/json” or “text/xml”. You can then customize how the conversion will occur

by clicking on the “Name Mapping” and “Attribute Encoding” links and also specifying

how undefined values will be encoded.

If your service provider requires that you provide binary content as parameter along with

some primitive values (for example, text or number) you should specify each parameter

in its own part. For example, if you need to provide a binary value and a number you

should define two parts – the first part (binary) should have “application/octet-stream” as

Content Type and it should refer to the attribute of some object in Context of the Picture

or Document type. The second part should have “text/plain” as Content Type and then

refer to some attribute of the Number or Plain Text type.

NOTE: If you are referring to the entire object in Context and this object has an

attribute of the Picture or Document type, the picture or document will be automatically

encoded without you having to define an additional part.

NOTE: If a provider requires that the value of some attribute is an array of primitive

values and you are referring to the entire object in Context, please make sure that the

value of the “array” attribute is a string that concatenates all array members delimited by

the “#” symbol, for example Object.Attribute = “Value1#Value2#Value3”

Aware IM 8.8 User Guide

NOTE: If a provider requires that the value of some attribute is a dictionary and you

are referring to the entire object in Context, please make sure that the value of the

“dictionary” attribute is a string containing pairs of key/values separated by the “|”

symbol. Each key/value pair must be separated by the “~” symbol, for example

Object.Attribute = “Key1~Value1|Key2~Value2|Key3~Value3”

To add a part, click on the “Add” button above the list of the defined parts.

HTTP Headers

Click on the “HTTP Headers” link to define one or more optional HTTP headers that will

be added to the HTTP request if the provider requires them. For each header provide its

name and value. Note that the value may refer to the current Context of the process

when the service is called. To do this, enclose the value in “tags” (double angular

brackets), for example: <<MyObject.MyAttribute>>

If the REST call returns a reply that you need to handle in your application you should

select the “Reply returned of type” radio button and then click on the “Details” button.

Then you should provide the details of the reply in a similar way that you define the body

of the request (see “Parameters” above). However, when you define a reply you should

always specify just one part:

1. For text replies all you can do is write the string with the reply into some

attribute of an existing object in Context of the process where the service is

called. You need to specify the name of the object and the attribute where the

reply will be stored. You will then need to add further rules to analyse the

provided reply and perform further actions

2. For JSON and XML replies you can get Aware IM to automatically parse the

contents of the reply into attributes of some object. Aware IM will create a new

instance of such object and populate its attributes from the values of the

corresponding fields in the reply. By default Aware IM will try to find an

attribute with exactly the same name as in the JSON/XML attribute definition,

but you can also provide your own mapping between names in JSON/XML

and the corresponding Aware IM attribute names.

OAuth Support

Many vendors providing REST services support OAuth protocol that mandates that the

caller of the service authenticates himself using a special protocol before a call to the

service is made. If this is the case you need to tick the “OAuth Supported” checkbox

underneath the services table and then click on the “Details” button to provide further

details:

Provider

Aware IM already includes settings that you need to specify for many popular REST

service vendors, so if your vendor is already in the list you can prepopulate most

settings with vendor-specific values by selecting the vendor from the drop down list.

Aware IM 8.8 User Guide

You can also add your own providers to the list if you know their values. To do this

modify the file

AwareIM/ConfigTool/eclipse/plugins/com.awaresoft.awareim.configto

ol_xxx.jar. This file is a zip file, so you can open it with an archiver utility. Then add

the appropriate property file to the config/oauth directory within this archive, You can

take a look at any existing property file in this folder for an example.

OAuth version

Different vendors support different versions of the OAuth protocol. The settings are quite

different depending on which version is supported. Choose either version 1.0 or 2.0

API Key, API Secret

The caller of the service must be registered with the vendor to make OAuth-based REST

calls. The vendor issues API Key and API secret to the caller. These need to be

specified here. If these values are stored in the attributes of some object (for example,

SystemSettings) you can refer to this attribute by using tag expressions, for example

<<SystemSettings.APISecret>>

Also when registering your application with a provider, make sure that you include the

following URI as “redirect URI”:

http://YourServerName:8080/AwareIM/req.awurl

Scope

Some vendors require that you specify the “scope” of the service request. This is

vendor-specifc – refer to the documentation of the vendor.

Signature type

This value is only for OAuth 1.0. Refer to the documentation of the vendor as to which

signature type you need to provide

Request for request token

The values in this section are only for OAuth 1.0 that requires that the system first sends

a request for a “request token” to the specified URL. The URL then returns a reply that

contains “request token” and “request secret”. You need to specify the URL to send the

request to, the HTTP verb of the request, the type of return and regular expressions to

extract token and secret from the reply.

Request for access token

A call to the service using OAuth can only be done if the vendor issues an “access

token”, which is then used for authentication. To get an access token the system first

needs to call an “authorization URL” that provides a special code in the reply. This code

is then used in the call to the “access token URL” that returns the access token, which

then needs to be stored in an attribute of some object (so that it can be used in the

service call). You need to specify the “authorization URL”, the name of the parameter of

the reply that contains authorization code, the “access token URL”, the regular

expression that extracts access token from the reply and finally an expression where to

store the access token. When specifying the expression use a tag expression, for

example, <<LoggedInRegularUser.AccessToken>>. The object referred to in the

Aware IM 8.8 User Guide

expression must be in the Context of the service call. For more details please refer to

the OAuth and vendor’s documentation.

Token expiry

Access tokens may expire. If a call to the service is made with an expired token an error

message will be returned. The error message is specific to the vendor. If you help

Aware IM identify the “token expiry” error message it will automatically invoke the

access token workflow again and request a new token. Otherwise, it will just display the

error message. To support automatic token expiry click on the “Token Expiry” button,

tick the “Check for expired tokens” checkbox and provide the string that distinguishes

token expiry error messages from other error messages.

Adding/Editing Attributes

The following section describes how to add or edit attributes of business objects or

notifications. Attributes are added or edited on the Attributes tab of a business object or

notification editor. To add an attribute click on the icon at the top of the attributes

table.

See also:

Common Properties

Setting Properties of Plain Text Attributes

Setting Properties of Number Attributes

Setting Properties of Date, Timestamp and Duration Attributes

Setting Properties of Reference Attributes

Setting Properties of Picture Attributes

Setting Properties of Document Attributes

Setting Properties of Shortcut Attributes

Setting Properties of Yes/No Attributes

Setting Options of Binary Data Attributes

Common Properties

Each attribute of a business object or notification must be assigned a particular type

(Plain Text, Number, Date etc). Some properties of the attributes are specific to the

assigned type whereas others are common to attributes of all types. Both common and

specific properties are specified in the Selection Properties window. When you select the

specific attribute its properties are displayed in the window. Which properties are

displayed depend on the attribute type. The following section describes properties

common to all attribute types.

Name

Specify the name of the attribute. The following restrictions apply:

Aware IM 8.8 User Guide

a. The name must start with a character (not digit) or underscore symbol. All other

symbols in the name must be either characters (including underscore symbol) or

digits. No spaces or special symbols are allowed.

b. The name must be unique among the names of other attributes of the business

object or notification owning the attribute.

c. The name cannot be one of the names reserved for system use – ID,

BASVERSION, BASTIMESTAMP, AccessLevel, LoginName, Password,

PersonalSettings.

d. The name cannot be the name of an identifier used in SQL – FROM, SELECT, IN,

INTEGER, TEXT, BLOB, CHAR, VARCHAR etc.

Description

Specify any text that describes what the attribute is for, the business concept that it

represents, how it is used etc. Any description if defined is included into the generated

documentation for the business space version – see Generating Documentation.

Type

Any attribute must be assigned a type. Choose the required type from the “Type” combo

box. The list of types contains basic types (Plain Text, Number, Date, Timestamp,

Yes/No, Binary Data, Document, Picture, Shortcut) and reference types. Reference

types include the names of all business objects and business object groups defined in

the business space version – see Reference Attributes.

Required

If you tick the “Required” checkbox Aware IM will check that there is a non-blank value

for the attribute when an instance of the business object that owns the attribute is

created or edited. The check will be made irrespective of whether the instance of the

business object is created or edited by the user or created/changed by rules. If the value

of the attribute is blank the appropriate message will be issued to the user and any

currently executing processes or rules will be aborted. If the user is creating or editing an

instance of the business object the input control displaying the attribute value will have a

red star next to it to indicate that the value of this attribute must be provided.

Calculated

If you tick the “Calculated” checkbox the user will not be able to change the value of the

attribute – the attribute will be read-only. The value of the attribute can only be changed

by rules. This option is not applicable for attributes owned by notifications.

Initial Value

Most attribute types allow specifying the initial value of the attribute. The initial value is

the value that the attribute is initialised with when an instance of the business object or

notification is created. This applies both to business objects created by the user or to

objects and notifications created by rules. If the user is creating an object she will see

the initial value when the form of the object is displayed. She can then change this value

if necessary. Be also aware of the following:

Aware IM 8.8 User Guide

- The type and format of the initial value must correspond to the type of the attribute.

- Rule expressions are not allowed as initial values (with the exception of expressions

that set the current date or time, such as CURRENT_DATE). If the attribute value

should be initialised to some expression a rule has to be attached to the business

object or notification that owns the attribute – see Adding/Editing Rules.

Choices

Most attribute types allow specifying a number of choices for the attribute value. Choices

indicate that the attribute may take values from the specified list. Clicking on the

“Choices“ property brings up the “Choices” dialog where you can add or delete choices.

If the “Other values allowed” checkbox is unchecked on the “Choices” dialog the

attribute may not take any other values. In this case if the attribute value is different from

the one specified in choices an error message will be issued to the user and the

currently executing process or rules will be aborted. When no other values are allowed

an attribute with choices is displayed on the form of the business object as a combo box

or as radio buttons.

If the “Other values allowed” checkbox is ticked the attribute may take values different

from the ones specified in choices. In this case Aware IM makes no checks of the

attribute value and the list of choices exists purely for convenience of the user. When a

form is generated the field is displayed as an editable combo box where you can choose

values from the list and also specify other values.

It is also possible to specify different values for when a choice is displayed to the user

and what is stored in the database. For example, if you have a choice of gender you can

display “Male” and “Female” as choices but store “M” and “F” in the database. By default

display value is equal to the database value.

It is also possible to use tag expressions as choice values – for example

<<SystemSettings.TaxRate>>

- To add a new choice entry click on the cell in the Choices list box and type in the text

of the choice entry. Press Enter to finish. To add another entry click on the next cell

and type in the text.

- To modify the existing choice entry click on the cell containing the entry in the

Choices list box, modify the text of the entry and press Enter.

- To delete the existing choice entry click on the cell containing the entry in the

Choices list box and press the Delete button located next to the Choices list box.

- To change the order of entries click on the cell containing the entry and press the Up

or Down buttons next to the Choices list box.

- If you want to add more blank entries to the list box press the “More Rows” button.

NOTE: The type and format of a choice value must correspond to the type of the

attribute.

Aware IM 8.8 User Guide

NOTE: Choices are not applicable for attributes owned by notifications.

Dynamic Choices

A list of choices can be calculated at run-time rather than explicitly specified by the

configurator. When the user clicks on the drop down with choices Aware IM can

dynamically run a query to load the choices into the drop down. This will happen if you

select the “Choices are determined at runtime” radio button on the “Choices” dialog. You

can specify any existing query that will be run to extract choices or define any custom

query. As a convenience option you can also select “Use Existing Attribute Values” radio

button. In this case Aware IM will automatically construct a query that will extract all

existing values of the current attribute and present them as choices.

Allow end users to add and edit choices

Ticking this checkbox will allow end users to manage the list of choices in the Operation

Mode. This may be necessary if the configurator does not know up front the list of

choices relevant for a particular end user and he does not want end users to work with

the Configuration Tool directly. If this option is on end users of particular access levels

(usually the system’s administrator) will see an icon on the object form next to the

attribute control. If they click on this icon a window will pop-up where they will be able to

add, edit or modify a list of choices.

The initial list of choices seen by end users will be pre-populated with the choices

entered by the configurator in the Configuration Tool (if any).

NOTE: The option for end users to edit list of choices will not be available if the

configurator provides her own list and specifies that “other values are not allowed”.

Include empty text

Tick this checkbox to include an empty line into the list of choices to allow the user to

select a “blank” value

Indexed

This is the database specific option for the advanced users. If the “Indexed” checkbox is

ticked Aware IM will instruct the underlying database system to create an index for this

attribute. Creating a database index for the attribute can significantly speed up database

queries involving the attribute. If your database is likely to have lots of records of

instances of the business object that owns the attribute and end users are likely to

frequently perform queries on this attribute you may consider making the attribute

“indexed”. The “Indexed” option is not available for attributes owned by notifications.

Validate as

This dropdown allows you to select an Input mask that will control how validation of Plain

Text attributes is performed. For example, an e-mail address attribute needs to conform

to the input standards of the e-mail address, some attributes need to be alphanumeric

only etc. When you specify the input mask for the attribute Aware IM will perform

validation of the values entered by the user to make sure that they conform to the

Aware IM 8.8 User Guide

requirements of the input mask. There are several pre-defined input masks provided by

Aware IM and you can also define your own input masks. The input masks provided by

Aware IM are:

 E-mail

 URL

 Alpha (characters only)

 Alphanumeric (characters and digits only)

 US Phone (999) 999-9999

If you need to provide an input mask different from the above you can enter a regular

expression defining the mask. The regular expression must start and end with the “/”

symbol, for example:

/\\(?\\d{3}\\)? ?\\d{3}[-.]\\d{4}/

The information about format of regular expressions can be found in the Appendix E or

on the following site: http://www.regular-expressions.info/reference.html

If you want to re-use the same regular expression in different attributes you can assign a

textual name to your expression. To do this you have to modify the UIConfig.props file

located in the BIN directory of your Aware IM installation to add an entry representing

your expression. The entry must start with the “TextInputMask” prefix and contain the

name of the expression followed by the “#” symbol and then followed by the expression

itself, for example:

TextInputMask1=US Phone#/\\(?\\d{3}\\)? ?\\d{3}[-.]\\d{4}/

Once you define your expression in the UIConfig.props file you need to re-start the

Configuration Tool and the name of your expression will appear in the “Input Mask”

combo box.

SQL type

Aware IM automatically manages database for all attributes that the configurator defines,

so SQL types of each attribute are usually determined by default. It is, however, possible

to specifically indicate an SQL type to be used for a particular attribute, for example:

DECIMAL (2,10)

Attribute Presentation

All attribute types allow specifying presentation options for the attribute. These options

control how the input control displaying attribute value will be generated on a business

object form.

Aware IM 8.8 User Guide

NOTE: Presentation options specified for an attribute will be used by default when the

attribute is shown on forms unless a particular form section overrides the default options

– see Adding/Editing Form Sections.

The following presentation options are common to many attributes:

Label

Specify the label that will be displayed next to the input control. By default it will be the

name of the attribute (if this name has capital letters they will be replaced with spaces –

for example, if the attribute name is AccountBalance the default label displayed will

be “Account Balance”). You can also indicate an empty label.

Do not add ‘:’ after label

By default Aware IM will automatically add the colon symbol after the label, Ticking this

checkbox prevents this and the label is displayed as is.

Icon

Specify the icon that will be displayed together with the label next to the input control. By

default no icon is displayed. Click on the “Edit” button to specify the icon.

Description

If you want to provide the description of the attribute click on the “Description” property

to bring up the “Attribute Description” dialog. You can type it in in the “Description” text

area. If the “Show description underneath the control” radio button is selected the

description will appear underneath the input control representing the attribute on the

form (see the “Max Borrow Number” attribute on the picture below):

Aware IM 8.8 User Guide

If the “Show description as popup window” radio button is selected, a little icon will be

displayed next to the control representing the attribute. When a user moves the cursor

over this icon a small popup window containing the text of the description will be shown

– see the “Max Renewals” attribute.

If the “Show description to the right of input control” radio button is selected the

description will be shown to the right of the control – see the “Max Loan Period” attribute.

NOTE: You can enclose attribute description in HTML tags to improve its

presentation, for example: <p style=”color:#ff0000”>This description will be displayed in

red. </p>

Save form on selection change

This option is only valid if an attribute has choices. Ticking this checkbox will make the

sure that the form of the object will be saved as soon as the user chooses a different

choice in the selection.

Save form on focus loss

This option is only valid if an attribute does not have choices. Ticking this checkbox will

make the sure that the form of the object will be saved as soon as the user moves away

from the control representing the attribute.

Widget property (Radio buttons)

For many attribute types there is a “Widget” property that allows you to specify which

widget will be used to display the attribute. If an attribute has choices and no other

values other than choices are allowed it will be possible to select “Radio buttons” as a

widget type. In this case you will also be able to set the “Number of columns” property.

Widget property (Checkboxes)

This option is only available for an attribute of the Plain Text type and only if it has

choices defined. Selecting this option indicates that the user can choose multiple

choices and each choice is represented as a checkbox. Setting details of this option is

similar to setting options of radio buttons.

NOTE: Aware IM represents selected choices as a single delimited string. You must

make sure that the length of the attribute is no less than the string formed as a result of

concatenation of all possible choices (in case a user selects all checkboxes) plus

delimiters.

Aware IM 8.8 User Guide

Input control style

This property allows you to define styling properties of the input control of the widget –

colors, fonts, borders etc

Label style

This property allows you to define styling properties of the label – colors, fonts, borders

etc

Presentation rules

This property allows you to define conditions when certain presentation elements are

displayed. You need to define a condition and select the type of the presentation

element that the condition applies to. Then you need to define properties of the element

specific to the selected element type. If a condition is not specified the properties of the

element will be applied unconditionally.The following element types are supported:

 ICON – this element type controls how attribute will be displayed in different lists,

such as in query results or in reference lists. Instead of displaying a value for the

attribute you can display an icon representing the value.. For example, you can

display different icons for the Balance attribute of the Account object –

depending on the value of the balance. You can also display icon only or both

icon and value – this is specified when you define a query or set up presentation

options for references.

 STYLE – this element type allows you to specify different CSS style options for

particular attributes when they are displayed on forms. By default attributes are

displayed using predefined colors, fonts and other properties. The “Style” element

type allows you to override the default settings. For example, you can display

account balance in red if its value is less than 50 or in green if it is more than 50.

To do this define two styles with different color settings and specify a condition for

the first style as Account.Balance<=50 and for the second one as

Account.Balance>50.

 DISPLAY FORMAT – this element type allows you to display attributes on forms

or inside query results using a different format than the format defined in the

attribute itself. This can be especially useful when displaying numbers – you may

want to display numbers in different formats on different forms. You can even

store the format in an attribute of some object – in this case you should specify a

tag expression as the format value, for example

<<SystemSettings.NumberFormat>>

 LABEL - this element type allows you to specify different labels for attribute

depending on conditions

 ACCESS – this element type allows you to make an attribute visible or read-only

based on a condition. This can be especially useful if you define a presentation

rule for an attribute on a particular form – this way you can make attribute visible

or read-only on a particular form only

 REQUIRED – this element type allows you to make an attribute mandatory based

on a condition. This can be especially useful if you define a presentation rule for

Aware IM 8.8 User Guide

an attribute on a particular form – this way you can make attribute mandatory on

a particular form only

 INPUT MASK - this element type allows you to specify an unput mask for

entering text attributes on forms, which can be different to the mask defined in the

attribute itself. You can even store the input mask in an attribute of some object –

in this case you should specify a tag expression as the input mask value, for

example <<SystemSettings.InputMask>>

Script

For users who are familiar with Javascript this dialog allows specifying additional

attribute configuration parameters when attributes are initialized and displayed. See

Programmers Reference Guide for more details.

Setting Properties of Plain Text Attributes

The Plain Text attribute type represents text strings. Most properties you need to specify

for attributes of the Plain Text type are common to all attribute types – see Common

Properties. The properties specific to the Plain Text type are:

Maximum length

This value specifies the maximum number of characters that the text string representing

the value of the attribute may have.

Content

You can choose “Standard” , “HTML” or Color. If you choose “HTML” it is assumed that

the text represents HTML. A text in the HTML format is displayed as HTML on forms

and can be edited using the built-in HTML editor (see Presentation Options below). If

you choose “Color” it is assumed that the text holds color value and can be edited with a

special Color Picker widget. In queries such text is displayed as a color box by default.

Presentation Options

Some common presentation options, such as “label” and description are described in

Common Properties. You can also define the following properties for the Plain Text

attributes:

Widget

If text has no choices there are two types of widgets that you can choose from – “Text

box or “Text area”. In the latter case you can also specify the height of the text area in

pixels and indicate whether the user will see how many characters are left to type

(“Count characters” property). The value specified in the “Width” control specifies the

width of the generated text box or text area in number of characters or pixels (one or the

other). If you select “Text box” you can also specify whether the control represents a

password and whether the user is required to enter password confirmation.

Aware IM 8.8 User Guide

If the attribute has choices and “Other values allowed” is un-ticked then possible widgets

are “Combo-box” or “Radio buttons” and “Checkboxes”. If “Other values allowed” is

ticked the choices are “Combo-box”, “Checkboxes” or “Multi-selector”.

With the “Multi-selector” widget the user can make multiple choices from the drop-down

list - see the picture of the “Multi-selector” widget below:

Just like “checkboxes” the “Multi-selector” option implies that the attribute can store

multiple strings and so internally all selected choices are stored as strings separated by

a delimiter.

Widget property (HTML Editor)

This option is only available for text in the HTML format. If you select this option the text

will be edited on forms using the built-in HTML editor (see the picture below):

Aware IM 8.8 User Guide

You can then specify the width and height of the HTML editor and whether this editor will

support the “inline mode”. In the inline mode the toolbar of the editor will only be

displayed when the user starts editing the text – this saves some screen real estate.

Input mask

Use this property to mask user input and only allow particular characters during input.

This is different from the “Validate as” masking which allows any characters during input,

but performs validation according to the mask when the form is submitted. Character

masking, on the other hand, only allows certain characters to be entered in certain

positions. When you click on this property you can define your mask or select from a

number of predefined masks.

Setting Properties of Number Attributes

The Number attribute type represents floating point and decimal numbers. Most

properties you need to specify for attributes of the Number type are common to all

attribute types – see Common Properties. The properties specific to the Number type

are:

Format

The format basically indicates whether the number may have decimal point and also

how many digits should be displayed before and after the decimal point. The format is

specified as a text string with special symbols. The allowed special symbols are

described in the Appendix C. You can specify the format directly or click on the “…” icon

of the property to bring up the “Number Format” dialog. The following settings can be

specified on this dialog:

Number of digits before decimal point

If “Automatic” is selected (this is the default option) the number of digits before the

decimal point is not limited; there will be as many digits displayed before the decimal

point as the number has. If you specify a particular value instead of selecting the

“Automatic” option the number of digits before decimal point will always be equal to this

Aware IM 8.8 User Guide

value. If the number has fewer digits than the value specified, the remaining digits will be

displayed as zeroes. For example if you specified 4 as the number of digits before the

decimal point, number 10 will be represented as 0010.

Number of digits after decimal point

If zero is specified (the default) the number represents an integer and no decimal point

will be displayed. If some non-zero value is specified the number will be displayed with

the specified number of digits after the decimal point padded with zeroes if necessary.

Custom format

Type the symbols directly into the text box according to the conventions described in the

Appendix C.

Min. value / Max. value

If specified indicates the upper and/or lower limit that the value represented by the

number may take (both are inclusive). Note that it is possible to indicate both upper and

lower limits, lower limit only, upper limit only or no limits at all.

Aware IM 8.8 User Guide

Auto Incremented

If this property is defined Aware IM will automatically set values of this attribute

incrementing by 1 every time a new instance of the object that owns the attribute is

created. The benefit of using auto-incremented numbers compared to incrementing

numbers by rules is that the auto-incremented number is set into the database

immediately without waiting for the current database transaction to commit. This avoids

the potential problem of having two users having the same number if numbers need to

be unique.

When you click the “…” button of the property you can control how auto-incremented

numbers are applied:

Auto-increment every object instance

This is the default option. Every time the new instance of the object is created the

number will be incremented by 1.

Auto-increment within a group of object instances

Sometimes it may be necessary to increment numbers within a “group” of instances. For

example, you may want to have invoice numbers automatically incremented for

customers from different countries. Every country may have its own group of numbers.

In this case you select this option and then select the attribute of the object that identifies

a “group”, for example Country.

Initial Value

This determines the value for the first instance of the object or the first instance of the

“group” of instances. The default value is taken from the Value Range defined for the

number (if undefined 1 is used). You can also specify an attribute that will hold the initial

value.

NOTE: Aware IM increments values of numbers that do not involve groups of

instances BEFORE rules are evaluated for the object, so if rules use auto-incremented

attributes, their values will already have been calculated. However, if auto-incremented

attributes involve group instances their values are incremented AFTER rules are

evaluated. If you have to use incremented values for such attributes in rules, set the

auto-incremented values “manually” using the NEXT_SEQUENCE_NMB function, for

example:

IF Order.RefNo IS UNDEFINED THEN

Order.AutoIncremented = NEXT_SEQUENCE_NMB(‘Order’,

‘AutoIncremented’, Order.GroupValue)

Order.RefNo = ‘Order Prefix ‘ + OrderAutoincremented

Aware IM 8.8 User Guide

Presentation Options

Some common presentation options, such as “label” and description are described in

Common Properties. You can also define the following properties for the Number

attributes:

Widget

Most of the choices here are similar to the Plain Text attribute – “Text box”, “Combo-

box”, “Radio buttons” and “Checkboxes”. If the number has “Min. value” and “Max.

value” defined there is also an option to display the number using a slider or a rating

widgets. For the slider you can then specify the orientation, the increment value and

whether to display a tip.

NOTE: the Rating widget can be displayed not only on forms but also in standard and

custom queries. To display rating number as stars in a standard query go to the

properties of the corresponding column and tick the “Display rating widget” checkbox. To

display rating as stars in a custom query refer to the attribute in a custom template like

so: {AttributeName,rating}

Spinner

This checkbox indicates whether or not to generate a spinner control when displaying

the number attribute.

Setting Properties of Date, Timestamp and Duration

Attributes

The Date attribute type represents dates, for example 12/09/95; the Timestamp attribute

type represents date and time, for example 12/09/95 12:45 and the Duration attribute

type represents the duration of an event, for example 2 weeks 10 days 3 hours. Most

properties you need to specify for attributes of the Date, Timestamp and Duration types

are common to all attribute types – see Common Properties. The properties specific to

these types are:

Format

This is the format of the date, timestamp or duration. The format is specified as text with

special symbols. The following symbols are most frequently used:

- d – day in month (number of days for duration)

- M – month in year

- y – year

- h – hour (1-12)

- H – hour (1-24) (number of hours for duration)

- m – minute in hour (number of minutes for duration)

Aware IM 8.8 User Guide

- s – seconds in hour

- w – number of weeks (duration specific)

For example, first of June 2004 will be displayed as 01/06/2004 if the format is specified

as dd/MM/yyyy.

Rather than specifying the explicit format of the attribute you can choose “Take from

locale” option if your application supports multiple languages. In this case the actual

format of the attribute will be defined by the currently used locale – see Creating

Applications in Different Languages.

Presentation Options

Some common presentation options, such as “label” and description are described in

Common Properties. You can also define the following properties for the Date,

Timestamp and Duration attributes:

Use browser control

By default Aware IM displays its own controls for Date and Timestamp attributes. These

conrols include calendars and drop downs for the selection of time. Some browsers

(especially mobile browsers) have their own controls for representing date and time.

Select this property to use native browser controls for representing date and time.

Time interval, Time min. value, Time max. value

These properties are only available for the attribute of the Timestamp type. Timestamp

control is displayed as a combination of the date control and time control. The time

control represents a drop down of times. You can specify the time increment and the

boundaries for the values displayed in this drop down. Note that if the format of the

Timestamp only includes time (for example, HH:mm) only the time control will be

displayed.

Setting Properties of Reference Attributes

Reference attributes are explained in detail in the Reference Attributes section.

Entering or editing values of reference attributes on a form of a business object in the

Operation Mode is somewhat different to other attribute types.

To provide a value of a reference attribute is to indicate that the instance of the business

object being created or edited is related through this attribute to one or more instances

of another business object. For example, an Account object can be configured to

contain a list of its transactions in a reference attribute called MyTransactions. Thus a

particular instance of the Account object can be related to a number of instances of the

Transaction object.

Aware IM 8.8 User Guide

To display a value of a reference attribute is to display a list of instances of related

business objects (or maybe just some members of this list).

When displaying a form containing reference attributes Aware IM generates the

appropriate controls required to display, enter or edit values of such attributes. An

example of a reference attribute is shown on the picture below:

The instances of the objects related to the instance currently being edited are shown in a

table where each row represents an instance of a related object. Table columns show

values of certain attributes of the related objects (which attributes will be shown can be

defined at the configuration stage – see Presentation Options for References).

The buttons in the rightmost columns of each row allow performing operations with the

related instance represented by a particular row. The list of operations is configurable –

see Presentation Options for References. In the example above the “Edit” operation

represented by the “Edit” button brings up a form of a related business object.

Configuring References

When configuring references the following properties must be specified:

Multiple allowed

If this checkbox is ticked the reference represents a “multiple” relationship, otherwise a

“single” relationship.

Aware IM 8.8 User Guide

Matching data

Click on this property to define relationship type (“Peer”, “Owner of” or “Owned by”) and

matching attribute in the referenced object. When defining a matching attribute select

the “None” radio button if the reference attribute represents a non-matching relationship;

if the reference attribute represents a matching relationship select either “Create” or

“Existing” radio buttons.

Create

The “Create” option is available if the new reference attribute is being created or the

reference attribute represents the non-matching relationship. Selecting this option will

create the matching attribute on the referred business object when changes to the

current business object are saved. If you select the “Create” option you must also

specify the name of the matching attribute on the referred object (the name must meet

the requirements imposed on the attribute names – see Common Properties). If the

referred object is a business object group the matching attribute is created for all

members of the group. You can also specify whether the matching attribute created will

be “multiple allowed” or not.

Existing

The “Existing” option is available if the new reference is being created or the reference

attribute represents the non-matching relationship and there is an attribute on the

referred business object or group that refers to the business object being edited through

a non-matching relationship. In this case we are “binding” two non-matching

relationships in one matching relationship. As there may be several attributes on the

referred object having non-matching relationship with the object being edited you may

need to select the attribute you want.

Matching relationships are not applicable to attributes owned by notifications.

Presentation Options for References

For reference attributes presentation options define how instances of the referred object

are displayed (if at all) on a business object form. There are several ways the referred

instances can be displayed on a form – as a table, as a list (either a combo box for

single references or a list box for multiple references), as a tree or as a calendar.

When the referred instances are displayed as a table usually only a few instances (the

most significant ones) are displayed on the form. Also, usually values of only certain

attributes of the referred instances (the most significant ones) are displayed on the form.

To display all attributes of a referred instance the user can press the Edit button next to

the referred instance entry in the table to bring up a form of the referred object. Aware

IM also provides buttons to add and remove instances of the referred object as well as

perform operations with the referred instances. An example of such a table is shown in

the Working with References in the Operation Mode section.

Aware IM 8.8 User Guide

When the referred instances are displayed as a combo box (for single references) or a

checkbox list (for multiple references) all instances of the referred object are always

displayed. Specific instances that are referred to by the object are selected (only one is

obviously selected in a combo box). Therefore this option is only recommended when

there are not many instances of the referred object in the system so that all of them will

fit into the combo box or the list box. In this case this option is preferable because the

user will see all instances she can choose from on the form. For example, a Car object

may refer to a CarModel object. There are only a fixed number of instances of a

CarModel object so a reference to a CarModel on the form of the Car object may be

represented as a combo box.

The details of the presentation options that can be specified on the Presentation dialog

for references are explained below:

Label

This is the label that will be displayed next to the input control. By default it will be the

name of the attribute (if this name has capital letters they will be replaced with spaces –

for example, if the attribute name is AccountReference the default label displayed will

be “Account Reference”).

Widget

This is is the most important presentation property that determines how the reference

attribute will be presented to the user. The choice of the widget depends on whether it is

a single or multiple reference attribute. For multiple references possible widget types are

“Grid”, “Checkboxes”, “Swap Select”, “Multi-selector”, “Chart”, “Custom List” “Timeline”

or “Tree”. For single references possible widget types are “Grid”, “Combo-box”,

“Checkboxes”, “Tree” and “Form”. Once you select the widget type you need to provide

settinsg of the widget in the “Widget settings” property. Widget settings obviously

depend on the selected widget.

Grid widget

With this widget type referred instances are represented as a standard table (or grid)

This is described in the “Displaying References as a Table” section.

Drop down widget

This option is only applicable for single references. Choose this widget type to display a

referred instance as the current selection in a combo box. The choices in the combo-box

display possible other instances to choose from and set as a referred instance. The

following properties are available for this widget type:

Aware IM 8.8 User Guide

Fetch records

Two choices are available – “Fetch all records” or “Fetch records as user types”. You

can choose the first option to get Aware IM to fill up the combo box with all existing

instances of the referred object for the user to choose from. Select this option when

there are not too many instances of the referred object in the database.

Choose the second option to get Aware IM to fill up the combo box dynamically. The

user will be able to type in values in the combo box. As soon as the user finishes typing

Aware IM will fill up the combo box with those instances of the referred object that start

with or contain values entered by the user. Select this option if there are a large number

of instances to choose from.

Empty Text

If you type any text into this property the drop down will include the specified text when it

has no value

Mobile style choices

If this checkbox is ticked the drop down pops up from the bottom of the screen. This is

especially useful for mobile applications

Save form on selection

If this checkbox is ticked the form will be saved every time the user selects a value in the

drop down

Include empty text in choices

If this checkbox is ticked Aware IM will add a blank record (if empty text is defined) or

the empty text (if it is defined) into the list of choices. This makes it possible for the user

to “clear out” the value

Page size

If this property is specified the drop down will display one page at a time, so that the

user can choose the page he wants to see. This is useful if the drop down shows large

amount of data

Operations

You can optionally specify the following operations – Add New Reference, Add

Reference, Edit Object, Delete Object and Execute Javascript. The icons representing

these operations will be displayed next to the dropdown.

Displayed columns

By clicking on this property you can specify which attribute(s) of the referred object will

be displayed in the drop down (usually just one). If you select more than one, they will

be separated by spaces if you select the Standard style of display (the Standard radio

button). If you select this radio button you can also optionnaly specify the custom

template with which the data will be displayed - defining this template is similar to

defining custom data template for custom query presentation – see Displaying Query

Aware IM 8.8 User Guide

Results. The picture of a custom drop down that uses an image, a bold subject on the

first line and the description on subsequent line is shown below:

If you select the “Multii-Column” style the combobox will be displayed with the header at

the top that will show the names of the columns (just like a standard grid). Here you can

also specify the widths of the columns, column labels and even the template of the data

display. Displayed columns in a multi-column drop-down can include attributes of the

Picture type.

HTML Box widget

This option is only available for single refereces. Use it if you want to represent the

reference as read-only HTML. When specifying HTML you can use tag expressions to

Aware IM 8.8 User Guide

refer to the attribute values of the reference, for example <<Account.Customer.Name>>.

You can also define operations (Add New Reference, Add Reference, Edit Object,

Delete Object and Execute Javascript) – the icons representing operations will be

displayed next to the HTML box

Checkboxes widget

Use this widget type if you want references to be displayed as a list of checkboxes. This

list shows all possible instances of the referred object and the instances referred to by

the attribute are ticked. The option should only be used if the list of all instances is not

too large.

The settings of this widget are similar to the “Grid” widget.

Swap select widget

This option is similar to the checkbox list in that it shows a list of all possible instances

and instances referred to by the attribute. The user moves instances from one list to

another – see the picture below. Just like checkbox list this widget should be used only if

the list of all instances is not too large.

Aware IM 8.8 User Guide

Multi-select drop down widget

This widget is similar to the “multi-selector” widget used for text attributes. See the

picture below:

Calendar widget

Choose this widget type if you want references to be displayed in a calendar-like fashion

(see Calendar Form of Query Results). Note that only references of the Appointment

type can be presented in this manner. The settings you can specify are similar to the

ones you specify when configuring a calendar query.

Chart widget

Choose this widget type if you want references to be displayed as a chart (see

Displaying Query Results). The settings you can specify are the same as when

configuring a chart.

Custom list widget

Choose this widget type if you want references to be displayed as a custom presentation

of a query (see Displaying Query Results). The settings you can specify are the same as

when configuring custom presentation of a query.

Timeline widget

Choose this widget type if you want references to be displayed as a timeline of events –

see the picture below. See also the “Displaying Results as Timeline of Events” section in

Displaying Query Results

Aware IM 8.8 User Guide

Record sorting/Filtering

Using this property you can specify whether referred instances will be sorted or filtered

in any way. Clicking on this property brings up the “Record Sorting/Filtering” dialog. The

“Record Filtering” section of the dialog allows setting up a filter to show only referred

instances that match the specified criteria. You can specify these criteria by specifying a

query (either choose the existing query or specify the custom one). For example, it is

possible to show only open accounts of a client (the query will be FIND Account

WHERE Account.Status=’Open’).

Aware IM 8.8 User Guide

TIP: using different filters you can display different referred instances of the same

reference attribute. For example, you could show open accounts of a client on one form

section and closed accounts on another form section – see Adding/Editing Form

Sections.

Existing query

If you select the “Existing query” radio button you must select the existing query (see

Adding/Editing Queries)

Custom query

If you select the “Custom query” radio button you must specify the query – press the

Edit button located next to this option and specify the query details – see Adding/Editing

Queries.

Clicking on the attribute in the “Record Sorting” table allows sorting the list of references

by the value of the attribute displayed in the column.

See also:

Displaying references as a table

Displaying references as a tree

Displaying references as a table

This section describes how to define settings of the “Grid” widget type When you click on

the “Widget Settings” property the “Standard Grid Sattings” dialog is displayed. You can

define the following settings on this dialog:

Items per page

Specify how many instances of the referred object will be shown in the table by default.

Aware IM 8.8 User Guide

Width/Height

Specify the width/height of the reference table in pixels. The default width will

accommodate all data in the table.

Allow inline editing

Tick this checkbox if you want to be able to add and edit instances of the referred

objects directly inside the table (see the picture below):

The table of Items on this picture shows Purchase Order Items on the form of the

Purchase Order object. Note that Purchase Order Items can be edited directly on the

form of the Purchase Order. If you click on the “Add New” button a new row will be

inserted.

You can even add/edit references of the referred objects inline. In the example above

each Purchase Order Item refers to a Product. To add/edit references inline you need to

define a shortcut to the reference you want to edit inline and include this shortcut into the

list of attributes to be displayed on the form. In this example Purchase Order Item

defines a shortcut to the referred Product and this shortcut is included into the list of

attributes displayed in the table of Purchase Order Items on the form of the Purchase

Aware IM 8.8 User Guide

Order object. When a user clicks on the Product cell to edit it Aware IM will display a list

of existing Products and the user will be able to pick a particular Product.

Use popup editor

This option is only available if inline editing is on. If the checkbox is ticked inline editing

will be performed for the entire row by a special popup editor.

Show column menu

If you tick this checkbox each column header in the table will have a button that allows

user to hide/show certain columns.

Show paging bar

If you tick this checkbox paging bar is displayed for the table. You can further control

how paging bar is displayed if you click on the More… button

Select first record

If you tick this checkbox the first record in the table will be selected when the table is

displayed. Using this option is especially useful if you also define a default item

operation for the table (see below). In this case this operation will be automatically

executed for the first record when the table is displayed.

Number rows

Tick this box to show item numbers next to each row

Operations with items

The Operations table shows operations that can be invoked with the instances of the

referred object. The operation types are similar to those configured for form operations.

Hyperlinks containing the names of the operations will be located next to the entry

representing the instance in the list. User invokes the operation by pressing on the

corresponding hyperlink (see the picture in the “Item Display Rules” section below). If

any applicability conditions are defined for the operation the hyperlink will appear only

for those instances that satisfy the applicability condition.

Press the Add button to define a new operation, Edit button to edit the existing operation

and Delete button to delete the existing operation. One of the operations can be marked

as a “default” operation. If such operation is defined it will be executed when the user

clicks on any item of the record, not just the operation hyperlink. In addition, if “Select

first record” option is ticked, the default operation will be automatically executed for the

first record.

Attributes to display

This option allows you to select which attributes of the referred object will be displayed

on the form. To specify which attributes will be displayed tick the “Displayed” checkbox

next to the required attributes. Use the Up and Down arrow buttons to change the order

in which attribute values will be displayed. You can also specify how the attribute will be

Aware IM 8.8 User Guide

displayed – the value of the attribute only, the value and icon or the icon only. Icons are

displayed according to the presentation rules for ICON elements – see Common

Properties.

Apart from the “Widget Settings” property you can set the following properties when

using the “Grid” widget:

Description

This option allows you to define the description of the attribute. It will be displayed as a

tip for the user.

Panel Operations/Buttons

This option allows you to define buttons that will be displayed on the toolbars around the

table – see Add/Edit Panel Operations for details.

Item Display Rules

This option allows you to highlight certain items in the list of the referred instances by

displaying them in different colors or font styles. Pressing the Item Display Rules button

invokes the “Display Rules dialog”. In this dialog you can specify colors, fonts and other

CSS properties of the highlighted items as well as conditions identifying which items will

be highlighted. Conditions are specified in the green cells whereas colors and fonts are

specified in the Style Dialog invoked by pressing the “Set Style” button. The following

picture shows the example of an item rule. In this example the Customer object has a

multiple reference to the PurchaseOrder object (the Orders attribute). Each referred

order is displayed differently depending on the state of the order: If the state of the order

is NEW it is displayed with a yellow background. The condition entered into the item rule

is: PurchaseOrder.State = ‘NEW’. The style used for this condition is the yellow

background color:

Aware IM 8.8 User Guide

Grouping

Click on this property to group referred instances based on the specified attribute. All

instances with the same value of the attribute will be displayed together. It will be

possible to expand and collapse the node with these values and specify summaries per

group

Drag-and-drop/Reordering

Clicking on this property allows you to enable users to reorder items in the table or drag

and drop records between different grids. This is explained in detail in the “How to

implement Item Reordering” and “How to implement drag-and-drop between grids”

sections of the “How To” Guide.

Resizing

Select this property to allow users to resize the table and specify minimum and

maximum sizes for the table

CSS Style and CSS class

These properties allow advanced users to customize the appearance of the table using

CSS styles and classes. See the “How to use CSS” section in the How To Guide for

more details.

Expansion of rows

Select this property to specify what happens when the row in the table is expaned. See

Add/Edit Queries for more details.

Filters

Select this option to assign filters to certain columns in the table. See Add/Edit Queries

for more details.

Script

Use this option to control behaviour of the table using Javascript. See Programmers

Reference Guide for more details.

Displaying references as a tree

Select the “Tree” widget type to display references as a tree. In this tree each node

representing a referred object may also have sub-nodes representing referred objects of

this object and so on.

Most of the options that you can specify for the tree representation are the same as for

the table representation. Tree-specific options are explained below:

Expand all levels

Tick this checkbox to get the tree to automatically expand nodes at all levels.

Aware IM 8.8 User Guide

Tree contents

Clicking on this property brings up the “Tree Contents” dialog. There are two radio

buttons in this dialog. Select the “Show all objects in the tree” radio button if you do not

want to impose any limitations on which objects should be included in a tree. When you

select this option all references of the encountered objects will be included in the tree.

Select the “Show types selected in the table below” radio button if you want to impose

limitations on which business objects and attributes should be included in the tree. You

will then need to define which robjects you want the tree to show.

In the pane on the left you can choose which business objects will be included in the

tree by ticking the box next to the object’s name. When you do this reference attributes

of this object will be displayed in the right pane. You can either select that all reference

attributes of the selected object will be considered when building a reference tree or

select particular attributes by ticking a box next to the attribute’s name. You can also tick

a box indicating whether the details of the selected object should be displayed in a tree.

This may be useful if you want to consider reference attributes of the object in a tree, but

you don’t actually want to display the details of the object itself.

One of the common examples of selecting particular references to be shown in a tree is

when you have a hierarchical object and you want to display this hierarchy in a tree. In

the example shown on the picture below the Part object has Components attribute that

also refers to the Part object – in other words, a Part can have other Parts, which can

have their own Parts etc. If you want the tree to show this hierarchy you would select the

Part object and its Components attribute to be displayed in a tree, but not any other

objects or attributes. The result is show on the picture below:

Aware IM 8.8 User Guide

Note that inline editing is available for references of the first level when only one object

is displayed in a tree (Part object in this case).

Diagram of Object Relationships

You can easily see all relationships between objects in your application if you right click

on the business space version and select the “Relationships Diagram” from the popup

menu (or select this menu item from the “Version” menu). You will see a picture that

looks something like this:

Aware IM 8.8 User Guide

This shows all business objects and business object groups in the application –

business object groups are shown with the blue edge. If there is a relationship between

an object and another object or group you can see an arrow from one object to another.

You can also see whether a relationship on either side is single or multiple (1 or 0…*). If

you click on the relationship you can see relationship attributes in the objects that

represent this relationship. You can drag objects around if necessary for better viewing

and you can zoom in/zoom out if you click on the corresponding buttons in the toolbar.

If you click on the “Settings” button you can specify height and width of the box

displayed for each object and you can also remove some objects from the diagram by

selecting those attribute that don’t need to be displayed. You can click on the “Exclude

non-referenced” button to exclude all objects/groups that do not have any relationships

from the diagram. You can also save settings under a particular name by clicking on the

Save button and then load them by clicking on the Open button. This can be useful if

you want to view different parts of a complex diagram – by selecting only the objects you

want and then saving selection.

Probably the best thing about this feature is that you can create/delete relationships

directly on the diagram. Creating a relationship can be done either by pressing the “Add

relationship” button on the toolbar or directly dragging a connector between those

objects that you want to create a relationship for.

When you create a relationship using the “Add relationship” button you need to select

the objects you want to create a relationship for and then specify the name of the

attribute either on the one side of the relationship or on both sides (if the relationship has

matching attribute). You also need to specify the type of the relationship on each side

and whether it is multiple or single.

Aware IM 8.8 User Guide

To create a relationship by dragging a connector click on one of the objects in the

relationship – this will display black circles around the object to indicate that it is

selected:

Then hover the mouse over one of the black circles:

Aware IM 8.8 User Guide

and start dragging a connector to another object from this point:

Aware IM 8.8 User Guide

When you release the mouse the dialog will popup where you can specify the remaining

properties of the new relationship – attribute names, types and cardinality.

To delete a relationship click on the arrow representing the relationship and click on the

“Delete” icon that pops up (or press the Delete key on the keyboard).

Setting Properties of Picture Attributes

The Picture attribute type represents images (pictures). When an attribute of this type is

shown on a form of the business object that owns the attribute Aware IM generates the

Browse button that allows the user to attach a particular image as an attribute value

(only image files, such as .gif, .jpeg, .bmp files should be attached). The image is

displayed on the form (see the example below):

Aware IM 8.8 User Guide

Most properties you need to specify for attributes of the Picture type are common to all

attribute types – see Common Properties. The properties specific to the Picture type are

described below.

Picture represents signature

Tick this checkbox if a picture attribute stores an electronic signature of the user. If this

option is on at runtime Aware IM will show the box in which the user can provide his

signature by using the mouse (or fingers/stylus pen on mobile devices). The signature

will then be stored as a picture in the attribute.

Stored in

You can specify where the images uploaded by the user for the picture attribute will be

stored. By default all images are stored in the database, but you can also store images

in the file system on disk or in Amazon S3 storage.

Database

This is the default option. Images will be stored by Aware IM in the database. You don’t

need to specify anything else.

File System

If you select the File System option images will be stored in the file system of the server

where Aware IM is running. The exact location of the image is determined from the

value of the specified expression. For example, if the file path of the image is stored in

the Path attribute, the expression should be Object.Path, where Object is the name of

the object that owns the attribute.

Aware IM 8.8 User Guide

Amazon S3

If you select the Amazon S3 option images will be stored in the Amazon S3 storage

system. You need to do the following:

 Create an account with Amazon at this URL: https://aws.amazon.com

 Create an IAM user using the IAM console.

 Open the Security Credentials tab and click on the “Create Access Key” button.

 In the resuling dialog box click "Show User Security Credentials" to view the IAM

user’s access key ID and secret access key.

 Click the Settings button in Aware IM next to the “Stored In” property and enter

the access key ID and secret access key in the dialog that opens (note that this

has to be done just once – if you have another attribute which is stored in

Amazon S3, you don’t need to do it again).

Just like with the File System storage you also need to specify an expression that holds

the path to the image in the Amazon S3 storage. This path includes the name of the

AWS bucket and the name of the AWS region:

https://AWSBucketName.s3-AWSRegionName.amazonaws.com/AWSObjectName

For example, if you store the name of the bucket and region in the corresponding

attributes of the SystemSettings object the path may look like this:

'https://' + SystemSettings.AWSBucketName + '.s3-' + SystemSettings.AWSRegionName

+'.amazonaws.com/' + AttributeName + '_' + Object.ID

where Object is the name of the object that owns the attribute.

Max. file size

If specified the value indicates maximum image size that can be stored in this attribute. If

the user uploads a larger image, the image will be automatically rejected.

Allowed extensions

This property specifies file extensions that can be stored in the attribute. If user uploads

an image with a different extension it will be rejected.

Display settings

This property describes presentation settings specific to the picture:

Display picture as circle

Tick this checkbox to show the picture as a circle like on the form above

Thumbnail and actual representation

A picture can be represented on a form or in a query results as a smaller (thumbnail)

version of the actual image. If you want to present a smaller version of the image you

have two options:

Aware IM 8.8 User Guide

 Load two different versions of the image and store them in different attributes of

the object

 Load and store just one image and get Aware IM to scale it down automatically

when displaying it on forms or query results

When you select the first option you need to provide the name of another attribute in the

business object (of the Picture type) that would store the larger (actual size) version of

the image. When you select the second option you can specify the scale in which the

image will be displayed on forms and query results independently.

You can also tick the “Show actual representation when thumbnail is clicked” checkbox.

If you do this Aware IM will show the larger (actual size) version of the image when the

user clicks on the thumbnail. The larger version will be shown regardless of whether the

larger image is stored in the same or different attribute. The larger image will be shown

using the popular “lightbox” technology.

Embed image data into HTML

When a picture stored in the database or in the file folder outside of the web application

directory (AwareIM/Tomcat/webapps/AwareIM is displayed to the user, by default

Aware IM extracts the picture from the database and creates a temporary file. This file

is then used by the browser to display the picture. To prevent accumulation of temporary

images you can tick the option to embed the image data into HTML. In this case Aware

IM will encode the image data into the HTML itself, so that the data is directly given to

the browser without the need to create a temporary file.

Allow cropping and resizing

If this checkbox is ticked users will be able to crop and resize the image before it is

saved

Setting Properties of Document Attributes

The Document attribute type represents document files. The term “document” here has

relatively broad sense. Usually document files are reports in the PDF format or MS Word

or MS Excel files, however, essentially any file can be treated as document (see also

Document Management). When an attribute of this type is shown on a form of the

business object that owns the attribute Aware IM generates the Browse button that

allows the user to attach any file as the attribute value.

Most properties you need to specify for attributes of the Document type are common to

all attribute types – see Common Properties. The properties specific to the Document

type are explained below:

Initial Value

The initial value property for attributes of the Document type are different from the Initial

Value property of other attribute types explained in the Common Properties section. You

can only initialize the attribute of the Document type with the name of a Document

Aware IM 8.8 User Guide

template defined in the business space version (see Adding/Editing Document

Templates) or not nitialise the attribute at all.

If you initialize the attribute with the name of a document template Aware IM will

automatically generate a document from the document template when the business

object owning the attribute is created (see Document Generation).

Stored in

You can specify where the documents will be stored (Database, File System or Amazon

S3) – see the explanation for the Stored In property of Picture attributes above.

Max. file size

If specified the value indicates maximum image size that can be stored in this attribute. If

the user uploads a larger document, the document will be automatically rejected.

Allowed extensions

This property specifies file extensions that can be stored in the attribute. If user uploads

a document with a different extension it will be rejected.

NOTE: If you select “Embedded Spreadsheet” from the list of allowed extensions you

will be able to edit the document at runtime using the Excel-like spreadsheet interface.

For more details about this please read the “How to work with embedded spreadsheets”

section in the How To Guide.

Zoho editing

This checkbox allows users to edit documents in-place using Zoho editors

(www.zoho.com) . Zoho provides powerful web-based editors to edit many types of

documents – MS Word, MS Excel, MS Power Point, Open Office, RTF, HTML etc. The

user edits the document using the browser and when he presses the Save button the

modified document is automatically saved in Aware IM. The details are explained in the

“How to let users edit documents” section in the How To Guide.

Office Online editing

This checkbox allows users to edit Microsoft Office documents in-place using Office

Online editors. The user edits the document using the browser and changes are

automatically saved in Aware IM. The details are explained in the “How to let users edit

documents” section in the How To Guide.

Setting Properties of Shortcut Attributes

Attributes of the Shortcut type are necessary when you want to display the value of an

attribute of the referred object on a business object form or in query results. For

example, if there is an Employee object that refers to the Company object via the

Employer attribute and the Company object has the Name attribute, it may be

necessary to display the company name on a form of the Employee object. This may be

Aware IM 8.8 User Guide

achieved by defining an attribute of the Shortcut type in the Employee object called

CompanyName. The path to the referred attribute will be Employer.Name. This path is

called the shortcut path. In this example it needs to be defined as the property of the

CompanyName attribute. The value of the attribute referred through the shortcut path is

always displayed as an un-editable label on a business object form.

NOTE: A shortcut path may only be via a single reference – multiple references are

not acceptable as it is not clear the attribute value of which particular instance of the

referred object should be displayed.

NOTE: The Shortcut type is not available for attributes owned by notifications.

The following properties specific to the Shortcut type should be specified:

Path

This is the shortcut path explained above. It must start with the name of a single

reference attribute defined in the business object followed by the name of the attribute in

the referred object (note that nested references are allowed provided that all references

mentioned in the path are single references). You can also press F3 to bring up the

Context Assistant while typing the path.

Presentation Options

You can specify the label that will be displayed next to the attribute value of the referred

object. By default it will be the name of the attribute. You can also optionally specify the

description of the attribute that will appear underneath the attribute value.

Setting Properties of Yes/No Attributes

Attributes of the Yes/No type are useful when the attribute value is either Yes or No.

Attributes of this type are either shown as checkboxes or as switches with the On and

Off state. The properties that you can specify for the attributes of the Yes/No type are:

Initial Value

See Common Properties. Allowed initial values are Yes, No, Y, N, On, Off.

Presentation Options

You can specify the label that will be displayed next to the checkbox or switch

representing the attribute on the business object. By default it will be the name of the

attribute. You can also optionally specify the description of the attribute that will appear

underneath the input control of the attribute. For switches you can also specify strings

that correspond to the “On” and “Off” states.

Aware IM 8.8 User Guide

Adding/Editing Rules

Rules can be defined in a number of places in the Configuration Tool:

- When rules are attached to a business object (see Business Rules as Carriers of

Business Logic). There are several ways to invoke the editor of rules attached to a

business object:

- When rules are defined as process implementation or to handle process failure – see

Adding/Editing Processes.

- When rules are attached to a notification to specify what happens after the

notification has been received or created.

Rules of a business object, process or notification can be managed on the

corresponding tabs of the respective editor. For example, to edit rules triggered when an

object is updated or created, open the business object for editing and go to the “Update

Rules” tab. The following sections describe how to manage rules on these tabs.

Working with Rule Collection

Setting Filtering Options

Context Assistant

Working with Rule Collection

Rules (or rule collections) are displayed as a table where each row in the table displays

the name of the rule and its textual representation. The table (with its toolbar) is

displayed in the top half of the screen. When you select a particular rule the rule editor

for the selected rule is displayed in the bottom half of the screen and the properties of

the selected rule are displayed in the Selection Property window (see the picture below):

Aware IM 8.8 User Guide

To add a new rule click on the icon in the toolbar at the top to the table. The Rule

Dialog will be displayed where you can specify the name of the new rule and then the

new entry will appear in the table. You can then enter the text of the rule in the Rule

Editor below and set its properties in the Properties window.

To edit an existing rule click on the rule entry in the table and modify the text of the rule

in the Rule Editor below and/or set its properties in the Selection Properties window.

To delete a rule, click on the rule entry in the table and then click on the icon in the

toolbar at the top of the table.

To change the order of rules in the rule collection, select the rule and press the Up or

Down icons at the top of the table. Note that changing the order of rules in a collection is

only relevant to rule collections implementing processes that have “Maintain rules order”

flag checked – see Adding/Editing Processes.

Aware IM 8.8 User Guide

NOTE: If you are editing rules attached to a business object Aware IM checks the

names of the objects used in rules. If you use an object name different from the name of

the object that the rules are attached to, Aware IM may issue a warning message when

the rules are saved. This behaviour safeguards you against mistakes when specifying

object names in rules. If you intentionally specified a name different from the name of

the object that the rules are attached to (for example, to use some other object in the

Context) you may ignore the warning message.

Adding/Editing Individual Rules

The text of individual rules is specified in the Rule Editor displayed below the rule

collection table when a particular rule is selected.

The Rule Editor has two tabs – Standard View and Textual View. The Standard View

and the Textual View tabs are two different ways of representing a rule. You can switch

between the tabs to see how the same rule is represented in both views.

Irrespective of which tab you are in, the following rule properties are always visible:

Adding/Editing Rule using Standard View

The Standard View tab of the Rule Editor allows specifying rules in a simpler format

compared to the Textual View. Specifically it is not necessary to type “If” and “Then”

keywords required by the Rule Language.

The Standard View consists of two areas – the area where you specify rule conditions

(displayed in green) and the area where you specify actions (displayed in yellow). The

rule conditions area is the table where each row represents a single condition. A rule

may have multiple conditions connected with AND or OR keywords. You can enter a

condition by clicking on the row in the table and typing the text of the condition directly

into the table. If a rule has more than one condition the conditions will be linked with the

AND keyword by default. To change the keyword click on the last column in the table

and select OR from the combo box that gets displayed. Note that AND or OR keywords

can be entered as part of the condition as well (see the second example below). If your

rule has more conditions than the number of rows currently displayed in the table click

on the icon at the bottom of the editor.

The Actions area is the table where each row represents a single action. To edit an

action, click on the action row in the table. If your rule has more actions than the number

of rows currently displayed in the table click on the icon at the bottom of the editor.

At any time when editing rule conditions or rule actions you can press F3 or F4 to bring

up the Context Assistant.

Let us consider some examples:

Aware IM 8.8 User Guide

If Policy.ExpiryDate < CURRENT_DATE AND Policy.Owner IS DEFINED

Then

SEND ReminderLetter TO Policy.Owner

Policy.LetterSent = ‘Yes’

To enter this rule in the Standard Form tab you would need to enter the following

conditions into the conditions table:

1. Policy.ExpiryDate < CURRENT_DATE (AND)

2. Policy.Owner IS DEFINED

Note that the AND keyword displayed in brackets will be automatically added by Aware

IM into the last column of the conditions table.

The following actions would need to be entered into the Actions table:

1. SEND ReminderLetter TO Policy.Owner

2. Policy.LetterSent = ‘Yes’

Let us look at another example:

If (Policy.Owner.Age > 70 AND Policy.Owner.Exempt = ‘No’) OR

(Policy.Owner.PostCode < 2030 AND Policy.Garage= ‘No’) Then

Policy.Premum = 300

To enter this rule in the Standard Form tab you would need to enter the following

conditions into the conditions table:

1. Policy.Owner.Age > 70 AND Policy.Owner.Exempt = ‘No’ (OR)

2. Policy.Owner.PostCode < 2030 AND Policy.Garage= ‘No’

Note that the AND keywords in the first and second conditions are entered as part of the

conditions whereas the OR keyword displayed in brackets must be set in the last column

of the conditions table.

NOTE: You cannot enter rules that have “Else” statement using the Standard View –

use the Textual View instead.

Adding/Editing Rule using Textual View

The Textual Form of the Rule dialog allows users to enter rules exactly as they are

specified in the Rule Language. If the rule has syntax error the error message will be

displayed at the bottom part of the tab and the location of the error will be highlighted.

At any time when editing rule conditions or rule actions you can press F3 or F4 to bring

up the Context Assistant.

Aware IM 8.8 User Guide

NOTE: You can use comments anywhere inside rules specified in the Textual View.

Comments are specified between /* and */ symbols, for example:

IF SomeCondition THEN

/* ActionOne */

ActionTwo

Comments in rules are ignored when the rule is evaluated.

Rule Properties

The following properties can be specified in the Selection Properties window:

Name

This is the mandatory name of the rule. Any identifier is allowed.

Description

This is the description of the rule. Providing a description is highly recommended. Any

description if defined is included into the generated documentation for the business

space version – see Generating Documentation. To provide the description of the rule,

click on the Description button next to the rule’s name. The Configuration Tool will

display the Description dialog – enter the description and press OK.

Enabled

Ticking this checkbox will enable or disable a rule. When the rule is disabled it does not

participate in the evaluation of rules by the Rule Engine.

Priority

The rule priorities are described in details in the Rule Priorities section. By default

Aware IM will assign a priority to the rule based on the rule actions. Actions that modify

attributes will have the highest priority whereas actions that call pre-defined operations

(such as FIND, SEND etc) will have lower priority while actions that initialise documents

from templates will have the lowest priority. You can set rule priority explicitly and

override automatic detection of priorities.

While loop

The rules supporting the semantics of a “while” statement are explained in detail in the

While Semantics section. If you tick the “while loop” checkbox, the conditions of the rule

will be checked repeatedly – immediately after the execution of the rule’s actions.

Form initialiazation

Initialization rules are explained in detail in the Initialization Rules section. Basically

when the user creates an instance of a business object the appropriate form of the

business object is displayed. The form is initialized with values calculated after

evaluation of certain rules attached to the business object. Only initialization rules are

evaluated. You can get Aware IM to automatically determine which rules are considered

Aware IM 8.8 User Guide

to be initializtion rules by selecting the “Automatic” option (default) or you can explicitly

indicate whether the rule should be evaluated during form initialization or not.

Note that these options are only available for rules attached to a business object.

Dynamic

Sometimes it may be necessary to dynamically re-calculate attribute values on forms

while the user is making changes. For example, you may have a calculation rule that

calculates value of an attribute based on values of other attributes and you want the

user to see the results of re-calculation immediately after he makes a change that

affects the calculation. In this case it is necessary to mark the rule that performs the

calculation as “dynamic”, so that Aware IM executes this rule dynamically while the form

is being changed.

Do not run on server

If you mark the rule as “dynamic” it will be executed both when form is recalculated and

on the server. Sometimes it may be necessary to execute rule only when form is

recalculated and do not execute it on the server. The typical scenario when this may be

necessary is when you want to initialize some attribute with a value after the user makes

a selection in a drop down. But at the same time you want the user to be able to override

the initial value if necessary. The rule that initializes the value based on some other

attribute has to be dynamic and for the user to be able to override the initial value you

need to make sure that the rule doesn’t run on the server

Don’t check referred

This checkbox controls whether the rule will be recognized as a cross-reference rule.

See Cross-reference Rules for details and the example of a scenario when turning off

cross-reference rules might be useful.

Rule Filter Dialog

To invoke the Rule Filter dialog where you can specify which rules will be shown click on

the icon in the toolbar at the top of the table.The following options can be specified:

Rule name

Select this option if you want to view only rules that have the specified text in their

names. You must also provide the text to filter by, whether you want the search for the

names to be case sensitive and whether you want to match rules with the names exactly

equal to the specified text or containing the specified text.

Rule text

Select this option if you want to view only rules that have the specified text anywhere in

their textual expression. You must also provide the text to filter by, whether you want the

search for this text to be case sensitive and whether you want to match rules with textual

expressions exactly equal to the specified text or containing the specified text.

Aware IM 8.8 User Guide

Show auto-generated rules

Select this option if you want to view rules generated by the Configuration Tool

automatically. When you define attributes of business objects and notifications (see

Adding/Editing Attributes) the Configuration Tool may generate certain rules behind the

scenes. Rules are automatically generated when:

- An attribute has an initial value.

- An attribute has choices.

- The “Value must be provided” option for an attribute is turned on.

- An attribute is “calculated”.

- An attribute has upper or lower limits.

Show rule priorities

Select this option if you want the table of rules to have a special column that shows rule

priorities

Show dynamic rules

Select this option if you want the table of rules to have a special column that shows

whether the rule is “dynamic” – see the “Dynamic” property above.

Context Assistant

The Context Assistant is a little pop-up window that helps you enter and edit expressions

of the Rule Language. The Context Assistant window comes up when you press F3

while typing text of a rule or tag expression. The Rule Editor with the Context Assistant

open is shown on the picture below:

Aware IM 8.8 User Guide

The main window of the Context Assistant contains prompts relevant to the text of the

rule expression currently being typed – note on the picture above the current text of the

rule expression is “Cu” so the Context Assistant window contains prompts of the existing

pre-defined operations and processes starting with “Cu”. The yellow window to the right

of the Context Assistant’s prompts window contains the explanation of the prompt

selected in the prompts window – the currently selected prompt is the Customer object,

and so the explanation window contains the description of this object.

The Context Assistant may be very useful if you want to type in the names of business

objects, attributes, processes etc without having to leave the rule editor and open the

corresponding node in the Elements Tree or the corresponding element editor. The

Context Assistant is also a very good help if you are not very familiar with the Rule

Language as it automatically suggests the right Rule Language construct when you type

in your rule expression. It also has a list of all expressions and pre-defined actions used

in the Rule Language as well as the list of all functions (all accompanied by the

appropriate explanation).

To use the Context Assistant press F3 while you are typing your Rule Language

expression. The Context Assistant will display a list of prompts relevant to your current

text. Press the Arrow Down button on the keypad to move to the prompted items in the

Context Assistant window. As you are moving between the items the explanation

window will show the explanation of the currently selected item (if there is any). To

Aware IM 8.8 User Guide

select the item press Enter – the text of the item will appear in the text of your Rule

Language expression. You can also click on a prompt item with a mouse to select it and

see its explanation or double click on the item to get it to appear in the text of the

expression.

If you press F4 instead of F3 the Context Assistant displayed will have a list of all

functions that can be used in rules.

Adding/Editing Processes

The following section describes how to work with the editor of processes when adding a

new process or editing an existing one. Processes are described in the Processes as

Links between User Interface and Business Logic section.

The editor of processes can be started as described in the Working with Configuration

Elements section. It has two tabs – Action Rules and Failure Rules. Properties of the

process are displayed in the Element Properties window. Action and Failure Rules

represent rule collections, which can be edited using the Rule Editor For details how to

work with the Rule Collection see Working with Rule Collection Editor.

Action rules determine what the process will do (unless the process is implemented by a

custom software component – see below). Failure rules deternine what happens (if

anything) if a process fails. Failure rules are explained in the Process Failure Rules

section.

The following properties can be specified for a process:

Name

Specify the name of the process uniquely identifying it within the business space

version. The following restrictions apply:

- The name must start with a character (not digit) or underscore symbol. All other

symbols must be characters (including underscore) or digits. Space symbols are not

allowed.

- The name must be unique among the names of other processes defined in the

business space version.

Description

Specify the description of the process. Providing a description is highly recommended.

Any description if defined is included into the generated documentation for the business

space version – see Generating Documentation.

See also:

Defining Frame Properties

Defining Tab Properties

Defining Content Panel Properties

Defining Layout of Content Panels

Setting Menu Properties

Defining Frame Properties

Most frames consist of one or more pages (tabs). The user can switch between tabs to

display a particular page. Each tab consists of one or more content panels that can be

laid out vertically, horizontally or on a grid. Each content panel can display an HTML

page or invoke an Aware IM command and display its results, for example, run a query

or start a process. The following picture displays the home page of the CRM sample

application. It has the following frames defined – the “top bar” frame at the top showing

the toolbar of system operations, the left frame containing the application menu, the

status bar at the bottom and the main frame. The main frame consists of several tabs.

The currently active tab (Dashboard) consists of 5 content panels each showing the

results of different queries, displaying calendar for this month, a list of customers,

current alerts etc.

Aware IM 8.8 User Guide

To define how a frame will look like within your visual perspective you need to select the

frame you want to edit, define its properties and specify its contents. The following

properties of a frame can be specified in the Selection Properties window:

Aware IM 8.8 User Guide

Visible

Tick this checkbox if the frame should be visible in the visual perspective (note that the

Main Frame is always visible)

Displays

Certan frames, such as left or right frames, can contain either an application menu or

content panels. You can specify what the frame will contain.

Title

Specify the title of the frame. The title will be displayed in a special window at the top of

the frame.

Show Borders

Tick this checkbox to display borders around the frame.

Can be resized

Tick this checkbox to allow the user to resize the frame.

Collapsible

Tick this checkbox to allow the user to minimize (“collapse”) the frame by clickling on the

special icon. Once the frame is minimized it will be displayed as a narrow window with

an icon to restore the frame to its previous size.

Show tab even if it is the only one

If this checkbox is ticked Aware IM will always show a tab even if there is only one tab

defined for the frame (if the checkbox is unticked Aware IM will not show tab when there

is one tab defined).

Tab bar location

Tabs can be displayed at the top, bottom, left or right of the page.

Mobile style tabs

Tick this option to display tabs in the style appropriate for mobile phones – with big font

and with the top icon alignment.

Background

You can specify background properties of the frame. You can either specify the

backround color or image or if you are familiar with CSS you can specify advanced

background properties using the CSS dialog.

Invisibility condition

You can specify that for certain screen sizes the frame should be invisible. This option is

one of the main implementation of the “responsiveness” feature. Please watch the video

tutorial about this feature for more details.

Initial size, maximum size, minimum size

Aware IM 8.8 User Guide

You can specify the initial size of the frame. If you allow resizing the frame you can also

specify maximum and minimum size that the frame can be resized to.

Defining Tab Properties

To add a tab click on the at the top of the editor. You can then specify the following

properties of the tab:

Title

Title of the tab. This title will be displayed on the tab.

Layout

Specify the layout of the content panels within a tab – see Defining Layout of the

Content Panels.

User Can Edit Layout

If you tick this checkbox end users will be able to customize the initial layout provided by

the developer. They can either specify which content panels will be visible or move and

resize content panels using a sophisticated layout editor (for Nested Grid layouts only).

For more details about layout editing please watch this video tutorial.

Closable

If this checkbox is ticked the user will be able to close the tab.

Default panel display settings

Display settings that will be used by default for all new content panels added to this tab –

see Defining Content Panel Properties

icon

You can provide an icon that will be displayed on the tab. You can either provide an icon

file or refer to a CSS class. See “How to use icons fonts to display an icon for a button”

section in the How To Guide.

Specify unique ID of the tab. This ID can be used in the tour feature.

Tour

Specify whether the tab will have a tour

Condition when invisible

You can display a tab conditionally and specify a condition under which the tab will be

invisible. The condition should usually check attributes of either the SystemSettings

object or logged in user. You can also define conditions that depend on the screen size

as part of the “responsiveness” feature. Please watch the video tutorial about this

feature for more details.

Aware IM 8.8 User Guide

Badge

Click on this button to display a “badge” for the tab. A badge is a little icon on top of the

tab usually showing a number (for example, a number of unread messages for the

current user). This number is constantly refreshed – it can be changed by the rules and

the number will then be displayed, When specifying badge properties you have to define

an expression for the number (or text) displayed on the badge (usually the value of the

attribute that stores this number). You can then specify the background color of the

badge as well as the refresh rate and tooltip.

Defining Content Panel Properties

At least one content panel must be defined for the tab. You can add more content

panels by clicking on the icon located at the top of the editor. If there is more than one

content panel they will be displayed according to the selection of the “Layout” property

(see Defining Layout of Content Panels)

There are many properties of content panels – some of them are specific to the layout

selected for the tab. The following properties of a content panel are common to all

layouts:

Name

Specify the name of the content panel. Every content panel must have a unique name.

This name will be displayed in the caption of the content panel if “Display title” checkbox

is ticked (see below).

Contents

This is the most important property of the content panel. It defines what the content

panel will contain. When you click on the button next to the property the dialog with the

following options will be displayed:

Display results of query

Select this option if you want Aware IM to run the specified query and display its results

inside the content panel. For example, if you are configuring an application that

manages forums you may want to display a list of available forums immediately after the

user logs in. This can be done by specifying a query that finds and displays all available

forums. If you select this option you must also select the query to run from the list of all

configured queries (this radio button is really a shortcut to specify a “Run Query”

command using the “Command” radio button – see below).

Display results of process

Select this option if you want Aware IM to run the specified proces and display its results

inside the content panel.

Aware IM 8.8 User Guide

DIsplay HTML

Select this radio button if you want Aware IM to display the specified HTML text. Click

on the HTML button to enter the HTML text. This is explained in more detail a little later

in this section.

Import HTML

Select this radio button if you want to provide custom HTML page to be displayed inside

the content panel. If you select this option you must also import the HTML page and any

page resources such as images. To import the page, press the Import button. The

Directory Selection Dialog will be displayed – specify the name of the directory that must

contain a single file with the .html extension and any resources that the page may have.

You can also export the existing page into a directory by pressing the Export button and

specifying the directory where the existing HTML page and all its resources will be

written.

TIP: You can use tag expressions that refer to the SystemSettings object or

LoggedInRegularUser in the HTML page, for example <<SystemSettings.Logo>>.

Calendar

Select this radio button if you want to display a calendar widget inside the content panel.

You will then be able to provide an attribute where the selected date will be stored, as

well as specify a command that will run after the date in the calendar is selected (see the

description of the Input Control Element in the next section)

NOTE: It is also possible to embed the calendar widget in a custom HTML that you

provide when you select the Display HTML option for the content panel. To do this,

define the Calendar widget as described above and press the HTML Code… button.

Then copy this HTML and use it inside your custom HTML code.

Google Map

Google Maps can be displayed as part of the business object presentation or form.

However, displaying a map as a widget in a content panel is even more flexible and

powerful. The properties that can be specified here are similar to defining Google Maps

for object forms

You can define a query that will be run to display markers on the map. One of the

attributes of the object that the query is searching for must store the address. This

address will be marked on the map with a marker. Displaying markers on the map is

optional.

You can define a query that will be run to display polygons on the map. One of the

attributes of the object that the query is searching for must store definition of the polygon

in the KML format.

Aware IM 8.8 User Guide

By clicking on the Other Settings button you can define which controls will be present on

the map.

Date Range Picker

Select this radio button if you want to display a “date range picker” widget that allows

users to enter start and end dates of the range at the same time. You will need to

specify attributes that will hold both dates, as well as the command that will run when the

range is selected (see the description of the Input Control Element in the next section)

NOTE: It is also possible to embed the Date Range Picker widget in an custom HTML

that you provide when you select the Display HTML option for the content panel. To do

this, define the Date Range Picker widget as described above and press the HTML

Code… button. Then copy this HTML and use it inside your custom HTML code.

Command

Select this option if you want Aware IM to run the specified command and display its

results inside the content panel. You must click on the button next to the radio button to

specify which command to run.

Display empty page

Select this option if you do not want Aware IM to display anything inside the content

panel. This option can be useful if you use the content panel as the target for some other

content panel.

Aware IM 8.8 User Guide

Width

Specify the width of the content panel in pixels or percent (for some layouts only). If you

do not specify the width the content panel will occupy all available width.

Height

Specify the height of the content panel in pixels. If you do not specify the height it will be

calculated automatically based on the contents of the panel.

Target

If you have more than one content panel defined for a tab you can designate one

content panel to be the target for the other one. This means that if the user clicks on

some hyperlink inside one content panel, the results of this click will be displayed in

another content panel. For example, you can get one content panel to display the results

of a query. If the user clicks on the entry in the query results table the form for the

instance of the business object represented by this entry can be shown underneath the

query results table. You can also specify other targets for the panel. The following

options are available:

Default (blank value)

The target is the panel itself, i.e. when the user clicks on a hyperlink the results will be

displayed in this content panel replacing the current contents.

New Tab

When the user clicks on a hyperlink the results will be shown in a new tab (this requires

that the “Always show tab” checkbox is ticked). Aware IM will create the tab

automatically and the user will be able to close the tab whenever she wants.

Full Screen

When the user clicks on a hyperlink the results will be shown inside the main frame

replacing the current contents – including any tabs and content panels (they will

disappear).

Popup window

When the user clicks on a hyperlink the results will be shown in a popup window. The

user won’t be able to access elements of the screen outside the window until he closes

the window.

Modeless window

When the user clicks on a hyperlink the results will be shown in a modeless window. The

user will be able to access all other parts of the system outside the window. The window

can be resized, repositioned or closed at any time. The user can open as many

modeless windows as he likes

Name of a content panel

Aware IM 8.8 User Guide

When the user clicks on a hyperlink the results will be shown inside the selected content

panel replacing its contents.

<DIV>

This option allows you to direct the output of the panel into a particular HTML element

(usually <DIV>) that can be located anywhere on the screen. The element must have a

unique id, for example, <div id=”my_id”></div>. The system will prompt you to enter this

id.

Display settings

This option is control how the header of the content panel is displayed – there are two

choices – Classic and Modern. With the classic style you can define the following

options:

Display title

Select this option if you want Aware IM to display the title in the caption of the content

panel. Normally you will not need to tick this box if you display query results or a form

inside the content panel because these already include their own captions.

Collapsible

Tick this checkbox if you want the user to be able to collapse and expand the content

panel. This will force the caption to be shown with a little icon in the top right corner to

collapse/expand the panel.

Show borders

Tick this checkbox to display borders around the content panel.

With the Modern style of the header you can specify the text of the header as well as its

CSS class and style

Hidden initially

Tick this checkbox if you want the panel to be hidden initially. This option is useful if the

tab property “User Can Edit Layout” is selected. In this case the end user can show the

content panel hidden initially if need be.

Outer margins/Inner margins

You can define outer and inner margins of the content panel.

Device visibility

You can specify that the content panel should be invisible on certain types of devices

and visible on others.

Refresh Info

If a content panel has HTML content (static HTML or imported HTML) you can define

conditions when this information is refreshed. Other types of content do not need this

option because they usually include queries or forms that have their own auto-refresh

Aware IM 8.8 User Guide

settings. The way you define auto-refresh information for HTML content panels is very

much the same as how you define it for queries and forms.

CSS class

You can further customise the appearance of the content panel by assigning a CSS

class to it. See the “How to use CSS” section in the How To Guide for more details.

Scripts

For users familiar with Javascript you can provide your own script here to override the

configuration of the panel that Aware IM generates. See Programmers Reference Guide

for more details.

Defining Content Panel with HTML Content

This section describes in more detail how you can define a content panel that displays

some HTML. As explained before you just need to provide HTML of your content and

Aware IM will display this HTML.

TIP: You can use tag expressions that refer to the SystemSettings object or

LoggedInRegularUser in this HTML, for example <<SystemSettings.Logo>>.

However, what if you want to provide input controls in your HTML? Defining HTML tags

for input controls is not difficult, but, you wouldn’t know how to interact with the server –

how to initialise your controls and how to submit entered data to the server. Aware IM

makes it easy to define such controls as part of your HTML.

When you select “Display HTML” as contents for your panel Aware IM displays a dialog

where you can enter your HTML text. On the right-hand side of the dialog there are “Add

Input” and “Add Button” links that allow adding text fields, combo-boxes and buttons to

your HTML. You define the above widgets not as HTML, but by selecting its properties

directly in the dialogs invoked by these links.. Once you finish defining these properties

Aware IM generates a special HTML element that contains all the properties that you

have specified, and adds this element to your HTML text. You do not have to understand

what’s inside this element – all you need to know that at run-time this element will work

exactly as you have specified.

NOTE: You can edit the properties of the generated HTML element if you select the

HTML code of the element and click on the “Edit…” link.

The following section describes the properties of these special HTML elements that you

can define in the dialog.

Input Control element

Input controls are text fields or combo-boxes. When defining properties of these

elements you must first specify where the resulting value entered by the user will be

Aware IM 8.8 User Guide

stored. Since there is usually no Context available for content panels you can only use

some attribute of the System Settings or System User object (the user that is currently

logged in) or the Session object (a non-persistent business object that is marked as

storing session values). So you need to specify which object and which attribute of this

object will store the entered value.

When the user submits the value it will be stored in the attribute you have specified and

then Aware IM will execute the specified command. For example, you can define a text

box to search the messages stored in the database (as in the toolbar of the CRM

sample application). You can define a special attribute in the user object called

“SearchFilter” and the following query:

FIND Message WHERE Message.Body CONTAINS

LoggedInRegularUser.SearchFilter

You will provide the SearchFilter attribute as the attribute to store the entered value in

and then you will provide the command to run the above query.

Display choices

If the attribute definition that you have specified has choices you can tick this checkbox

and Aware IM will display a combo-box instead of the textbox. You can also specify that

the choices can be edited by the user.

Initial Value

If the attribute definition that you have specified has initial value defined you can tick this

checkbox to display this initial value when the textbox is displayed

Trigger button class

This is only applicable for textboxes. The value is submitted when the user presses the

Enter key. In addition you can define a button that will be displayed next to the text box.

Clicking on this button will also submit the value.

Width

Width of the control in pixels

Undefined value

The text to be displayed when the control is empty (“Search correspondence” in the

picture above)

Aware IM 8.8 User Guide

Button element

This element displays a button that will execute the specified command when the user

clicks on it. The button will be styled according to the currently used theme. You can

define the following properties:

Command

A command that will be executed when the button is clicked

Button text

Text of the button (optional)

Icon CSS class

CSS class for the icon displayed on the button (optional). See “How to use icons fonts to

display an icon for a button” section in the How To Guide.

Width

Width of the button in pixels

Aware IM 8.8 User Guide

Defining Layout of Content Panels

You can select among several layouts when arranging multiple content panels within a

tab. The following layouts can be selected from the Layout dropdown:

Responsive Grid (Simple)

Responsive Grid (Nested)

Vertical Anchor

Vertical Box

Horizontal

Column

Table

Border

Accordion

TIP: Click on the icon at the top of the editor to see pictures and explanation of

each layout Use preview to see how the layout looks in the browser.

Responsive Grid (Simple) Layout

In Aware IM there are two “responsive” layouts, i.e. layouts that can readjust themselves

to the amount of screen real estate available on a particular device according to the

rules you provide. This is important because you want your application to look good on

all types of devices and screen sizes – big screens, smaller screens, tablets, mobile

phones.

The first layout is a “simple” one. In this layout you just provide a list of the content

panels that your screen will contain. The content panels will be displayed as a grid and

you can define the number of rows and columns for this grid for each device type.

For example, let’s say your screen has 12 content panels. On bigger screens you want

to maximise the real estate and display these panels as a grid with 3 rows and 4

columns. On smaller screens you would display the layout as a grid with 3 columns and

4 rows. On tablets – 2 columns and 6 rows; and on phones – one column and 12 rows.

See the picture below:

Aware IM 8.8 User Guide

To implement this layout in your visual perspective all you have to do is select the

Responsive Grid (simple) layout in the Layout dropdown, define your 12 content panels

and then go to the Layout Properties tab. In this tab you need to define the number of

columns for each device type. You would define 1 for phones (up to 768 pixels wide), 2

for tablets (lup to 992 pixels wide), 3 for medium devices ( up to 1200 pixels wide) and 4

for large devices (wider than 1200 pixels).

Aware IM 8.8 User Guide

Responsive Grid (Nested) Layout

The simple layout is very useful but it only supports layouts that can be displayed as a

single grid. With the responsive nested layout you can define more complicated layouts

that consist of multiple nested grids – see the picture below:

This is where the “responsive nested” layout becomes useful. The Responsive Nested

layout implements a popular “grid system” by the Twitter’s Bootstrap (see

http://getbootstrap.com/css/ ). In this system you can define the width of your panel not

as an absolute value in pixels but as a relative factor – a number from 1 to 12. A number

of 12 indicates that the panel will always occupy all available width. A number of 1

indicates that the panel will occupy 1/12

of the available width.

For each panel you can define this factor for each device type (see Responsive Grid

(Simple) layout for the list of available device types. In addition you can define “parents”

for content panels.

This is best illustrated by an example (from the Sales Portal sample application). Let’s

say that we want our screen to look like this on devices with enough real estate – see

picture below.

Aware IM 8.8 User Guide

To implement it we first divide the screen into rows at the top level. Here we have the

row that includes the title (Team Efficiency) and input controls (Starts From and To) and

everything else. So we define two panels called Period Container and Main Content

Container (highlighted with red boxes on the picture below).

Within the Period Container we have two sub-panels – the title and input boxes. So we

define two sub-panels underneath the Period Container Panel called Header and Filters.

We want the title to occupy roughly 1/4

of the screen with filters occupying the rest. So

we assign a factor of 3 to the Header sub-panel and the factor of 9 – to the Filters sub-

panel. We define these factors for all device types. If there is not enough real estate to

display the sub-panels side-by-side Aware IM will automatically display the filters

underneath the title. We could also assign different factors for different devices – for

example, we could assign a factor of 6 to both sub-panels on large devices and factors

of 3 and 9 on smaller ones.

Aware IM 8.8 User Guide

Let’s now look at the Main Content panel. In this panel we have two columns – the list of

employees on the left and the rest (see picture below). So we define two sub-panels for

this panel called “Employee List” and “Employee Details Container” We assign the

factors of 2 and 10 to these panels respectively.

Aware IM 8.8 User Guide

We then continue this process and look at the Employee Details Container. It consists of

3 rows: “Employee Stats Container”, “Employee Sales Chart” and “Employee Schedule”

(see picture below). So we create 3 sub-panels underneath the Employee Details

Container. We want them to occupy all available width so we assign a factor of 12 to

each.

Aware IM 8.8 User Guide

And finally we break the “Empoyee Stats Container” into sub-panels called “Bio”,

“Quarter Sales” and “Average Sales” and assign equal factors of 4 for each of them (see

the picture below):

Aware IM 8.8 User Guide

You can check the behaviour and responsiveness of the Sales Portal sample application

by displaying it on different devices or just resizing your browser screen.

Aware IM 8.8 User Guide

Vertical Anchor Layout

In a vertical layout content panels are placed underneath each other – see the picture

below.

You can control width and height of each content panel individually or you can set the

“Anchor” property of each content panel. The anchor indicates how much space the

horizontal direction the content panel will occupy relative to the space occupied by the

On the picture below the width of the first panel is set to 450 pixels, the width of the third

panel is set to 300 pixels and the anchor of the second panel is set to 40% (of the

available width). The height for each panel is set to 100 pixels.

Aware IM 8.8 User Guide

Vertical Box Layout

This layout arranges items vertically down a container. This layout optionally divides

available vertical space between panels containing a numeric flex property.

The “Flex” property defines the ratio that this content panel occupies relative to other

content panels. For example, if you have two content panels with flex values of 1 and 2,

the total value is 3 and the first panel occupies 1/3 of the space and the second – 2/3 of

the space (where “space” means width for the horizontal layout and height for the

Vertical Box layout).

Each content panel with a flex value will be flexed vertically according to each panel's

relative flex value compared to the sum of all panels with a flex value specified. In the

example below the fourth button has flex=3 while others have flex=1.

Aware IM 8.8 User Guide

It is also possible to specify how the panels should be aligned and packed. In the

example shown panels are centre-aligned.

Horizontal Layout

In the horizontal layout content panels are placed next to each other (see the picture

below):

You can specify width and height of each individual content panel.

Column Layout

In the column layout content panels are arranged in columns (see the picture below).

Aware IM 8.8 User Guide

Note that each column is laid out independently of other columns. This means that there

is no guarantee that the second content panel of the first column will line up nicely with

the second content panel of the second column (it depends on the heights of the first

panel in each column). To line up content panels in rows and columns use the Table

Layout.

Aware IM traverses content panels from the top panel in the table of content panels to

the bottom panel. Wherever there is a column break, Aware IM starts a new column. To

indicate a column break select Yes for the “Last in Column” property of the last content

panel in each column (you don’t have to do it for the last column). You can also indicate

the column width of each column as a percentage of the available width. To do this set

the corresponding value into the Column Width property of the content panel.

Table Layout

Table layout allows arranging content panels in a tabular fashion (see the picture below):

Aware IM 8.8 User Guide

Unlike the Column Layout, panels in the table layout form not only columns but also

rows. Panels belonging to the same row are aligned at the top. It is possible, however, to

indicate that a particular panel spans several rows or columns by setting the

corresponding properties of the content panel (see the picture below):

The content panel in the second row spans two columns.

Aware IM 8.8 User Guide

When you select the Table layout you must also specify the number of columns in the

table (in the Layout Properties tab). The panels are traversed “from left to right” – for

example, the second panel in the table becomes the second in the row, the third panel

becomes the first in the second row if the table has two columns or the third in the first

row if the table has 3 columns. The following table shows the properties of the content

panels for the picture above (the number of columns for the layout has been specified as

2):

Name

Width

Height

Column span

Row span

Main

250

100

Panel2

250

100

Panel3

520

100

Panel4

250

100

Panel5

250

100

Border Layout

In a border layout the area of the container is divided into a fixed number of regions

called 'centre', 'north', 'south' and 'west'. You must provide the contents of the centre

region, whereas other regions are optional.

Aware IM 8.8 User Guide

Accordion Layout

The Accordion layout is shown on the picture below:

Only one panel is active at a time, other panels are collapsed. When the user clicks on

the “plus” icon to expand another panel it becomes active and is placed on top (see

below):

Aware IM 8.8 User Guide

Setting Menu Properties

The menu is the area of the screen in the Operation Mode where the user can select

actions to be performed, such as starting a process, running a query, creating or

modifying an instance of a business object etc.

Some frames in a visual perspective (Top Bar, Left and Right) may contain a menu

rather than tabs (you define this by specifying the “Displays” property of the frame).

When you expand such a frame in the tree structure of the visual perepectives editor

you see the entry for the menu. The following properties of the menu can be specified in

the Selection Propertes window when you select the menu entry:

Widget

Specify the type of the widget that will implement the menu. The following options are

available:

Aware IM 8.8 User Guide

Standard menu

This menu supports unlimited levels of hierarchy and can be vertical (if placed in the left

or right frames) or horizontal (if placed in the Top Bar frame):

However you cannot add arbitrary HTML or input controls to this menu type.

Toolbar

This menu type supports only two levels of hierarchy, but it can include HTML items and

input controls. It also supports right alignment of items:

This menu type can only be used in the Top Bar frame.

Aware IM 8.8 User Guide

Panel Bar

This menu type also supports only two levels of hierarchy and can be used only in the

left or right frames. Items of the second level pop down. You cannot use HTML or input

controls for this menu:

Tree

This menu type supports unlimited levels of hierarchy and can be used only in the left or

right frames

Aware IM 8.8 User Guide

Plain List

This menu type supports one level of hierarchy only. Can be useful for mobile phones

menus.

Header

You can display a header above the menu (vertical menus only). Provide HTML of the

header here

Footer

You can display a footer underneath the menu (vertical menus only). Provide HTML of

the footer here

CSS class / CSS style

Customise the appearance of the menu further by assigning a CSS style or class to the

menu. See the “How to use CSS” section in the How To Guide for more details.

Aware IM 8.8 User Guide

Setting Menu Item Properties

A menu consists of menu items. You can add an item to a menu if you select the menu

entry in the tree structure of the editor and click on the icon at the top of the editor. To

delete the item click on the icon. The following properties of the menu item can be

specified in the Selection Properties window:

Name

Specify the name of the menu item. Any text is acceptable.

Command

Click on this property to specify the command that will run when the item is selected.

When you specify the command in most cases you also need to provide the settings

specific to the selected command. The commands available and their settings are listed

in the table below:

Command

Description of the action in the

Operation Mode

Settings

Folder

The item represents a folder, which

can only have child items and no

actions.

None

Active Processes

Displays a list of the currently active

processes (see Rules and

Transactions).

None

Change Login

Details

Brings up a form displaying attribute

values of the currently logged in

user so that she can change the

None

Change

Perspective

Switches visual perspectives by

displaying the specified perspective.

Select a visual

perspective to switch to

from the list of

perspectives defined in

the business space

version.

Configure User

Defined Processes

This command is only available if

the product includes the “User

Defined Processes” option. This

command allows administrators of

the system to configure “User

Defined Processes” module – define

access levels and user friendly

names of objects and attributes

used in the module. For more

details about user defined

None

Aware IM 8.8 User Guide

processes please watch the video

tutorial.

Create Business

Space

Creates a new business space in

the Operation Mode (see Working

with Aware IM in Hosting

Environment).

None

Create Document

Creates document(s) from the

specified document template(s) (see

Document Generation) If more than

one document template is specified

for this item Aware IM displays a

choice of these document templates

when the user selects the menu

item. At run time the user will be

able to define a query to be used as

the data source for the resolution of

tag expressions (see Document

Generation)

Select a document

template(s) to be used by

the action by selecting

them from the list of all

document templates

available in the business

space version.

Create Object

Brings up a form for the specified

business object to create a new

instance of this object (see Business

Object Form) If more than one

business object is specified for this

item Aware IM displays a choice of

these business objects when the

user selects the menu item.

Select a business

object(s) to be used by

the action by selecting

them from the list of all

business objects

available in the business

space version.

Create Process

Allows end users to define their own

processes (“user defined

processes”). This command is only

available if the product includes the

“User Defined Processes” option

None

Export

Exports instances of the specified

business object into a file on disk

(see Export and Import) If more than

one business object is specified for

this item Aware IM displays a

choice of these business objects

when the user selects the menu

item.

Select a business

object(s) to be used by

the action by selecting

them from the list of all

business objects

available in the business

space version.

Execute Javascript

Executes the specified Javascript

Specify the Javascript to

execute

Go Back

Goes back to the previous screen

(especially useful for mobile

phones).

None

Go Online

This command finishes the “offline

mode” (when the system works with

None

Aware IM 8.8 User Guide

no Internet connection) and starts

synchronizing edits performed while

offline with the system’s database.

For more details watch this video

tutorial

Home Page

Displays the initial page (which is

usually shown immediately after the

user logs in) – see also Setting Main

Page Properties.

None

Other menu items

Import

Imports instances of the specified

business object into the system from

a file on disk (see Export and

Import) If more than one business

object is specified for this item

Aware IM displays a choice of these

business objects when the user

selects the menu item.

Select a business

object(s) to be used by

the action by selecting

them from the list of all

business objects

available in the business

space version.

Input Control

Allows adding text boxes and

combo-boxes to the menu of the

toolbar type.

Very similar to defining

text boxes and combo-

boxes for content panels

with static HTML

List Business

Spaces

Lists existing business spaces in the

Operation Mode and allows deleting

or changing properties of the

selected business space (see

Working with Aware IM in Hosting

Environment).

None

List Business

Space Versions

Lists all existing business space

versions of the current business

space in the Operation Mode and

allows deleting or changing

properties of the selected business

space versions (see Working with

Aware IM in Hosting Environment).

None

Locale Editing

Allow users to edit locale strings.

This can be useful if end users need

the ability to customise strings for

their application. This command is

only available if the product includes

the “User Defined Processes”

option. For more details about user

defined processes please watch the

None

Aware IM 8.8 User Guide

video tutorial.

Displays the screen allowing users

to enter their credentials (user name

and password) to log into the

application.

None

Logout

Logs out of the application.

Specify a URL of the

page that will be

displayed after the logout

is complete. By default

this is the page that just

shows a message that

the logout has been

completed.

Manage

Import/Export

Templates

This command allows end users to

define their own templates for

importing or exporting data in

Aware IM. See this video tutorial for

more details about import/export

templates.

Manage

Import/Export

Templates Events

For every run of import/export

templates Aware IM creates an

event. This command allows users

to see these events. For more

details about import/export

templates see this video tutorial.

Manage E-mail

Templates

This command is only available if

the product includes the “User

Defined Processes” option. Allows

end users to create, edit and delete

e-mail templates to be used when

defining their processes. For more

details about user defined

processes please watch the video

tutorial.

None

Manage Queries

Allows end users to add, edit and

delete their own queries (see

Building Query in the Operation

Mode).

None

Manage

Processes

This command is only available if

the product includes the “User

Defined Processes” option. Allows

end users to edit, delete, copy,

export, import and lock their

processes. For more details about

user defined processes please

watch the video tutorial.

None

Aware IM 8.8 User Guide

Manage Process

Events

This command is only available if

the product includes the “User

Defined Processes” option. Aware

IM creates an event record every

time a user-defined process is

executed. This command allows

users to view these records. For

more details about user defined

processes please watch the video

tutorial.

None

Offline Data

Management

This command allows the user to

specify which data will be available

in the “offline mode”. For more

details watch this video tutorial

None

Prepare for Offline

This menu command should be

used to start the “offline mode”

(working with the system with no

Internet connection). For more

details watch this video tutorial.

Select a visual

perspective that will be

used in the offline mode

Profiling On

This menu command turns

Performance Profiling on.

None

Profiling Off

This menu command turns

Performance Profiling off and

displays profiling report.

None

Publish Business

Space Version

Uploads the business space version

from a file into the Aware IM server

in the Operation Mode (see Working

with Aware IM in Hosting

Environment).

None

Registers a new user. The action

will bring up a form to fill out and

create an instance of a user object

when the form is submitted. This

action may be useful for “guest”

users who want to register with the

system – see Adding/Editing Access

Levels.

Select a business object

(must be a member of

the SystemUsers

group) that will be

created by the action.

Run Query

Runs the specified query and

displays the instances found by the

query (see Running Query in the

Operation Mode) If more than one

query is specified for this item

Aware IM displays a choice of these

queries when the user selects the

menu item.

Select a query(ies) to be

used by the action by

selecting them from the

list of all queries

available in the business

space version.

Run User Defined

Allows end users to execute the

None

Aware IM 8.8 User Guide

Queries

queries they have defined (see

“Manage Queries” operation above)

Run User Defined

Processes

This option allows users to run

processes that they define provided

that the trigger of the processes

allows running them from the menu.

For more details about user defined

processes please watch the video

tutorial.

Search Objects

Shows the screen which allows the

user to search for all instances of

the selected business object, run

the existing query or build a new

query (see Running Query in the

Operation Mode).

None

Slide In Left

Frame/Slide In

Right Frame

These commands can only be used

for the top bar frame. They are only

applicable if you also define a menu

for the left or right frames. When the

user clicks on the button

representing this menu item in the

See also:

Adding/Editing Locales

The following section describes how to work with the editor of locales when adding a

new locale or editing the existing one. Locales are described in the Creating Applications

in Different Languages section.

The editor of locales can be started as described in the Working with Configuration

Elements section. The working area of the locale editor contains a table of stings used in

the application. When a locale is created for the first time Aware IM automatically

extracts all strings used in the configuration and adds to them the system strings. You

can provide translation to both configuration and system strings by clicking on the

“Translation” column in the table. Initially the translation is set to “use the original string”,

which means that if you do not provide a translation the original string will be used.

Strings that have not been translated are displayed in pink. Translated system strings

are displayed in green and translated configuration strings are displayed in white.

You can also click on the following buttons:

Import

This allows you to import system strings from a file. System strings for some locales are

already provided. You can use those as an example for creating your own files for other

locales.

Aware IM 8.8 User Guide

Export

This allows you to export locale strings into a file

Refresh

If the configuration has been changed since you defined the locale you can refresh the

strings – Aware IM will re-extract all configuration strings defined in the application and

add the new ones to the table, so that you can provide translation to the newly added

strings or delete those that are no longer used.

Delete

This allows you to delete strings that are no longer used in the application

The following properties of the locale be specified in the Element Properties window:

Name

Specify the name of the locale uniquely identifying it within the business space version.

Default

Tick this box if you want the locale to be used in the application by default – the

application will start in this locale and all users will be assigned this locale unless

changed by rules (see the Creating Applications in Different Languages section).

Date format

Select the date format of the locale. This format will be used for those attributes of the

“Date” type that have “Take from locale” value set as their format (see Adding/Editing

Date Attributes)

Timestamp format

Select the timestamp format of the locale. This format will be used for those attributes of

the “Timestamp” type that have “Take from locale” value set as their format (see

Adding/Editing Date Attributes)

Language of system messages

Some system messages (such as month names used in the calendar control, for

example) have already been translated. You don’t need to provide translation for these

messages, just select the language from the list of languages

Culture

Culture defines default formatting of numbers and dates. For example, in some cultures

decimal point is represented by a dot, whereas in other cultures it is represented by a

comma.

Aware IM 8.8 User Guide

Right-to-left Support

Aware IM supports right-to-left orientation of the screen (RTL) for certain categories of

users that require this. When a user with RTL support enabled logs in Aware IM

automatically shows the screen in right-to-left orientation. All forms that the user sees

will also support right-to-left input.

To enable RTL-support for a user make sure that the value of the RTL attribute in the

user is set to Yes. The RTL attribute is a predefined attribute that is added by Aware IM

automatically to all members of the SystemUser group. You can set the value of the

RTL attribute by rules or explicitly from the user interface when the user record is

created.

Adding/Editing Services

The following section describes how to work with the editor of services when adding a

new service or editing the existing one. Services are described in the Communication

with Other Systems section.

The editor of services can be started as described in the Working with Configuration

Elements section.

You can define the following settings of the service in the working area of the editor:

Process

Select a process that will implement the service from a list of all processes defined in the

business space version. When the service is requested the specified process will be

executed. If the specified process requires input, this input must be provided by a

service requestor.

SOAP/Web Services support

Choose this option if you want Aware IM to expose the service as “web service”

implementing the SOAP protocol. When the business space containing such service is

published Aware IM will automatically create a WSDL file for the service.

IMPORTANT: After a business space version has been published the system

administrator has to login into the Operation Mode to cause the deployment of a new or

changed service and the creation of the WSDL file.

REST support

Tick this checkbox if the service is to be exposed as REST-ful service (REST-ful service

does not need any special deployment and should be available as soon as the business

space is published). If you tick this checkbox you will also need to provide REST settings

(see below)

Aware IM 8.8 User Guide

Service Reply

Service reply defines a business object or an array of business objects sent by a service

provider as a reply to the service request. If you select the “Service will return object”

radio button you will need to select the object that will be returned from the list of all

objects. Your implementing process must populate the context with the instance(s) of

the business object being returned. Tick the “Return multiple instances” checkbox to

return an array of instances. Again your implementing process must populate the

context with instances of the object to be returned.

The following properties can be specified in the Element Properties window:

Name

Specify the name of the service uniquely identifying it within the business space version.

The following restrictions apply:

- The name of the service must be unique among the names of other services defined

in the business space version.

- The name must start with a character or underscore symbol; all other symbols must

be characters (including underscore symbol) or digits. Space symbols are not

allowed.

Description

Specify any text that describes what the services does etc. Providing a description is not

mandatory but is highly recommended. Any description if defined is included into the

generated documentation for the business space version – see Generating

Documentation.

REST settings

If you ticked “Rest support” checkbox in the editor you will need to provide the following

details:

Default URL mapping

Services exposed as REST will be called by other parties using a particular URL. If you

choose the default option the default URL the other parties will have to use the default

URL. It has the following format:

http://ServerName:port/AwareIM/REST/BusinessSpace/ServiceName?parameters

for example:

http://myserver.com:8080/AwareIM/REST/CRM/Service1?param1=value1&param2=valu

URL must contain string

If default URL cannot be used you can construct your own URL by choosing this option

and providing your own custom string. For example, if you provide the following string:

someName1/someName2

Aware IM 8.8 User Guide

the following URL can be used:

http://ServerName:port/AwareIM/someName1/someName2?parameters

NOTE: If you choose this option you must also provide a file called rest.props and

put it in the AwareIM/CP/eclipse directory of your Aware IM installation. The

file must have a string that specifies the name of the business space containing

REST-ful services, for example DOMAIN=CRM

Name mapping

If your REST-ful service is implemented by a process that takes some object as input

(should only be one object) then values of attributes of this object have to be provided as

parameters in the URL (see example above). The name of the parameters must match

the names of the attributes of the object. If this, however, is impossible for whatever

reason, then you need to provide a mapping between the names of the parameters

(“External Name”) and the name of the corresponding attribute. You should only do it for

those parameters that have different names to the names of the attributes.

Reply Format

If a service returns a reply it can be either in the XML format (also Default) or in JSON

format. The format can also vary depending on the URL used – the extension of the

expected format can be specified in the URL itself. Choose the appropriate option here.

REST Handing of Undefined Values

This only applies to services exposed as REST-ful services. If values of the attributes of

the returned object are undefined, you can choose how Aware IM will encode such

values. By default Aware IM will skip undefined values (“Do not encode” option), but you

can also encode an empty value or a particular string. You can also specify different

encoding options depending on the name of the attribute.

Scheduling

Scheduling is configuration of special rules that execute processes or request services

at a particular time interval. Each rule that executes such a process or service is called a

scheduling item.

Scheduling items are added or edited by the editor of scheduling items, which is started

as described in Working with Configuration Elements. The editor of scheduling items is

essentially the editor of a special rule collection. Working with it is very similar to working

with the editor of standard rule collections as described in Adding/Editing Rules section.

The only difference is in adding/editing of a single rule (which represents a scheduling

item). The difference is that along with the Standard View tab (see Adding/Editing

Individual Rule)” of the editor looks different for the scheduling rules.

Aware IM 8.8 User Guide

The following information can be specified on the Standard View tab of the scheduling

rules editor:

Recurrence Pattern

Controls in this group box allow you to specify how often a process or service being

scheduled is going to be executed:

Once

Select this radio button if a process or service is to be executed only once (you will also

need to provide the date and time of this event (see Recurrence Range and Start Time

below).

Daily

Select this radio button if a process or service is to be executed every day starting and

finishing on the dates specified in the Recurrence Range group box and at the time

specified in the Start Time group box (see below).

Weekly

Select this radio button if a process or service is to be executed every week starting and

finishing on the dates specified in the Recurrence Range group box and at the time

specified in the Start Time group box (see below). You will also need to provide the

day(s) of the week when the process or service is going to be executed by ticking the

appropriate checkboxes.

Monthly

Select this radio button if a process or service is to be executed on the specified day of

every month starting and finishing on the dates specified in the Recurrence Range group

box and at the time specified in the Start Time group box (see below). You will also need

to provide the day of the month when the process or service is going to be executed.

Yearly

Select this radio button if a process or service is to be executed on the specified day of

the specified month of every year starting and finishing on the dates specified in the

Recurrence Range group box and at the time specified in the Start Time group box (see

below). You will also need to provide the month and the day when the process or service

is going to be executed.

Every few minutes

Select this radio button if a process or service is to be executed every few minutes

Recurrence Range

Controls in this group allow you to specify the starting and ending dates of the time

period when the process or service being scheduled is going to be executed:

- Start date – you must provide the starting date of the recurrent pattern in the

dd./MM/yyyy format (see Recurrence Pattern).

Aware IM 8.8 User Guide

- No end date – select this radio button if a process or service is to be executed

indefinitely according to its recurrence pattern.

- End by – select this option if you want to specify the end date when the process or

service execution will end.

Start Time

You must specify the time of the day when the process or service is going to be started.

Actions

The options in this group box allow you to specify which process or service is going to

be executed:

- Start process – select this option if you want to start the specified process. You will

also need to select the process from the list of all processes defined in the business

space version.

- Call service – select this option if you want to request the specified service of the

specified service provider. You will also need to select the name of an intelligent

business object providing the service and select the service to be requested.

Adding/Editing Business Spaces

Business space is explained in the Business Space section.

When Aware IM is installed one business space is created by default. The name of this

business space is specified during installation. The elements that you define when

configuring the application usually belong to this default business space. Sometimes,

however, it may be necessary to define other business spaces – for example, if you are

configuring several separate applications or if there are entities within the business that

function more or less as independent units. In these cases you may need to create new

business spaces and/or delete the existing ones. The following section describes how to

do it.

To create a business space, follow the steps below:

1. Click on any existing business space in the Elements Tree.

2. Select File/New in the menu or right click and select “New” from the popup menu.

The Business Space Dialog will be displayed.

3. Specify the following properties of a new business space in the Business Space

Dialog:

a. Name – the name of the new business space. The name must be unique

among the names of other business spaces. It must start with a character

Aware IM 8.8 User Guide

or underscore symbol; all other symbols must be characters or digits;

space symbols are not allowed.

b. Description – a description of the new business space. Providing a

description is highly recommended.

c. Create options – if you choose the “Create from sample application” radio

button Aware IM will automatically import the file with the selected sample

application into the business space version created with the business

space.

d. Database allocation options – usually Aware IM database tables for

business spaces are stored in the same database named BASDB (or

BASDBTEST in the testing mode). Selecting the “Allocate separate

database” radio button will force Aware IM to allocate a separate database

for the business space. This can be useful if you host an application for

several clients and you want data of your clients to be stored in separate

databases.

e. Default Date/Time Formats – this option specifies the default format of

attributes of the Date and Timestamp. New attributes of these types will

have these formats by default.

f. Theme and Font Size – this allows picking a default theme and font size

for the new business space

4. Press OK on the Business Space Dialog – the new business space will be displayed

in the Elements Tree.

To edit the existing business space:

1. Double click on the node representing the business space in the Elements Tree or

select the business space entry and choose “File/Open” from the menu.

2. Change the description and/or visibility options of the business space in the Element

Properties window. Note that you cannot change the name of the existing business

space.

To delete the existing business space:

1. Right click on the node representing the business space in the Elements Tree to

bring up the pop-up menu.

2. Select “Delete” from the pop-up menu.

CAUTION: Deleting a business space will delete all business space versions defined

in the business space and all the operational data created by the users!

Setting Options for Incoming E-mail Handling

Quite often an application needs to process e-mails arriving to the business’s e-mail

address and perform certain functions automatically based on the e-mail contents. For

example, a customer relationship management system might register all e-mails from

Aware IM 8.8 User Guide

customers in its database, assign a unique ID to the e-mails and automatically reply to

customers with the details about their request.

In Aware IM it is possible to configure an application to process incoming e-mails and

perform the necessary actions. As mentioned before all communication with the external

parties in Aware IM is performed either via notifications or service requests (see also

Defining Intelligent Business Objects). Incoming e-mails are no exception – Aware IM

treats them as notifications sent to the Aware IM application via a special channel. Once

incoming e-mails have been delivered to Aware IM as notifications Aware IM evaluates

any rules attached to the notification as usual. It is up to the configurator to define the

appropriate rules.

All that the configurator has to do to make sure that the application handles incoming e-

mails is turn on the e-mail handling capability for the business space version, set the

properties of the incoming e-mail channel and define the rules that deal with the

incoming e-mail notification. This is explained in more detail below:

NOTE: Starting from version 5.7 it is now possible to handle incoming e-mails

dynamically from a process. To do this select the business space version in the

Configuration Tree and select the “Add Incoming Email Account” object from the Edit

menu. This will create a special object that stores values of the incoming email account.

You can use instances of this object in the CONNECT FROM EMAIL action in a process.

For more details see the CONNECT TO EMAIL and DISCONNECT FROM EMAIL actions

in the Rule Language Guide.

To turn on incoming e-mail handling capability for a business space version follow the

steps below:

1. Double click on the node representing the business space version to start editing it

(or select File/Open from the menu).

2. Click on the “Incoming emails” property displayed in the Elements Properties window

The “Incoming E-mails” dialog will be displayed.

3. Specify the following properties in the “Incoming E-mails” Dialog:

a. Select the “The system will handle incoming e-mails” radio button to turn

on the e-mail handling capability.

b. Select the “Use values below” radio button and provide the following

values:

i. Specify the DNS name of the mail server that will receive e-mails in

the Mail Host text box.

ii. Specify the credentials (the user name and password) of your

account on the mail server.

iii. Specify the e-mail protocol supported by your mail server and the

port number (check with your e-mail provider if not sure).

Aware IM 8.8 User Guide

c. Alternatively you can select the “Use values from SystemSettings object”

radio button. In this case the system administrator will have to provide the

values for the DNS name, e-mail protocol and user credentials when the

application is initialized – see Setting Initial Values of the System.

4. Press OK on the “Incoming E-mails” Dialog.

The Configuration Tool will automatically add the following business objects and

notification into the business space version:

IncomingEmail notification

This is the notification that represents an incoming e-mail. This notification has a special

structure that you cannot change (you can define other attributes but you cannot change

the existing ones). The attributes of the notification contain the properties of the received

e-mail, such as who it is from, when it was received etc. Any rules that you want to

specify to handle incoming e-mails must be attached to the events of this notification –

see Adding/Editing Rules. You can check values of the pre-defined attributes of the

notification in your rules and perform the appropriate actions.

To turn off the incoming e-mail handling capability for the business space version select

the “Incoming emails” property of the business space version to bring up the “Incoming

Emails” dialog and select “The system will not handle incoming emails” radio button.

Handling Login Events

It may be necessary for your application to execute certain rules when a new user logs

in. For example, your application may collect the statistics of how many users are online

or how many users have been using the application.

If you want to handle the login events in your application you need to define a special

To add the login notification to the business space version:

1. Right click on the “Notifications” node of the business space version in the Elements

Tree to bring up the pop-up menu.

2. Select the “Add Login Notification” or “Add Login Notification Attempt” command from

the pop-up menu (it will be greyed out if the login notification has already been

added). A new notification with the pre-defined name LoginNotification or

LoginNotificationAttempt will appear in the Elements Tree. The difference

between the LoginNotification and LoginNotificationAttempt is that the

first is sent when a user successfully logs into the system and the second one –

when the user’s attempt to login fails.

Aware IM 8.8 User Guide

The login notification has a special structure that you cannot change (you can define

other attributes but you cannot change the existing ones). This structure includes the

LoginName attribute. The value of this attribute contains the name of the current user.

There is also the RemoteAddress attribute which contains the IP address of the user

who tries to login. You can check the value of these attributes in the rules attached to

this notification and perform appropriate actions if required.

To turn off handling of the login events in the business space version delete the

LoginNotification from the Elements Tree – see Adding/Editing Configuration

Elements.

See also:

Report/Presentation Bands

Adding Report/Presentation Elements

Editing Report/Presentation Elements

Using Toolbar to Change Report/Presentation Elements

Setting Report/Presentation Properties

Setting Band Properties

Viewing Bands

Adding Custom Font

Finding Design Element

Aligning Elements

Positioning Elements in Band

Changing Size of Elements

Miscellaneous Commands

Report/Presentation Bands

The following bands are defined in the Report/Presentation Designer:

Aware IM 8.8 User Guide

Title

This band usually shows the title of a report or presentation. It is only processed once at

the start of the report when the report or presentation is filled out with data at run time.

Page header and Page footer

A report or presentation may contain several pages (the size of a page is determined in

the Report Presentation properties – see Setting Report/Presentation Properties).

Elements of these bands are shown in the header and footer of each report/presentation

page respectively.

Column header and Column Footer

The data shown in a report or presentation may be displayed as several vertical columns

(the size and number of columns are determined in the Report Presentation properties –

see Setting Report/Presentation Properties). Elements of these bands are shown in the

header and footer of each column respectively.

Details

This is probably the main section of a report or presentation. Elements in the details

band are repeated over and over again for different sets of data available in the data

source at run time (see Reports). For example, if the details band contains elements that

display values of the two attributes of a business object and at run time there are 5

instances of the business object (found by a query, for example) the elements in the

details band will be repeated 5 times. Each time the band will be filled with attribute

values of the corresponding instance. See also the picture in the Defining Presentation

section for an example of a presentation design and the resulting document in the

Operation Mode.

Group bands

The data of a report or presentation may be divided into groups. For example, each

group may only show the data starting with a particular letter of the alphabet. The Group

bands are explained in greater detail in the Reports section. See also the picture in the

Defining Presentation section for the example of a presentation design that has one

group defined (Product Category) and the resulting document in the Operation Mode.

Summary

This band usually shows the report or presentation summary. It is only processed once

at the end of the report.

You can change properties of the bands or specify which ones are visible – see Setting

Band Properties and Viewing Bands.

Adding Report/Presentation Elements

Report or presentation may have the following elements:

Aware IM 8.8 User Guide

Text

This element represents static text or a mixture of static text and tags (see Reports). To

add a text element:

1. Click on the icon in the toolbar and select “Text”.

2. Draw a rectangle in the appropriate band in the Design Area that will define the

area occupied by the text or click anywhere in the Design Area to get the

rectangle of the default size.

3. The text dialog will be displayed. Enter the text into the dialog. To include a tag

expression, enter tag symbols explicitly. For example: Name is:

<<Account.Name>>

Tag

Tags are explained in the Document Generation section. To add a tag element:

1. Click on the icon in the toolbar and select “Tag Expression”.

2. Draw a rectangle in the appropriate band in the Design Area that will define the

area occupied by the tag element or click anywhere in the Design Area to get the

rectangle of the default size.

3. The text dialog will be displayed. Enter the text of the tag expression into the

dialog (do not include tag symbols). You can press F3 or F4 at any time to bring

up the Context Assistant.

4. Click OK on the dialog to complete the tag element. Note that the contents of the

tag element will be validated at this point and if there is a problem an error

message will be shown.

NOTE: Aggregate operations, such as SUM, MAX, MIN etc when used inside tags in a

report are calculated depending on whether they use conditions or not. Aggregate

operations that do not use conditions operate only on objects iterated over in the report,

whereas aggregate operations using conditions operate on all objects in the system. For

example, if a report prints out all accounts with balance greater than 1000, the

expression <<SUM Account.Balance>> will calculate the total balance of these

accounts, whereas the expression <<SUM Account.Balance WHERE

Account.Balance > 500>> will calculate the total balance of the accounts that are

greater than 500 (even though the report only works with the accounts greater than

1000).

Rectangle

An element represents a rectangle. To add a rectangle element:

1. Click on the icon in the toolbar and select “Rectangle”.

2. Draw a rectangle in the appropriate band in the Design Area.

Line

An element represents a straight line. To add a line element:

Aware IM 8.8 User Guide

1. Click on the icon in the toolbar and select “Line”.

2. Draw a line in the appropriate band in the Design Area.

Image

An element represents an image. To add an image element:

1. Click on the icon in the toolbar and select “Image”.

2. Click on the spot in the appropriate band in the Design Area where the top left

corner of the new image will be. The Report Designer will display the File

Selection Dialog.

3. Select the file representing an image (must be a .gif or .jpeg format) and press

OK. The new image element will be displayed in the Design Area.

Sub-report or Sub-presentation

This element represents a report or presentation that is embedded into the current report

or presentation. To add a sub-report or sub-presentation:

1. Click on the icon in the toolbar and select “Subreport” (the icon will be greyed

out if there are no reports or presentations other than the current one in the

business space version).

2. Draw a rectangle in the appropriate band in the Design Area that will define the

area occupied by the sub-presentation or sub-report. The Report Designer will

display the Sub-report/Sub-presentation dialog.

3. Specify the properties of the sub-report or sub-presentation as described in

Editing Sub-report/sub-presentation Element and click OK. The new sub-

report/sub-presentation element will be displayed in the Design Area.

Table

This element represents a table. Quite often tables can be used instead of sub-reports to

show related records (such as line items of an order, for example) in a tabular fashion.

To add a table:

1. Click on the icon in the toolbar and select “Table”.

2. Draw a rectangle in the appropriate band in the Design Area that will define the

area occupied by the table. The Report Designer will display the Table dialog.

3. Specify the properties of the sub-report or sub-presentation as described in

Editing Table section and click OK. The new table element will be displayed in the

Design Area.

Barcode

This element represents a barcode.To add a barcode:

1. Click on the icon in the toolbar and select “Barcode”.

2. Draw a rectangle in the appropriate band in the Design Area that will define the

area occupied by the barcode. The Report Designer will display the Barcode

dialog.

Aware IM 8.8 User Guide

3. Select the type of the barcode and specify an expression that contains the code

(a textual string) of the barcode, for example: <<Package.Code>>

QRCode

This element represents a QRCode element.To add a QRCode:

1. Click on the icon in the toolbar and select “QRCode”.

2. Draw a rectangle in the appropriate band in the Design Area that will define the

area occupied by the QRCode. The Report Designer will display the Barcode

dialog.

3. Specify an expression that contains the code (a textual string) of the QRCode, for

example: <<Package.Code>>

Conditional Element

A conditional element may be represented by any number of previously mentioned

elements. A conditional element includes rules that define under which circumstances a

particular sub-element will be included into the resulting document (see Reports). To

add a new conditional element:

1. Click on the icon in the toolbar and select “Conditional Element”

2. Draw a rectangle in the appropriate band in the Design Area that will define the

area occupied by the conditional element. The Report Designer will display the

Conditional Element dialog.

3. Specify the properties of the conditional element as described in the Editing

Conditional Element section and click OK. The new conditional element will be

displayed in the Design Area.

Chart Element

To add a chart element, do the following:

1. Click on the icon in the toolbar and select “Chart”.

2. Draw a rectangle in the appropriate band in the Design Area that will define the

area occupied by the chart element. The Report Designer will start the Chart

Wizard that will help you design a chart. See the Working with Charts section for

more details.

Page Break Element

When you insert a Page Break element Aware IM will start a new page at the spot where

the break is inserted. To insert a Page Break element:

1. Click on the icon in the toolbar and select “Page Break”.

2. Click on the spot in the Design Area where you want the new page to start.

Google Map

This element represents a Google Map that can show one or more addresses. Note that

this element is only available for object presentations. An object or group that owns the

presentation must have an attribute that stores the complete address or a reference to

Aware IM 8.8 User Guide

the special MGeoLocation object containing latitude and longitude of the location. To

add a Google Map to your presentation:

1. Click on the icon in the toolbar and select “Google Map”.

2. Draw a rectangle in the appropriate band in the Design Area that will define the

area occupied by the Google Map. The Report Designer will display the Google

Map dialog.

3. Specify the properties of Google Map and click OK. The new element will be

displayed in the Design Area.

NOTE: For details how to use the “Polygons” feature of the Google Map please

refer to the How To Guide.

NOTE: Some usages of Google Maps require you to create an account and

specify a special key. If you need to provide a key for your Google Maps account you

can do this in the predefined GoogleMapsKey attribute of the SystemSettings object.

Editing Report/Presentation Elements

To edit report or presentation elements:

1. Select one or more elements – see Selecting Elements.

2. Move or scale the elements graphically see Scaling and Moving Elements

3. Click on the buttons of the toolbar to change certain properties of the elements,

such as the background color, font settings (for text and tags) etc – see Using

Toolbar to Change Report Presentation Elements.

4. Alternatively change properties of the element(s) in the Selection Properties

window – see Changing Element Properties.

See also:

Deleting Elements

Copying and Pasting Elements

Changing Element Properties

Selecting Elements

To select a report/presentation element, click anywhere in the area occupied by the

element or draw a rectangle around the element(s). When an element is selected the

little black markers are displayed around the element. Alternatively find an element in

the Outline View window and click on its textual entry in this window. This will

automatically select the element in the Design Area as well

Aware IM 8.8 User Guide

NOTE: If several elements are overlapping and you click on the overlapping area an

element that was created last is selected. If you want to select a different element use

“Bring To Front” and “Send to Back” commands – see Miscellaneous Commands.

To select multiple elements within the same band:

1. Select one element using the technique described above.

2. Press down SHIFT or CTRL key to select other elements.

3. Alternatively press the mouse button on some point not occupied by any element

and hold down the mouse button to drag a box around the elements you want to

select. When you release the mouse button all elements enclosed by the box will be

selected.

You can also move the selection between the elements of the current band.

1. To move the selection to the next element in the band (after the currently selected

element), press the N key on the keyboard. If no element is selected the first

element in the band will be selected.

2. To move the selection to the previous element in the band (before the currently

selected element), press the P key on the keyboard. If no element is selected the

last element in the band will be selected.

Once an element is selected you can scale or move it graphically (see Scaling and

Moving Elements) or edit its properties using the Properties Selection window (see

Changing Element Properties).

Scaling and Moving Elements

To scale a report or presentation element graphically:

1. Make sure that the element is selected – see Selecting Elements.

2. Press the mouse button on one of the markers around the element and drag the

marker to scale the selected element up or down. When you release the mouse

button the element will be scaled. You can also hold down SHIFT key while dragging

to make sure that scaling is proportional in both directions.

To move report or presentation elements:

1. Make sure that the elements are selected – see Selecting Elements.

2. Press the mouse button anywhere inside the area occupied by any of the selected

elements and drag the elements to a new position. When you release the mouse

button the elements will be moved. You can also hold down SHIFT key while

dragging to constraint the movement in a horizontal or vertical direction.

Aware IM 8.8 User Guide

NOTE: You can also press the arrow keys on the keyboard to nudge the selected

elements left, right, up or down.

See also: Aligning Elements, Positioning Elements In Band, Changing Size of Elements.

Deleting Elements

To delete report or presentation elements:

1. Make sure that the elements are selected – see Selecting Elements.

2. Press the Del key on the keyboard. Alternatively click on the icon in the toolbar or

select Delete from the Edit menu.

Copying and Pasting Elements

To copy report or presentation elements to the clipboard:

1. Make sure that the elements are selected – see Selecting Elements.

2. Press Ctrl-C key on the keyboard. Alternatively click on the icon in the toolbar or

select Copy from the Edit menu.

To paste the elements from the clipboard:

1. Press Ctrl-V key on the keyboard. Alternatively click on the icon in the toolbar or

select Paste from the Edit menu.

Changing Element Properties

Once an element or elements are selected (see Selecting Elements) it is possible to edit

them in the Selection Properties window.

Most properties are specific to the type of element being edited, however, some general

properties are common for any element.

See also:

Editing General Properties

Editing Text Element

Editing Tag Element

Editing Rectangle Element

Editing Line Element

Editing Image Element

Editing Conditional Element

Editing Sub-report/Sub-presentation Element

Editing Table Element

Working with Charts

Aware IM 8.8 User Guide

Editing General Properties

The following properties are common to all elements being edited:

Size and Position

These properties include X and Y coordinates of the top left corner of the element’s

bounding rectangle (in points) and the width and height of the element’s bounding

rectangle (in points). Note that each point is 1/72 of an inch. You can use the rulers and

grid to help you understand where the left top corner of the element’s bounding

rectangle is.

Colors and Style

These properties determine fill and outline properties of the element. Note that for some

elements the fill properties are not applicable (for example, for lines) whereas for others

– the outline properties are not applicable (for example, for sub-reports). The following

options may be specified:

Fill color

Tick this box if you want the element to be filled with a particular color (if applicable).

You must also select the color by pressing the Edit button and choosing the color in the

Color Dialog. Note also that for text and tag elements this color is the background color

of the text

Line color

Tick this box to specify the line color of an element (for rectangles an outline will be

drawn around the rectangle; for text and tag elements this is the foreground color of the

text). You must also select the color by pressing the Edit button and choosing the color

in the Color Dialog. Note also that for text and tag elements this color is the foreground

color of the text.

Line style

Select whether the line is solid or dotted (if applicable).

Line width

Select the width of the line in points (if applicable).

Aware IM 8.8 User Guide

Position Type

There are three possible values for this property:

 Float. When this value is selected the element floats in its parent section if it is

pushed downward by other elements found above it. It tries to conserve the

distance between it and the neighboring elements placed immediately above it.

 Fixed relative to top. When this value is selected the report element

simply ignores what happens to the other section elements and tries to conserve

the y offset measured from the top of its parent report band.

 Fixed relative to bottom. If the height of the parent report band is

affected by elements that stretch, the current element tries to conserve the

original distance between its bottom margin and the bottom of the band.

Name

You can optionally specify the name of the element. The name can be used to find an

element in the design – see Finding Design Element. It can also be used by the report

scriptlets (see Setting System Calculation Properties).

Stretchable

This property is only available for tag, line and rectangle elements. Tick this box if you

want the element to automatically stretch downwards to make sure that all its contents

are visible at run time. For example, you could define a tag element that refers to an

attribute of a business object. At run time when the tag contents are replaced with the

attribute value it is possible that the value occupies more space than the height of the

tag element (for example, if the value represents a multi-line text). Ticking this box will

make sure that the value is always visible no matter how high it is; otherwise only part of

the text that fits into the original bounding rectangle of the element will be shown in the

resulting document.

Editing Text Element

The following section explains how to set text specific properties.

Text

Specify the text of the element. Note that if the text element is specified as “calculated

by the system” (see below) you cannot enter the text and the text control is disabled.

Font

Choose the font of the text from the combo box containing available fonts. Note that for

reports the combo box contains the default fonts supported by the PDF format and any

custom fonts added explicitly (see Adding Custom Fonts). For presentations the combo

box contains all fonts installed on your system.

Font style

Select Regular, Bold or Italic font style.

Font size

Select the size of the font in points.

Aware IM 8.8 User Guide

Underline

Tick this box if the text is to be underlined

Strikethrough

Tick this box if the text is to be strikethrough.

Transparent

Tick this box if the text background should be transparent.

Horizontal alignment

Select how the text should be aligned in the horizontal direction within its bounding

rectangle. Choose between the Left, Right, Center and Justified alignments.

Vertical alignment

Select how the text should be aligned in the vertical direction within its bounding

rectangle. Choose between the Top, Bottom and Middle alignments. Baseline alignment

is also available for presentations (this alignment corresponds to the baseline alignment

in HTML).

Line spacing

If the text consists of multiple lines select the Line Spacing property and specify line

spacing of the text and its indentation.

Borders

If you want borders around the text click on the Borders property of the element and

select the “Dsiplay Borders” radio button on the dialog. Then specify the following

properties:

Border Type

Select Left, Right, Top or Bottom border to specify the properties of this border type. If

this border type is not to be displayed tick the “Do not display this border type”

checkbox. You can also click on the “Copy to All” button to copy the settings of this

border type to all other border types.

Padding

Select the distance in pixels between the element and the border.

Border width, border color, border style

Select the width of the border in pixels, the color of the border and the style.

Aware IM 8.8 User Guide

Rotation

You can specify rotation of the text as 90 degrees (Left), -90 degrees (Right) or 180

degrees (or Upside Down);

Hyperlink

This property is only available for presentations. Tick the box if you want the text

element to represent a hyperlink. Clicking on the hyperlink in the resulting document in

the Operation Mode will invoke an action as specified in the properties of the hyperlink.

To set the properties of the hyperlink press the Details button next to the “Hyperlink”

checkbox and set the properties in the Hyperlink dialog – see Setting Hyperlink

Properties.

Auto-calculated

Define this property if the text element is calculated by a scriptlet plug-in (see “Aware IM

Programmer’s Reference”). In this case you may not specify the text of the element

explicitly. You must also specify the scriptlet’s settings – see Setting System Calculation

Properties.

NOTE: The text of the element may contain a mixture of static text and tag

expressions, for example “Account balance is <<Account.Balance>>”.

Alternatively such text may be split into the text element (“Account balance is”) and the

tag element (“Account.Balance”). It is more tedious to split the text into text and tag

elements, however it may be necessary if, for example, the tag element represents a

separate hyperlink.

Editing Tag Element

Setting properties of a tag element is very similar to setting properties of a text element –

see Editing Text Element. The differences are summarized below:

1. You can press F3 and F4 at any time when specifying text of the element (tag

contents) to bring up the Context Assistant.

2. It is not necessary to include the tag symbols (“<<” and “>>”) in the text of the

element.

3. The text of the element is validated for syntax errors when you press OK on the

dialog.

4. The “Auto-calculated” property is not applicable for tag elements.

5. You can set the Evaluation Details property of the tag element. This property is only

applicable when the contents of the tag represent a report specific expression (such

as ELEMENT_COUNT function or an aggregate expression without a condition - see

Reports). The property determines when the expression inside the tag is going to be

calculated at run time. The following options are available:

Aware IM 8.8 User Guide

At the end of the report

Select this option if you want the calculation to be performed only once at the end of the

report or presentation. If, for example, the ELEMENT_COUNT function is used in the tag

expression, the result of the calculation will be the total number of elements in the report.

At the end of each page

Select this option if you want the calculation to be performed at the end of each page of

the report or presentation. If, for example, the ELEMENT_COUNT function is used in the

tag expression, the result of the calculation will be the number of elements on each page

in the report.

At the end of each column

Select this option if you want the calculation to be performed at the end of each column

of the report or presentation. If, for example, the ELEMENT_COUNT expression is used in

the tag expression, the result of the calculation will be the number of elements in the

report column.

At the end of the group

Select this option if you want the calculation to be performed at the end of the specified

group. If, for example, the ELEMENT_COUNT function is used in the tag expression, the

result of the calculation will be the number of elements in the group. You must also

select the name of the group.

Setting Hyperlink Properties

Text, tag or image elements used in presentations can represent a hyperlink. When the

user clicks on this hyperlink in the Operation Mode the action specified in the hyperlink

properties will be performed. The following section explains which properties can be

specified in the Hyperlink dialog.

To specify the properties of the hyperlink you need to select the type of the operation

(action) and specify parameters specific to each operation type. The following operation

types are supported:

Start Process

This operation type starts a process selected from the list of processes defined in the

business space version. If the process has input then you may need to provide the value

for this input. Two scenarios are possible:

- If the object defined as the process input is the same as the owner of the

presentation, you don’t have to do anything, as the system will automatically provide

the input when the process starts.

- If the object defined as the process input is different from the owner of the

presentation, then you must specify the input in the “Value” column of the “Process

Input Table”. Click on the appropriate cell in the “Value” column and enter the

process input as the reference attribute of the presentation owner. For example, let

us assume that we are creating a forum management system where we have the

Aware IM 8.8 User Guide

Topic and a Forum objects defined. The Topic object has a single reference

attribute named Forum that refers to the Forum where the Topic belongs. Let us

assume also that we are editing the presentation of the Topic object and we want to

define a hyperlink that starts the PostNewTopic process, which allows posting a

new topic from the presentation of the existing one. Let us assume that the

PostNewTopic process requires Forum object as its input. When defining the

hyperlink we would define an operation that starts the PostNewTopic process and

we would specify Topic.Forum in the “Value” column of the Process Input Table as

process input (note that Topic is the owner of the presentation we are editing).

Edit Business Object

An operation of this type brings up a form to edit the specified instance of the business

object. You need to select the instance of the business object to be edited from the

following options:

- Owner of the presentation being edited – this is the current instance of the business

object displayed by the presentation.

- Determined by contents of the tag – specify the expression identifying the instance of

the business object. This is useful when you want to edit instances of the business

objects referred to by the current instance, for example, Transaction.Account.

- Determined by contents of the current tag – this option is available for tag elements

only. It indicates that the instance of the business object is determined by the

contents of the tag element.

Run Query

An operation of this type.runs the specified query. You will need to select the query to

run from the list of queries defined in the business space version. Note that the instance

of the presentation owner may be referred to dynamically by the query (see Configuring

Queries).

View Presentation

An operation of this type shows the specified presentation of the specified instance of

the business object. You will need to define the business object that owns the

presentation to be viewed (see the Edit Business Object operation for the explanation

how to do it) and then select the presentation to view.

Delete Business Object

An operation of this type deletes the specified instance of the business object. You will

need to define the business object to delete (see the Edit Business Object operation for

the explanation how to do it).

Link to URL

An operation of this type navigates to the specified URL. You will need to select the

instance of the business object to be edited from the following options:

- Specify – specify the URL to navigate to

Aware IM 8.8 User Guide

- Determined by contents of the tag – specify the expression identifying the URL. This

is useful when you want to navigate to the URL which is determined from the value of

the Plain Text attribute of some business object, for example, Person.HomePage

- Determined by contents of the current tag – this option is available for tag elements

only. It indicates that the URL is determined by the contents of the tag element.

NOTE: if a tag element in a presentation refers to an attribute of the Document type

the hyperlink for this tag is automatically generated in the Operation Mode even if the

tag element does not define it. When a user clicks on this hyperlink the document stored

in this attribute is shown in a separate browser.

Setting System Calculation Properties

Text elements and images can be specified as “auto-calculated”. This means that there

is a report/presentation scriptlet plug-in that is executed at run time to calculate the

contents of the text or image element (see “Aware IM Programmer’s Reference”). When

you specify that a tag or image element is calculated by such a scriptlet you also need to

specify the calculation module of the scriptlet. The calculation module is the fully

qualified name of the scriptlet component (that must be written in the Java Programming

Language) - for example, “com.mysystem.myscriptlets.Scriptlet1”.

Editing Rectangle Element

The Element Properties dialog for a rectangle element only contains general properties

– see Editing General Properties.

Editing Line Element

The Element Properties dialog for a line element only contains general properties – see

Editing General Properties.

There is one difference – the “Size and Position” group box for a line element contains

the coordinates of the starting and ending points of the line, instead of the coordinates of

the top left corner of the bounding rectangle and width/height as for other elements.

Editing Image Element

Loaded from file

Select this option if the image is loaded from a file rather than calculated by the system

(see below). Press the Browse button to specify the image file (must be gif or jpeg

format).

Borders

If you want borders around the image click on the Borders property of the element and

select “Display borders” radio button. The values you need to specify are the same as

for the borders of the text element.

Aware IM 8.8 User Guide

Auto-calculated

Select this option if the image element is calculated by a scriptlet plug-in. You must also

specify the scriptlet’s module – see Setting System Calculation Properties.

Horizontal alignment

Select how the image should be aligned in the horizontal direction within its bounding

rectangle. Choose between the Left, Right and Center alignments.

Vertical alignment

Select how the image should be aligned in the vertical direction within its bounding

rectangle. Choose between the Top, Bottom and Middle alignments. The Baseline

alignment is also available for presentations (this alignment corresponds to the baseline

alignment in HTML).

Hyperlink

This property is only available for presentations. Define this property if you want the

image element to represent a hyperlink. Clicking on the hyperlink in the Operation Mode

will invoke an action as specified in the properties of the hyperlink. To set the properties

of the hyperlink press the Details button next to the Hyperlink checkbox and set the

properties on the Hyperlink dialog – see Setting Hyperlink Properties.

Editing Conditional Element

Conditions

The conditions of the elements are specified using the Conditions table which has two

columns – “Condition” and “Element”. To set the conditions identifying when the element

is going to be printed specify the condition directly into the “Condition” column. To set

the properties of the element that will be printed when the condition holds click on the

“Set Report Element” button to bring up the “Report Element” dialog. In this dialog select

the type of the element to be printed and then specify its properties.

As an example let us assume that we are designing a presentation of an Account

business object and we want to show the account balance in green if it is greater than

100 and in red if it is less than 100. To do this we need to define a conditional element.

The condition table of this element will define two elements – both elements will be tag

elements containing the Account.Balance expression. We will set the foreground

color of the first tag element to be green and the second one – to be red. In the condition

cell of the first element we will specify the following expression: Account.Balance >=

100 and in the condition cell of the second element we will specify Account.Balance

< 100.

Collapse height

Tick this box if you want to collapse the element if nothing is printed. It is possible that

after evaluating conditions of a conditional element at run time no element is printed into

the document at all. In this case the area occupied by the conditional element can be left

Aware IM 8.8 User Guide

blank (if the checkbox is not ticked) or it can collapse and leave the space for other

elements.

See also the Attach Conditions command in the Miscellaneous Commands section.

Editing Sub-report/Sub-presentation Element

Subreport (sub-presentation) Settings

Click on this property to bring up the “Subreport Settings” dialog. Define the following

settings on this dialog:

Query

You must specify the query that will be used as a data source for the sub-report or sub-

presentation. Note that this query may use the current instance of the business object

being processed in the main report as a dynamic value (see Configuring Queries). For

example, if the main report shows instances of the Account object and the sub-report

shows instances of the Transaction object that belong to the account the query might

look something like this:

FIND Transaction WHERE Transaction IN Account.Transactions

To specify a query press the Query button on the dialog and enter the properties of the

query as described in Adding/Editing Queries.

Subreport(sub-presentation)

Select the name of the sub-report or sub-presentation from the list of other reports

available in the business space version or the list of other presentations of the business

object.

Report (presentation) parameters

If the report or presentation requires any parameters the names of these parameters will

be displayed in the Parameters table (see also Reports). You must provide the values of

these parameters by clicking on the Parameter expression cell in the table and typing in

the values directly into the cell.

Query

You must specify the query that will be used as a data source for the sub-report or sub-

presentation. Note that this query may use the current instance of the business object

being processed in the main report as a dynamic value (see Configuring Queries). For

example, if the main report shows instances of the Account object and the sub-report

shows instances of the Transaction object that belong to the account the query might

look something like this:

FIND Transaction WHERE Transaction IN Account.Transactions

Aware IM 8.8 User Guide

To specify a query press the Query button on the dialog and enter the properties of the

query as described in Adding/Editing Queries.

“When there is no data” options

These options refer to a situation when the sub-report or sub-presentation has no data

to show (for example, the Account object has no transactions yet). You can select the

following options:

- Print nothing – select this radio button if you do not want to print anything.

- Print all except detail section – select this option if you would still like to print the title

and/or summary of the sub-report or sub-presentation (the Detail band will not be

printed at all as there is no data).

Editing Table Element

Properties of this element are specified on the Table Element dialog.

Aware IM 8.8 User Guide

Data Source

You can select either “Use data of the report/presentation” or “Run sub-query” radio

buttons. Usually you will select the “Run sub-query” option to specify the query

extracting related records. For example, to embed a table of line items into a

report/presentation of an order you would define a query that looks something like this:

FIND LineItem WHERE LineItem IN PurchaseOrder.Items

The text of the query should be specified in the textbox next to the radio-button.

Table Columns

Here you define the columns of the table.

Tag Expression

Specify which attribute the column will show as a tag expression. If you defined a sub-

query as data source the expression should start with the name of the object retrieved

by the sub-query, for example, <<LineItem.Price>>

Column Name

Name of the column that will be shown in the table

Width

Width of the column in pixels

Alignment

Alignment of the column header and data in the column

Appearance

In this section you should specify how the table will look like.

Background Color

Specify background color of the cells in either the header of the table or the data section

of the table.

Height

Specify height in pixels of either the header of the table or the data section of the table.

Font

Specify font of the cells in either the header of the table or the data section of the table.

Border Color

Specify color of the table’s border

Border Style

Specify the style of the border by clicking the appropriate button.

Aware IM 8.8 User Guide

Using Toolbar to change Report/Presentation Elements

You can use the report/presentation toolbar to change certain properties of the selected

elements.

Make sure you select the elements that you want to change the properties of – see

Selecting Elements.

Font

To change the font of the selected elements select the required font in the font combo

box in the toolbar. This applies only to text elements, tag elements and conditional

elements that define text elements in their conditions. If no elements are selected

pressing this button will set the font to be used for new text and tag elements.

Font Size

To change the font size of the selected elements select the required size from the font

size combo box in the toolbar. You can also type the size directly into the size text box

and press Enter. This feature applies only to text elements, tag elements and conditional

elements that define text elements in their conditions. If no elements are selected

pressing this button will set the font size to be used for new text and tag elements.

Bold

To change the boldness of the font of the selected elements click on the icon in the

toolbar. This applies only to text elements, tag elements and conditional elements that

define text elements in their conditions. If no elements are selected pressing this button

will set the bold property to be used for new text and tag elements.

Italics

To change the italics property of the font of the selected elements click on the icon in

the toolbar. This applies only to text elements, tag elements and conditional elements

that define text elements in their conditions. If no elements are selected pressing this

button will set the italics property to be used for new text and tag elements.

Underline

To change the underline property of the font of the selected elements click on the

icon in the toolbar. This applies only to text elements, tag elements and conditional

elements that define text elements in their conditions. If no elements are selected

pressing this button will set the underline property to be used for new text and tag

elements.

Left alignment

To make the selected elements left aligned click on the icon in the toolbar. This

applies only to text elements, tag elements, images and conditional elements that define

Aware IM 8.8 User Guide

text elements or images in their conditions. If no elements are selected pressing this

button will make sure that any new text or tag element will be left aligned.

Center alignment

To make the selected elements center aligned click on the icon in the toolbar. This

applies only to text elements, tag elements, images and conditional elements that define

text elements or images in their conditions. If no elements are selected pressing this

button will make sure that any new text or tag element will be center aligned.

Right alignment

To make the selected elements right aligned click on the icon in the toolbar. This

applies only to text elements, tag elements, images and conditional elements that define

text elements or images in their conditions. If no elements are selected pressing this

button will make sure that any new text or tag element will be right aligned.

Setting Report/Presentation Properties

The properties of the report or presentation can be specified in the Element Properties

window. The following properties can be specified:

Report size

You can select the size of the page from a list of pre-defined sizes in the “Sizes” combo

box. When you select the pre-defined size its width and height will be displayed in the

“Width” and “Height” properties (you cannot edit width and height of the pre-defined

size). You can also select the “Custom” size in which case you will be able to specify the

width and height of the page in points

Report orientation

Choose either portrait or landscape orientation.

Margins

Specify margins between the edges of the page and the design from the top, bottom, left

and right in points. You will not see the margins in the Design Area but you will see them

in the resulting document.

Columns

Specify the number of vertical columns in the report or presentation as well as the width

of each column and spacing between columns in points.

Report layout

Specify whether the report or presentation layout will be vertical or horizontal. In the

vertical layout data elements iterated in the iterative bands (all bands except Summary

and Title) are laid out vertically – each next item is placed below the previous one (see

the Defining Presentation section for an example of such a layout). In the horizontal

Aware IM 8.8 User Guide

layout elements in the iterative bands are laid out horizontally – each next item is placed

next to the previous one unless there is no more horizontal space on the page.

Setting Band Properties

To set the properties of a report/presentation band (see Report/Presentation Bands),

click on the band’s bar in the Design Area. The properties of the selected band will be

displayed in the Selection Properties window.The following properties of the band can

be specified:

Name

Specify the name of the band. This name is shown in the band’s bar in the Design Area.

You can only define the names of the group bands that you add to the design yourself

(see Viewing Bands). You can’t change the names of the pre-defined bands.

Height

Specify the height of the band in points. Note that you can also drag the band’s bar in

the design area to change the height of the bands on both sides of the bar being

dragged.

Start new page

This option is only applicable to the Title, Summary and group bands. If this box is

checked the elements of the band will be printed on a new page in the resulting

document.

Visible

Selecting this option will toggle visibility of the band in the Design Area (see Viewing

Bands). It does not affect the presence of the band in the resulting document.

Start new column

This option is only applicable to group bands. If checked indicates that when a new

group is started a new column should be started as well.

Reprint header on each page

This option is only applicable to group bands. If checked indicates that the group header

should be printed not only at the start of the group but also on each new page.

Reset page number

This option is only applicable to group bands. If checked indicates that page number

should be reset when a new group is started.

Minimum height to start new page

This option is only applicable to group bands. It indicates minimum amount of vertical

space needed at the bottom of the column in order to place the group header on the

current column.

Aware IM 8.8 User Guide

Header height

Specify the height of the group header in points (only applicable to group bands).

Footer height

Specify the height of the group footer in points (only applicable to group bands).

Condition of group printing

This option is only applicable to group bands. It indicates the expression that will be

calculated by the report engine to check whether a new group should be started. The

new group will be started if the value of the expression changes. For example, if the

group condition is specified as Product.Category the new group will be started

whenever the category of the product changes (this works especially well if products are

sorted by category). Specify any valid report expression as group condition – see also

Reports). You can press F3 at any time while typing the expression to bring up the

Context Assistant.

Add/Delete Group Bands

You can add group bands to a report or presentation by selecting the “Create Group…”

command in the Actions menu of the Report Designer toolbar. Alternatively, you can

right click on the name of the report in the Outline window and select “Create Group…”.

In the the dialog that appears you can specify the name of the new group and the bands

representing the group (Group Header and Group Footer) will be added to the Design

Area of the report. You can click on any of these bands and set properties of the group

band in the Selection Properties window.

To delete a group select either the Group Header or Group Footer bands in the Outline

window, right click and select “Delete” from the popup menu.

Adding/Deleting Custom Font

Adding a custom font to a design is only relevant to reports. As explained in the Working

with Report/Presentation Designer section the PDF format that is used to produce the

report documents uses only a fixed number of default fonts. If you want to use a different

font you have to add it to your design as a custom font (this font will be embedded in the

PDF file).

To add a custom font, select the “Add Font” command from the Actions menu in the

Report Designer toolbar. The True type font selection dialog will be displayed. Select the

font you want and press the Open button. The selected font will appear in the list of fonts

in the toolbar and will be available when creating new text and tag elements.

Aware IM 8.8 User Guide

To delete a custom font select the “Delete Font” command from the Actions menu in the

Report Designer toolbar.

Finding Design Element

If your report or presentation design contains many elements it may be necessary to find

a particular element in the design. To find an element in the design select the Find

Design Element command in the Actions menu of the Report Designer toolbar. The Find

Element dialog will be displayed. Specify the following options on the dialog:

Criteria of search

By element name

Elements will be matched against their “name” property.

By element content

This option is applicable only to text and tag elements. Elements will be matched against

their text content.

By attributes used in the element

Elements will be matched against the names of business objects and attributes used in

the elements. Note that an element may refer to an attribute not only if it is a tag

element, but also if it represents a hyperlink (hyperlink properties may contain

expressions referring to attributes of business objects –see Setting Hyperlink

Properties). This option may be especially useful if the business space version has an

integrity problem in one of the elements of a report or presentation – see Checking

Integrity of Business Space Version. The integrity checker will display which report or

presentation has the problem and also the attribute that it could not resolve, but it will not

bring you straight to the problem. You can open the report or presentation with the

problem and look for the offending element using this option.

By name of the process used in the element

This option is analogous to the previous option.

By name of the query used in the element

This option is analogous to the “By attributes used in the element” option.

By name of the document/presentation used in the element

This option is analogous to the “By attributes used in the element” option.

Text to use

Specify a text to be used in the search. You can also specify whether the search is case

sensitive and whether the search should match the text exactly as specified or find

elements that contain the specified text.

Aware IM 8.8 User Guide

The elements found by the command will be selected.

Aligning Elements

To align several elements in the same band select the element you want to align against

first and then select all other elements holding down SHIFT or CTRL keys – see

Selecting Elements. Then click on the icon in the Report Designer toolbar to bring up a

popup menu.

- To align the selected elements with the left edge of the first element in the selection

choose the Left command in the popup menu.

- To align the selected elements with the right edge of the first element in the selection

choose the Right command in the popup menu.

- To align the selected elements with the top edge of the first element in the selection

choose the Top command in the popup menu.

- To align the horizontal axis of the selected elements with the horizontal axis of the

first element in the selection choose the Horizontal Axis command in the popup

menu.

- To align the vertical axis of the selected elements with the vertical axis of the first

element in the selection choose the Vertical Axis command in the popup menu.

Positioning Elements in Band

To move one or more elements in the same band to the left edge of the band select the

elements you want to move (see Selecting Elements) and choose the icon in the

Report Designer toolbar to bring up a popup menu and then select the edge you want

position against from the popup menu.

Changing Size of Elements

To change size of several elements in the same band select the element you want to

use as the prototype first and then select all other elements holding down SHIFT or

CTRL keys – see Selecting Elements. Then click on the icon in the Report Designer

toolbar to bring up the popup menu.

- To make the selected elements the same size as the first element in the selection,

choose the “Same Size” command in the popup menu.

- To make the selected elements the same width as the first element in the selection,

choose the “Same Width” command in the popup menu.

- To make the selected elements the same height as the first element in the selection,

choose the “Same Height” command in the popup menu.

- To space elements vertically select the “Space Vertically” command

- To space elements horizontally select the “Space Horizontally” command

Aware IM 8.8 User Guide

Working with Charts

To add a new chart to a report click on the icon in the Report Designer toolbar and

select “Chart”. Then drag a box around the area in one of report bands where the chart

will be located. The Report Designer will then start the Chart Wizard that will help you

define the properties of the new chart.

NOTE: a chart can only be added to the Title, Summary or one of Group Header or

Footer bands. You cannot add a chart to the Details, Column Header, Column Footer,

Page Header or Page Footer bands.

Defining a new chart consists of the following steps:

1. Define general properties of the chart, such as chart type and orientation.

2. Define data for the chart

3. Define other chart properties, such as chart title, axes labels, whether or not to

include a legend etc.

Defining general properties of the chart

First of all you need to define the type of chart. Some of the other properties of the chart

will depend on the type of the chart chosen. Four types of charts are currently available:

 Bar chart

 Line chart

 Area chart

 Pie chart

You also need to specify the background color of the chart and plot and chart

orientation. The preview window will show you the result of your selection and will make

it easier to understand what each of the properties mean.

Defining data for the chart

The second step is to define the data that the chart will display. The data is usually the

subset or all data that the report works with. For example, a report may show the details

of a company’s departments – staff members, sales, expenditure etc and a particular

chart may show a graph of expenditure per department.

You usually define the data for a chart by specifying expressions for X and Y axes of the

chart similar to the ones you define for a tag element. For example, if a report lists staff

members of a company represented by a business object StaffMember and you want

a chart that displays ages of staff members you can define data expressions like this:

For X axis:

StaffMember.Name

For Y axis:

Aware IM 8.8 User Guide

AGE (StaffMember.DateOfBirth)

You can also specify specific values for both X and Y axes.

A chart can display one graph or a series of graphs. Let’s look at some examples (the

configuration for these examples can be found in the SAMPLES directory of your Aware

IM installation – the file SampleCharts.bsv).

Example1. In this example a report will be showing expense records for some company.

Every expense record (ExpenseRecord object) will store a date of the expense, the

expense amount and the name of the department. The report will show expense records

for each department. The report will show separate charts of expense records for every

department. At the end of the report there will be a chart showing total expenses for

each department. This is how we can define a report for this example:

The report will have a group band with the following group condition:

ExpenseRecord.DepartmentName. Every time the value of the DepartmentName

attribute changes the new group will be started. We will include a chart into the Group

Footer section of the department group. This chart will show expense records for this

particular group. We will define the following expressions for the data of this chart:

For X axis:

ExpenseRecord.Date

For Y axis:

ExpenseRecord.Amount

We will also include another chart in the Summary band of the report. This report will

show total expenses for each group. We will define the data for this group like so:

For X axis:

ExpenseRecord.DepartmentName

For Y axis:

SUM ExpenseRecord.Amount

Note that we will set evaluation time for the SUM expression to be at the end of the

Department group.

The picture below shows the resulting charts for the Sales department and for all

departments:

Aware IM 8.8 User Guide

Example2. This example will also show expenses for a company’s departments as in

example 1, but instead of showing separate charts for each department we will be

showing expenses for each department as separate graphs on the same chart.

In this case we will also define the Department group as in the example 1 with the same

group condition. We will define a chart in the Summary band of the report. This chart will

show expenses of all departments. This is how we will define the data for this report:

For X axis:

ExpenseRecord.Date

For Y axis:

ExpenseRecord.Amount

Aware IM 8.8 User Guide

We will also tick the “Support series” checkbox, click on the “Details” button, select the

“Series of data determined by group” radio button and select the Department group.

Then we will specify the following expression that will determine the name of each series

ExpenseRecord.DepartmentName. This is the crucial step – it will tell the Report

Designer that it should combine data for every group on the same chart.

The resulting chart is shown on the picture below:

Example 3. In this example we will be designing a chart that will be showing patient’s

records for a particular day in a hospital – heart rate and blood pressure measurements

taken at different times during the day.

We assume that the PatientRecord business object has been defined with the

following attributes:

 PatientName

 TimeTaken

 HeartRate

 BloodPressureLow

 BloodPressureHigh

We want to define a chart that will show all these measurements at once. We want to

have one X-axis showing time of the day and we want to have separate Y-axis for heart

rate, low blood pressure and high blood pressure values. This is how we can define the

data for this chart:

For X axis:

Aware IM 8.8 User Guide

PatientRecord.TimeTaken

For Y axis:

PatientRecord.HeartRate

Note that for Y-axis we can pick any of the attributes that we want to show –

HeartRate, BloodPressureLow or BloodPressureHigh. We will also tick the

“Support series” checkbox, click on the “Details” button, select the “Series of data

determined by expressions” radio button and define the following additional data

expression for Y-axis:

PatientRecord.BloodPressureLow

PatientRecord.BloodPressureHigh

We will also choose the name and color for each series. The resulting chart is shown on

the picture below:

Defining other properties of the chart

The final step is to define other properties of the chart. These include the following:

 The title of the chart. You can define a static title, for example “Company

Expenses” or you can define an expression similar to those you define in tag

elements, for example “<<’Expenses for department ’ +

Company.DepartmentName>>. Expressions should be enclosed in tag symbols

“<<” and “>>”

Aware IM 8.8 User Guide

 Up to two subtitles of the chart. You can define a static text for a subtitle or an

expression. If you do not want to define a subtitle leave it blank.

 Whether or not to include a legend for the chart

 Labels of the axes, font and colors of label marks

 Whether or not to include labels for values on the chart

 Whether or not to include gridlines

 Whether or not to include effects, such as 3D effect, gradient effects and others

 Other chart type specific properties

All different properties are grouped in tabs and you can switch between tabs to navigate

to a different group of properties. The preview window will show you the result of your

selection and will make it easier to understand what each of the properties mean.

Previewing the Report

To see how the report will look like to the user select the “Preview Report” item from the

Actions menu displayed on the Report Designer toolbar. A dialog will be displayed

where you can specify how many records Aware IM will generate fo the preview dataset.

This will be the number of test records displayed in the Details Band of the displayed

report.

Miscellaneous Commands

The following section has the description of some miscellaneous commands of the

Report/Presentation Designer.

Bring To Front and Send To Back

You can change the relative order of elements in the design by using the Bring to Front

or Send to Back commands. This may be useful when selecting one out of several

overlapping elements. Bring To Front command makes the selected element last in the

band so it will have preference over other overlapping elements. Send to Back

command makes the selected element first in the band. To invoke these commands

select them from the Actions menu of the Report Designer toolbar.

Attach Conditions

This command makes a conditional element out of the existing non-conditional element.

The command creates a conditional element with the original element being the sub-

element of the conditional element (initially without the conditions but you can add them

later) - see Editing Conditional Element. The command may be useful if you want to

attach conditions to the existing element, but you do not want to re-create the element

as part of a conditional element. To invoke the command right click on the element you

want to attach the conditions to and select the Attach Conditions from the pop-up menu.

Aware IM 8.8 User Guide

Show rulers

Rulers may be helpful when determining coordinates and dimensions of elements in the

design. It is possible to change measurements units of the rulers from points (each point

is equal to 1/72 of an inch) to centimetres by clicking on the corner point where vertical

and horizontal rulers meet. You can also turn visibility of the rulers on or off by selecting

the Rulers command in the Actions menu in the Report Designer toolbar.

Zoom

Zooming in and out may be very useful when working with the design. The following

options are available:

Zooming using toolbar

Specify the zoom scale in the toolbar or select from a number of the pre-defined scales

(scale of 100% corresponds to the actual size of the design).

Zooming in

Click on the . Icon in the Report Designer toolbar. The current zoom scale will be

increased by a factor of two.

Zooming out

Click on the . In the Report Designer toolbar. The current zoom scale will be reduced

by a factor of two.

Fit to page

Select “Fit to page” in the zoom box of the toolbar to fit the entire design into the screen.

Show grid

When the grid is displayed new elements created in the design will be snapped to the

grid. All movements of the elements will be snapped to the grid as well. To turn grid on

or off select the Show Grid command from the Actions menu of the Report Designer

toolbar.

Grid settings

To specify grid settings select the Grid Settings command from the Actions menu of the

Report Designer toolbar – the Grid Settings dialog will be displayed, where you will be

able to specify the resolution of the grid and its color.

Copy Style/Apply Style

You can quickly apply the entire presentation style of the one element to some other

element. To do this select the element the style of which you want to use and click on

the icon in the Report Designer toolbar to “copy” the style. Then select the element

you want to apply the style to and click on the icon in the toolbar to “paste” the style.

Aware IM 8.8 User Guide

Building Runtime Executable

NOTE: This feature is only available in the Aware IM Developer Edition.

If you want to sell applications configured with Aware IM you can use the “Build

Executable” feature to prepare the system for your end users with your own product

name and copyright.

To do this select the business space version containing the final configuration of your

application and select the “Build Executable” menu item from the “Version” menu.

Aware IM will display the “Build Executable” dialog. Enter the following information in the

dialog:

Name of the application

Specify the name of your application to be displayed by the Installation program and the

“About” menu item. This value is mandatory.

Version number

Specify the version number of your application to be displayed by the Installation

program and the “About” menu item. This value is mandatory.

Company name/Copyright

Specify your company name and copyright to be displayed by the “About” menu item.

This value is optional.

Target platform

Specify the target operating system platform where your application will be used. If your

application is to be used for multiple platforms, run “Build Executable” feature for each

target platform independently. This value is mandatory.

Target database

Specify the database that your application will use. This value is mandatory.

Do not allow end users to change business space version configuration

Tick this box if you do not want users to change the configuration of your application

using the Configuration Tool. In this case also specify the protection password to make

sure that only you can access the configuration.

Output directory

Specify the directory where the executable will be built. This value is mandatory.

License file location

Specify the location of your license file. This must be an ASCII text file. This value is

mandatory.

Aware IM 8.8 User Guide

Readme file location

Specify the location of the “README” file of your application. This must be an ASCII text

file. This value is mandatory.

Documents directory

If you include electronic documentation with your application specify the directory where

your documentation files are stored. This value is optional.

Web resources

If your application requires any resources (such as images and styles), which are used

in the custom HTML pages of your application, move these resources into a separate

directory and specify the name of this directory. Make sure that your HTML pages refer

to these resources using this directory as the parent directory. This value is optional.

Other resources

If your application requires any other resources (such as images used in the IMPORT

DOCUMENT action), move these resources into a separate directory and specify the

name of this directory. Make sure that these resources are referred to using

'../OtherResources', for example

IMPORT DOCUMENT Statement.StatementDocument FROM

'../OtherResources/myfile.doc'

This value is optional.

Custom JAR’s location

If your application requires any custom JAR files (for example if you write your own Java

extensions – see Extending Aware IM and Aware IM Programmer’s Reference), move

these JAR files into a separate directory and specify the name of this directory. This

value is optional.

JDK location

If you are building an application for the Linux platform and your current operating

system is not Linux, you need to download the Linux JDK1.4 or later

and specify the

directory where it is stored.

Once you provide the required values and press OK Aware IM will build the executable

(for Windows platform) or zip file (for Linux and Mac OS X platforms) in the output

directory that you specified. You can distribute this executable or zip file to your end

users

The license of Sun Microsystems does not allow distributing the complete JDK. However, Aware IM

only requires Java Runtime environment (JRE) and the file tools.jar (you can take it from the JDK and put

into the lib directory of the JRE – this file can be freely distributed together with the JRE).

Aware IM 8.8 User Guide

NOTE: When you install the runtime application you will not be able to run the

Configuration Tool. If you want users to be able ton run the Configuraton Tool install the

standalone Configuration Tool on the runtime machine or copy the AwareIM/ConfigTool

directory from your development machine to the runtime machine.

NOTE: If you are distributing an application for Mac OS X platform you can take the

resulting zip file to the Mac platform, unpack it and create an application bundle and/or

distributable package out of it (see Mac OS X manuals for details). You can then

distribute the application bundle or package to your customers. If you decide to distribute

the application as an original zip file, you will need to provide startup instructions in a

readme file. Customers will need to unpack the zip file, start the Mac OS X Terminal

application, change to the BIN directory and run the startAwareIM.sh script.

Configuring Applications for Mobile Devices

This is described in detail in the Aware IM For Mobile Devices document.

Creating Native Mobile Applications

This is described in detail in the Aware IM For Mobile Devices document.

Determining Current Location of the User

This is described in detail in the Aware IM For Mobile Devices document. Note,

however, that this functionality is available for all devices that support location detection

– all mobile devices do, but many desktop devices and laptops support this as well.

Rule Language Reference

This section provides the description of the Aware IM Rule Language. The rule language

is used to specify rules, queries, tags and other configuration elements. The rule

language is simple and intuitive and, unlike traditional programming languages does not

require special software development skills.

The description of the Rule Language provided in this section is intended to give readers

an informal and simple-to-understand introduction to the capabilities of the Rule

Language. For a more formal and comprehensive description please refer to a separate

document called the “Aware IM Rule Language Reference”.

Aware IM 8.8 User Guide

See:

Rule

Rule Condition

Calculations

Actions

Functions

Rule

The most basic construct in the Rule Language is the rule. The rule consists of a

condition followed by one or more actions. The condition part starts with the “IF”

keyword and the action part – with the “THEN” keyword. Therefore most rules look like

this:

If Condition Then Action

For example,

IF Policy.Driver.Age > 70 THEN Policy.Premium = 300

If Account.State='CLOSED' AND Account.Balance<>0 Then

REPORT ERROR 'Account with non-zero balance cannot be closed'

As seen from the examples above both the condition and action parts of a rule may refer

to a business object (or business object group or notification) and its attributes. Business

objects are referred to by name, for example Account. Attributes of a business object

are referred to by the attribute name where the name of the attribute is separated from

the name of the business object by a dot symbol, for example Account.State.

NOTE: The condition part of a rule may be omitted. A rule without a condition is

called an unconditional rule – it consists of one or more actions only, for example:

CreditAccount.AvailableFunds=CreditAccount.CreditLimit +

CreditAccount.Balance - CreditAccount.NonClearedFunds

Aware IM 8.8 User Guide

NOTE: A rule may also include the “ELSE” part which specifies what should happen if

a condition does not hold, for example:

IF Policy.Driver.Age > 70 THEN Policy.Premium = 300

ELSE Policy.Premium = 250

IF Policy.Driver.Age > 70 THEN Policy.Premium = 300

ELSE If Policy.Driver.Age > 80 Then Policy.Premium = 350

ELSE Policy.Premium = 250

Rule Condition

The following section describes the expressions that can be used in the conditional part

of a rule (see Rule). The conditional part of a rule consists of one or more expressions,

which are connected with the “AND” or “OR” keywords. For example,

1. IF Policy.Driver.Age > 70 THEN Policy.Premium = 300

The conditional part of this rule has one expression: Policy.Driver.Age > 70

2. If Account.State='CLOSED' AND Account.Balance<>0 Then

REPORT ERROR 'Account with non-zero balance cannot be closed'

The conditional part of this rule has two expressions:

- Account.State='CLOSED'

- Account.Balance<>0

3. If Policy.Driver.Age < 70 AND (Policy.Driver.PostCode BETWEEN

2010 AND 2040 OR Policy.Driver.PostCode BETWEEN 2060 AND 2070)

Then Policy.Premium = 250

The conditional part of this rule has three expressions:

- Policy.Driver.Age < 70

- Policy.Driver.PostCode BETWEEN 2010 AND 2040

- Policy.Driver.PostCode BETWEEN 2060 AND 2070

The rest of this section describes various types of expressions that can be used in the

conditional part of the rule. See:

Comparison

String Expression

EXISTS Expression

Aware IM 8.8 User Guide

IN Expression

Range Expression

WAS Changed Expression

IS UNDEFINED Expression

IS NEW Expression

Negation

Comparison

Comparison is used in the conditional part of a rule (see Rule Condition) to compare

values of two attributes using the following operators:

1. “=”

2. “<”,

3. “>”

4. “<=”

5. “>=”

6. “<>” (not equal)

For example:

- Account.State = 'CLOSED'

- Account.Balance < Account.Type.MinBalance

NOTE: All attribute types can be compared for equality or non-equality (even

attributes of the reference type – see Reference Attributes). If the types of the attributes

on both sides of the comparison are different, Aware IM automatically converts the

attribute types if it can. For example, if attributes of the Plain Text type are compared

with the attributes of the Number type, numbers are converted to strings as in the

example below:

Account.Name = 1000

this comparison will only be true if the value of Account.Name is ‘1000’

NOTE: Only attributes of the Number, Date, Timestamp and Duration may be

compared using other operators (‘<”, “>”, “<=”, “>=”)

NOTE: If a value of an attribute is undefined (blank) it is considered to be 0 for

comparison purposes.

Aware IM 8.8 User Guide

String Expression

The String Expression is used in the conditional part of a rule (see Rule Condition) to

check whether an attribute starts with (or ends with or contains) the specified text, for

example:

- Account.Name STARTSWITH 'John'

- Account.Name ENDSWITH 'Smith'

- Account.Name CONTAINS 'it'

NOTE: Typically the String Expression checks attributes of the Plain Text type.

However, it can also be used to check attributes of other types, for example:

Account.Balance STARTSWITH '10'

EXISTS Expression

The EXISTS Expression is used in the conditional part of a rule (see Rule Condition) to

check whether there are any instances of the specified business object (or business

object group) in the system, for example,

If EXISTS Account Then …

The expression may also check if only instances that match a particular condition exist

in the system. The condition may be indicated using the WHERE keyword and must be

enclosed in brackets, for example:

EXISTS Account WHERE (Account.State = 'OPEN')

The above expression checks whether there are open accounts in the system. The

condition that follows the WHERE keyword may have one or more expressions connected

with AND or OR keywords – just like the conditional part of a rule ((see Rule Condition),

for example:

EXISTS Account WHERE (Account.State = 'OPEN' AND Account.Balance

> 100)

NOTE: The expression checks all instances of the specified business object that

exist in the system’s database, not in the current Context – see Aggregate Operations.

Aware IM 8.8 User Guide

IN Expression

The IN Expression is used in the conditional part of a rule (see Rule Condition) to check

whether the value of a particular attribute of a business object , business object group or

notification is equal to one of the specified values in the provided list. For example,

- Account.State IN 'Open', 'Closed'

- Account.Balance IN 1000, 2000, 3000

As seen from the examples above, values in the list must be separated by a comma

symbol. There is no limit on a number of entries in the list.

The IN Expression may also check whether an instance of a business object is in the list

of references of another object. This form of the IN expression is typically used inside

the condition that follows the “WHERE” keyword (see EXISTS Expression). For

example,

EXISTS Account WHERE (Transaction IN Account.Transactions AND

Account.State = 'Open')

The above expression checks whether there is an open account in the system that

contains a particular transaction (the instance of a Transaction must be in the Context).

NOTE: It is possible to use a special expression LOGGED_IN_USERS instead of the

list of references. This will check if the specified user is logged in, for example:

FIND SystemUser WHERE SystemUser.LoginName=’john’

IF SystemUser IN LOGGED_IN_USERS Then

DISPLAY MESSAGE ‘John is logged in’

Range Expression

The Range Expression is used in the conditional part of a rule (see Rule Condition) to

check whether the value of a particular attribute of a business object, business object

group or notification is within the specified range. For example,

- Account.Balance BETWEEN 10000 AND 20000

- Transaction.Amount BETWEEN Account.Balance AND 5000

NOTE: A comma can be used instead of AND. For example,

Account.Balance BETWEEN 10000,20000

NOTE: Both lower and upper limits are included in the range.

Aware IM 8.8 User Guide

WAS CHANGED Expression

The WAS CHANGED Expression is used in the conditional part of a rule (see Rule

Condition) to check whether the value of a particular attribute of a business object or

business object group has been changed compared to the value stored in the system.

For example,

If Account.State WAS CHANGED Then …

The WAS CHANGED Expression can also be used to check if any attribute of the object

has changed, for example:

If Account WAS CHANGED

The WAS CHANGED Expression can also check whether an attribute has been

changed to a particular value, for example:

If Account.State WAS CHANGED TO 'Open' Then …

NOTE: When comparing new and old values of the attribute, the WAS CHANGED

expression only checks whether the value has been changed compared to the value of

the attribute in the last stable version of the business object – see the Evaluation of

Rules Containing WAS CHANGED Expressions section).

Expressions that track changes in a list

The WAS CHANGED expression can be used for reference lists as well as for ordinary

attributes. The WAS CHANGED expression for lists indicates whether there were any

references changed or removed from the list. For example,

If Account.Transactions WAS CHANGED Then…

It is possible to identify more precisely how a reference list has been changed and

perform actions based on the attribute values of objects that have been added or

removed from the list. The WAS ADDED TO expression can be used to check whether

any objects have been added to the list and the WAS REMOVED FROM expression can

be used to check whether objects have been removed from the list. To refer to the

objects that have been added or removed, the Added and Removed instance prefixes

can be used respectively (see Instance Prefixes). For example,

If Transaction WAS ADDED TO Account.Transactions Then INCREASE

Account.Balance BY AddedTransaction.Amount

If Transaction WAS REMOVED FROM Account.Transactions Then REDUCE

Account.Balance BY RemovedTransaction.Amount

Aware IM 8.8 User Guide

If the list itself hasn’t been changed, but an element belonging to a list has been, then

this situation can be checked using the combination of “FROM” and “WAS CHANGED”

keywords, for example:

If Transaction FROM Account.Transactions WAS CHANGED Then …

IS UNDEFINED Expression

The IS UNDEFINED Expression is used in the conditional part of a rule (see Rule

Condition) to check whether the value of a particular attribute of a business object,

business object group or notification is defined. Typically a value is undefined if it is

“blank” – for example, a user didn’t fill in the value in a form of the business object. For

attributes of the Reference Type (see Reference Attributes) “undefined” means that the

reference list is empty. For example,

- Account.State IS UNDEFINED

- Account.Transactions IS UNDEFINED

The variation of the IS UNDEFINED expression checks whether the value is defined, for

example:

Account.State IS DEFINED

IS NEW Expression

The IS NEW Expression is used in the conditional part of a rule (see Rule Condition) to

check whether a particular business object specified in the expression is being created

(does not exist in the system yet), for example

If NOT (Message IS NEW) Then PROTECT Message.Subject

In this example the Subject attribute of the Message object is protected if the object

already exists in the system.

Negation

All the expressions used in the conditional part of a rule (see Rule Condition) can be

negated by adding the NOT keyword in front of the expression (in this case the

expression must be enclosed in brackets), for example:

- NOT (EXISTS Account WHERE (Account.State = 'OPEN'))

- NOT (Account.Balance BETWEEN 100 AND 200)

Aware IM 8.8 User Guide

- NOT (Account.State IN 'OPEN', 'CLOSED' AND Account.Balance >

100)

Calculations

Expressions that can be used in the conditional part of a rule (see Rule Condition) may

work not only with attributes of business objects, business object groups or notifications

but also with calculations performed with these attributes. For example,

- If Account.ClosingDate < Account.OpeningDate + 5 Then …

- If Account.Balance < SUM Transaction.Amount WHERE (Transaction

IN Account.Transactions) Then …

Calculations can include the following constructs:

Constants

Arithmetic operations

Functions

Aggregate calculations

Constants

The following types of constants can be used in calculations:

1. Number (integer or floating point), for example, 3 or 5.6.

2. String (must be enclosed in apostrophe), for example ‘CLOSED’ or ‘Balance must

be positive’.

3. Date (in dd/mm/yy format), for example 05/12/98.

4. Date/Time (in dd/mm/yy HH:mm format), for example 05/12/98 17:05.

5. Duration (in #w#dHH:mm, where # stands for any digit, HH – for hours and mm -

for minutes), for example, 2w3d10:45.

6. UNDEFINED, for example Loan.Item = UNDEFINED

Arithmetic Operations

Basic arithmetic operations such as addition, subtraction, multiplication and division can

be used in calculations, for example:

- Account.Balance/2

- Account.InterestRate * Account.Balance – Account.Fee

Aware IM 8.8 User Guide

Functions

A function performs some calculation and returns a result. The result of a function is a

constant. There are a number of built-in functions that Aware IM supports. New

functions can be plugged in as well (see “Aware IM Programmer’s Referefence”). A

function may or may not have parameters. Parameters of a function must be either

attributes or calculationswith attributes. If a function does not have parameters then it

can be referred to by name only. If a function has parameters, they are listed after the

function name and enclosed in brackets. Parameters are separated by the comma

symbol. For example:

- CURRENT_DATE - function with no parameters.

- LENGTH (Customer.Name) – function with one parameter.

- MONTH_DIFFERENCE (Account.OpeningDate, Account.ClosingDate) –

function with two parameters.

The complete list of built-in functions supported by Aware IM is provided in the

Functions section.

Aggregate Calculation

The Aggregate Calculation performs calculations on a number of business objects or

business object groups and/or their attributes, for example, calculates the sum total of

an attribute:

SUM Account.Balance

The calculation above calculates the total balance of all available accounts.

The calculation may be applied not only to all available business objects of the specified

type, but also to objects that meet the specified condition. The condition can be specified

after the WHERE keyword and must be enclosed in brackets, for example:

SUM Account.Balance WHERE (Account.State='OPEN')

The calculation above calculates the total balance of all open accounts. The condition

that follows the WHERE keyword can have one or more expressions connected with the

AND or OR keywords – just like a conditional part of a rule ((see Rule Condition).

The following types of the Aggregate Calculation are supported:

1. SUM – calculate sum total of an attribute.

2. COUNT – calculate the number of available objects.

3. MIN – calculate minimum value of an attribute.

4. MAX – calculate maximum value of an attribute.

Aware IM 8.8 User Guide

5. AVG – calculate average value of an attribute.

NOTE: SUM, MIN, MAX, AVG calculations must not use attributes of the Reference

type, for example the following expression is not valid:

SUM Account.Transactions.Amount

If aggregate of the referred object is required as in the example above, the following

expression must be used:

SUM Transaction.Amount WHERE (Transaction IN Loan.Transactions)

NOTE: The COUNT calculation must only use the names of business objects or

business object groups – it is not allowed to use attributes, for example,

COUNT Account or COUNT Account WHERE (Account.State='Open').

Using references is also not allowed in the COUNT calculation, for example the following

expression is invalid:

COUNT Account.Transactions.

The valid expression that achieves the desired result is:

COUNT Transaction WHERE (Transaction IN Account.Transactions)

NOTE: The Aggregate Calculation uses instances of business objects that exist in

the system’s database, not in the current Context – see Aggregate Operations.

Actions

The action part of a rule consists of actions that are executed when the rule condition

holds true (see Rule). The following section describes different actions of the Rule

Language. See:

Modify Attribute Action

INCREASE BY and REDUCE BY Actions

INSERT and REMOVE Actions

REPLACE Action

CREATE Action

DELETE Action

SEND Action

REQUEST SERVICE Action

REPORT ERROR Action

Aware IM 8.8 User Guide

PROTECT Action

FIND Action

ENTER NEW Action

EDIT Action

VIEW Action

DISPLAY PERSPECTIVE Action

DISPLAY DOCUMENT Action

PRINT DOCUMENT Action

EXPORT DOCUMENT Action

IMPORT DOCUMENT Action

EXPORT Action

IMPORT Action

SET Action

UPDATE Action

IMPORT RELATIONSHIPS Action

DISPLAY MESSAGE Action

DISPLAY QUESTION Action

PICK FROM Action

DISPLAY Action

Process Call Action

Modify Attribute Action

The Modify Attribute action modifies the value of a particular attribute of a business

object, business object group or notification. The action assigns a new value to the

attribute. For example:

- Account.State = 'Open'

- Account.Balance = 1000 + Transaction.Amount

It is possible to assign values to attributes of the Reference type (see Reference

Attributes), for example:

Loan.Item = Item

It is also possible to clear the single references or references lists by assigning an

UNDEFINED constant as the value (see Constants), for example:

Member.Loans = UNDEFINED

INCREASE BY and REDUCE BY Actions

These actions increment or decrement the value of an attribute of a business object,

business object group or notification. For example:

Aware IM 8.8 User Guide

- INCREASE Account.Balance BY 1000

- REDUCE Account.Balance BY Transaction.Amount

The actions also allow specifying the amount to increase or reduce by in percents, for

example:

- INCREASE Account.Balance BY 10%

- REDUCE Account.Balance BY 5%

INSERT and REMOVE Actions

These actions insert or remove an instance of a business object or business object

group into a reference list of another object. For example,

- INSERT Transaction IN Account.Transactions

- REMOVE Transaction FROM Account.Transactions

REPLACE Action

The REPLACE Action replaces an instance of a business object or business object

group from a reference list of another object with some other instances. This action can

be especially useful when combined with the This and That prefixes (see Instance

Prefixes). For example,

REPLACE ThisTransaction IN Account.Transactions WITH

ThatTransaction

CREATE Action

The CREATE Action creates an instance of the specified business object. For example,

CREATE Account

CREATE action can optionally initialize one or more attributes of the business object that

it creates, for example:

CREATE Account WITH Account.State='Open', Account.Balance=0

The attributes to be initialized must follow the WITH keyword and must be separated by

the comma. An initialization expression may contain any constant or other calculation.

Aware IM 8.8 User Guide

Sometimes it may be necessary to create several instances of a business object with a

single CREATE action. For example,

1. CREATE Transaction FOR EACH Account

2. CREATE Transaction FOR EACH

DAY/WEEK/MONTH/QUARTER/YEAR/WEEK_DAY/WEEKEND_DAY BETWEEN

Account.OpeningDate AND Account.ClosingDate

3. CREATE Transaction FOR EACH NUMBER BETWEEN 1 AND 3

4. CREATE Attachment FOR EACH FILE IN 'c:/mydirectory'

The action in the first example will create as many instances of the Transaction object as

there are instances of the Account object in the Context.

The action in the second example will create as many instances of the Transaction

object as there are days in the specified date interval. The date interval includes both

starting and ending dates.

The action in the third example will create 3 instances of the Transaction. The interval

includes both starting and ending numbers.

The action in the fourth example will create as many instances of the Attachment object

as there are files in the specified directory.

NOTE: You can use LOOP_ITERATION expression to get values of the current file

name, current date or current iteration number, for example:

CREATE TRANSACTION FOR EACH FILE IN 'c:/mydirectory' WITH

Transaction.FileName=LOOP_ITERATION

See also the “Aware IM Rule Language Reference” for more details.

DUPLICATE Action

The DUPLICATE Action duplicates an instance of the specified business object. For

example,

DUPLICATE Account

The action will create a copy of the instance of the object with attribute values equal to

those of the original object. The action will not copy multiple references, document or

picture attributes. You have to copy them separately.

It is possible to exclude some attributes from the copied attributes, for example:

DUPLICATE Account EXCEPT Attribute1,Attribute2

Aware IM 8.8 User Guide

The above action will copy all attributes except Attribute1 and Attribute2.

Multiple references can be duplicated using the following syntax:

DUPLICATE ThisPerson.Accounts TO ThatPerson.Accounts

The above action will duplicate each instance of the Account object stored in the

ThisPerson.Accounts attribute and insert the duplicated instances into

ThatPerson.Accounts.

DELETE Action

The DELETE action deletes all instances of the specified business object or business

object group, which exist in the Context. For example,

DELETE Account

DELETE Account.Owner

CLEAN Action

The CLEAN action is similar to the DELETE action in that it deletes instances of the

specified business object. Unlike the DELETE action the CLEAN action does not invoke

execution of rules – records are deleted in the database directly. CLEAN action is much

more efficient than the DELETE action, however, you should use this action with care

because it does not check the integrity of the data – if there are instances of the

business objects left that refer to the deleted instances the data will be inconsistent. It is

your responsibility to make sure that the data remains consistent after deletion.

The syntax of the CLEAN action is similar to that of the FIND action. Examples:

CLEAN ALL Account

The above action deletes all records of the Account object in the database.

CLEAN Account WHERE Account.Name=’Smith’

The above action deletes all accounts with the name “Smith”

NOTE: The CLEAN action is not supported for business object groups. You cannot

use references in the condition of this action either.

Aware IM 8.8 User Guide

DELETE FILE Action

The DELETE FILE action deletes the specified file or directory (with all files in the

directory). For example,

DELETE FILE 'c:/temp/myfile.txt'

DELETE FILE Account.FileName

COPY FILE Action

The COPY FILE action copies the specified file to the specified location. For example,

COPY FILE 'c:/temp/myfile.txt' TO ‘c:/temp2/mynewfile.txt’

MAKE DIRECTORY Action

The MAKE DIRECTORY action creates the specified directory. For example,

MAKE DIRECTORY 'c:/temp/mydirectory'

MAKE DIRECTORY Account.DirectoryName

SEND Action

The SEND action allows sending a notification to a particular notification receiver. For

example,

SEND ReservationOfferEmail TO Reservation.Member

The receiver of the notification must be an intelligent business object with active

communication channels (see Intelligent Business Objects).

The VIA keyword can be used to indicate the specific channel through which a

notification will be sent, for example

SEND ReservationOfferNotification TO Reservation.Member VIA Email

If the VIA keyword is not specified, the default channel of the business object is used.

The USING keyword can be used to send emails using a particular email account, for

example:

SEND ReservationOfferNotification TO Reservation.Member USING

EmailAccount

Aware IM 8.8 User Guide

Here the instance of the EmailAccount object is taken from the Context and it should

contain email account values to use when sending an email (host server, port,

authentication details etc). Therefore, the object representing an account must have

certain attributes defined. The definition of such an object can be created in the

Configuration Tool using the “Add Outgoing Email Account” command.

REQUEST SERVICE Action

The REQUEST SERVICE action makes it possible to use a service of an intelligent

business object (see Communication Between Systems). For example,

REQUEST SERVICE RegisterProduct OF Awaresoft

The VIA keyword can be used to indicate specific channel through which the service is

requested, for example

REQUEST SERVICE RegisterProduct OF Awaresoft VIA Sockets

If the VIA keyword is not specified, the default channel of the service provider is used.

REPORT ERROR Action

The REPORT ERROR Action causes Aware IM to stop executing rules and issue the

specified error message to the original requestor (typically the error message is

displayed on the user’s screen). For example,

REPORT ERROR 'Value of the attribute is not defined'

This action is typically used to validate attribute values, for example:

If Account.Balance < 0 Then REPORT ERROR 'Account balance cannot

be negative'

NOTE: the action stops execution of any rules triggered by the initial request to the

system (unless there are process failure rules defined – see other notes). If the request

was issued by the user the specified error message is displayed on the user’s screen. If

the request did not originate from the user interface (for example, the request originated

from a scheduled process) the error message is written into the log and the current

process is terminated.

Aware IM 8.8 User Guide

NOTE: The request that eventually caused the REPORT ERROR action could have

changed a number of objects and attributes prior to the execution of the REPORT ERROR

action. All changes to the business objects and their attributes prior to the REPORT

ERROR action within the context of the request are discarded when the REPORT ERROR

action is triggered (unless there are process failure rules defined – see the next note).

See the Rules and Transactions section for more details.

NOTE: If evaluation of rules that caused execution of REPORT ERROR action was

initially triggered by a process and this process had failure rules attached to it, the

changes to the business objects and their attribute prior to the REPORT ERROR action

are not discarded. Instead process failure rules are evaluated and the execution of the

process continues – see Process Failure Rules.

PROTECT Action

The PROTECT action protects a business object or business object group or their

attributes from access by all or specified users. When a business object or its attribute is

protected it is not possible for the user to modify the object or attribute in any way - if an

attribute of a business object is protected it is read-only on the form of this business

object. If the entire object is protected all its attributes are read-only on the form (see

Conditional Access). The examples of the PROTECT action are shown below:

1. If Transaction.State='APPLIED' Then PROTECT Transaction FROM

ALL

2. If Transaction.State='APPLIED' Then PROTECT Transaction FROM

ALL EXCEPT Administrator

3. If Account.State='CLOSED' Then PROTECT Account.Name FROM User

AND Operator

The action in the first example protects the Transaction object from access by all users.

The action in the second example protects the Transaction object from access by all

users except those operating at the “Administrator” access level.

The action in the third example protects the Name attribute of the Account object from

users operating at the “User” and “Operator” access levels.

Aware IM 8.8 User Guide

NOTE: By default protection applies not only to changes done via the user interface,

but also to changes done by a process. It is possible to distinguish between these two

situations by specifying System as the access level, for example:

If Account.STATE <> 'NEW' THEN PROTECT Account.Balance FROM ALL

EXCEPT System

In this case users will not be able to change the account balance when the state of the

account is not new, however, it is possible to configure the process rules that change the

account balance.

NOTE: Protecting attributes of referred objects is not allowed, for example the action

PROTECT Transaction.Account.State FROM ALL is invalid.

NOTE: The PROTECT action can only be used in rules attached to a business object

to be protected. The action may not be used in processes.

NOTE: The action specified in the format described above protects against changes

to a business object or its attribute (“write protection”). If “read protection” is required,

READ prefix should be added in front of the action. When a business object is “read

protected” instances that match the protection condition will not be read from the

system. For example,

If Transaction.State='APPLIED' Then READ PROTECT Transaction FROM

ALL

If an attribute is “read protected” it is not visible on any form of the business object and

its value cannot be changed.

FIND Action

The FIND action finds particular instances of a business object or business object group

in the system. There are several variations of the action:

1. Find all instances of the specified business object or group. For example,

FIND ALL Account

2. Run the specified query that finds particular instances of the business object or

group. For example,

FIND 'Open accounts'

Aware IM 8.8 User Guide

The action above will run the query named ‘Open accounts’. Note that the apostrophe

must only be used if the query name contains space symbols otherwise the identifier of

the query name can be used without the apostrophe.

3. Find all instances of the business object or group that match the specified condition.

For example,

FIND Account WHERE Account.State = 'Open'

The condition must be specified after the “WHERE” keyword. The format of the condition

is exactly the same as the one used in the Rule Condition.

The following keywords can be optionally used after the FIND action (written in any of

the above formats):

1. ORDER BY

If this keyword is used after the FIND action, the instances found by the action will be

sorted by the specified attribute in the specified order. For example,

FIND ALL Account ORDER BY Account.Balance DESC

The above action finds all accounts sorted by their balances in the descending order.

The ASC keyword indicates the ascending order and the DESC keyword indicates the

descending order. If ASC and DESC keywords are omitted the ASC keyword is implied.

2. TAKE BEST

If this keyword is used after the FIND action, only the specified number of business

object instances which match the specified criteria, will be found by the action. Typically

this keyword is used together with the ORDER BY keyword. For example,

FIND ALL Account ORDER BY Account.Balance DESC TAKE BEST 5

The above action will find 5 accounts with the highest balance.

3. IN BATCHES OF

If the action is likely to find many instances of the business object (hundreds or even

thousands) their processing may take a while. In this case it is better to perform the

processing of instances in smaller chunks (batches). After processing of each batch is

finished the results will be immediately committed to the system and stored in the

database. If the batch size is not specified the system will only commit the results once

all the instances have been processed (see Batch Operations). For example:

Aware IM 8.8 User Guide

FIND Account WHERE Account.State = 'OPEN' AND Account.Balance >

1000 ORDER BY Account.Balance IN BATCHES OF 5

Perform some actions with found objects

(The actions will be performed in batches of 5 objects)

If IN BATCHES OF keyword is omitted the default batch size of 1000 is used.

ENTER NEW Action

The ENTER NEW action is similar to the CREATE action in that it creates a new instance

of a business object. Unlike the CREATE action it lets the user fill in the initial values of

the business object. The action displays a form of the specified business object and

waits for the user to provide the initial values of the attributes and submit them to the

system. For example,

ENTER NEW Account

NOTE: if the name of a business object group is specified in the action, Aware IM will

first display a list of all members of the group and when the user selects the name of the

required business object, Aware IM will display a form of this object.

NOTE: It is possible to indicate the initial values of the attributes using the WITH

keyword. The syntax is the same as for the CREATE action. The form will be pre-

populated with the supplied values (this initialization though is not available for groups –

see previous note). For example:

ENTER NEW Account WITH Account.Name='John Smith'

NOTE: It is possible to indicate the name of the specific form of the business object

that will be used when entering the object, for example:

ENTER NEW Account USING 'Form for administrators'

In this action ‘Form for administrators’ is the name of the form that must be

configured with the Account object (see Business Object Forms).

NOTE: By default the form of the object will be displayed in a pop-up window. If the

process finishes immediately after the user enters form values, you can designate the

form to be displayed in the current window or in a new tab. For example:

ENTER NEW Account AND VIEW

ENTER NEW Account AND VIEW IN TAB

Aware IM 8.8 User Guide

EDIT Action

The EDIT action displays a form of the existing instance of a business object to the user

and waits for the user to provide the new values of the attributes. For example,

- EDIT Account

- EDIT Account.Type

NOTE: It is possible to indicate the name of the specific form of the business object

that will be used when editing the object, for example:

EDIT Account USING 'Form for administrators'

In this action ‘Form for administrators’ is the name of the form that must be

configured with the Account object (see Business Object Forms).

VIEW Action

The VIEW action is very similar to the EDIT action. The difference is that the process in

which the action has been called does not wait for the user to change the values of the

object and continues execution immediately after displaying the form. Also the VIEW

action allows viewing the specific presentation (see Business Object Presentation) or

form of the business object. For example,

- VIEW Account

- VIEW Account.Type

- VIEW Account USING 'Some fancy presentation'.

In the last example ‘Some fancy presentation’ is the name of the presentation that

must be configured with the Account object.

NOTE: If NOEDIT keyword is specified at the end of the action the form viewed by the

action will have all its input controls disabled so that a user won’t be able to change any

attribute values. NOEDIT keyword is not applicable if a presentation is being viewed. For

example:

VIEW Account NOEDIT

DISPLAY PERSPECTIVE Action

The DISPLAY PERSPECTIVE action shows the specified visual perspective on the

screen, for example:

Aware IM 8.8 User Guide

DISPLAY PERSPECTIVE Orders

DISPLAY LAYOUT Action

The DISPLAY LAYOUT action shows the layout of the specified tab of the main frame of

the specified visual perspective on the screen, for example:

DISPLAY Layout Main FROM_VP Orders

The above action shows the content panels of the tab Main of the visual perspective

Orders. The benefit of this action is that it allows using layouts of content panels

defined in a visual perspective without using other elements of the perspective (menu,

tabs etc). Moreover, the action makes the context of the current process available to

commands invoked by the layout (such as processes, queries etc).

DISPLAY DOCUMENT Action

The DISPLAY DOCUMENT action displays the specified document on the screen. The

action has two variations:

1. Display the document contained in an attribute of the Document Type. Whatever

document is stored in the attribute will be displayed – no document processing is

performed (see Document Management). For example,

DISPLAY DOCUMENT Statement.StatementDocument

2. Generate the document from a document template and display the result on the

screen (see Document Generation). Consider the following rules as an example:

FIND Person WHERE Person.Name='John Smith'

DISPLAY DOCUMENT AccountOpeningLetter

In this example AccountOpeningLetter is the name of the document template. If this

template has the following line:

Dear <<Person.Name>>,

it will be replaced with the line

Dear John Smith

when the document is generated and displayed.

Aware IM 8.8 User Guide

Text and HTML documents can also be displayed inside a pop-up window if you use the

AS MESSAGE clause at the end of the action, for example:

DISPLAY DOCUMENT SplashScreen AS MESSAGE

Report documents can be displayed in the XLS format rather than the default PDF

format:

DISPLAY DOCUMENT AccountOpeningLetter AS XLS

You can also specify a query in this action to be used as the data source for the

document. Aware IM will produce as many documents as there are instances returned

by the query. If MERGE INTO ONE option is not used Aware IM will display all instances

on screen (the user will have to click on an icon next to each entry to see the document).

If MERGE INTO ONE clause is specified Aware IM will automatically merge all

documents into one document and show it to the user immediately. For example,

DISPLAY DOCUMENT AccountOpeningLetter USING ‘All accounts’ MERGE

INTO ONE

You can also merge the display document with any other document stored in some

attribute of the Document type (not necessarily used by a query). This is only supported

for PDF documents at the moment. For example:

DISPLAY DOCUMENT AccountOpeningLetter MERGE WITH

SystemSettings.TermsAndConditionsDoc

PRINT DOCUMENT Action

This action is very similar to the DISPLAY DOCUMENT action, but instead of displaying

the document on the screen, it sends the document to the default printer. It is also

possible to specify the name of the network printer to print to (if not specified the default

printer will be used) and the number of copies to print (if not specified 1 copy will be

printed). For example:

PRINT DOCUMENT StaffReport 2 COPIES

PRINT DOCUMENT StaffReport TO `Network Printer 1` 2 COPIES

EXPORT DOCUMENT Action

The EXPORT DOCUMENT action exports the specified document into a file on disk.

The action has two variations:

Aware IM 8.8 User Guide

1. Export the document or picture contained in an attribute of the Document or Picture

Type. Whatever document or picture is stored in the attribute will be exported – no

document processing is performed (see Document Management). For example,

EXPORT DOCUMENT Statement.StatementDocument TO FOLDER

'c:/mydocuments'

2. Generate the document from a document template and export the result (see

Document Generation). Consider the following rules as an example:

FIND Person WHERE Person.Name='John Smith'

EXPORT DOCUMENT AccountOpeningLetter TO FOLDER 'c:/mydocuments'

In this example AccountOpeningLetter is the name of the document template. If this

template has the following line:

Dear <<Person.Name>>,

it will be replaced with the line

Dear John Smith

when the document is exported.

The FOLDER keyword specified after the TO keyword identifies the directory in the file

system where the file will be written. If a directory doesn’t exist it will be created. The

name of the file that the document will be written to will be the name of the original file

that the document was created from. Note that if the file with this name already exists in

the specified folder, it will not be overwritten. Instead another file with the variation of the

original name (for example, originalName0) will be created.

The FILE keyword can be specified instead of the FOLDER keyword. In this case the

string after the FOLDER keyword must contain the full path of the file that the document

will be exported to. If a file with the specified name already exists it will be overwritten.

For example,

EXPORT DOCUMENT AccountOpeningLetter TO FILE

'c:/mydocuments/myfile.doc'

Report documents can be exported in the XLS format rather than the default PDF

format:

EXPORT DOCUMENT AccountOpeningLetter TO FOLDER 'c:/mydocuments'

AS XLS

Aware IM 8.8 User Guide

IMPORT DOCUMENT Action

The IMPORT DOCUMENT action imports the specified file into an attribute of the

specified business object (provided that the attribute is of the Document or Picture

type). For example,

IMPORT DOCUMENT Statement.StatementDocument FROM

'c:/mydocuments/myfile.doc'

EXPORT action

The EXPORT action exports existing instances of the specified business object or

results of running a query into a comma delimited text file (CSV file). For example:

EXPORT PersonalSavingAccount TO 'c:/mydocuments/psa.csv'

EXPORT ‘My Query’ TO 'c:/mydocuments/psa.csv'

If the name of the business object is used, the instances available in the current context

will be exported. If the name of the query is used Aware IM will run the query and export

the results. If the query has attributes to display defined, only those attributes will be

exported. Query names have to be enclosed in apostrophe.

There are several options that can be used with the action:

1. If the FOR UPDATE keyword is specified the ID attributes of the business objects will

be written into the export file. If such a file is later imported into the system, the

system will look for the objects with the specified ID’s and modify them rather than

insert the new ones. If the FOR UPDATE keyword is not specified the ID attributes of

the objects will not be written into the export file and if such a file is later imported

into the system, each record in the file will create the new instance of the business

object. For example:

EXPORT PersonalSavingAccount TO 'c:/mydocuments/psa.csv'FOR

UPDATE

2. If EXCLUDE RELATIONSHIPS keyword is specified any relationships that the

exported object has with other objects will not be written into the output file. By

default all relationships are exported. For example:

EXPORT PersonalSavingAccount TO 'c:/mydocuments/psa.csv' EXCLUDE

RELATIONSHIPS

3. If EXCLUDE BINARY keyword is specified any binary attributes that the exported

object has (such as Pictures and Documents) will not be written into the output

file. By default all binary attributes are exported. For example:

Aware IM 8.8 User Guide

EXPORT PersonalSavingAccount TO 'c:/mydocuments/psa.csv' EXCLUDE

BINARY

4. The USING expression allows you to use an existing export template. For example:

EXPORT PersonalSavingAccount TO 'c:/mydocuments/psa.csv' USING

`Account Template`

5. The APPEND clause allows you to append to an existing file rather than create a

new one. For example:

EXPORT PersonalSavingAccount TO 'c:/mydocuments/psa.csv' APPEND