7 Working with Data Objects and Expressions

This chapter describes how to use data objects and expressions within Oracle Business Process Composer. Data objects and expressions allow you to define how data is handled within your process.

This chapter includes the following sections:

• Section 7.1, "Introduction to Data Objects"

• Section 7.2, "Working with Data Objects and Data Associations"

• Section 7.3, "Working with Business Indicators and Counter Marks"

• Section 7.4, "Introduction to Expressions"

• Section 7.5, "Defining Process Input and Output"

• Section 7.6, "Introduction to the Expression Editor"

• Section 7.7, "Working with Expressions"

7.1 Introduction to Data Objects

Data Objects are variables used to define the type of information used by your business process. They are also used to store the value of this information.

Oracle BPM supports two types of data objects:

• Basic data objects

  Basic data objects define the basic types of variables that you can use within your processes and projects. Basic data objects can be used explicitly within your process or they can be combined into complex data objects.

  Table 7-1 lists the types of basic data objects supported by Oracle BPM.

  Table 7-1 Basic Data Objects

  Type	Description
  Bool	Represents the logical values true or false.
  Int	Represents an integer. For example: 23, -10, 0
  Decimal	Represents a number than can be expressed in decimal notation. For example: 3.14, 62, 0.023.
  Real	Represents a floating-point numeric value. For example: 2e-1, 2.3E8.
  String	Represents a sequence of characters. For example: "This is a string."
  Time	Represents a specific time expressed as: year-month day hour:minute:second. For example: 1995-02-03 13:30:28-08:00
  Interval	Represents a duration of time expressed as a number in years, months, days, hours, minutes, and seconds. For example: 1d3h30m.
  Binary	Used to store binary data, including images or videos.

  
  

• Complex data objects

  Complex data objects allow you to group data. Complex data types are defined using business objects.

  Business objects allow you to create data structures based on basic data objects. For example, you can create a complex data object called employee that contains different data types for employee name, id, and salary.

  Figure 7-1 shows the relationship between basic data objects, complex data objects, and business objects.

  Figure 7-1 Relationship Between Basic and Complex Data Objects

  
  Description of "Figure 7-1 Relationship Between Basic and Complex Data Objects"
  
  

  Business Process Composer does not allow you to create or edit business objects. However, when editing projects based on templates, you can create new complex based on business objects defined in the business catalog.

7.1.1 Introduction to Process and Project Data Objects

Basic and complex data types can both be defined as either process or project data objects. This determines the scope of the variable.

Process data objects are data objects that are defined for a specific process. In contrast, project data objects are defined for an entire project.

Therefore, you can only use process data objects within the process where they are created, while project data objects are applicable to the entire project. This is known as variable scope.

Figure 7-2 shows the difference in scope between project and process variables.

Figure 7-2 Scope of Process and Project Data Objects

Description of "Figure 7-2 Scope of Process and Project Data Objects"

Process data objects allow you to define data objects that are only used within a single process. When designing a process-based application, if you know that a data object is only used within a process, it is better to define it as a process data object to conserve system resources.

Project data objects allow you to share data between processes. For example, the Purchase Order process and the Request Approval process may both track the value of the employee that created the request, or the priority of the request.

Project data objects ensure that all processes in a project use the same data. Each process must assign and update the value of this data.

The main benefit of defining project data objects is that after publishing your project you can configure Oracle BPM WorkSpace views to display the values of those variables. This is possible only if you use project data objects.

Note:

Although project data objects allow you to define data objects that are used by all processes in a project, they are not "global" data objects. Each process within your project uses its own version of the data object. Project data objects are not used to share data between processes.

7.1.2 Using Data Objects in Project Blueprints

Within project blueprints, you can create project and process data objects only for start and end message events. Project blueprints enable process analysts to define types of data objects used between process. These data objects can be incorporated by process developers as part of the implementation created in Oracle BPM Studio.

7.1.3 Using Data Objects in Projects Based on Project Templates

Project templates allow you to create reusable components from the business catalog. In addition to services such as business rules and human tasks, you can also create business objects.

When creating an Oracle BPM project based on a project template, you can use the data objects defined in the business catalog within data associations. Also, you can create new project data objects using Business Process Composer.

These project variables can be simple data objects or they can be based on complex data objects created as part of the business catalog.

Note:

You cannot create new types of complex data objects in Business Process Composer.

7.1.4 Introduction to Data Associations

Data associations are used to pass the information stored in data objects in the following contexts:

• To and from another process or service invoked from a BPMN process

• To and from a Human Task service

• To and from an Oracle Business Rule

• To and from a script task. This BPMN flow object is used to pass data objects through data associations.

Table Figure 7-2 lists the flow objects where you can define data associations. It also lists the objects implemented.

Table 7-2 Flow Objects that Accept Data Associations

