For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10 (unreleased)

Object and list variable support

Object variables​

Complex object variables can be imported into Optimize and thereafter be used in reports and filters. During import, Optimize flattens the given object variable to create individual variables for each property of the object, resulting in multiple "sub variables" for each imported object variable.

For example, an object variable called user with the properties firstName and lastName will result in two flattened variables: user.firstName and user.lastName. These variables can be used within reports and filters.

In addition to the flattened properties, Optimize also imports the entire raw value of the object variable. In the example above, this creates a variable called user with the value {"firstName": "John", "lastName": "Smith"}. You can inspect this raw object variable in Raw Data Reports, but other report types and filters do not support it.

List variables​

Optimize also supports object variables that are JSON-serialized lists of primitive types, such as a list of strings or numbers. For Camunda 7 and external variables, the type of list variables must still be set to Object. During import, Optimize evaluates the number of entries in each list and persists it in an additional _listSize variable.

For example, a list variable with the name users and the values ["John Smith", "Jane Smith"] will result in two imported variables: one users variable with the two given values, and one variable called users._listSize with value 2. Both can be used in reports and filters.

However, filters are not yet fully optimized for list support, and some filter terms may be initially misleading. This is because filters currently apply to each list item individually rather than the entire list. For example, an "is" filter on a list of string values filters for those instances where any individual list item is equal to the given term, for example, instances whose list variable "contains" the selected value.

Similarly, the "contains" filter matches process instances whose list variable contains at least one value which in turn contains the given substring.

The value of list properties within objects as well as variables which are lists of objects rather than primitives can be inspected in the raw object variable value column accessible in raw data reports.

Optimize configuration​

As of Camunda 8.10, the import of object variable values is disabled by default. It can be enabled using the zeebe.includeObjectVariableValue configuration. Alternatively, this can be set using the CAMUNDA_OPTIMIZE_ZEEBE_INCLUDE_OBJECT_VARIABLE environment variable.

When enabled, each flattened property and the raw object itself are stored as separate variables. As a result, object-heavy processes can significantly increase Optimize's storage and CPU usage. See Impact of Optimize for sizing guidance.

When disabled (the default), Optimize logs a WARN on startup as a reminder, and object variables are neither flattened nor stored.

Depending on where the imported object variables originate, the following configuration is required to ensure that your system produces object variable data that Optimize can import correctly:

If you are creating object variables using a Zeebe process, ensure date properties within the JSON object are stored using a common date format (for example yyyy-MM-dd'T'HH:mm:ss.SSSZ) other than unix timestamps. If Optimize imports unix timestamp date properties, these properties cannot be identified and parsed as dates and will instead be persisted as number variables.