5 Handling Information in Your Process Design

This chapter describes how to handle the information in your process using data objects and project data objects. It also shows you how to pass that information along the process and how to transform it when necessary.

This chapter includes the following sections:

5.1 Introduction to Handling Information in Your Process Design

Processes make use of information and also generate information from their tasks. Process flows can be affected by information values.

Oracle BPM supports the following data structures to keep track of this information:

Process Data Objects
Subprocess Data Objects
Project Data Objects
Arguments

Additionally, you can pass information between the different elements of a process using data associations. Data associations enable you to map the values of project and process data objects to the input and output arguments of the flow object implementations.

The Structure window shows the different data structures in your project: data objects, project data objects, and business indicators. For callable process it also shows arguments.

Figure 5-1 Shows the Structure window for a process that defines business indicators and process data objects.

Figure 5-1 Structure Window

Description of "Figure 5-1 Structure Window"

5.1.1 Basic Data Objects versus Complex Data Objects

Basic data objects are defined using basic data types such as int, boolean or string.

Complex data objects are defined using business objects and can group data. See Modeling Business Objects for more information on how to define business objects.

Business objects include 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.

The structure of complex data objects is the same for all the process instances of a process. However the data values they contain are specific to each instance of a process.

Figure 5-2 shows the relationship between basic data objects and complex data objects.

Figure 5-2 Basic Data Objects versus Complex Data Objects

Description of "Figure 5-2 Basic Data Objects versus Complex Data Objects"

5.2 Introduction to Data Objects

The main elements of a business process are tasks and information related to those tasks. The information in a process instance changes as the process executes. The information in a process instance defines the state of the process instance at any given time.

This information also determines how a process behaves and can change its flow of execution. You can monitor this information or store it to an external system.

The Sales Quote example process uses the following information:

Approval flow
Approval terms outcome
Quote

Oracle BPM uses data objects to store the information related to the process. The value of these variables may or may not change as you run the process.

Oracle BPM data objects have the following characteristics:

A name that identifies the data object
A data type that determines the type of data that can be stored in the variable.

Data objects store information related to each process instance you create. The value of these data objects is different for every instance in the process. However the structure of the data object is the same for all process instances.

When you define a process you must define the data object to store information. You must also define in which part of the process you assign a value to these data objects. The value of data objects may come from the user input, from external systems or might be calculated based on other data objects.

When you create an instance, the Process Engine assigns Null as the default value for all the data objects defined for that process. Later on the activities in the process assign values to these variables.

In the purchase order process each order has its own total amount, payment type and customer ID. You can model this data by defining data objects that store this process information.

5.2.1 Supported Data Types for Data Objects

Data objects can be of the following data types:

string
int
boolean
double
decimal
time
duration
base64Binary
Component (enables you to select a complex data type)

Note:

The binary data type is only used to map elements of an XML schema type. You cannot perform any operations with binary data types, but they can be passed between different components and flow objects.

5.2.2 Default Values

If you configure a data object to initialize automatically, the BPMN Engine assigns it a default value. The default value varies according to the type of the data object.

Table 5-1 shows the default values for the supported data types.

Table 5-1 Default Values

Data Type	Default Value
string	""
time, date	'now'
int, double,decimal	0
boolean	false
duration	'0'

5.3 Working with Process Data Objects

Typically the services in your process modify the value of the data objects in your process, but you might assign them an initial value, or change their value during the process.

You can add new process data objects to the process you are working on. You can also edit or delete them.

5.3.1 How to Add a Process Data Object

You can add a process data object to store a value to use in your BPMN process.

To add a process data object:

In the Applications window, select the process where you want to add the data object.
In the Structure window, right-click the Process Data Objects node.
Select New.
Enter a name to identify the data object.
Select a type from the Type list.

To use a complex type, select <Component>.
If you selected <Component>, select a complex type:
1. Click the Browse Types button.
  
  The Browse Types dialog box appears.
