Workflow engine

This article explains how Casewhere workflows are executed: triggers, states, state transitions, and how workflows interact with processes, cases, and data objects.

Workflow triggers

Casewhere provides multiple ways to trigger workflows. See the individual articles for detailed configuration:

Trigger Description
UI trigger End-users trigger workflows by clicking widget buttons. The only way to trigger a UI workflow.
Data trigger A database change triggers an automatic workflow.
Time trigger A scheduler triggers an automatic workflow at a specific time.
Event trigger A system event triggers an automatic workflow.
Web trigger An external system triggers a workflow via a Web API endpoint.

Workflow states

A workflow has the following states:

  • Open: The initial state when the workflow starts.
  • Completed: All required activities have been completed.
  • Queued: The workflow execution is deferred to a queue, allowing Casewhere to handle high volumes without overload.
  • Locked (deprecated): The workflow is locked. This state is deprecated and should not be used in new implementations.
stateDiagram-v2
    [*] --> Open: Engine starts
    [*] --> Queued: Place in queue
    Queued --> Open: Engine starts
    Open --> Completed: If all required activities completed
    Open --> Locked: Lock (deprecated)
    Locked --> Open: Unlock (deprecated)
    Completed --> [*]
    Open --> [*]:  If any required activity incompleted

Workflow execution paths

A workflow can have many execution paths activated depending on current data and user input. The workflow engine evaluates the activity navigation rules to decide the next execution path after each activity.

  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.