Follow-Along Tutorial: Water Point Repair Request Workflow

This tutorial creates a "Water Point Repair Request" workflow that covers most features. Follow each step in order.

Scenario

A water utility needs a workflow to:

  • Report broken water points
  • Assign technicians for inspection
  • Track repair progress
  • Mark repairs as complete

Step 1: Create the Workflow Type

  1. Click "New Workflow Type" or navigate to create a new workflow type
  2. Set Name: "Water Point Repair Request" (base language: English)
  3. Set Description: "Tracks repair requests for water points from initial report through completion"
  4. Save

Step 2: Configure Basic Settings

  1. Open the Design tab
  2. Locales: Ensure English is set as the base locale
  3. Permissions: Add yourself as Administer role

Step 3: Define Variables

  1. Click Variables → Add Variable
  2. Variable 1:
    • Name: "Water Point"
    • Description: "The water point that needs repair"
    • Type: Reference
    • Table: Select your water points table (e.g., "entities.water_point")
  3. Variable 2:
    • Name: "Issue Description"
    • Description: "Description of the problem"
    • Type: Text
  4. Variable 3:
    • Name: "Repair Status"
    • Description: "Current status of the repair"
    • Type: Single Choice
    • Options:
      • "Reported"
      • "Inspected"
      • "In Progress"
      • "Completed"
  5. Save

Step 4: Add Summary Fields

  1. Click Summary Fields → Add Summary Field
  2. Summary Field 1:
    • Label: "Water Point"
    • Field to Show: Select the Water Point variable
  3. Summary Field 2:
    • Label: "Status"
    • Field to Show: Select the Repair Status variable
  4. Save

Step 5: Add an Alert

  1. Click Alerts → Add Alert
  2. Alert:
    • Label: "Repair Overdue"
    • Severity: Warning
    • Condition: Create an expression that checks if the workflow has been in "In Progress" status for more than 7 days
    • (This is a conditional alert - shown when overdue)
  3. Save

Step 6: Create Custom Role (Optional)

  1. Click Custom Roles → Add Custom Role
  2. Custom Role:
    • Name: "Field Technician"
    • Description: "Technicians who perform field inspections and repairs"
  3. Save

Step 7: Create Entry Points

