Skip to main content

Workflows & State Machines

Detail workflow modeling, transition guards, explain endpoints, and migration patterns relevant to long-lived processes.

Workflow State Machine Example​

Workflow Transition Flow​

What are Workflows?​

Workflows are finite-state machines that manage the lifecycle of objects. Each workflow defines:

  • States – Possible states an object can be in (e.g., draft, review, approved, published)
  • Transitions – Allowed state changes
  • Guards – Rules that must be satisfied before a transition can occur
  • Initial state – The starting state for new objects

Creating a Workflow​

Via API​

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "document-approval",
    "displayName": "Document Approval Workflow",
    "states": [
      {"id": "draft", "displayName": "Draft"},
      {"id": "review", "displayName": "Under Review"},
      {"id": "approved", "displayName": "Approved"},
      {"id": "rejected", "displayName": "Rejected"},
      {"id": "published", "displayName": "Published"}
    ],
    "transitions": [
      {
        "from": "draft",
        "to": "review",
        "guard": "has_permission"
      },
      {
        "from": "review",
        "to": "approved",
        "guard": "approval_rule"
      },
      {
        "from": "review",
        "to": "rejected",
        "guard": "rejection_rule"
      },
      {
        "from": "approved",
        "to": "published",
        "guard": "publish_rule"
      },
      {
        "from": "rejected",
        "to": "draft",
        "guard": "revise_rule"
      }
    ],
    "initialState": "draft"
  }' \
  https://core.example.com/v1/workflows

Via Admin Console​

  1. Navigate to Workflows in the Admin Console
  2. Click Create New Workflow
  3. Define states and transitions
  4. Configure guards for each transition
  5. Save and publish

Transition Guards​

Guards are rules that must be satisfied before a transition can occur. They can check:

  • Permissions – User roles and capabilities
  • Object attributes – Current values of object fields
  • Spatial conditions – Geometry-based rules
  • External conditions – Results from API calls or database queries

Example Guards​

{
  "guard": {
    "type": "and",
    "rules": [
      {
        "type": "permission",
        "requiredRole": "admin"
      },
      {
        "type": "attribute",
        "path": "$.status",
        "operator": "equals",
        "value": "ready"
      }
    ]
  }
}

Triggering Transitions​

Via API​

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "targetState": "review",
    "metadata": {
      "reason": "Ready for review"
    }
  }' \
  https://core.example.com/v1/objects/{objectId}/workflow/transitions

Explaining Transitions​

Before attempting a transition, you can check why it might fail:

curl -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/objects/{objectId}/workflow/explain-transitions

This returns:

  • Available transitions
  • Required guards for each transition
  • Current guard evaluation results
  • Reasons why transitions are blocked

Workflow Versioning​

Workflows follow the same versioning lifecycle as object types:

  1. Draft – Can be modified freely
  2. Sandbox – Test with sample objects
  3. Published – Immutable, used in production

Migrating Objects​

When a workflow is updated, existing objects continue using their original workflow version. To migrate:

  1. Create a migration script
  2. Read objects with the old workflow
  3. Transition objects to compatible states in the new workflow
  4. Update objects to use the new workflow version

Best Practices​

  1. Start simple – Begin with basic states and add complexity as needed
  2. Test thoroughly – Use sandbox mode to test workflow logic
  3. Document guards – Clearly document why each guard exists
  4. Handle edge cases – Consider what happens when guards fail
  5. Version carefully – Published workflows are immutable
  6. Monitor transitions – Track transition success/failure rates
  7. Use explain endpoints – Help users understand why transitions fail