Flow Objects	Implementation
Message start and end events	Services and other BPMN processes
Message throw and catch events	Services and other BPMN processes
Send and receive tasks	Services and other BPMN processes
Script tasks	Do not contain an implementation, are used to pass data objects through data associations.
User tasks	Oracle Human Tasks
Business rule tasks	Oracle Business Rules
Service Tasks	Services and BPMN processes

Data associations are used to define the input and output from a flow object to an external service or process. Figure 7-3 shows the relation ship between a flow object, its corresponding implementation, and external processes or services.

The blue arrows represent the input and output arguments to the external process or service. These are defined using data associations.

Figure 7-3 Relationship between a Flow Object, Implementation and an External Service or Process

Description of "Figure 7-3 Relationship between a Flow Object, Implementation and an External Service or Process"

It is important to note that although the inputs and outputs are defined in the data associations for a flow object, the define values that are passed to the implemented systems and services. These systems and services are external to the process as shown in Figure 7-5.

Figure 7-4 Data Associations between a process

Description of "Figure 7-4 Data Associations between a process "

You can use expression to evaluate and change the input and output values

7.1.5 Introduction to the Data Association Editor

The data associations editor enables you to configure the input and output values passed between a flow object and a its implementation.

Figure 7-5 The Data Association Editor

Description of "Figure 7-5 The Data Association Editor"

Table 7-3 describes the different areas of the data association editor.

Table 7-3 The Data Association Editor User Interface

UI Area	Description
Inputs	Contains text boxes that display the data objects assigned as inputs to the service or process implemented in the flow object. Next to each text box is an icon that launches the expression editor
Flow Object Interface	Lists the expected input arguments for the service or process implemented. The flow object interface also contains an expandable list of the data objects supplied as input and output. Within the flow object area, you can expand complex data objects to map to specific basic data objects within a complex data object.
Outputs	Contains text boxes that display the data objects assigned as outputs from the service or process implemented in the flow object.
Data Objects	Displays a list of all the data objects. This list is divided between process and project data objects.

7.2 Working with Data Objects and Data Associations

The following sections describe how to create and delete data associations and configure data associations.

7.2.1 How to Create a Data Object

Using Business Process Composer, you can create process and project data objects in projects created based on a project template.

To create a data object:

1. Select a flow object that enables you to configure data associations.

   For a list of flow objects that allow you to configure data associations, see Table 7-2.

2. Click Data Associations.

3. Select a processes or the project from the expandable list.

4. In the right-hand column, enter a name for your data object, then select a type from the drop-down menu.

5. Click Create

7.2.2 How to Delete a Data Object

You can delete a data object from a process or project.

To delete a data object:

1. Open the process where you want to delete a data object. If you want to delete a project data object, you can open any process in the project.

2. Select a flow object that enables data associations. See Table 7-2 for the list of sequence flows that allow data associations.

3. Click Data Associations

4. In the Data Objects column, expand the process or project containing the data object you want to delete, then select the data object.

5. Click the Delete icon

Note:

You can delete simple and complex data objects. However, you cannot delete simple data objects within complex data objects.

7.2.2.1 What You Need to Know About Deleting Data Objects

After deleting a data object, you must ensure that all references to it are removed. This includes any data associations and expressions that use the data object. If you do not remove references to the deleted data object, the project does not validate.

7.2.3 How to Configure Data Associations for a Flow Object

You can configure data associatons for flow objects.

To configure a data association for a flow object:

1. Open the process where you want to configure data associations.

2. Select a flow object that enables data associations. See Table 7-2 for the list of sequence flows that allow data associations.

3. Click Data Associations.

4. From the data objects column on the right, select the data object you want to map as an input argument.

5. Click and drag the data object to an input text field.

7.3 Working with Business Indicators and Counter Marks

This section describes how to create business indicators and counter marks using Business Process Composer.

7.3.1 Introduction to Business Indicators and Counters

Business Indicators are project data objects you use to store the value of the key performance indicators of your process. For your convenience business indicators have their own entry in the structure window. Although Oracle BPM allows you to create business indicators using different types of data objects, Business Process Composer only allows you to create business indicators used as counter marks.

Counters keep track of the number of times an instance completes a certain activity. You must use them with counter marks. The counter variable does not store the actual value, its value is always 1. The value that specifies the number of times an instance completes an activity is updated directly in the Process Analytics databases. To monitor the value of a counter business indicator, you must create a dashboard based on a counter mark that is configured to track this counter business indicator.

7.3.2 Introduction to Counter Marks

Counter marks enable you to update the value of the counter business indicators defined for your process. A counter mark may update multiple counter mark business indicators. When a token arrives at an activity that has a counter mark defined, the BPM Service Engine updates the value of its associated counters in the Process Analytics databases. Each time the BPM Service Engine updates a counter business indicator, it adds one unit to the current value.

