Skip to content

Introduction

Workflows provide a way to define step based behavior with state and transitions from step to step. The definition is a directed graph defined by JSON.

Every workflow includes a special step called "start" that is always the first step. From there the additional steps are defined as paths.

Each step has a scope that can be defined with either the keywords $sink, $source, $all or with a user query. The scope defines the users that receive the workflow step. This enables several users to get access to the same workflow.

Step definition

Each step has three sections that define behavior:

  1. Paths - these are the possible next steps from the current step. These are shown to the user in the client.
  2. Actions - these are server side actions that happen when the step is activated
  3. Bheaviors - these are client side behaviors that are activated when a path is chosen.

Scope

The step scope governs whose inbox the workflow item will appear in. The scope can have the following values:

  1. $sink - this is the workflow recipient
  2. $source - this is the user that activated that step
  3. $all - any user that has previously received the inbox action
  4. user query - any other string will be processed as a user query and the result used as the scope

The best practice is to make this either $sink for all steps - which provides a single user with the workflow - or a user query for the first step and $all for all subsequent steps to ensure everyone has the same state updates.

Step definition

Each step has:

  1. Template - this is the title for the item; this is only set for Start
  2. Step name + name style for background color - this is the label used in the list; this is updated for each step
  3. Step description - this is the subtitle for the item; this is updated for each step

Template supports server side template processing - See Server Templates. Workflows that are initiated by a dispatch provide access to the dispatch attributes and data. Workflows initiated by a script provide access to the data object passed into the script function.

Step status can be either active or retired. A retired item will disappear from the inbox.

Display in the inbox

Triggered from script

Inbox

  1. Template = title
  2. Step name = label
  3. Step description = subtitle; changes for each step
  1. summaryTitle
  2. summary
  3. icon

Example

{
    "start": {
        "step": {
            // step paths definition
        }, 
        "behaviors": {
            // client behavior
        },
        "actions": {
            // server behavior
        },
        // ... step
    },
    [step name]: {
        // step
    }
}

Step definition

The step definition defines the behavior at each step in the workflow.

  • name: appears as a small tag
  • template: initial string for entry
  • description
  • scope: query string | $sink | $source | $all
  • paths:
    • label
    • step
    • behavior
    • icon
  • status: active | retired
  • nameStyle: danger | success | info | dark | warning

Behaviors

Behaviors are client side.

  • handle
  • behavior: dispatch
  • target: query string | $sink | $source | $all
  • fields: parameter for the behavior
  • data: JSON for the behavior
  • templates: string [] with paths that should be processed with ParseTemplate

Actions

Actions are server side.

  • action: see below
  • scope: query string | $sink | $source | $all
  • args: parameter for the action

Possible actions

  1. status - change status for scope users
  2. task - update dispatch task status
  3. lock, unlock - lock and unlock the entry
  4. script - execute script
  5. notify - send push notification
  6. trigger - trigger a new rule step
  7. chat (BETA)