8 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:

Section 8.1, "Introduction to Handling Information in Your Process Design"
Section 8.2, "Introduction to Data Objects"
Section 8.3, "Working with Process Data Objects"
Section 8.4, "Introduction to Activity Instance Attributes"
Section 8.5, "Working with Activity Instance Attributes"
Section 8.6, "Introduction to Subprocess Data Objects"
Section 8.7, "Working with Subprocess Data Objects"
Section 8.8, "Introduction to Project Data Objects"
Section 8.9, "Working with Project Data Objects"
Section 8.10, "Introduction to Arguments"
Section 8.11, "Naming Conventions"
Section 8.12, "Scope and Access"
Section 8.13, "Introduction to Data Associations"
Section 8.14, "Introduction to Transformations"
Section 8.15, "Defining Transformations"

8.1 Introduction to Handling Information in Your Process Design

Generally processes access and store information. Often the process flow is based on the value of this information. In other cases this information is the result of running the tasks in the process.

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 8-1 Shows the Structure window for a process that defines business indicators and process data objects.

Figure 8-1 Structure Window

Description of "Figure 8-1 Structure Window"

8.1.1 Basic Data Objects versus Complex Data Objects

Basic data objects are data objects defined using the basic types. For example, Int, Bool or String.

Complex data objects allow you to group data. Complex data objects are defined using business objects. See Chapter 13, "Modeling Business Objects" for more information on how to define 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.

The structure of complex data objects is the same for all the process instances of a process. However the data they contain generally varies between the different instances of the process.

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

Figure 8-2 Basic Data Objects versus Complex Data Objects

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

8.2 Introduction to Data Objects

The main elements of a business process are tasks and information related to those tasks. The information of a process may change as you run the process. This information defines the state of a process at a given time.

This information determines how the process behaves for a particular instance. According to the value of this information the instance may take one path or another. You may monitor this information or store it to an external system.

The information of a process may change as the process runs. This information defines the state of a process at a given time.

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.

8.2.1 Supported Data Types for Data Objects

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

String
Int
Bool
Real
Decimal
Time
Interval
Binary
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. You can only pass them between different components and flow objects.

8.2.2 Default Values

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

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

Table 8-1 Default Values

Data Type	Default Value
String	""
Time, Date	'now'
Int, Real, Decimal	0
Bool	false
Interval	'0'

8.3 Working with Process Data Objects

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

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.

8.3.1 How to Add a Process Data Object

To add a process data object:

In the BPM Project Navigator, 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 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 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.

8.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 BPM Project Navigator, 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 to edit the data object name and type appears.
Make the changes you want.
Click OK.

8.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 BPM Project Navigator, 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.

8.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 Section 8.13, "Introduction to Data Associations" for information on how to define a data association.

See Section 8.14, "Introduction to Transformations" for information on how to define a transformation.

8.4 Introduction to Activity Instance Attributes

Some data, like the status of the process, applies to all the process 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 8-2 provides detailed information about the activity instance attributes available for the different elements of a process.

Table 8-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.

8.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.

8.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.

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.

8.7 Working with Subprocess Data Objects

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

8.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 BPM Project Navigator, 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 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 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.

8.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 BPM Project Navigator, 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 to edit the data object name and type appears.
Make the changes you want.
Click OK.

8.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 BPM Project Navigator, 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.

8.8 Introduction to Project Data Objects

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.

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 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.

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.

8.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 Chapter 11, "Using Process Analytics".

8.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
Bool
Real
Decimal
Time
Interval
Binary
Component

8.9 Working with Project Data Objects

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

8.9.1 How to Add a Project Data Object

To add a project data object:

In the BPM Project Navigator, 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, Real, Decimal, Bool, 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.

8.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 BPM Project Navigator, 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 to edit the project data object properties appears.
Make the changes you want.
Click OK.

8.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 BPM Project Navigator, select a process from the Project whose project data object you want to edit.
In the BPM Project Navigator window, select a project.
In the Structure windows, expand the Project Data Objects node.
Right-click the project data object you want to delete.

8.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 Section 8.13, "Introduction to Data Associations" for information on how to define a data association.

See Section 8.14, "Introduction to Transformations" for information on how to define a transformation.

8.10 Introduction to Arguments

You can 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 it 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.

8.11 Naming Conventions

When you name a process data object, a project data object or an argument, you should respect the following rules:

Use one or more nouns, or nouns modified by adjectives.
Do not start the name with a number.
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.

8.12 Scope and Access

The scope an access 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 8-3 Scope of the Data Structures in a Process

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

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

Table 8-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

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

Figure 8-5 The Data Association Editor

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

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

Table 8-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.

8.14 Introduction to Transformations

You can use XSL transformations to transform:

the values of the data objects in the process, before you pass them to the implementation of a flow object as input arguments.
the values of the output arguments of a flow object implementation, before you assign them to the data objects in your 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.

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 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite for more information on how to use the SOA XLS Editor.

8.15 Defining Transformations

You can modify the values you use assign to input arguments and output arguments in the implementation of a flow object using XSL transformations.

8.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 appears.
Click the Transformations button located in the upper right corner and drag it to the target node.
Drop the tranformation in the target node.

The Create Transformation dialog 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.

8.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.