Process management

Process management addon allows to add extra capabilities on top of the domain specific service (the one that is build from workflow definition).

Process management comes with two parts

  • REST api

  • Basic UI to visualize current state of the service

Configure

To enable process management addon add following dependency to your service

<dependency>
  <groupId>io.automatiko.addons</groupId>
  <artifactId>automatiko-process-management-addon</artifactId>
</dependency>

This will include both the REST api and UI

REST api

REST api of the process management addon provides following capabilities

  • List of available workflows (definitions)

  • List of available workflow instances of the given workflow

  • Workflow instance details

  • Error of given workflow instance

  • List of active nodes in given workflow instance

  • Retrigger given workflow instance that is in error state

  • Skip node that caused error in given workflow instance and continue with next node

  • Trigger given node in given workflow instance

  • Retrigger active node in given workflow instance

  • Cancels active node in given workflow instance

  • Cancel entire workflow instance

  • Export workflow instance

  • Import (previously exported) workflow instance

REST api of process management addon is not included in the OpenAPI definition of the service by default. This is to avoid exposing non domain specific endpoints in the service. It can be enabled by setting quarkus.automatiko.include-automatiko-api property to true in application.properties

Export workflow instance

Exporting of workflow instance can be rather useful feature especially in situation where one or more instances are stuck and there is no clear reason the the problem. Being able to export such an instance from production environment and importing it back on test or development environment for further investigation can help significantly.

Export of a workflow instance is responsible for extracting complete set of information about workflow instance, this includes:

  • workflow instance metadata such as id, business key, state etc

  • active node instances with their metadata and variables

  • workflow instance variables

  • timers

  • sub instances when there are any being currently active

Exported workflow instance is delivered as a JSON document that can be stored and later on used to import that workflow instance in different environments.

Export format is not considered public API and thus might change between releases.

Exported instance includes all the details of the instance meaning it has exactly the same identifiers, timestamps and variables. Keep in mind that same instance cannot be imported twice as it will cause a duplicate id of the instance and thus result in an error.

Instance can also be aborted directly after the export so this allows simple way of exporting and removing instance from a given environment.

Here is a curl command that will export instance with id 1234 of a workflow definition with id orders and version 1.0

curl -X GET 'Accept:application/json' http://localhost:8080/management/processes/orders_1_0/instances/1234/export

Import workflow instance

An exported instance can be imported into another environment. There is only one main requirement - it needs to be an environment with the same workflow definitions as the exported one.

Import of the workflow instance is based on the exact data that where exported. There is no need to make any changes to the structure to make it successfully imported.

Import of the instance includes

  • importing all sub instances first

  • importing top level instance

  • scheduling timers for all imported instances - note that this preserves the exact same times from the exported instance and not rescheduling them again

  • includes user restrictions if they were any defined.

Imported instance is directly usable as it have been started in this environment from the beginning.

Here is a curl command that will import instance of a workflow definition with id orders and version 1.0

curl -X POST 'Content-Type: application/json' 'Accept: application/json' http://localhost:8080/management/processes/orders_1_0/instances - d '$EXPORTED_INSTANCE'

EXPORTED_INSTANCE environment variable must be set with content of the exported instance.

Import of a workflow instance can also serve as instance migration between workflow definition versions. Though this will require some manual updates on the exported data.

Archive workflow instance

Additionally to export feature, there is also an option to archive a workflow instance which essentially performs export and collects all variables of the workflow instance and saves them individually. That in turn will give a hierarchical structure of archived instance. Main use case for it is to save the results of the workflow instance execution to keep the record of it. In many situations workflow instances are handling legal business processes which require to keep the record of the execution. Archive can actually be performed at any point in life time of the instance. Usually archive will either happen at the end of execution or when it is no longer expected to be active.

Process management api allows to archive instance with following characteristics:

  • exported instance is in JSON format

  • variables are stored in JSON format

  • sub instances are stored in dedicated folders including their variables and sub instances

  • complete archived instance is delivered as zip archive

Archive operation on the management api allows you to optionally abort the instance after archive operation is completed.

Here is a curl command that will archive instance with id 1234 of a workflow definition with id orders and version 1.0

curl -X GET 'Accept:application/json' http://localhost:8080/management/processes/orders_1_0/instances/1234/archive

User interface

Currently UI of process management is read only but over time it will be enhanced with majority of the REST api operations

Process management comes with very basic UI to help visualize the state of the service. It can be accessed via http://localhost:8080/management/processes/ui

This will show entry point that displays available workflow definitions in the service

management ui entry

For each of the listed wokflows you can list active instances by clicking on the Instances button. This will expand a table with all active instances of that workflow.

management instances

Further you can look at instance details that will include

  • workflow instance visualization with active nodes and retrying nodes annotated

  • list subworkflow instances if any

  • display complete data model of given workflow instance

weather retry mgmt