Workflow engine

This article explains the execution of Casewhere workflows, how they are triggered, the workflow states' meaning, how they are transitioned, and more importantly, how workflows work with processes, cases and data objects.

Workflow triggers

There are many ways a workflow can be triggered in Casewhere. Here we only briefly introduce the workflow triggers. There are separate articles explaining how they work in detail and how to configure them.

  • UI trigger: End-users can trigger workflows by clicking widget buttons. This is the only way to trigger a UI workflow while it is totally possible to trigger an automatic workflow here.
  • Data trigger: You can configure a rule so that a change in database can trigger an automatic workflow.
  • Time trigger: You can configure a scheduler to trigger an automatic workflow at a specific time.
  • Event trigger: You can configure Casewhere to listen to a specific event and trigger an automatic workflow.
  • Web trigger: You can expose a Web API endpoint for external systems to trigger a workflow in Casewhere.

Workflow states

A workflow has four states:

  • Open: When the workflow starts, it sets the workflow's state to Open.
  • Completed: A workflow completes when all required activities are completed.
  • Locked: When a workflow is locked, it cannot be run again. Locking workflows have been deprecated since version 2.5.
  • Queued: Casewhere can defer the workflow's execution by putting them in queues. Queueing is an important technique to ensure that Casewhere can handle many workflows without being overloaded. When a workflow is placed in a queue successfully, it has the state Queued.

The diagram below explains how the state transition works:

stateDiagram-v2
    [*] --> Open: Engine starts
    [*] --> Queued: Place in queue
    Queued --> Open: Engine starts
    Open --> Completed: If all required activities completed
    Completed --> [*]
    Open --> [*]:  If any required activity incompleted

Workflow execution paths

A workflow can have many execution paths that are activated depending on the current data and user input. The workflow engine will evaluate the activity navigation rule to decide which execution path to take next. This happens every time the workflow engine executes an activity.

To help you understand better, let's set up a simple workflow for sending message as below:

  1. Form activity: Select message type
  2. Script activity: Send SMS
    1. Included When: message.Type == "SMS"
  3. Script activity: Send email
    1. Included When: message.Type == "Email"
  4. Form activity: Inform result
    1. Included When: message.IsSent == true

image-20211207160630586

In one scenario, the workflow can execute as below:

  1. After triggered, the workflow stops at the first activity and waits for user input. The current execution path is Select message type, and it's the only activity you can see in the workflow wizard.

  2. The user selects the message type Email and clicks Save.

  3. The workflow navigates to the scripted activity Send SMS. Since the user selected Email in the previous activity, the inclusion rule fails, so Casewhere will skip the activity.

  4. The workflow navigates to the scripted activity Send Email. The inclusion rule passes since the user selected Email, so Casewhere will execute the activity and set IsSent to true. At this point, the execution path is Select message type -> Send Email.

  5. The workflow navigates to the scripted activity Send Email. Since the message is sent, the inclusion rule passes, Casewhere will execute the activity. At this point, the execution path is Select message type -> Send Email -> Inform result, and the user will see the form Inform result appear as the last step of the workflow wizard.

In another scenario where the user selects SMS, the execution path will be Select message type -> Send SMS -> Inform result.

Working with cases and data objects

When setting up a workflow definition, you must specify whether it will be "Case creating" or "Case editing" via the setting Used For Creating New Cases.

Casewhere always requires a case context when triggering new workflows. If a workflow is "Case creating", Casewhere will create a Draft case when it starts the workflow. Casewhere will place all data objects created during the workflow execution in that case. These data objects will have the state Draft until the workflow completes. If the workflow fails to complete, the case and all data will remain to be Draft and thus are inaccessible from other workflows.