Chapter 13. Persistence and Transactions

13.1. Process Instance State

JBoss BPM Suite allows persistent storage of information. For example, you can persistently store process runtime state to ensure that you will be able to resume your process instance in case of failure. You can also store process definitions and logging information (logs of current and previous process states are stored by default).

13.1.1. Runtime State

When you start a process, JBoss BPM Suite creates a process instance, which represents the execution of the process in the specific context. For example, when you start a process that specifies how to process a sales order, JBoss BPM Suite creates a process instance for each order. A process instance represents the current execution state in that specific context, and contains all the information related to the process instance. Process instances contain minimal runtime state required to continue the execution at any time. However, it does not include process instance logs unless needed for execution of the process instance.
You can make the runtime state of an executing process persistent, for example, in a database. This allows you to restore the state of execution of all running processes in case of failure, or to temporarily remove running instances from memory and restore them at later time. JBoss BPM Suite allows you to plug in different persistence strategies. Note that process instances are not persistent by default.
When you configure the JBoss BPM Suite engine to use persistence, it automatically stores the runtime state into a database without further prompting. When you invoke the engine, it ensures that all changes are stored at the end of that invocation. If you encounter a failure and restore the engine from the database, do not manually resume the execution. Process instances automatically resume execution if they are triggered.
Inexperienced users should not directly access and modify database tables containing runtime persistence data. Changes in the runtime state of process instances which are not done by the engine may have unexpected results. If you require information about the current execution state of a process instance, use the history log.

13.1.2. Binary Persistence

Binary persistence, or marshaling, converts the state of the process instance into a binary dataset. Binary persistence is a mechanism used to store and retrieve information persistently. The same mechanism is also applied to the session state and work item states.
When you enable persistence of a process instance:
  • JBoss BPM Suite transforms the process instance information into binary data. Custom serialization is used instead of Java serialization for performance reasons.
  • The binary data is stored together with other process instance metadata, such as process instance ID, process ID, and the process start date.
The session can also store other forms of state, such as the state of timer jobs, or data required for business rules evaluation. Session state is stored separately as a binary dataset along with the ID of the session and metadata. You can restore the session state by reloading a session with given ID. Use ksession.getId() to get session ID.

13.1.3. Data Model Description

Process instance binary datasets are usually small because they contain only the minimal execution state of a process instance. Each entity of the data model is described below.
A data model that provides sessioninfo, processinstanceinfo, eventtypes, and workiteminfo nodes.

Figure 13.1. Data Model

The sessioninfo entity contains the state of the (knowledge) session in which the process instance is running.

Table 13.1. SessionInfo

Field Description Nullable
id The primary key. NOT NULL
lastmodificationdate The last time that the entity was saved to a database.  
rulesbytearray State of a session. NOT NULL
startdate The start time of a session.  
optlock Version field containing a lock value.  
The processinstanceinfo entity contains the state of the process instance.

Table 13.2. ProcessInstanceInfo

Field Description Nullable
instanceid The primary key. NOT NULL
lastmodificationdate The last time that the entity was saved to a database.  
lastreaddate Contains the last time that the entity was retrieved from the database.  
processid The ID of the process.  
processinstancebytearray State of a process instance in form of a binary dataset. NOT NULL
startdate The start time of the process.  
state An integer representing the state of a process instance. NOT NULL
optlock Version field containing a lock value.  
The eventtypes entity contains information about events that a process instance will undergo or has undergone.

Table 13.3. EventTypes

Field Description Nullable
instanceid Reference to the processinstanceinfo primary key, and foreign key constraint on this column. NOT NULL
element A finished event in the process.  
The workiteminfo entity contains the state of a work item.

Table 13.4. WorkItemInfo

Field Description Nullable
workitemid The primary key. NOT NULL
name The name of the work item.  
processinstanceid The (primary key) ID of the process. There is no foreign key constraint on this field. NOT NULL
state The state of a work item. NOT NULL
optlock Version field containing a lock value.  
workitembytearay Tthe state of a work item in form of a binary dataset. NOT NULL
The CorrelationKeyInfo entity contains information about correlation keys assigned to the given process instance - loose relationship as this table is considered optional. Use it only when you require correlation capabilities.

Table 13.5. CorrelationKeyInfo

Field Description Nullable
keyid The primary key. NOT NULL
name Assigned name of the correlation key.  
processinstanceid The id of the process instance which is assigned to the correlation key. NOT NULL
optlock Version field containing a lock value.  
The CorrelationPropertyInfo entity contains information about correlation properties for a correlation key assigned the process instance.

Table 13.6. CorrelationPropertyInfo

Field Description Nullable
propertyid The primary key. NOT NULL
name The name of the property.  
value The value of the property. NOT NULL
optlock Version field containing a lock value.  
correlationKey-keyid A foreign key to map to the correlation key. NOT NULL
The ContextMappingInfo entity contains information about the contextual information mapped to a Ksession. This is an internal part of RuntimeManager and can be considered optional when RuntimeManager is not used.

Table 13.7. ContextMappingInfo

Field Description Nullable
mappingid The primary key. NOT NULL
context_id Identifier of the context. NOT NULL
ksession_id Identifier of a Ksession. NOT NULL
optlock Version field containing a lock value.  

13.1.4. Safe Points

During the execution of the process engine, the state of a process instance is stored in safe points. When you execute a process instance, the engine continues to execute it until there are no more actions to be performed. That is, the process instance has been completed, aborted, or is in the wait state in all of its paths. At that point, the engine has reached the next safe state, and the state of the process instance (and all other process instances that it affected) is stored persistently.