Instance Variables

Instance Variables are custom variables whose scope is contained within a process. Instance Variables contain information that flows through the process from the Begin to the End activities. The value of each variable is stored independently for each process instance.

Most activities within a process can access and modify the value of an Instance Variable, with the exception of Global Creation and Global Automatic activities. Global Interactive activities can access instance variables only when the Has Instance Access property of the activity is checked.

Examples of instance variables that may be found in a shipping order management process include: invoiceNumber, customerName, customerNumber, orderStatus, orderAmt and shipStatus.

Instance Variable Storage Categories

Instance variables have a property called category. This property determines how the Process Engine stores the value of the variable in the database, but does not affect the logic of the process. This property takes one of the following values:

Category	Description
Normal	By default instance variables are defined as normal, and only those that have some special characteristics need to be categorized in a different way. For each process instance, the process execution engine stores all normal instance variables together by serializing their values into a single BLOB in the Process Execution Engine database. After the execution of each process activity, the Engine updates this BLOB in the database. To keep resources under control, the process engine limits the size of this BLOB for each process instance. The Maximum Instance Size property of the Engine defines this limit (in kilobytes), and is configurable from the Process Administrator application. The default value is 16 KB.
Separated	The process execution engine stores separated variables in a separate table in the database. The Separated storage category is intended for variables which must hold large amounts of data (10 KB or more) and are used (and modified) rarely in the process. A common use case for separated variables is when the input to the process is a potentially big XML document, which must be parsed only once and is not modified throughout the process. If the variable holding the XML is defined as Normal, every time the process instance flows from activity to activity the XML is serialized to the database along with the other Normal variables (even if the XML was not modified). By defining the variable as Separated, the Process Engine updates Normal variables independently, updating the XML only if it was modified. Important: In Multiple Gateways, separated instance variables values are not automatically copied to the separated instance variables of the copies. They have to be copied manually in the Multiple Gateway PBL method. Note: The size of a the BLOB for Separated variables is only limited by the underlying DBMS used by the Process Execution Engine. Mind though that storing big data elements as instance variables (Normal or Separated) is not recommended as it has a negative impact on Engine performance.

Category

Description

Normal

By default instance variables are defined as normal, and only those that have some special characteristics need to be categorized in a different way. For each process instance, the process execution engine stores all normal instance variables together by serializing their values into a single BLOB in the Process Execution Engine database. After the execution of each process activity, the Engine updates this BLOB in the database.

To keep resources under control, the process engine limits the size of this BLOB for each process instance. The Maximum Instance Size property of the Engine defines this limit (in kilobytes), and is configurable from the Process Administrator application. The default value is 16 KB.

Separated

The process execution engine stores separated variables in a separate table in the database.

The Separated storage category is intended for variables which must hold large amounts of data (10 KB or more) and are used (and modified) rarely in the process.

A common use case for separated variables is when the input to the process is a potentially big XML document, which must be parsed only once and is not modified throughout the process. If the variable holding the XML is defined as Normal, every time the process instance flows from activity to activity the XML is serialized to the database along with the other Normal variables (even if the XML was not modified). By defining the variable as Separated, the Process Engine updates Normal variables independently, updating the XML only if it was modified.

Important: In Multiple Gateways, separated instance variables values are not automatically copied to the separated instance variables of the copies. They have to be copied manually in the Multiple Gateway PBL method.

Note: The size of a the BLOB for Separated variables is only limited by the underlying DBMS used by the Process Execution Engine. Mind though that storing big data elements as instance variables (Normal or Separated) is not recommended as it has a negative impact on Engine performance.

Default Values

Instance Variables are initialized based on their type according to the following table:

Type	Default Value
Numeric (int, real, decimal)	0
Boolean	FALSE
All other types	Null

Accessing Instance Variables

All PBL methods of the process can refer to any instance variable by the variable's name. You may also use the explicit this. prefix to avoid naming conflicts with variables defined at another scope (i.e.: argument or local variables).