Workflow Events

Last modified: September 25, 2024

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.

Configuration

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

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

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-persistable 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.

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.

Event Types

Workflow Lifecycle Events

Event Type Description Examples
Workflow Completed Triggered when a workflow completes successfully
Workflow Initiated Triggered when a new workflow instance is initiated
Workflow Restarted Triggered when a workflow is restarted See the Operation section in Change Workflow State
Workflow Failed Triggered when a workflow instance fails When a user task fails, the workflow fails
Workflow Aborted Triggered when a workflow is aborted See the Operation section in Change Workflow State
Workflow Paused Triggered when a workflow is paused See the Operation section in Change Workflow State
Workflow Unpaused Triggered when a paused workflow is resumed See the Operation section in Change Workflow State
Workflow Retried Triggered when a workflow is retried after being failed or incompatible See the Operation section in Change Workflow State
Workflow Updated Triggered when a parent workflow is put back into progress after the sub-workflow is retried, restarted, or when jump-to option is applied See the Operation section in Change Workflow State
Workflow Upgraded Triggered when the workflow definition has a new version having non-conflicting changes See Successful Upgrades to the Latest Workflow Definition
Workflow Conflicted Triggered when the workflow definition has a new version having conflicting changes See Workflow Versioning Conflict Types
Workflow Resolved Triggered when the workflow is continued after being incompatible See the Operation section in Change Workflow State
Workflow Jump-To Option Applied Triggered when a jump-to option is applied on the workflow See Jumping to Different Activities in a Workflow

Activity Events

Event Type Description Examples
Start Event Executed Triggered when the start event is executed
End Event Executed Triggered when the end event is executed
Decision Executed Triggered when a Decision is executed See Decision in Workflows
Jump Executed Triggered when a Jump activity is executed See Jump Activity
Parallel Split Executed Triggered when a Parallel split activity is started See Parallel Split
Parallel Merge Executed Triggered when all parallel split paths are completed
Call Workflow Started Triggered in the following cases:
  • Sub-workflow is successfully instantiated
  • Sub-workflow definition is not found (in this case it is triggered together with Call Workflow Ended event)
  • Sub-workflow is retried, restarted, or when jump-to option is applied
 See Call Workflow
Call Workflow Ended Triggered in the following cases:
  • Workflow is Completed, Failed, or Aborted
  • Sub-workflow definition is not found (in this case it is triggered together with Call Workflow Started event)
  • Workflow suspended on Call workflow activity is aborted, restarted, or when jump-to option is applied
  • Parallel path containing Call workflow activity is removed and workflow is continued
 See Call Workflow
Call Microflow Started Triggered when Call microflow activity is started See Call Microflow
Call Microflow Ended Triggered in the following situations:
  • Microflow is executed successfully with a valid outcome
  • Workflow suspended on Call microflow activity is aborted, restarted, or when jump-to option is applied
  • Parallel path containing Call microflow activity is removed and workflow is continued
  • Microflow is executed with an invalid outcome
 See Call Microflow
Wait for Notification Started Triggered when Wait for notification activity is started See Wait for Notification
Wait for Notification Ended Triggered in the following situations:
  • Notification is received successfully
  • Workflow suspended on Wait for notification activity is aborted, restarted, or when jump-to option is applied
  • Parallel path containing Wait for notification activity is removed and workflow is continued
 See Wait for Notification
Timer Started Triggered in the following cases:
  • Timer is successfully scheduled
  • Delay expression results in an empty value
  • Delay expression is invalid (for example, divide by zero error in an expression)
 See Timer
Timer Ended Triggered in following cases:
  • Timer has expired
  • Delay expression results in an empty value
  • Delay expression in invalid (for example, divide by zero error in expression)
  • Workflow suspended on Timer activity is aborted, restarted, or when jump-to option is applied
  • Parallel path containing Timer activity is removed and workflow is continued
 See Timer
Non-Interrupting Timer Event Executed Triggered when the scheduled timer for the non-interrupting boundary event expires See Boundary Events
User Task Started Triggered in following cases:
  • User targeting is evaluated
  • On-created microflow is successfully scheduled
 See User Task or Multi-User Task
Multi-User Task Outcome Selected Triggered when a vote is specified for a multi-user task
User Task Ended Triggered in following cases:
  • User task fails
  • Workflow suspended on a user task is aborted, restarted, or when jump-to option is applied
  • Parallel path containing a user task is removed and workflow is continued
 See User Task or Multi-User Task

User task can fail due to the following reasons:
  • On-created microflow fails
  • When number of required users is more than the targeted users in a multi-user task

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.

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.