Skip to main content

History Level Configuration

Introduction​

The Flowable engines generate many different types of historical data, when executing processes, cases, decision tables, etc. This historical data is stored in the relation database tables and accessible by various Java and REST API's. This historical data is also used when reindexing data in Flowable Work.

The "history level" is a setting that can be configured globally or on a BPMN/CMMN model level and it defines what data is retained in the historical data tables. Flowable Work ships with a default setting that stores quite a bit of historical data, as many customers want or need to keep this data for various purposes.

However, in certain situations such as for example high-volume microservice orchestrations there is no need to store all this data or any data at all. In such occassions, it might be worthwhile to use a history level that stores less data as to not have the database size grow out of control.

BPMN​

The history level for a particular BPMN model can be set when no element is selected in Flowable Design. All instances of that model will use that history level at runtime.

For BPMN the history levels are (in order of amount of data stored):

  • None: No history is stored.
  • Instance: Only one entry is stored that contains process instance information. This level is useful if you need a single entry per instance to store that the instance has ran, but no additional data such as variables is needed.
  • Task: Same as instance level but additionally stores an entry for each user task executed.
  • Activity: Same as Task level, but additionally stores an entry for each activity executed in the instance. Also stores a historical counterpart of all variables.
  • Audit: Same as Activity, but additionally stores historical information about identitylinks and entitylinks even after instances have been completed. This is the default audit level.
  • Full: Same as Audit, but stores variable changes. Be careful, as this generates a lot of data.

CMMN​

The history level for a particular CMMN model can be set when no element is selected in Flowable Design. All instances of that model will use that history level at runtime.

For CMMN the history levels are (in order of amount of data stored):

  • None: No history is stored.
  • Instance: Only one entry is stored that contains case instance information. This level is useful if you need a single entry per instance to store that the instance has ran, but no additional data such as variables is needed.
  • Task: Same as instance level but additionally stores an entry for each user task executed.
  • Activity: Same as Task level, but additionally stores an entry for each plan item executed in the instance. Also stores entries for all milestones reached.
  • Audit: Same as Activity, but additionally stores historical information about identitylinks and entitylinks even after instances have been completed. Also stores a historical counterpart of all variables. This is the default audit level.
  • Full: Same as Audit, but stores variable changes. Be careful, as this generates a lot of data.

Selectively Storing Activity or Planitem History​

In certain situations it's wanted to run with none, instance or task history level. In such occasions, there won't be a historical trace of which activities have been executed.

All activities in BPMN and all plan items in CMMN have the Include in history flag however: when checked, its history will be stored, regardless of the history level.

Selectively Storing Variable History​

In certain situations it's wanted to run with none, instance or task history level. In such occasions, there won't be a historical storage of variables.

Both in BPMN and CMMN models it is possible to configure on the root level of the model which variables should be stored using the Allowed historic variable property. Variables configured in such a way will always be stored, regardless of the history level. This is useful, as when the amount of variables stored in those tables becomes large this has an impact on the table size and its related performance. By selecting only relevant variables, this problem can be alleviated.

Indexing​

As described in details in the indexing documentation, historical data is used to populate the various indices. When selectively configuring the history (or running on a lower non-default level) this means that certain indices won't contain certain data.

For example, when running with history level Task, the identity links such as participants are not stored (they are indeed mentioned in the Audit level above) which means this data won't be indexed and it cannot be used to build dashboards needing this data. In that case, the audit level would have to be chosen.

When running with the none level, data required for populating the Work inboxes (such as work and tasks) will not be available. Instances can still be started; however, they will not appear in the list upon refreshing the page. In such cases, evaluate whether running without indexing enabled is appropriate, as the data for the inboxes will be loaded from the database.

Note that reindexing of Elasticsearch data also uses the historical data to rebuild the indices, so the same reasoning applies there, too.