Step-by-Step Guide: Designing Workflow Types

Overview

A Workflow Type is a template that defines steps, actions, entry points, and automations. Workflows are instances created from a type. Workflows move through steps as actions are performed.

Step 1: Basic Setup

  1. Create a new workflow type

    • Provide a Name and optional Description (localized strings)
    • Set the base locale (first locale in the locales array)

  2. Configure locales

    • Add locales for translations
    • The first locale is the base language

  3. Set workflow type permissions

    • Assign roles: Administer, Manager, Observe, View, or Deploy
    • Administer: Can edit this workflow type and manage steps and actions and deployments
    • Manager: Can view and edit all workflows of this type and deployments
    • Observe: Can view all workflows and events of this type
    • Deploy: Can create a new deployment of the workflow type
    • View: Can view this workflow type (required to interact with the workflow type)

Step 2: Define Variables

Variables store data per workflow instance.

  1. Add variables

    • Provide: Name, optional Description, Type
    • Type options: Text, Number, Boolean, Date, Date & Time, Single Choice, Multiple Choice, Reference, Reference List, Text List, Geometry
    • For Reference or Reference List types: set Table
    • For Single Choice or Multiple Choice: set Options

  2. Use cases

    • Site references (e.g., water point ID)
    • Status flags
    • Calculated values
    • Data passed from entry points

Step 3: Configure Summary Fields and Alerts (Optional)

  1. Summary fields

    • Display key info in the workflow header
    • Each field has a Label and a Field to Show (expression evaluated against the workflow row)

  2. Alerts

    • Conditional status indicators
    • Set Severity (Info, Warning, or Danger)
    • Set a Condition expression
    • Alert is shown when this expression evaluates to true

Step 4: Define Custom Roles (Optional)

  1. Create custom roles

    • Provide: Name, optional Description
    • Referenced as custom:<role_id> in permissions
    • Subjects assigned per deployment

  2. Use cases

    • Team-specific roles (e.g., "tech_lead", "supervisor")
    • Roles that vary by deployment

Step 5: Configure Sub-Workflow Sets (Optional)

  1. Define sub-workflow sets

    • Provide: Name, optional Description
    • Set Workflow Type (the type for sub-workflows)
    • Set Number of Sub-Workflows: Single or Multiple

  2. Use cases

    • Related workflows (e.g., "Equipment Inspections" for a repair workflow)
    • Hierarchical workflows

Step 6: Create Entry Points

Entry points start workflows. A workflow type can have multiple entry points.

1. Manual Entry Point

  • User starts via button/list
  • Set Name, optional Description
  • Set Start Step (initial step)
  • Set Who can start (who can trigger)
  • Set Enabled (true/false) - Allow this entry point to start new workflows
  • Optional: Automations to run after starting

2. Site Entry Point

  • Starts from a site page
  • Set Site Type (e.g., "water_point")
  • Set Name, optional Description
  • Set Start Step
  • Set Who can start
  • Set Enabled
  • Optional: Automations

3. Programmatic Entry Point

  • Started from another workflow (e.g., as a sub-workflow)
  • Set Name, optional Description
  • Set Start Step
  • Set Who can trigger from parent workflow (checked for the user who triggered the parent)
  • Set Enabled
  • Define Input Parameters (Variables that can be set when starting this workflow from a parent workflow)
  • Optional: Automations

Step 7: Design Steps

Steps are states where workflows pause, waiting for actions.

  1. Create steps

    • Provide: Step Name
    • Set Status: Draft, Active, or Completed
    • Add Actions (see Step 8)
    • Optional: Transitions (see Step 9)

  2. Step status mapping

    • Draft: Drafts can be discarded and are not displayed in the workflow list by default
    • Active: Normal steps within an active workflow
    • Completed: Completed workflows are not displayed in the workflow list by default

  3. Step transitions (optional)

    • Define when this step automatically moves to another step
    • Trigger when all listed actions are completed
    • Set type: "all"
    • List actions (action IDs)
    • Set Condition (evaluated against workflow row)
    • Set Next Step (target step ID)

Step 8: Add Actions to Steps

Actions are tasks users or the system perform in a step.

1. Base Action Properties

  • Name
  • Who can perform: who can perform (e.g., "Workflow Creator", "Workflow Assignees", custom roles)
  • Who can view details: who can view details
  • Recurrence: Recurring, Once per workflow, or Once per step
    • Recurring: The action can be performed as often as possible when in the step
    • Once per workflow: The action can be performed once for the entire workflow
    • Once per step: The action can be performed once for each time the step is entered from another step
  • Optional: Automations (run after completion)
  • Optional: Transitions (conditional next steps)

2. Action Types

a. Survey Form Action (type: "form_response")

  • Launches a survey form
  • Set Select Form
  • Optional: Deployment (deployment ID to use for the form response)
  • Optional: Prefills (expressions evaluated against workflow row)

b. Mini Form Action (type: "mini_form")

  • Embedded form (no rosters)
  • Set Form Design
  • Optional: Prefills

