Workflows & Automation

Workflows are how you orchestrate complex, multi-step ITSM processes in Protocol. Powered by Temporal.io for durable, long-running execution and BullMQ for background job processing, workflows ensure that every ticket escalation, approval chain, and automated action completes reliably -- even across restarts and failures. On this page, we will explore the endpoints for managing workflows and automation rules programmatically.

The workflow model

The workflow model represents a single durable execution within the Temporal engine. Each workflow runs on a dedicated task queue and maintains a full timeline of execution events for audit and observability.

Task queues

Temporal task queues partition work across service domains: itsm-workflows (general), itsm-accessories (asset provisioning), itsm-fleet (device management), itsm-network (infrastructure), and itsm-high-priority (SLA-critical). BullMQ provides 12 additional queues for background jobs including email, notification, sync, AI inference, and report generation.

Properties

Name
id
Type
string
Description
Unique identifier for the workflow execution.
Name
name
Type
string
Description
Human-readable name describing the workflow.
Name
status
Type
string
Description
Current execution status. One of draft, active, paused, completed, failed, or archived.
Name
trigger_type
Type
string
Description
How the workflow is initiated. One of automatic, manual, scheduled, or event_based.
Name
task_queue
Type
string
Description
The Temporal task queue this workflow runs on (e.g., itsm-workflows, itsm-high-priority).
Name
started_at
Type
timestamp
Description
Timestamp of when the workflow execution started.
Name
completed_at
Type
timestamp
Description
Timestamp of when the workflow execution completed. Null if still running.
Name
timeline
Type
array
Description
An array of execution event objects tracking each step, signal, and state transition.

GET/v1/workflows

List all workflows

This endpoint allows you to retrieve a paginated list of all workflow executions. By default, a maximum of ten workflows are shown per page. You can filter by status and task queue.

Optional attributes

Name
status
Type
string
Description
Filter workflows by status (e.g., active, completed, failed).
Name
task_queue
Type
string
Description
Filter workflows by Temporal task queue.
Name
limit
Type
integer
Description
Limit the number of workflows returned.

Request

GET

/v1/workflows

curl -G http://localhost:3000/v1/workflows \
  -H "Authorization: Bearer {token}" \
  -d status="active" \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "id": "wf_7bR3kLmNpQ9xYz",
      "name": "Laptop Provisioning - New Hire",
      "status": "active",
      "trigger_type": "automatic",
      "task_queue": "itsm-accessories",
      "started_at": 1708732800,
      "completed_at": null,
      "timeline": [
        {
          "event": "workflow_started",
          "timestamp": 1708732800,
          "detail": "Triggered by ticket TKT-4829"
        },
        {
          "event": "activity_completed",
          "timestamp": 1708732860,
          "detail": "Asset availability checked"
        }
      ]
    },
    {
      "id": "wf_2dF8gHjKsT4wVb"
      // ...
    }
  ]
}

POST/v1/workflows

Create a workflow

This endpoint allows you to create and start a new workflow execution. The workflow is dispatched to the specified Temporal task queue and begins processing immediately unless the trigger type is scheduled.

Required attributes

Name
name
Type
string
Description
Human-readable name for the workflow.
Name
task_queue
Type
string
Description
The Temporal task queue to run this workflow on.

Optional attributes

Name
trigger_type
Type
string
Description
How the workflow should be initiated. Defaults to manual.
Name
input
Type
object
Description
Input parameters to pass to the workflow execution.

Request

POST

/v1/workflows

curl http://localhost:3000/v1/workflows \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{\
    "name": "VPN Access Revocation",\
    "task_queue": "itsm-network",\
    "trigger_type": "manual",\
    "input": { "ticket_id": "TKT-5102", "user_id": "usr_9xKmPq" }\
  }'

Response

{
  "id": "wf_4nT6vWxBcR1mZa",
  "name": "VPN Access Revocation",
  "status": "active",
  "trigger_type": "manual",
  "task_queue": "itsm-network",
  "started_at": 1708819200,
  "completed_at": null,
  "timeline": [
    {
      "event": "workflow_started",
      "timestamp": 1708819200,
      "detail": "Manually initiated"
    }
  ]
}

GET/v1/workflows/:id

Retrieve a workflow

This endpoint allows you to retrieve a workflow execution by providing the workflow id. The response includes the full timeline of execution events.

Request

GET

/v1/workflows/wf_7bR3kLmNpQ9xYz

curl http://localhost:3000/v1/workflows/wf_7bR3kLmNpQ9xYz \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "wf_7bR3kLmNpQ9xYz",
  "name": "Laptop Provisioning - New Hire",
  "status": "active",
  "trigger_type": "automatic",
  "task_queue": "itsm-accessories",
  "started_at": 1708732800,
  "completed_at": null,
  "timeline": [
    {
      "event": "workflow_started",
      "timestamp": 1708732800,
      "detail": "Triggered by ticket TKT-4829"
    },
    {
      "event": "activity_completed",
      "timestamp": 1708732860,
      "detail": "Asset availability checked"
    },
    {
      "event": "activity_started",
      "timestamp": 1708732861,
      "detail": "Awaiting manager approval"
    }
  ]
}

GET/v1/workflows/:id/status

Get workflow status

This endpoint returns the current execution status of a workflow along with a summary of completed and pending steps. Use this for lightweight polling without fetching the full timeline.

Request

GET

/v1/workflows/wf_7bR3kLmNpQ9xYz/status