Entry Point 1: Manual Entry Point

  1. Click Entry Points → Add Entry Point
  2. Set Entry Point Type: Manual
  3. Set Name: "Report New Issue"
  4. Set Description: "Report a broken water point"
  5. Set Start Step: Select "Start" (or create a step first - we'll create steps next)
  6. Set Who can start: Leave empty (deployment admins/managers can always start)
  7. Set Enabled: ✓
  8. Save

Entry Point 2: Site Entry Point

  1. Click Entry Points → Add Entry Point
  2. Set Entry Point Type: Site
  3. Set Name: "Report from Water Point Page"
  4. Set Description: "Report an issue directly from a water point page"
  5. Set Site Type: Select your water point entity type
  6. Set Start Step: Select "Start"
  7. Set Who can start: Leave empty
  8. Set Enabled: ✓
  9. Save

Step 8: Create Steps

Step 1: Reported

  1. Click Steps → Add Step
  2. Set Step Name: "Reported"
  3. Set Status: Active
  4. Save

Step 2: Inspection

  1. Click Steps → Add Step
  2. Set Step Name: "Inspection"
  3. Set Status: Active
  4. Save

Step 3: Repair

  1. Click Steps → Add Step
  2. Set Step Name: "Repair"
  3. Set Status: Active
  4. Save

Step 4: Completed

  1. Click Steps → Add Step
  2. Set Step Name: "Completed"
  3. Set Status: Completed
  4. Save

Step 9: Update Entry Points to Use Correct Start Step

  1. Edit the Manual Entry Point
  2. Set Start Step: "Reported"
  3. Save
  4. Edit the Site Entry Point
  5. Set Start Step: "Reported"
  6. Save

Step 10: Add Actions to Steps

Action 1: Report Issue (in "Reported" step)

  1. Edit the Reported step → Add Action
  2. Set Name: "Report Issue"
  3. Set Action Type: Mini Form
  4. Form Design: Create a simple form with:
    • A text field for "Issue Description"
    • A reference field for "Water Point" (if not set by site entry point)
  5. Set Recurrence: Once per workflow
  6. Set Who can perform: Leave empty (anyone can report)
  7. Add Automation:
    • Type: Set Variable
    • Variable: "Repair Status"
    • Value: "Reported"
  8. Add Transition:
    • Condition: Leave empty (always transition)
    • Next Step: "Inspection"
  9. Save

Action 2: Assign Inspector (in "Reported" step)

  1. Edit the Reported step → Add Action
  2. Set Name: "Assign Inspector"
  3. Set Action Type: Manual Assignment
  4. Set Who can be assigned: Check "Deployment Admins", "Deployment Managers"
  5. Set Selection Type: Check "User", "Group"
  6. Set Allow multiple selections: No
  7. Set Recurrence: Recurring
  8. Set Who can perform: "Deployment Admins", "Deployment Managers"
  9. Save

Action 3: Complete Inspection (in "Inspection" step)

  1. Edit the Inspection step → Add Action
  2. Set Name: "Complete Inspection"
  3. Set Action Type: Survey Form
  4. Set Select Form: Choose your inspection form
  5. Set Recurrence: Once per workflow
  6. Set Who can perform: "Workflow Assignees", "Custom: Field Technician"
  7. Add Automation:
    • Type: Set Variable
    • Variable: "Repair Status"
    • Value: "Inspected"
  8. Add Transition:
    • Condition: Leave empty
    • Next Step: "Repair"
  9. Save

Action 4: Start Repair (in "Repair" step)

  1. Edit the Repair step → Add Action
  2. Set Name: "Start Repair"
  3. Set Action Type: Mini Form
  4. Form Design: Create a form with:
    • A text field for "Repair Notes"
    • A date field for "Repair Start Date"
  5. Set Recurrence: Once per workflow
  6. Set Who can perform: "Workflow Assignees", "Custom: Field Technician"
  7. Add Automation:
    • Type: Set Variable
    • Variable: "Repair Status"
    • Value: "In Progress"
  8. Save (no transition - we'll use a timed action)

Action 5: Complete Repair (in "Repair" step)

  1. Edit the Repair step → Add Action
  2. Set Name: "Complete Repair"
  3. Set Action Type: Survey Form
  4. Set Select Form: Choose your repair completion form
  5. Set Recurrence: Once per workflow
  6. Set Who can perform: "Workflow Assignees", "Custom: Field Technician"
  7. Add Automation:
    • Type: Set Variable
    • Variable: "Repair Status"
    • Value: "Completed"
  8. Add Transition:
    • Condition: Leave empty
    • Next Step: "Completed"
  9. Save

Action 6: Reminder (Timed Action in "Repair" step)

  1. Edit the Repair step → Add Action
  2. Set Name: "Send Reminder"
  3. Set Action Type: Timed Action
  4. Set Delay: 7 Days
  5. Set Recurrence: Recurring
  6. Add Automation:
    • Type: Assign
    • Roles: "Deployment Managers"
    • (This sends a reminder to managers if repair takes too long)
  7. Save

Step 11: Add Step Transition (Optional)

  1. Edit the Repair step
  2. Click Transitions → Add Transition
  3. Set Actions: Select "Start Repair" and "Complete Repair" (both must be completed)
  4. Set Condition: Leave empty (or add logic if needed)
  5. Set Next Step: "Completed"
  6. Save

Step 12: Create Deployment

  1. Go to the Deploy tab
  2. Click Add Deployment
  3. Set Name: "Main Operations"
  4. Set Admins: Add yourself and other administrators
  5. Set Managers: Add operations managers
  6. Set Observers: Add supervisors who need view access
  7. Set Initiators: Add users/groups who can start workflows
  8. Set Custom roles → Field Technician: Add your field technicians
  9. Save

Step 13: Test Your Workflow

  1. Go to the Workflows tab
  2. Click Start New Workflow
  3. Select your workflow type
  4. Select the Manual Entry Point: "Report New Issue"
  5. Select the deployment: "Main Operations"
  6. Complete the "Report Issue" action
  7. Verify it transitions to "Inspection"
  8. Assign an inspector
  9. Complete the inspection
  10. Verify it transitions to "Repair"
  11. Start the repair
  12. Complete the repair
  13. Verify it transitions to "Completed"

Step 14: Verify Features

  • Variables: Check that Water Point, Issue Description, and Repair Status are stored
  • Summary Fields: Check that Water Point and Status appear in the header
  • Alerts: If a repair is overdue, the warning should appear
  • Entry Points: Test both manual and site-based entry points
  • Actions: Test all action types (Mini Form, Survey Form, Manual Assignment, Timed Action)
  • Automations: Verify variables are set and assignments work
  • Transitions: Verify workflows move between steps correctly
  • Permissions: Test with different user roles
  • Recurrence: Verify actions can/cannot be repeated as configured

Summary

You've created a workflow that includes:

  • Variables (Reference, Text, Single Choice)
  • Summary Fields
  • Alerts
  • Custom Roles
  • Multiple Entry Points (Manual and Site)
  • Multiple Steps with different statuses
  • Various Action Types (Mini Form, Survey Form, Manual Assignment, Timed Action)
  • Automations (Set Variable, Assign)
  • Transitions (Action-level and Step-level)
  • Deployments with custom roles

This workflow demonstrates most features while remaining simple and practical for a water utility use case.