2. Select a type from the list or create a Business Object by clicking the New button next to the search list.
  
  To locate a type, enter the name in the Search text box. If the type does not exist, the name you typed appears in red.
3. Click OK.
  
  The Browse Types dialog box closes and the complete name of the type you selected appears in the field next to the Browse Types button.
Optionally, check Auto Initialize to initialize the data object with a default value.
Click OK.

Note:

You can also add process data object from the Data Object tree in the Simple Expression Builder, XPath Expression Builder, and Data Association Dialog.

5.3.2 How to Edit a Process Data Object

You can modify the name and type of an existing process data object.

To edit a process data object:

In the Applications window, select the process that contains the data object you want to edit.
In the Structure window, expand the Process Data Objects node.
Right-click the data object you wan to edit.
Select Edit.

A dialog box to edit the data object name and type appears.
Make the changes you want.
Click OK.

5.3.3 How to Delete a Data Object

You can delete a data object that you do not need or use.

To delete a data object:

In the Applications window, select the process that contains the data object you want to delete.
In the Structure window, expand the Process Data Objects node.
Right-click the data object you want to edit.
Select Delete.

5.3.4 How to Assign a Value to a Process Data Object

You can assign values to process data objects using a script task.

To assign a value to a process data object:

In the Process Editor, add a script task to the process.
Edit the implementation properties of the script task.
Define the data association or transformation to assign the value to the process data object.

See Introduction to Data Associations for information on how to define a data association.

See Introduction to Transformations for information on how to define a transformation.

5.4 Introduction to Activity Instance Attributes

Some data, like the status of the process, applies to all the processes you define. You can use this data to trigger an event based on its value, or to provide it as input to a service. In both cases the process flow depends on the value of this data. Oracle BPM tracks this data using a predefined set of activity instance attributes.

You can access these activity instance attributes in the same way you access regular data objects, but you cannot assign them new values.

You can access activity instance attribute from the following components:

Data associations
Simple Expression Builder
XPath Expression Builder

Table 5-2 provides detailed information about the activity instance attributes available for the different elements of a process.

Table 5-2 Activity Instance Attributes

Name	Type	Description	Availability
state	string	Specifies the state of the instance. Possible values are: none ready active canceled aborted completing completed	In complex gateways
loopCounter	int	Specifies the number of times the engine ran this activity. The Process Engine updates this variable each time it runs a new loop.	In activities with loop marker.
loopCounter	int	Specifies the sequence number that identifies each of the activations of this activity. The BPMN Engine assigns this number to each activation when it runs the activity.	In activities with multi-instance marker.
numberOfInstances	int	.Specifies the number of activations created for a multi-instance activity. You can only access this value from the main instance.	In activities with multi-instance marker.
numberOfActiveInstances	int	Specifies the number of active inner instances for a multi-instance activity. You can only access this value from the main instance. For sequential multi-instance activities this value is either 1 or 0. For parallel multi-instance activities this value is smaller or equal to the value specified by the predefined data object numberOfInstances.	In activities with multi-instance marker.
numberOfCompletedInstances	int	Specifies the number of completed inner instances for a a multi-instance activity. You can only access this value from the main instance.	In activities with multi-instance marker.
numberOfTerminatedInstances	int	Specifies the number of terminated inner instances for a a multi-instance activity. You can only access this value from the main instance.	In activities with multi-instance marker.
activationCount	int	Specifies the number of tokens in the incoming sequence flow of the gateway.	In complex gateways.

5.5 Working with Activity Instance Attributes

Some process elements support activity instance attributes. You can use these activity instance attributes to control the flow of a process.

Generally the Process Engine assigns the values of activity instance attributes, however some of them require you to assign them a value.

5.6 Introduction to Subprocess Data Objects

You can define data objects for a certain subprocess. These data objects are available only when the subprocess is running. When the instance leaves the subprocess the value of subprocess data objects is lost.

Using subprocess data objects is a good practice because:

It reduces the number of unnecessary data objects in the main process, making it simpler and easier to read.
By reducing the number of process data objects, it reduces the amount of memory each process instance occupies.
It makes the subprocess easier to understand.