Note:

The actual value of the counter variable is stored in the Process Analytics databases. You must not use the counter variable in your process to perform any calculations because its default value never changes. The value of the counter variable is always equal to 1.

You can use counter marks for the following:

• Auditing: The number of activities the instance completed combined with other performance measurements are important information for auditing the process.

• Identifying performance issues: You can use a counter to identify performance issues within your process. Your process might be taking longer than expected because the instances are following a different path than expected or because the loop in an activity is running more times than it should. You can identify these situations by comparing the actual number of completed activities to the number you expected.

• Identifying the process path the instance followed: You can mark different paths using different counter business indicators. When the instance reaches the end of the process, the path the instance followed has the greatest number of completed activities.

Typically you define one counter business indicator for each of the process paths you want to monitor. Then you add counter marks in all the activities that are part of that process path. Finally you associate the counter business indicators that correspond to the paths that activity is part of, to the counter mark.

7.3.3 How to Add a New Counter Mark to a Process

You can add new counter marks to activities and tasks within your process.

To add a new counter mark to a process

1. Right-click on the task or activity where you want to add a counter mark.

2. Select Create Counter Mark.

3. If required, create a new business indicator.

   1. Click the Add button.

   2. Provide a name for the business indicator.

   3. Click OK.

4. Select the business indicators you want to assign to this counter mark.

5. Click OK.

7.3.4 How to Edit a Counter Mark

After you have added a counter mark to an activity or task, you can edit the business indicators assigned to it.

To edit a counter mark:

1. Right-click on the activity or task where you want to edit a counter mark.

2. Select Properties.

3. Select the Counter tab.

4. Edit the counter mark as necessary.

5. Click OK.

7.3.5 How to Delete a Counter Mark

You can delete counter marks you have defined within a process.

To delete a counter mark:

1. Right-click the activity or task where you want to delete a counter mark.

2. Select Delete Counter Mark.

7.4 Introduction to Expressions

Expressions allow you to perform calculations on data objects. Using Business Process Composer, you can define and edit expressions in the following contexts:

• Conditional sequence flows

• Complex gateways

• Timer events

• Data associations

Expressions do not allow you to directly reassign the values to data objects. However, you can use expressions to change the values passed to and from the implementation of a sequence flow. See Section 7.1.4, "Introduction to Data Associations" for more information.

7.4.1 Types of Expressions

Oracle Business Process Composer supports the following types of expressions:

• Simple

• Plain text

• XML Literal

7.4.2 Simple Expressions

Simple expressions are defined using a basic expression language supported by Oracle BPM.

7.4.2.1 Operator Types

Simple expressions support the following operator types:

• Arithmetic Operators

• Unary Operators

• Equality and Relational Operators

• Conditional Operators

You can use these operators to write expressions and conditions to define your process flow. Generally these expressions perform their calculations based on the data objects in your process. You can write expressions and conditions using the value of the data objects, but you cannot modify their value.

The following examples of expressions use operators:

• totalAmount - discount

• activationCount > 3

• unitsSold <= 1200

Table 7-4, Table 7-5, Table 7-6, and Table 7-7 describe the supported operators in the simple expression builder.

Table 7-4 Arithmetic Operators

Operator	Name	Description
+	Addition	Adds numeric data types. Concatenates Strings.
-	Subtraction	Subtracts numeric data types.
*	Multiplication	Multiplies numeric data types.
/	Division	Divides numeric data types.
rem	Remainder	Calculates the remainder of a division in which the divisor does not exactly divide the dividend.
( )	Precedence	Indicates the order of evaluation of an arithmetic expression.

Table 7-5 Unary Operators

Operator	Name	Description
+	Plus	Has no effect in the value of the numeric operand. Use it to indicate explicitly that a certain value is positive.
-	Minus	Negates an arithmetic expression.
*	Not	Logical complement operator. Negates the value of a boolean expression.

Table 7-6 Equality and Relational Operators

Operator	Name	Description
= or ==	Equal	Returns true is the first operand equals the second operand.
!=	Not Equal	Returns true is the first operand is not equal to the second operand.
>	Greater Than	Returns true if the first operand is greater than the second operand.
>=	Greater Than or Equal to	Returns true if the first operand is greater than or equal to the second operand.
<	Less Than	Returns true if the first operand is less than the second operand.
<=	Less Than or Equal to	Returns true if the first operand is less than or equal to the second operand.

Table 7-7 Conditional Operators

Operator	Name	Description
and	Conditional And	Returns true if both operands evaluate to true.
or	Conditional Or	Returns true if either operand evaluates to true.

7.4.2.2 Operator Precedence

Operator precedence indicates the order in which the compiler evaluates them. You can change operator precedence in an expression by using parenthesis.

