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.

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.

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

Changes made to a shared business object instance are tracked by the system. However, if the property of a shared business object instance or one of its nested complex type properties is of the following type, changes cannot be tracked:
  • Map
  • XMLDocument
  • XMLElement
  • XMLNodeList

Changes that are made to the value of such a variable type cannot be recognized. For example, it cannot recognize when you add an entry to a map. As a result, the shared business object instance isn’t saved 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.