Quick Start Guide

Create your first workflow in 10 minutes and learn the basics of workflow design and execution.

What We’ll Build

A simple Task Approval workflow with three states: - Draft - Task is being created - Pending Approval - Waiting for manager approval - Completed - Task approved and closed

Prerequisites

  • Access to Ambience with Workflow module installed
  • Privileges: mod-workflows, mod-workflow, mod-workflow-edit
  • Basic familiarity with ETL chains (optional for this tutorial)

Step 1: Create the Workflow

  1. Navigate to the Workflows page
  2. Click the Add button (upper right corner)
  3. Fill in the dialog:
  • Name: TaskApproval
  • Copy From: Blank Workflow
  • Database: Select your database (e.g., main)
  • Collection: Enter taskApprovals
  • Chainset: Select an ETL chainset (any will work for now)
  1. Click OK

Your new workflow appears in the list.

Step 2: Open the Workflow Designer

  1. Click on the workflow name TaskApproval in the list
  2. The Workflow Designer opens

You’ll see a default workflow with: - Start state (grey circle) - Running state (blue rounded rectangle) - Stop state (grey circle with square) - Two transitions connecting them

Step 3: Design the Workflow

Rename the Running State

  1. Click on the Running state to select it
  2. In the Properties Panel (left side, bottom), find the Label field
  3. Change Running to Draft
  4. Press Enter (workflow auto-saves)

Add Pending Approval State

  1. With the Draft state still selected, click Add State in the Actions Panel
  2. A new state (New State) appears
  3. Click on the new state to select it
  4. In Properties Panel, change Label to Pending Approval

Add Completed State

  1. Click Add State again
  2. Select the new state
  3. Change Label to Completed

Rename Transitions

  1. Click on the transition from Start to Draft
  2. In Properties Panel, change Label to create
  3. Click on the transition from Draft to Pending Approval
  4. Change Label to submit
  5. Add a new transition from Pending Approval to Completed:
  • Select Pending Approval state
  • Click Create Transition in Actions Panel
  • Click on Completed state
  1. Select the new transition
  2. Change Label to approve
  3. Click on the transition from Completed to Stop
  4. Change Label to close

Set Event Names

For transitions to respond to specific events, set event names:

  1. Select the submit transition (Draft → Pending Approval)
  2. In Properties Panel, find Event field
  3. Enter submit
  4. Select the approve transition (Pending Approval → Completed)
  5. Set Event to approve

Your workflow is now designed! It should look like:

Start → Draft → Pending Approval → Completed → Stop
       create   submit          approve      close

Step 4: Test the Workflow via REST API

Create a Workflow Instance

Use curl or your preferred HTTP client:

curl -X POST http://localhost:8080/api/workflow/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "workflowId": "YOUR_WORKFLOW_ID",
    "data": {
      "elxPublic": {
        "taskName": "Review Q1 Report",
        "assignedTo": "john.doe",
        "priority": "high"
      }
    }
  }'

Response:

{
  "workflowId": "...",
  "instanceId": "...",
  "state": {
    "elxPublic": {
      "taskName": "Review Q1 Report",
      "assignedTo": "john.doe",
      "priority": "high"
    },
    "elxPrivate": {},
    "elxHistory": [...],
    "_id": "...",
    "states": [
      {
        "stateMachineId": "...",
        "nodeId": "Draft"
      }
    ]
  }
}

The instance is now in Draft state.

Send Submit Event

curl -X POST http://localhost:8080/api/workflow/event \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "workflowId": "YOUR_WORKFLOW_ID",
    "instanceId": "YOUR_INSTANCE_ID",
    "event": {
      "name": "submit",
      "data": {
        "submittedBy": "john.doe",
        "submittedAt": "2026-02-28T10:00:00Z"
      }
    }
  }'

The instance transitions to Pending Approval state.

Send Approve Event

curl -X POST http://localhost:8080/api/workflow/event \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "workflowId": "YOUR_WORKFLOW_ID",
    "instanceId": "YOUR_INSTANCE_ID",
    "event": {
      "name": "approve",
      "data": {
        "approvedBy": "manager.smith",
        "approvedAt": "2026-02-28T11:00:00Z",
        "comments": "Approved"
      }
    }
  }'

The instance transitions to Completed state.

Step 5: View the Audit Log

  1. Navigate to the Audit Log module
  2. Filter by your workflow collection (taskApprovals)
  3. You’ll see entries for:
  • Instance creation
  • State transition: Draft → Pending Approval
  • State transition: Pending Approval → Completed

Each entry shows: - User who triggered the event - Timestamp - State changes - Data modifications

What You’ve Learned

✅ Create workflows using the Workflow Designer
✅ Design state machines with states and transitions
✅ Set event names for transition triggering
✅ Create instances via REST API
✅ Send events to progress workflows
✅ View audit logs for compliance

Next Steps

Add ETL Integration

Enhance your workflow with ETL chains:

  1. Create ETL chains for notifications:
  • notifySubmission - Email when task submitted
  • notifyApproval - Email when task approved
  1. In Workflow Designer:
  • Select Pending Approval state
  • Set OnEntry to notifySubmission
  • Select Completed state
  • Set OnEntry to notifyApproval

Now emails are sent automatically on state transitions!

Add Guard Conditions

Add approval logic:

  1. Create ETL chain checkApprovalRules:
  • Check if approver has permission
  • Check if task priority requires higher approval
  • Return success/failure
  1. In Workflow Designer:
  • Select approve transition
  • Set Guard → Chain → checkApprovalRules

Now the transition only fires if the guard passes.

Add Timeout Handling

Add automatic escalation:

  1. Select Pending Approval state
  2. In Properties Panel, set OnAfter:
  • Units: Days
  • Time: 3
  • Event: escalate
  1. Add new transition from Pending Approval to Pending Approval (loop):
  • Label: escalate
  • Event: escalate
  • OnTransition: ETL chain that sends escalation email

Now if no approval within 3 days, an escalation email is sent automatically.

Learn More

Next: Workflow Management