5.7 Working with Subprocess Data Objects

From within a subprocess you can access process data objects and subprocess data objects. If the name of a subprocess data object matches the name of a process data object, then when you access the data object you obtain the value of the subprocess data object.

You can add new project data objects to subprocesses. If necessary you can edit or delete them.

5.7.1 Adding a Data Object to a Subprocess

You can add data object to a subprocess. You can only access this data objects from within the subprocess.

To add a data object to a subprocess:

In the Applications window, select the process that contains the subprocess where you want to add a data object.
In the Structure window, expand the Activities node.

The expanded node shows the subnodes Activities, Events and Gateways.
Expand the Activities subnode.
Expand the node that corresponds to the subprocess.
Right-click the Data Objects node located under the subprocess node.
Select New.
Provide a name to identify the new data object.
From the Type list, select a type.

To use a complex type, select <Component>.
If you selected <Component>, select a complex type:
1. Click the Browse Types button.
  
  The Browse Types dialog box appears.
2. Select a type from the list or create a Business Object by clicking the New button next to the search list.
  
  To locate a type, enter the name in the Search text box. If the type does not exist, the name you typed appears in red.
3. Click OK.
  
  The Browse Types dialog box closes and the complete name of the type you selected appears in the field next to the Browse Types button.
Optionally, check Auto Initialize to initialize the data object with a default value.
Click OK.

5.7.2 Editing a Data Object in a Subprocess

You can modify the name and type of an existing subprocess data object.

To edit a data object in a subprocess:

In the Applications window, select the process that contains the subprocess with the data object you want to edit.
In the Structure window, expand the Activities node.

The expanded node shows the subnodes Activities, Events and Gateways.
Expand the Activities subnode.
Expand the node that corresponds to the subprocess.
Expand the Data Objects node located under the subprocess node.
Right-click the data object you want to edit.
Select Edit.

A dialog box to edit the data object name and type appears.
Make the changes you want.
Click OK.

5.7.3 Deleting a Data Object from a Subprocess

You delete a subprocess data object that you do not need or use. If there are flow objects in your subprocess that use the removed data object, then you must remove these references manually.

To delete a data object from a subprocess:

In the Applications window, select the process that contains the subprocess with the data object you want to delete.
In the Structure window, expand the Activities node.

The expanded node shows the subnodes Activities, Events and Gateways.
Expand the Activities subnode.
Expand the node that corresponds to the subprocess.
Expand the Data Objects node located under the subprocess node.
Right-click the data object you want to delete.
Select Delete.

5.8 Introduction to Project Data Objects

Project data objects allow you to ensure that all the processes in a certain project keep track of a set of data. Then each process has to assign and update the value of this data.

The processes in a BPM project often have a set of data they share. 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. The value of this data is different for every instance in each of those processes, they only share the necessity to keep track of that data.

The processes in a BPM project only share the data definition of project data objects, not their actual values. Each BPMN process has its own copy of the project data object with a value that might or might not be different.

5.8.1 Business Indicators

When you mark a project data object as a business indicator the Process Engine stores its value in the Process Analytics databases. You can use this information to monitor the performance of your business processes.

For more information about Process Analytics, see Using Process Analytics.

5.8.2 Supported Data Types for Project Data Objects

You can set the type of a project data object to the following data types:

string
int
boolean
double
decimal
time
duration
base64Binary
Component

5.9 Working with Project Data Objects

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

Another benefit is that if you change the definition of a data object, then you only have to do it one time, as opposed to having to make those changes in all the processes in the project that define the same data object.

You can add new project data objects to the project you are working on. You can also edit or delete them.

Note:

It is not advisable to change the data type of a project data object after deploying a BPM Project. This can cause problems when the Process Workspace tries to render the value of the instances created before changing the data type.

Note:

Avoid naming a project data object with the same name used for a process data object. If you name a process data object and a project data object with the same name, then the data associations editor does not allow you to access the project data object.

