Workflows

The workflow system provides state machine automation for any collection. Workflows control how items move between states (e.g., draft → review → published), who can trigger each transition, and what side effects run automatically.

Concepts

Workflow Definition Structure

{
  "initial_state": "Draft",
  "states": [
    {
      "name": "Draft",
      "commands": [
        {
          "name": "Submit",
          "next_state": "Pending Approval",
          "policies": [],
          "actions": []
        }
      ],
      "isEndState": false
    },
    {
      "name": "Pending Approval",
      "commands": [
        {
          "name": "Reject",
          "next_state": "Draft",
          "policies": [],
          "actions": []
        },
        {
          "name": "Approve",
          "next_state": "Published",
          "policies": ["550e8400-e29b-41d4-a716-446655440000"],
          "actions": [
            {
              "name": "Publish",
              "event_name": "xtr.item.promote",
              "parameters": {}
            }
          ]
        }
      ],
      "isEndState": false
    },
    {
      "name": "Published",
      "commands": [],
      "isEndState": true
    }
  ]
}

State fields

Command fields

The workflow:approve and workflow:reject keys are seeded in the Module Access Keys registry, so Approve/Reject commands can be gated with a key grant (a policy’s Module-Level Access tab) without creating dedicated policies. See Module Access for enforcing the same keys in your own routes.

Action fields

Automatic Instance Creation

When an item is created in a collection that has a Workflow Assignment, the system automatically:

1. Checks daas_wf_assignment for matching assignments (by collection + filter rule)
2. Creates a daas_wf_instance with current_state set to initial_state
3. Updates the item’s workflow instance field and state field

Required collection fields

Two fields must exist in the collection: a Many-to-One link to daas_wf_instance and a Workflow State string field.

New collections — enable both switches in the collection creation wizard under System Fields → Workflow Fields:

Existing collections — add the fields manually via Data Model → [Your Collection] → New Field:

Mark both as read-only in the field metadata — users should not edit them directly.

Execute a Transition

POST /api/workflow/transition

{
  "workflowInstanceId": "uuid",
  "commandName": "Approve"
}

Success (200):

{ "message": "Successfully transitioned workflow state" }

Unauthorized (403):

{ "message": "You are not authorized to perform this transition" }

The endpoint:

1. Validates the command exists in the current state
2. Checks the user holds at least one required policy UUID (directly or via role) or one of the command’s module_access_keys (granted via a policy’s Module-Level Access tab) — the two lists are OR’d
3. Updates current_state in daas_wf_instance
4. Records the transition in daas_wf_history
5. Updates the workflow state field in the target collection or version
6. Fires all configured actions in sequence

Locking Commands to Roles

policies entries must be policy UUIDs (daas_policies.id) — not the id of the daas_access row that links a policy to a role. The authorization check resolves the caller’s held policies via the get_user_policies database function and compares that list directly against command.policies; daas_access is only the join table connecting a policy to a role or user, and its own id is never checked against anything.

// 1. Create a policy
POST /api/policies
{ "name": "Article Reviewer", "description": "Can approve/reject articles" }
// → { "data": { "id": "3f1e...-policy-id", ... } }
 
// 2. Link the policy to a role
POST /api/access
{ "role": "editor-role-uuid", "policy": "3f1e...-policy-id" }
 
// 3. Reference the POLICY id (not the daas_access row's id) in the command
{
  "name": "Approve",
  "next_state": "Published",
  "policies": ["3f1e...-policy-id"],
  "actions": []
}

Scope-Aware Authorization

If the request carries an X-Resource-Uri header, the policy and module-key checks resolve at that scope: only policies granted at the asserted scope (or an ancestor, including root) authorize the transition. An invalid or unauthorized Resource URI fails the request — it does not fall back to the scope-blind check. Requests without the header keep the legacy flat resolution across all scopes.

Built-in Actions

xtr.item.promote

Promotes a content version to the main item. Only runs when the workflow instance is linked to a version (version_key is not null).

{ "name": "Promote to Main", "event_name": "xtr.item.promote", "parameters": {} }

Custom actions

Register any event_name in a file-based extension or runtime extension:

export function register(sdk) {
  sdk.emitter.onAction('xtr.notification.send-email', async (meta, context) => {
    // action parameters are spread onto meta.payload[0] alongside workflow_instance
    const { recipient, workflow_instance } = meta.payload[0];
    await sendEmail(recipient, 'Workflow state changed');
  });
}

Workflow Assignments

Assignments connect a workflow definition to a collection with an optional filter rule:

{
  "collection": "articles",
  "workflow": "workflow-definition-uuid",
  "filter_rule": { "category": { "_eq": "news" } }
}

An empty filter_rule matches all items in the collection.

Version Workflows

Workflows can track content versions. When a version is created:

• The filter rule is tested against the parent item (not the version itself)
• The instance is linked with a version_key
• The xtr.item.promote action applies the version delta to the main item

Best Practices

1. One assignment per collection/filter combination — avoid overlapping filter rules
2. Mark workflow fields as read-only — users should not manually edit workflow_instance or workflow_state
3. Use empty policies arrays for commands that any authenticated user can trigger
4. Test filter rules with Supabase queries before production
5. When gating a command, always use the policy’s own id — see Locking Commands to Roles. Copying the daas_access row’s id instead is a common mistake that silently locks everyone out.

REST API