Persistent State Data Storage

To persist process data, the persistent state engine writes entries to generic database tables. Generic in this context means that the database tables do not depend on the process class - any process will be mapped to the same tables.

These tables hold information about the state of the process instance and all instance data. The lifecycle of the process instance is defined by the underlying state machine. This means, changes to the state of an instance are triggered by events.
Events in this context are completion events (triggered by an automatic state transition), signal events (triggered by a signal reception), and time events (triggered by a time trigger).

After having created a persistent state object representing the process instance, the object lives on the database until it reaches its final state (where it will be deleted).

Data Storage

Persistent states, data and pending events can be stored to the following locations.

Memory

Storing the persistent state data items to memory has a huge performance advantage over the possibilities. In case of service shutdown, the content of the state database is written to a local file, and read from the same file when the service is started again. The generated file pstate.db is a SQLite database file.

However, in the case of a power failure or server crash, any changes to the state database since the last startup will be lost.

As local file and memory use the same format, it is possible to switch between these configurations without losing any data.

Local File

A local file as data storage is about 5 times slower than memory. Unless the file system is corrupted, no data is lost upon power failure or server crash. The generated file pstate.db is a SQLite database file.

For Docker/Integration (Bridge), SQLite is the default configuration. This configuration should only be used for development and testing, though.
For productive usage, we strongly recommend to set up an external database, as SQLite is not ready for heavy data load and high performance data handling, and you risk to lose data.

As local file and memory use the same format, it is possible to switch between these configurations without losing any data.

External Database System

Using an external database is about 2-3 times slower than local files and requires some further actions by the modeler and database administrator to get started. An empty database schema/instance needs to be set up by the administrator, and the deployed service needs to be reconfigured. However, this enables the modeler to use any relational database supported by the xUML Runtime.

The major advantage of this approach is that backup, restore procedures and scaling mechanisms are delegated to the database management system. Additionally, any service that accesses the same state database can send signals to the same objects. This includes, for example, services that are sharing the same objects in load-balancing environment, e.g. Kubernetes.

Refer to Persistent State Databases for a detailed explanation of how this can be configured.

Volatile

The volatile option is similar to memory but does not backup/restore persistent state data to a file upon shutdown and restart. This storage method is recommended if the state database should be reset after each service restart.