5.9.1 How to Add a Project Data Object

To add a project data object:

In the Applications window, select a process from the Project whose project data object you want to edit.
In the Structure window, right-click the Project Data Objects node.
Select New.
Provide a name to identify the new project data object.

Note:

You cannot use the name of existing process data objects.
Select a type.

Available types are: string, int, double, decimal, boolean, time.
Optionally, check Auto Initialize to initialize the project data object with a default value.
Click OK.

Note:

You can also add process data object from the Data Object tree in the Simple Expression Builder, XPath Expression Builder, and Data Association Dialog.

5.9.2 How to Edit a Project Data Object

You can modify the name and type of an existing project data object.

To edit a project data object:

In the Applications window, select a process from the Project whose project data object you want to edit.
In the Structure window, expand the Project Data Objects node.
Right-click the project data object you want to edit.
Select Edit.

A dialog box to edit the project data object properties appears.
Make the changes you want.
Click OK.

5.9.3 How to Delete a Project Data Object

You can delete a project data object that you do not use or need. If there are processes in your project that use the deleted project data object, then you must remove these references manually.

How to delete a project data object:

In the Applications window, select a process from the Project whose project data object you want to edit.
In the Applications window, select a project.
In the Structure windows, expand the Project Data Objects node.
Right-click the project data object you want to delete.

5.9.4 How to Assign a Value to a Project Data Object

You can assign a value to a project data object using a script task.

To assign a value to a project data object:

In the Process Editor, add a script task to the process.
Edit the implementation properties of the script task.
Define the data association or transformation to assign the value to the project data object.

See Introduction to Data Associations for information on how to define a data association.

See Introduction to Transformations for information on how to define a transformation.

5.10 Introduction to Arguments

You use arguments to pass data between the different components in a process.

A component may require you to provide certain data when you invoke it. To pass this data you use input arguments. When you run a component, it provides results through its output arguments.

The process components that may have arguments are:

Service Operations: may require data to process and may provide data that contains the results of running them, the input and output arguments of the component represent this data.
Human Tasks: may require data to run and may provide data that contains the results of running them, the input and output arguments of the Human Task represent this data.
Business Rules: require an input that they use to evaluate the rules they contain, they return the result of this evaluation using output arguments. When you run a Business Rule using a business rule task it uses the input and output arguments to invoke the selected decision function.
Message Start Events: enable you to define input arguments. You can add input arguments to a start event when a process is used as a subprocess and it receives data from the invoking process. These input arguments represent the data that a process requires when another process invokes it.
Message End Events: enable you to define output arguments. You can add input arguments to an end event, when a process is used as a subprocess and passes information to the process that invokes it. These output arguments represent the data that result from running the process.
Catch Events: allow you to define input and output arguments that define the process interface. If the operation they expose is asynchronous, then you can only define input arguments. If the operation they expose is synchronous, then you can define input and output arguments.
Throw Events: enable you to define input and output arguments that define the process interface.If the operation they expose is asynchronous, then you can only define output arguments. If the operation they expose is synchronous, then you can define input and output arguments.

5.11 Naming Conventions

Names of process data objects, projects data objects, and arguments should follow certain conventions.

You should respect the following rules:

Use one or more nouns, or nouns modified by adjectives.
Do not start the name with a digit.
Use capital letters only to distinguish internal words.
Keep names simple and descriptive.
Use whole words, avoid using acronyms, unless they are widely known.
Avoid using the same name for a process data object and a project data object.

5.12 Scope and Access

The scope and access to process data objects, subprocess data objects, project data objects, and arguments varies according to the structure used to store information.

