Workflow Events

1 Introduction

The Workflow Engine emits near real-time workflow events. These events provide a great way to build audit trails, handle errors, update KPI dashboards, etc. For example, you can define an event handler that only collects data from user task events.

2 Configuration

There are two ways in which you can configure workflow-related event handlers:

• The events can be configured via the Event handlers setting in workflow properties.

• The Event handlers setting can also be configured in App Settings:

  

The image below presents an example of how you can configure an event handler either in workflow properties or in App Settings:

3 Event Mechanism

When something happens in the workflow engine, an event is emitted when subscribed to that event. This event is posted asynchronously using the task queue as described in Workflow Engine. We take a snapshot of the event state at the time when it occurs to get real-time data. This snapshot data is then converted by the task queue task to the system module non-persistent workflow entities: WorkflowEvent, WorkflowRecord, and WorkflowActivityRecord.

There are a few advantages of this mechanism:

• The event handler microflow might fail, without failing or halting the workflow.
• The execution (time) of the event handler microflow is not delaying the continuation of the workflow.

The WorkflowEvent entity represents workflow event data at a specific execution moment. It contains the following attributes and association:

• EventTime – the time at which the event occurred.
• EventType – the type of the event being triggered. For more information, see the Event Types section below.
• WorkflowEvent_Initiator – an association to the current user object which is logged in. The activity workflow events will have an initiator in cases where a user takes some action, otherwise it will be empty. For example, when a user specifies the outcome of a user task or when a user notifies a suspended workflow, then this user becomes the initiator. As a special case, it will also be empty for the Workflow Initiated event of a sub-workflow because a sub-workflow is directly related to the Call workflow activity.

The WorkflowActivityRecord entity represents workflow activity data at a specific execution moment. For example, a snapshot of a workflow activity at the moment when it was completed.

The WorkflowRecord entity represents workflow instance data at a specific execution moment. For example, a snapshot of a workflow instance at the moment when it was completed.

These non-persistent entities are provided as the default input parameters to the microflow specified in the event handler configuration:

You can use the data from these input parameters to construct audit trails, for logging purposes, etc. For example, you can define an event handler that only collects data from user task events.

4 Event State

When a particular workflow action triggers multiple events (for example, aborting or ending a workflow), we treat this action as an atomic action and include the state of the workflow and activity, as it will be at the end of the transaction. The rationale behind this is that the database reflects the same behavior: all objects are updated atomically in a single transaction.

Examples are shown below:

• Both the End Event Executed and the subsequent Workflow Completed event will have an identical workflow record, with state Completed.
• On an abort, all events (for example, User Task Ended, Wait For Notification Ended, Call Microflow Ended, Call Workflow Ended and Workflow Aborted) will have an identical workflow record, with state Aborted.

In the case of workflow operations, the workflow lifecycle events are the last event being triggered and the activity-related events come before that. For example, if you abort a workflow which is currently suspended on a user task, then the User Task Ended event is triggered first and later on the Workflow Aborted event.

5 Event Types

5.1 Workflow Lifecycle Events

5.2 Activity Events

6 Sub-Workflows

A sub-workflow emits exactly the same events as a main workflow. This means that it will have its own Workflow Initiated event when it starts, and either Workflow Completed or Workflow Aborted event when it ends. Basically, a workflow outputs exactly the same events when it is executed as a sub-workflow as when it is executed as a main workflow.

7 Removed Definitions

When a workflow definition is removed while there are active workflow instances, they will be marked as Incompatible. Since the definition no longer exists, workflow instances can only be aborted, which will also abort all their activities.

However, without the definition, it is no longer possible to determine what type of activities they were. As such, it is impossible to send the appropriate {Activity name} Ended event. So, in this particular case, no event is sent at all for the aborted activities. This exception to the rule that a {Activity name} Started event is matched with an {Activity name} Ended event is acceptable, because this situation is rare.