Shared business objects

You can ensure the integrity of data that is passed between process components at run time by using shared business objects. The data in a shared business object is always current because it is refreshed from the data store before it is used. If you use shared business objects, you can also control how data is passed and how changes are handled in running processes and services.

General considerations

You create shared business objects like normal business objects by using JavaScript:

// Create shared object
tw.local.sharedObject = new tw.object.SharedObject();
tw.local.sharedObject.property = "value";

A shared business object has a key that you can retrieve by using JavaScript:

// Retrieve key for shared object
tw.local.sharedObjectKey = tw.local.sharedObject.metadata("key");
log.info("sharedObjectkey: " + tw.local.sharedObjectKey);

You can retrieve a shared business object by its key by using JavaScript:

// Retrieve shared object by key
var sharedObject2 = new tw.object.SharedObject(tw.local.sharedObjectKey);
log.info("sharedObject2.property: " + sharedObject2.property);

A shared business object is logically connected to the process instance that created it. If the shared business object is created in a human service that started independently of a process, it is connected to the corresponding task. Other process instances can also use the shared business object if it is referred to by one of the process variables. When the connected process or task is deleted and no other process instances refer to the shared business object, the shared business object is automatically deleted. When a new version of a shared business object is saved, older versions of the shared business object that are no longer required are automatically deleted. However, you can specify how many versions of business objects are kept in the system. For more information, see Cleaning up shared business objects.

Data in a shared business object is passed by reference between process components; the object's values are accessible to other instances at run time.

You can send data from one process to another process either by using a message event or by loading the data into the second process with the unique key of the shared business object.

Important: Do not return a shared business object as an output. Returning a shared business object on an output variable causes the local variable to refer to the new business object instance. You might receive outdated data if this variable is also used with other services or linked processes.

Data synchronization

Shared business objects allow concurrent modification. For example, two users can view and modify the same shared business object instance in a human service. When users trigger a boundary event, the data of the shared business object instance is saved. Only the fields that each user modifies are saved. Therefore, if two users modify different fields, both changes are saved. If both users modify the same field, the last user's update is saved. In addition to having multiple users, you can have a situation with automated steps, for example, a server script that modifies shared business objects.

By default, the data in a shared business object is persisted to the database and synchronized across all scopes when any of the following events occur:

The shared object is created.
Restriction: If a service is started independently of a process instance without a task, the data is not synchronized when the shared business object is created.
The state of a process instance is persisted and automatic synchronization is enabled for the process. If you use linked processes, at run time, the setting of the top-level business process definition is taken.
The state of a task or service instance is persisted and automatic synchronization is enabled for the service definition. If you use nested services, the setting of the top-level server definition is taken.

For processes and service implementations, you can specify whether the shared business objects in a process instance are automatically updated and saved when the business object is changed in other instances or tasks. You can control this behavior by using the setting for synchronizing business objects in the Overview section of a process or service. This setting is always enabled for case types created with the Basic Case Management feature in previous releases and cannot be turned off; it is never enabled for Ajax services and it cannot be turned on.

If automatic synchronization is not enabled for the process or the service implementation does not support automatic synchronization, you must invoke the JavaScript save method on the shared business object to persist the object data and the load method to load the latest data from the data store into the variable.

// Save the variable data
tw.local.sharedObject.save();

// Load the variable data
tw.local.sharedObject.load();

Tips:

If changes to business objects in processes and services are automatically synchronized and saved, do not include a save statement in your script.
Activity preconditions that are based on shared business objects require data synchronization so that they can be reevaluated when changes happen. For processes that contain ad hoc activities, always enable the synchronization setting. If you do not enable the setting, you must call the JavaScript load and save methods in a server script to load the latest content or to save changes.

Running process instances or services use the synchronization setting of the top-level process or service. Linked processes also use setting of the top-level process regardless of what is set for the linked process. Nested services use the synchronization setting of the top-level service.

Limitations to property types

In order to perform data synchronization, IBM® Business Process Manager keeps track of changes that are made to a shared business object instance. However, if the property of a shared business object instance or one of its nested complex type properties is of the following type, IBM BPM cannot track changes that are made to the property value:

Map
XMLDocument
XMLElement
XMLNodeList

IBM BPM does not recognize changes that are made to the value of such a type of variable. For example, it cannot recognize when you add an entry to a map. As a result, IBM BPM does not save the shared business object instance even if you invoke the save() function explicitly.

Consider using the Record business object instead of the Map business object. It has similar capabilities and is not affected by this limitation.

Processes that use the Basic Case Management feature

New processes that use the Basic Case Management feature and converted case types automatically contain shared variables, backed by a system-generated private folder variable. This variable is a shared business object that mirrors the collection of properties that you define for the process. For example, when you add a folder property, a field with the same attributes is added to the business object. You cannot delete, instantiate, or directly modify this business object.

You can access the folder variable and its associated business object, just like a locally declared variable. To ensure the integrity of data wherever it is used, pass the folder variable, rather than individual properties, as arguments to linked processes and services. At run time, updates to property values are automatically synchronized between the running instance and the folder.

For case types from versions earlier than IBM BPM 8.5.6.0, you must first convert the case type into a process, and you can then add the private folder variable when you open the process for the first time in the editor. For more information, see Upgrading cases: Adding a case folder variable.

Additional considerations for services

An output shared business object for an external service, such as a web service, and an Advanced Integration service returns a new and typically updated copy of the original input shared business object. When the output mapping refers to the shared business object, the service returns a new shared business object. To return an updated version of the shared business object in the input mapping, refer to the individual fields of the shared business object in the output mapping.