In Oracle BPM the operator precedence is:

• Addition, Subtraction

• Multiplication, Division, Remainder

• Plus and Minus

• Less than, Greater Than, Less Than or Equal to, Greater Than or Equal to

• Equal, Not Equal

• Not

• Conditional And

• Conditional Or

7.5 Defining Process Input and Output

When you add operations to a BPMN process, you are defining points in the process that other processes or services can use to communicate with it. The communication between processes and other processes or services generally requires an input and returns an output. The flow events that you use you to define the BPMN process operations enable you to define input and output arguments. These input and output arguments define the process input and output.

7.5.1 How to Define the Input Arguments for a Process

When you create a process that begins with a message start event, you must define the input arguments to that are passed to that process.

To define the input arguments for a process:

1. Add a message start event to your process.

2. Right-click on the message start event, the select Properties.

3. Click the Implementation tab.

4. Select Define Interface.

5. Click the Add icon.

6. Determine the type of data object.

7. Click OK.

7.5.2 How to Define Data Associations for a Message Start Event

After you have defined the input arguments to your process, you must map them to data objects in your process.

To define data associations for a message start event:

1. Select the message start event of your process.

2. Click Data Associations.

3. Drag the data objects from the list on the right-hand side to the text boxes listed under Outputs.

4. Click Apply.

7.5.3 How to Define the Output Arguments for a Process

When you create a process that contains message end events, you must define the output arguments for each end event. These are the output arguments for the process.

To define the output arguments for a process:

1. Add a message end event to your process.

2. Right-click on the message end event, then select Properties.

3. Click the Implementation tab.

4. Select Define Interface.

5. Click the Add icon.

6. Determine the type of data object.

7. Click OK.

7.5.4 How to Define Data Association for a Message End Event

After you have defined the output arguments for your process, you must map them to the data objects in your process.

To define data associations for a message end event:

1. Select a message end event in your process.

2. Click Data Associations.

3. Drag the data objects from the list on the right-hand side to the text boxes listed under Inputs.

4. Click Apply.

7.6 Introduction to the Expression Editor

The expression editor provides a simple way of creating expressions by allowing you to select data objects and operators from a list and insert them into your expression. You can also enter the expression manually if necessary.

Figure 7-6 shows the expression editor user interface.

Figure 7-6 The Oracle Business Process Composer Expression Editor

Description of "Figure 7-6 The Oracle Business Process Composer Expression Editor"

Table 7-8 The Expression Editor User Interface

Area	Description
Expression field	Contains the text of the expression. You can edit this field directly, or use the Insert Into Expression tool.
Insert Into Expression	Inserts the selected data object or operator into the expression.
Data Object and Operator Chooser	Contain tabbed panes that allow you to select the data object or operator you want to insert into the expression.
Description tab	Provides a description of the selected operator.
Errors	Displays errors in the current expression.

7.7 Working with Expressions

The following sections describe how to define expressions using Business Process Composer.

7.7.1 How to Define a Simple Expression for a Conditional Sequence Flow

Using Business Process Composer, you can create and edit expressions for conditional sequence flows. Conditional sequence use expression to determine the flow of your process.

To define an expression for a conditional sequence flow:

1. Open your process.

2. Ensure that the project is in edit mode.

3. Right-click a conditional transition, then select Properties.

4. Click Edit.

   The expression editor window displays.

5. Add any required data objects and operators.

   To add a data object to an expression:

   1. Select the Data Objects tab.

   2. Select a data object from the list.

      If you add a basic data object that is part of a complex data objects, expand the complex data object and select the basic data object.

   3. Click Insert Into Expression

   To add an operator to an expression:

   1. Select the Operators tab.

   2. From the expandable list, select the operator you want to add.

   3. Click Insert Into Expression.

6. Click the Error tab, then verify that there are no errors in your expression.

7. Click OK.

7.7.2 How to Define a Simple Expression in Data Associations

Using Business Process Composer, you can create and edit expressions for Data associations. Data associations use expression to alter the values data objects passed as inputs. and outputs.

To define an expression within a data association input or output:

1. Open your process

2. Ensure that the project is in edit mode.

3. Select an activity in your process, then click Data Associations in the process editor toolbar.

4. Click Launch Expression Builder.

5. Add any required data objects and operators.

   To add a data object to an expression:

   1. Select the Data Objects tab.

   2. Select a data object from the list.

      If you add a basic data object that is part of a complex data objects, expand the complex data object and select the basic data object.

   3. Click Insert Into Expression

   To add an operator to an expression:

   1. Select the Operators tab.

   2. From the expandable list, select the operator you want to add.

   3. Click Insert Into Expression.

6. Click the Error tab, then verify that there are no errors in your expression.

7. Click OK.