How variables are passed between BPD components at run time

Using variables, business data is passed between business process definition (BPD) components at run time. Depending on the components that are involved, the data is passed either by value or by reference.

Variables capture business data. If the business data is a simple type (for example, a String) then the variable contains a value of the business data. If the business data is a complex type, then the variable is a reference to an object that contains multiple values.

Variables can be passed by reference or by value, as shown in the following table.

Table 1. How variables are passed
Call		Pass-by
From	To	Simple type	Case property, complex business object, or shared business object
BPD activity	Linked BPD	Value	Reference (complex business object, shared business object)
BPD activity	Client-side human service	Value	Value (complex business object) Value with reference (shared business object)
BPD activity	Other service	Value	Value (complex business object) Value with reference (shared business object)
Case type activity	Linked BPD	Value	Value (case property) Reference (complex business object, shared business object)
Case type activity	Client-side human service	Value	Value (case property, complex business object) Value with reference (shared business object)
Case type activity	Other service	Value	Value (case property, complex business object) Value with reference (shared business object)
Client-side human service	Nested service	Value	Value (case property, complex business object) Value with reference (shared business object)
Other service	Nested service	Value	Value (case property) Reference (complex business object, shared business object)

BPDs, case types, and services have references to their variables. When complex variables are passed from a BPD or case type to a service, a deep copy of the variable is transferred from the BPD or case type space to the service space, and the service gets a reference to the copy. Similarly, when a complex variable is passed from the service to a BPD or case, a deep copy of the variable is transferred from the service space to the BPD or case type space, and the BPD or case type gets a reference to the copy.

When the service changes the values of the existing complex variable, the changed values are passed back to the BPD or case type by replacing the entire complex variable with a deep copy from the service. If the replaced variable was originally passed by value from an outer process (BPD or case type), the inner and outer processes no longer access the same variable. Therefore, changes made to the inner process are not reflected in the outer process.

Variables that are passed by reference

Most data interactions in a process are passed by reference (from BPD to BPD, between a case type activity and a linked BPD or subprocess, or from service to service). Therefore, most of the time the same object is passed from location to location. Also, changes to that object happen at all levels.

Variables that are passed by value

Variables between BPDs or case types and services are passed by value. When a variable is passed by value from a BPD or case type to an underlying service, the changes that are made to the variable in the service are not visible in the calling BPD or case. To make the variables visible to the caller, you must pass them back as output to the caller.

Variables that are passed by value with reference

For variables to be passed by value with reference, synchronization of business objects must be set either by using the save method or the Automatically sync shared business objects setting in the Overview section of the BPD or service. If a variable is defined as the system generated case folder variable, or as a shared business object type, its values are refreshed from the data store.

Shared business objects are passed by value with reference. This means that changes that you make are saved and propagated to other instances that work with the same data. The setting Automatically sync shared business objects must be enabled in the BPD or service to enable the automatic save and data synchronization.

For example, a shared object is passed by value with reference from a BPD to two different services. The BPD and services each contain a separate copy of the business object. When the first service completes, the shared object values are automatically persisted to the data store. When the second service starts, the shared object values are automatically loaded from the data store. So even though the BPD and the two services reference separate objects, the values of these objects are updated by the data store and the services operate on current data.

For information about shared business objects, see Creating custom business objects in Process Designer.

Example

An outer process has a reference, tw.local.pair, that points to a NameValuePair object, NVP1. The outer process passes the .pair reference to an inner process:

Outer process -> NVP1
Inner process -> NVP1

Changes to either process affect the other process.

The inner process passes the .pair reference to a service. A copy of NVP1 is made, NVP2, and a reference of the copy is passed to the service.

Outer process -> NVP1
Inner process -> NVP1
Service -> NVP2

The service exits and outputs the .pair reference, which is mapped back to the variable of the inner process .pair reference. A copy of NVP2 is created, NVP3, and a reference is passed back to the inner process.

Outer process -> NVP1
Inner process -> NVP3

Changes made to NVP3 are not reflected in NVP1.

If you want a service to modify a top-level variable in a BPD, use either an embedded server script to store the service result in a temporary variable and copy its members to the original variable, or a shared business object. The parent BPD is not updated until the child BPD has finished.

Guidelines for passing variables

Because of how variables are handled at run time, follow these guidelines:

If the variable is a simple type, declare the variable as an input and an output in linked BPDs, services, and nested services.
If an input variable is a complex type and you are passing it from a BPD to a service, it will be passed as a value. If you want the updated value to be returned, also declare it as an output variable. If the complex type is a shared business object, you do not need to return it as an output because the updates that are made in a service will become visible to everyone who uses the shared business object.
Always use an identical name and data type for a set of input and output variables for data that is passed in, processed, and then passed back.
For case types, instead of passing individual folder properties to linked BPDs, services, and nested services, pass the system-generated case folder variable by reference.