curl http://localhost:3000/v1/workflows/wf_7bR3kLmNpQ9xYz/status \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "wf_7bR3kLmNpQ9xYz",
  "status": "active",
  "current_step": "Awaiting manager approval",
  "steps_completed": 2,
  "steps_total": 5,
  "started_at": 1708732800,
  "elapsed_seconds": 3600
}

POST/v1/workflows/:id/signal

Send a signal to a workflow

This endpoint sends a Temporal signal to a running workflow execution. Signals allow external events -- such as approvals, user input, or third-party callbacks -- to advance workflow state without polling.

Required attributes

Name
signal_name
Type
string
Description
The name of the signal to send (e.g., approval_received, user_responded).

Optional attributes

Name
payload
Type
object
Description
Data to pass along with the signal.

Request

POST

/v1/workflows/wf_7bR3kLmNpQ9xYz/signal

curl http://localhost:3000/v1/workflows/wf_7bR3kLmNpQ9xYz/signal \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{\
    "signal_name": "approval_received",\
    "payload": { "approved_by": "usr_3mKpLq", "decision": "approved" }\
  }'

Response

{
  "id": "wf_7bR3kLmNpQ9xYz",
  "signal_name": "approval_received",
  "accepted": true,
  "status": "active",
  "current_step": "Provisioning asset"
}

POST/v1/workflows/:id/cancel

Cancel a workflow

This endpoint cancels a running workflow execution. Temporal ensures that any in-flight activities are gracefully terminated and compensation logic is executed. The workflow status transitions to failed with a cancellation reason recorded in the timeline.

Request

POST

/v1/workflows/wf_7bR3kLmNpQ9xYz/cancel

curl -X POST http://localhost:3000/v1/workflows/wf_7bR3kLmNpQ9xYz/cancel \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "wf_7bR3kLmNpQ9xYz",
  "status": "failed",
  "cancelled_at": 1708736400,
  "timeline": [
    {
      "event": "workflow_cancelled",
      "timestamp": 1708736400,
      "detail": "Cancelled by user"
    }
  ]
}

GET/v1/automation/rules

List all automation rules

This endpoint returns a paginated list of automation rules. Automation rules define trigger-based logic that automatically starts workflows or performs actions when specific ITSM events occur. Supported triggers include on_ticket_created, on_ticket_updated, scheduled, and webhook.

Optional attributes

Name
trigger
Type
string
Description
Filter rules by trigger type.
Name
enabled
Type
boolean
Description
Filter by enabled or disabled rules.
Name
limit
Type
integer
Description
Limit the number of rules returned.

Request

GET

/v1/automation/rules

curl -G http://localhost:3000/v1/automation/rules \
  -H "Authorization: Bearer {token}" \
  -d enabled=true \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "id": "rule_8fG2hJkLmN3pQr",
      "name": "Auto-assign P1 tickets to on-call",
      "trigger": "on_ticket_created",
      "conditions": {
        "priority": "P1",
        "category": "incident"
      },
      "action": {
        "type": "start_workflow",
        "workflow_name": "P1 Incident Response",
        "task_queue": "itsm-high-priority"
      },
      "enabled": true,
      "created_at": 1708646400,
      "updated_at": 1708732800
    },
    {
      "id": "rule_5aB9cDeFgH1iJk"
      // ...
    }
  ]
}

POST/v1/automation/rules

Create an automation rule

This endpoint allows you to create a new automation rule. Rules are evaluated against ITSM events in real time and can trigger workflow executions, send notifications, or update ticket fields automatically.

Required attributes

Name
name
Type
string
Description
A descriptive name for the automation rule.
Name
trigger
Type
string
Description
The event that activates this rule. One of on_ticket_created, on_ticket_updated, scheduled, or webhook.
Name
action
Type
object
Description
The action to perform when the rule is triggered. Includes type (e.g., start_workflow, send_notification, update_field) and action-specific parameters.

Optional attributes

Name
conditions
Type
object
Description
Conditions that must be met for the rule to fire (e.g., priority, category, assignee).
Name
enabled
Type
boolean
Description
Whether the rule is active. Defaults to true.

Request

POST

/v1/automation/rules

curl http://localhost:3000/v1/automation/rules \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{\
    "name": "Escalate stale tickets after 24h",\
    "trigger": "scheduled",\
    "conditions": { "status": "open", "idle_hours": 24 },\
    "action": {\
      "type": "start_workflow",\
      "workflow_name": "SLA Escalation",\
      "task_queue": "itsm-high-priority"\
    }\
  }'

Response

{
  "id": "rule_6cD4eFgHiJ2kLm",
  "name": "Escalate stale tickets after 24h",
  "trigger": "scheduled",
  "conditions": {
    "status": "open",
    "idle_hours": 24
  },
  "action": {
    "type": "start_workflow",
    "workflow_name": "SLA Escalation",
    "task_queue": "itsm-high-priority"
  },
  "enabled": true,
  "created_at": 1708819200,
  "updated_at": 1708819200
}

POST/v1/automation/rules/:id/toggle

Toggle an automation rule

This endpoint toggles the enabled state of an automation rule. If the rule is currently enabled, it will be disabled, and vice versa. This is useful for temporarily pausing rules during maintenance windows without deleting them.

Request

POST

/v1/automation/rules/rule_8fG2hJkLmN3pQr/toggle

curl -X POST http://localhost:3000/v1/automation/rules/rule_8fG2hJkLmN3pQr/toggle \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "rule_8fG2hJkLmN3pQr",
  "name": "Auto-assign P1 tickets to on-call",
  "enabled": false,
  "toggled_at": 1708822800
}