c. Manual Assignment Action (type: "assign")

  • Assigns workflow to users/groups/roles
  • Set Who can be assigned (e.g., "Workflow Creator", "Deployment Admins", custom roles)
  • Set Selection Type: User, Group, Role, or combinations (What the performer will choose at runtime)
  • Set Allow multiple selections (true/false)

d. Start Sub-Workflow Action (type: "start_subworkflow")

  • Creates a sub-workflow
  • Set Sub-workflow (Which sub-workflow to start)
  • Set Trigger (Which trigger to use to start the sub-workflow)
  • Set Trigger Configuration:
    • Programmatic: Input Values (Expressions to populate the trigger inputs)
    • Site: Site ID (Expression that evaluates to the site ID)
    • Manual: Manual triggers require no configuration

e. Sub-Workflow Actions (type: "subworkflow_action_proxy")

  • Proxies actions from sub-workflows to the parent
  • Set Sub-workflow (Which sub-workflow to perform actions on)
  • Optional: Allowed Actions (Optionally filter which actions can be performed. Leave empty to allow all actions.)

f. Timed Action (type: "timed")

  • Executes automatically after a delay
  • Set Delay: amount and unit (Minutes, Hours, Days, Weeks, Months, Years)
  • How long to wait before automatically executing this action
  • Timer starts when entering the step
  • Recurrence behavior:
    • Once per step: Executes once after the workflow enters this step
    • Recurring: Executes repeatedly every time the delay elapses
    • Once per workflow: Executes only once in the workflow's lifetime

3. Action Transitions

  • Conditional next steps after an action
  • Each transition has a Condition (evaluated against event data) and a Next Step
  • Evaluated in order; first matching condition wins
  • If no condition matches, workflow stays in the current step

Step 9: Configure Automations

Automations run automatically based on conditions.

1. Automation Types

a. Set Variable (type: "set_variable")

  • Updates a workflow variable
  • Set Variable (variable ID)
  • Set Value (expression evaluated against workflow/event row)

b. Assign (type: "assign")

  • Replaces all assignees
  • Set Roles (e.g., "Workflow Creator", "Deployment Admins", custom roles)

c. Start Sub-Workflow (type: "start_subworkflow")

  • Creates a sub-workflow automatically
  • Set Sub-workflow, Trigger, Trigger Configuration
  • Expressions in Trigger Configuration evaluated against workflow/event row

2. Where Automations Run

  • On entry points: after workflow starts (evaluated against workflow row)
  • On actions: after action completes (evaluated against event row)

3. Conditions

  • Each automation can have a Condition expression
  • If true (or null), the automation runs
  • If false, it is skipped

Step 10: Create Deployments

Deployments define who can access and use workflows. A workflow type must have at least one deployment.

  1. Create a deployment

    • Provide: Name
    • Set subjects for:
      • Admins: Admins can edit the deployment and all workflows in the deployment
      • Managers: Managers see all workflows and their details in the deployment and perform any action
      • Observers: Observers can view all workflows and their details in the deployment
      • Initiators: Users or groups who can start any workflow in this deployment
    • Set Custom roles: map role IDs (without "custom:" prefix) to subject arrays

  2. Deployment permissions

    • Deployment admins/managers can always perform actions
    • Deployment observers can always view
    • Deployment initiators can trigger workflows
    • Custom roles are deployment-specific

Step 11: Test and Validate

  1. Validation checklist

    • All entry points have valid Start Step references
    • All steps exist and are referenced correctly
    • All action transitions reference valid step IDs
    • All step transitions reference valid step IDs
    • All variable references are valid
    • All custom role references use custom:<role_id> format
    • All sub-workflow sets reference valid workflow types
    • At least one deployment exists

  2. Test workflow flow

    • Verify entry points start workflows correctly
    • Verify actions can be performed
    • Verify transitions work as expected
    • Verify automations execute correctly
    • Verify permissions are correct

Step 12: Share and Deploy

  1. Share workflow type

    • Assign roles to users/groups
    • Ensure viewers can access workflows

  2. Deploy

    • Create deployments with appropriate subjects
    • Test that initiators can start workflows
    • Verify deployment permissions

Key Concepts Summary

  • Workflow Type: template/specification
  • Workflow: instance created from a type
  • Entry Point: starts a workflow (replaces "Trigger" in UI)
  • Step: state where workflow pauses
  • Action: task performed in a step
  • Event: record of an action being performed
  • Transition: movement between steps
  • Automation: automatic action based on conditions
  • Variable: data stored per workflow
  • Deployment: configuration defining access and permissions
  • Custom Role: deployment-specific role
  • Sub-Workflow: related workflow linked to a parent

Best Practices

  1. Start simple: begin with basic steps and actions, then add complexity
  2. Use meaningful names: clear IDs and names for steps, actions, and variables
  3. Test transitions: ensure workflows move correctly between steps
  4. Set permissions carefully: use custom roles for team-specific access
  5. Use automations wisely: they run automatically, so test conditions
  6. Document variables: clear descriptions help users understand data
  7. Plan sub-workflows: design parent and child workflows together
  8. Consider recurrence: choose the right recurrence for each action

This guide covers the workflow type design process. Each workflow type should be tailored to your specific use case.