Process Data Objects: You can access them from any task within the process. The Process Engine creates them when it creates an instance in the process. Generally the process data objects have different values for each instance in the process. After the instance arrives to the end event, you cannot access process data objects anymore.
Subprocess Data Objects: You can access them from any task within a subprocess. The Process Engine creates them when the subprocess is triggered. After the instance leaves the subprocess, these data objects are no longer available.
Project Data Objects: You can define project data objects at a project level. However, the scope of project data objects is a process. Project data objects are predefined for all the processes in a BPM project. The value of a project data object may vary between processes. Generally project data objects have different values for each instance in the process. You can access project data objects from any process in a project, however the value assigned to it during a process is lost when the process finishes running. Figure 7-12 shows the difference between the scope and the life span of project data objects.
Arguments: You can only access arguments from within data associations. You use arguments to pass information between processes or process components. When the Process Engine runs a process or a process element that contains a data association, it maps the value of the arguments to the data objects defined in the data association.

Figure 5-3 shows the scope of input arguments, process data objects, subprocess data objects and output arguments. The image shows a BPMN process and the red bars with the variables name show the scope where those variables are available.

Figure 5-3 Scope of the Data Structures in a Process

Description of "Figure 5-3 Scope of the Data Structures in a Process"

Figure 5-4 shows the scope and life span of project data object. The image the various BPMN processes in a BPM project, above them there is a red bar that indicates the scope of the project data objects, below each process there is a green bar that indicates their life span.

Figure 5-4 Scope and Life Span of Project Data Objects

Description of "Figure 5-4 Scope and Life Span of Project Data Objects"

5.13 Introduction to Data Associations

Data associations are used to pass the information stored in data objects in the certain contexts.

Data associations can be used to pass data:

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 5-4 lists the flow objects where you can define data associations. It also lists the objects implemented.

Table 5-3 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
Error events	Exception
Signal events	Event

You can use data associations to define the input and output from a flow object to 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 defined values are passed to the implemented systems and services.

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

5.13.1 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 5-5 shows the data association for the Enter Quote user task in the Sales Quote example.

Figure 5-5 The Data Association Editor

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

Table 5-4 describes the different areas of the data association editor.

Table 5-4 The Data Association Editor User Interface

UI Area	Description
Input Tab	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
Output Tab	Contains text boxes that display the data objects assigned as outputs from the service or process implemented in the flow object.
Flow Object Tree	Contains an Arguments node that lists all the expected argument. According to the tab you selected it lists input or output arguments. You can expand complex data objects to map to specific basic data objects within a complex data object.
Data Objects Tree	Displays all the data objects. This tree contains process data objects, predefined data objects and project data objects.You can expand complex data objects to map to specific basic data objects within a complex data object.

5.14 Introduction to Transformations

You can use XSL transformations to transform the values of a data object in the process before they are passed to a flow object as input arguments. XSL transformations can also transform the values of the output arguments of a flow object before you assign them to the data objects in the process.

You can combine the use of transformations with the use of data associations only if you apply them over different arguments.

Note:

You must not use transformations and data associations to map the value of an argument simultaneously.

5.15 Defining Transformations

When you define the transformation you can only use as sources data objects that are based on an business object created using an XML schema or type.

You can edit the transformations you create using the SOA XLS Editor. See Developing SOA Applications with Oracle SOA Suite for more information on how to use the SOA XLS Editor.

5.15.1 How to Define a Transformation

You can define an XSLT transformation to transform the data you pass to and from the implementation of a flow object.

To Define a transformation:

Edit the flow object implementation properties.
Click the Data Associations link.

The Data Associations dialog box appears.
Click the Transformations button located in the upper right corner and drag it to the target node.
Drop the transformation in the target node.

The Create Transformation dialog box appears.
From the Sources List, select a source.

The sources list only contains data objects that are based on a business object created using an XML schema or type.
Click Add.

The source appears in the Selected Elements list.
From the Target list, select a target to assign the result of the transformation.
In the Transformation section select a way to define the transformation:
- Create: creates a new transformation and opens the SOA transformation editor for you to define the transformation.
- Use Existing: enables you to select an existing transformation that you copied to the project XSL directory.

5.15.2 What Happens When You Define a Transformation

The BPMN Service Engine uses the specified XSL transformation to assign the values of the input an output arguments of a flow object. The XSL transformation modifies the values before assigning them.