External Variable Ingestion
The external variable ingestion API is a beta feature and will be subject to future changes.
With the external variable ingestion API, variable data held in external systems can be ingested into Optimize directly, without the need for these variables to be present in your Camunda platform data. This can be useful when external business data, which is relevant for process analysis in Optimize, is to be associated with specific process instances. Especially if this data changes over time it is advisable to use this REST API to persist external variable updates to Optimize, as otherwise Optimize may not be aware of data changes in the external system.
The external variable ingestion API allows users to ingest batches of variable data which Optimize stores in a dedicated index. All variable data includes a reference to the process instance each variable belongs to, this reference then enables Optimize to import external variable data from the dedicated index to their respective process instances at regular intervals. Once Optimize has updated the process instance data, the external variables are available for Report evaluations in Optimize.
Please note that external variables should be treated as separate from engine variables. If you ingest variables that are already present in the engine, engine imports may override the ingested data and vice versa, leading to unreliable report results. Similarly, if the same ingested batch contains variables with duplicate IDs, you may experience unexpected report results because Optimize will assume only one of the updates per ID and batch to be the most up to date one. Also please ensure that the reference information (process instance ID and process definition key) is accurate, as otherwise Optimize will not be able to correctly associate variables with instance data and may create new instance indices, resulting in data which will not be usable in reports. External variables can only be ingested for process instances and will not be affected by any configured variable plugin.
Please refer to the configuration section to learn more about how to set up external variable ingestion.
Every variable ingestion request has to be authorized with an authorization token, this token can either be given as
Authorization request header or as a URI Query Parameter
access_token. This token is configurable, please refer to
the configuration section for further
Given a valid token,
mySecret, the header would need to be set in one of the following ways:
Authorization: Bearer mySecret
For sending the token as a query parameter the HTTP Query would look like the following:
Method & HTTP Target Resource
The following request headers have to be provided with every variable ingestion request:
The request body contains an array of variable JSON Objects:
|The unique identifier of this variable.
|The name of the variable.
|The type of the variable. Must be one of: String, Short, Long, Double, Integer, Boolean or Date.
|The current value of the variable.
|The ID of the process instance this variable is to be associated with.
|The definition key of the process instance this variable is to be associated with.
This method returns no content.
Possible HTTP Response Status codes:
|Returned if some of the properties in the request body are invalid or missing.
|Secret incorrect or missing. See Authorization on how to authorize.
"value": "Main Street 1",