ITSM approval workflows vs automation workflows

AtlasAI’s Tenant Plane has two separate workflow systems. They use different APIs, different step shapes, and solve different problems. Do not mix their definition IDs on catalog items without verifying compatibility.

1. Quick comparison

	ITSM approval workflows	Automation / orchestration workflows
Purpose	Human approval chains for service requests and change requests	Runbook execution, delays, notifications, conditions, and approval gates in a technical pipeline
Typical user	Service owners, managers signing off requests	SRE, automation engineers
Where to design	Definitions are created via `POST /api/workflows/definitions` (or seeding). ITSM UI may reference a definition ID.	Automation → Workflows in the TP UI (`/workflows`; `/workflow` redirects here), or `POST /api/workflows` — see Workflow builder (step-by-step)
Step model	Ordered steps: approver (`user` / `group` / `role` / `any`), order, required, optional approver_value	Steps from the automation schema: `runbook`, `approval`, `condition`, `notification`, `delay`; optional edges for branching
Execution engine	`workflow-engine` — instances track current_step and step_results (approved/rejected per step)	`execution-job-runner` — runs runbooks, pauses on approval jobs, supports resume after approval
Service catalog link	Catalog field `workflow_definition_id` → on new request, TP calls `startWorkflowInstance` for that approval definition	Not what `workflow_definition_id` on the catalog targets today. Use catalog fulfillment (e.g. runbook after approval) instead

2. When to use which

Use ITSM approval workflows when:

You need sequential human sign-off (e.g. manager → CAB delegate) on a service request or change.
You want an instance tied to the service request record as soon as the user submits from the catalog (if the catalog item has workflow_definition_id set to an approval definition).
Approvers are modeled as roles, users, or groups in the ITSM sense.

Use automation workflows when:

You need to chain runbooks, add wait/delay, branch on a condition, send notifications, or pause for an automation approval job before continuing.
You are automating remediation, provisioning, or operational pipelines, not only ITSM sign-off.
You want a graph (steps + edges with conditions) rather than a simple approval ladder.

Service catalog and runbooks

The catalog does not require a runbook. fulfillment_type defaults to manual.
Optional: set fulfillment_type to runbook and put runbook_id in fulfillment_config so fulfillment can run a runbook after approval (see ITSM request fulfillment logic).
Optional: set workflow_definition_id to an ITSM approval definition ID (from /api/workflows/definitions, not the automation canvas UUID unless you know they share a compatible row — prefer keeping approval definitions created through the definitions API).

3. How catalog requests start an approval workflow

Admin creates catalog items under ITSM (/api/itsm/catalog or ITSM UI).
If workflow_definition_id points to a valid approval definition, POST /api/itsm/requests starts a workflow instance via the ITSM workflow engine.
Approvers act on the instance through the workflow instances APIs / UI (e.g. approve step).

If workflow_definition_id is empty, the request is still created; no approval instance is started automatically.

4. Example use cases

ITSM approval workflows — typical scenarios

Use case	What you model
Access or software request	Line manager approves, then service desk or app owner approves before fulfillment.
Standard change	Pre-approved path: one approver; normal change: multiple steps (e.g. tech lead → CAB).
Purchase or vendor action	Finance or procurement role must approve before any automated fulfillment runs.
Regulated environments	Every catalog item for production access includes a fixed approval ladder tied to the request record.

Automation / orchestration workflows — typical scenarios

Use case	What you model
Incident remediation	Run diagnostic runbook → condition on outcome → escalate runbook or notify on-call.
Provision-after-approve	After ITSM approval completes, a runbook chain creates accounts, opens tickets, or updates CMDB.
Maintenance window	Delay step, then runbook execution, then notification that work completed.
Guard-railed automation	Approval step in the middle of a runbook chain so an operator confirms before destructive steps.

Together, you often use both: ITSM approval on the service request, then fulfillment (manual, runbook, or a separate automation workflow) once the request is approved.

For technical API and table notes, see the repository: docs/WORKFLOWS_ITSM_VS_AUTOMATION.md.

5. Summary checklist

I need…	Use
Manager approves before fulfillment	ITSM approval definition + catalog `workflow_definition_id`
Chain runbooks + wait + notify	Automation workflow on `/workflows`
Both	Approval on the request (ITSM) + fulfillment runbook or separate automation triggered after approve