Concepts

Automatiko is based on the concept of modeling business logic and decisions to capture and express business requirements. It is all about using this model to understand and explain what the service is about.

Workflow

Workflow (aka process) is the main entry point of the service or function. Depending on the language, a workflow can be expressed either as flow chart (in case of BPMN2), or a text-based format (JSON or YAML in case of Serverless Workflow).

A workflow consists of activities that are executed within the life time of each of its instances. These activities have different meaning depending of their type or place in the workflow model, such as:

  • Activities that invoke services ('service task' in BPMN or 'operation state' in Serverless Workflow)

  • Events that either capture events or produce events

  • Subworkflows that creates new workflow instance of another workflow to build hierarchy of workflow instances and take advantage of workflow composition pattern ('call activity or reusable subworkflow' in BPMN or 'subflow state' in Serverless Workflow)

Automatiko comes with following approaches to use workflows

  • Workflow as a service

  • Workflow as a function

  • Workflow as a function flow

Identification and description

A workflow must include an assigned id. The id serves as an unique workflow identifier and as such should be:

  • short (typically a single word, or a compound word using the CamelCase naming convention)

  • descriptive (carry only the most important information)

The reason why these rules are describe is that the workflow id here is again used as your service identification parameter. With that said, it will be the top level resource of the workflow REST API.

Best practice is to think about workflow id in context of its domain. For example the id of a workflow managing orders should be orders

In addition to the id, a workflow also contains a name that should be provided and include a description of the logic encapsulated by the workflow definition. It should however not be too long as workflow allows you to define extra documentation on various other levels such as:

  • the workflow itself

  • every workflow activity

  • every data object (a.k.a. variable) in the workflow

  • every event defined in the workflow

Using documentation is recommended as it automatically enhances the service description. This allows service consumers to better understand the overall intention of the service which can aid with their integration efforts.

Versioning

Versioning of a workflow should be considered from the very beginning as it might have severe impacts on service consumers and its maintainability.

Following are the basic principles to how to handle versioning in Automatiko:

  • a version can be assigned to any workflow (public and private)

  • version will be part of the service contract - in REST api it will prefix the paths e.g. /v1/orders or /v1_2/orders for versions 1 and 1.2 respectively.

  • multiple versions of the workflow should be kept in the same service, meaning a new version should be a copy of the previous one

Change the version only when there is good reason for it. As a rule of thumb it is recommended to not change the workflow version if the change is backward compatible. In other words, change the version only when the modifications to the workflow make the existing instances impossible to continue.

Types of workflows

workflow types are currently only supported in BPMN language and not in Serverless Workflow.

Workflow types defines the visibility of given workflow on the service API. There are two types of workflows:

  • Public - exposed as top level service endpoints

  • Private - hidden from the service API, meaning instances of such workflows cannot be started from outside.

Private workflows provide a perfect fit for subworkflows. This allows you to limit the creation of new instances of subworkflows only to their, so called, owning workflow instance.

Workflow data

Workflow data defines the actual domain of the service that is being modeled. In the end, all services are meant to deal with data and as such alter it.

Properly defining the workflow data model is extremely important to the service and the contract it will expose. To help with that, Automatiko promotes the use of so called tags to annotate and enhance data handling.

Data object tags

Workflow data, also known as data objects or variables, can be annotated with tags to enable additional features:

Tag name Description

input

Marks a given data object as input that should be available upon starting a new instance

output

Marks a given data object as output that will be always returned when an instance is altered or is completed

internal

Marks a given data object as internal, meaning it not be visible from the outside

sensitive

Marks a given data object as sensitive, meaning it not be visible from the outside and is not published via events

notnull

Marks a given data object as non-nullable, meaning once it was assigned a value it cannot be reset to null

readonly

Marks a given data object as read only, meaning that it cannot be changed after being set once

required

Marks a given data object as required to start new instance

auto-initialized

Marks a given data object to be auto initialized upon start, meaning it guarantees that the value will be set

business-key

Marks a given data object to be used as a business key of the instance. Applies only for the start of a new instance

initiator

Marks a given data object to be the source of initiator of the instance instead of relying on security context

versioned

Marks a given data object to be versioned. Each change to the variable records the previous one and makes it available to be fetched with construct variablename$VERSION for example person$3 will get the version 3 of the person variable. Note that versions start at 0. person$ will return list of all versions of the variable and person$-1 will return the last version.

transient

Marks a given data object as transient meaning it will never be persisted and by that will not retain the value (will always have null value on reload of the instance from data store)
Serverless Workflow does not define data objects explicitly and allows to have data pushed on demand and thus do not make use of tags.

Workflow instance

Workflow instance is an individual instance of a given workflow. This is a runtime representation of a single execution according to given workflow definition.

Depending on the workflow definition (how it was modeled), a workflow instance can be short lived or it can span hours, days, months and more.

Each workflow instance is uniquely identified with generate id (of a form of UUID). This id remains unchanged during the entire life time of the instance.

Business key

Business key can provide an alternative to the workflow instance id. Similarly to the id, a business key, when assigned, remains unchaged during the entire live-time of the workflow instance. A business key can be used exactly as id and can be used to reference a given instance from the outside via service API.

Even though business key is assigned the generated id can still be used to reference the instance.
Business key must be unique within the scope of a workflow (or version of the workflow). That means you can have only one active instance with a given business key.

Execution timeout

Execution timeout of an instance can be defined within the workflow definition as part of custom attributes. It allows to specify the maximum amount of time (since the start) that workflow instance is allowed to remain active. It is given as a ISO formatted duration PT5H, P5D (5 hours and 5 days respectively).

To define it add timeout custom attribute on the workflow definition with desired duration

End of instance strategy

When workflow instance reaches its end (either by completing successfully or by being aborted) there might be situations that requires it be handled in one way or another. For this exact purpose, end of instance strategies are provided. These allow to have different behavior depending on your needs. For example due to legal requirements instances must be kept for given amount of time, or they should be archived to another location for reference.

Automatiko provides three out of the box strategies:

  • remove

  • keep

  • archive

Remove

Remove strategy is the default one that simply removes the workflow instance from the data store. That operation is permanent and by that means the information about the workflow instance (including its data) are gone.

This strategy helps at keeping the storage to minimum size by holding only instances that are not yet finished.

Configuration of this strategy

Property name Environment variable Value

quarkus.automatiko.on-instance-end

QUARKUS_AUTOMATIKO_ON_INSTANCE_END

remove

Keep

Keep strategy is the opposite of remove, it will update the status and its content and keep the workflow instance in the data store. That will allow to access completed and aborted instances at any time, including their data and complete execution path that can also be visualized on the workflow definition image.

Keep strategy comes with limitation that does not allow to reuse the same identifiers of workflow instances. In most of the cases this is not an issue as identifiers are generated. The situation when this can manifest itself is when workflow instances uses business keys. These are considered alternative identifiers and by that cannot be reused.

Configuration of this strategy

Property name Environment variable Value

quarkus.automatiko.on-instance-end

QUARKUS_AUTOMATIKO_ON_INSTANCE_END

keep

Archive

Archive strategy allows to automatically extract complete set of information about workflow instance at its completion. That data are then exported into an archive (zip file) that consists of

  • process instance export format

  • each variable as separate file (regular variables as json documents, files as dedicated files with proper extensions)

Archives are by default stored on file system so extra configuration property is required. Although this is also extensible and custom implementations of io.automatiko.engine.api.workflow.ArchiveStore can be provided that will be used to store the produced archive.

Archives will be stored in the given directory grouped in folders named based on workflow definition id and version. Each archive will be named like {workflow-instance-id}.zip where {workflow-instance-id} is going to be replaced with actual id of the workflow instance.

Configuration of this strategy

Property name Environment variable Value

quarkus.automatiko.on-instance-end

QUARKUS_AUTOMATIKO_ON_INSTANCE_END

archive

quarkus.automatiko.archive-path

QUARKUS_AUTOMATIKO_ARCHIVE_PATH

/my/custom/archive/folder

Tags

Similar to workflow data tags, a workflow itself can define tags. Tags allow you to put extra information (in addition to a business key) used for correlation purpose.

Tags can be both simple (constant) values that won’t change over time or expressions that are evaluated every time a workflow instance changes.

Additional feature of workflow tags (compared to workflow data tags) is that tags can be added and removed during the entire life time of a workflow instance.

Tags defined in a workflow (definition) cannot be removed. Only tags added on top of active workflow instance can.

Decisions

Decisions are used to capture the workflow decision logic. They are not exposed as a separate services but instead are invoked from within a workflow. Decisions in Automatiko are defined as DMN diagrams which goes hand in hand with BPMN to have both defined in a graphical way.

Best practices to properly integrate decisions include:

  • decisions should be identified by model and namespace and optionally decision or decision service

  • decisions must define inputs which will then be mapped from the workflow data

  • decisions define various decision logic constructs such as

    • literal expression to encapsulate expression like decisions

    • decision tables

Decision results are then mapped (by name) to workflow data.