Workflows API

REST API reference for workflow definitions, stages, instances, approvals, and actions

Overview

The Workflows API lets you manage workflow definitions, configure stages, query pending approvals, and submit approval actions. All endpoints require authentication.

Endpoints

Method	Path	Description
GET	`/api/settings/workflows`	List all workflow definitions
POST	`/api/settings/workflows`	Create a workflow
GET	`/api/settings/workflows/{id}`	Get workflow with stages
PATCH	`/api/settings/workflows/{id}`	Update workflow
DELETE	`/api/settings/workflows/{id}`	Delete workflow
GET	`/api/settings/workflows/{id}/stages`	List stages
POST	`/api/settings/workflows/{id}/stages`	Add a stage
PUT	`/api/settings/workflows/{id}/stages`	Bulk replace all stages
GET	`/api/workflows/my-approvals`	Pending approvals for current user
GET	`/api/workflows/{instanceId}`	Instance detail with timeline
POST	`/api/workflows/{instanceId}/action`	Submit approval action
POST	`/api/admin/seed-workflows`	Seed pre-built templates

List Workflows

GET /api/settings/workflows

Returns all workflow definitions with stage counts.

Create Workflow

POST /api/settings/workflows

{
  "name": "Leave Request Approval",
  "triggerEntity": "LeaveRequest",
  "triggerEvent": "CREATE",
  "isActive": false
}

Get Workflow Detail

GET /api/settings/workflows/{id}

Returns the workflow definition with all stages and instance count.

{
  "data": {
    "id": "clx...",
    "name": "Leave Request Approval",
    "triggerEntity": "LeaveRequest",
    "triggerEvent": "CREATE",
    "isActive": true,
    "instanceCount": 12,
    "stages": [
      {
        "id": "clx...",
        "name": "HOD Review",
        "stageOrder": 1,
        "stageType": "WF_APPROVAL",
        "assigneeType": "WF_DEPARTMENT_HEAD",
        "slaHours": 48,
        "onApprove": null,
        "onReject": { "fieldUpdates": [{ "fieldApiName": "status", "value": "REJECTED" }] },
        "notifyOnEntry": { "channels": ["NOTIF_IN_APP", "NOTIF_EMAIL"] }
      }
    ]
  }
}

Update Workflow

PATCH /api/settings/workflows/{id}

All fields optional: name, description, triggerEntity, triggerEvent, triggerConditions, isActive.

Delete Workflow

DELETE /api/settings/workflows/{id}

Cascades to stages, instances, actions, and assignments.

Bulk Replace Stages

PUT /api/settings/workflows/{id}/stages

Replaces all stages for a workflow. Used by the visual builder to save the entire configuration at once.

{
  "stages": [
    {
      "name": "HOD Review",
      "stageOrder": 1,
      "stageType": "WF_APPROVAL",
      "assigneeType": "WF_DEPARTMENT_HEAD",
      "slaHours": 48,
      "notifyOnEntry": { "channels": ["NOTIF_IN_APP", "NOTIF_EMAIL"] },
      "onApprove": null,
      "onReject": { "fieldUpdates": [{ "fieldApiName": "status", "value": "REJECTED" }] }
    },
    {
      "name": "Principal Approval",
      "stageOrder": 2,
      "stageType": "WF_APPROVAL",
      "assigneeType": "WF_ROLE",
      "assigneeRoleId": "clx...",
      "slaHours": 24,
      "onApprove": { "fieldUpdates": [{ "fieldApiName": "status", "value": "APPROVED" }] },
      "onReject": { "fieldUpdates": [{ "fieldApiName": "status", "value": "REJECTED" }] }
    }
  ]
}

Stage Fields

Field	Type	Description
`name`	string	Stage display name
`description`	string	Optional description
`stageOrder`	number	Order in the pipeline (1-based)
`stageType`	enum	`WF_APPROVAL`, `WF_NOTIFICATION`, `WF_AUTO_ACTION`, `WF_PARALLEL_APPROVAL`, `WF_CONDITIONAL`
`assigneeType`	enum	`WF_ROLE`, `WF_SPECIFIC_USER`, `WF_REPORTING_MANAGER`, `WF_DEPARTMENT_HEAD`, `WF_DYNAMIC`
`assigneeRoleId`	string	Role ID (when assigneeType = `WF_ROLE`)
`assigneeUserId`	string	User ID (when assigneeType = `WF_SPECIFIC_USER`)
`assigneeDynamic`	string	Field name on the record (when assigneeType = `WF_DYNAMIC`)
`slaHours`	number	Hours before the task shows as overdue
`escalateTo`	string	User ID to escalate to on SLA breach
`onApprove`	object	Field updates to execute when approved
`onReject`	object	Field updates to execute when rejected
`notifyOnEntry`	object	Notification channels when stage starts

My Approvals

GET /api/workflows/my-approvals

Returns pending workflow stage assignments for the authenticated user.

{
  "data": [
    {
      "id": "clx...",
      "instanceId": "clx...",
      "workflowName": "Leave Request Approval",
      "entity": "LeaveRequest",
      "entityId": "clx...",
      "stageName": "HOD Review",
      "stageId": "clx...",
      "stageType": "WF_APPROVAL",
      "assignedAt": "2026-04-14T...",
      "dueAt": "2026-04-16T...",
      "isOverdue": false,
      "isDueSoon": true
    }
  ],
  "meta": { "total": 3 }
}

Instance Detail

GET /api/workflows/{instanceId}

Returns the full workflow instance with stages, action history, and assignments.

{
  "data": {
    "id": "clx...",
    "status": "WF_ACTIVE",
    "entity": "LeaveRequest",
    "entityId": "clx...",
    "startedAt": "2026-04-14T...",
    "currentStageId": "clx...",
    "workflow": {
      "name": "Leave Request Approval",
      "stages": [...]
    },
    "actions": [
      {
        "stageId": "clx...",
        "action": "WFA_APPROVED",
        "comment": "Looks good",
        "actor": { "name": "Dr. Kumar" },
        "decidedAt": "2026-04-14T..."
      }
    ],
    "assignments": [...]
  }
}

Instance Statuses

Status	Description
`WF_ACTIVE`	Workflow is in progress
`WF_COMPLETED`	All stages approved — workflow finished successfully
`WF_REJECTED`	A stage was rejected — workflow terminated
`WF_CANCELLED`	Workflow was manually cancelled
`WF_ESCALATED`	Stage was escalated due to SLA breach

Submit Action

POST /api/workflows/{instanceId}/action

{
  "stageId": "clx...",
  "action": "WFA_APPROVED",
  "comment": "Approved — all looks good"
}

Field	Type	Required	Description
`stageId`	string	Yes	The current stage ID
`action`	enum	Yes	`WFA_APPROVED`, `WFA_REJECTED`, `WFA_COMMENTED`, `WFA_REASSIGNED`, `WFA_ESCALATED`
`comment`	string	No	Optional comment (required for `WFA_COMMENTED`)

Action Types

Action	Effect
`WFA_APPROVED`	Advances to next stage, or completes if final stage
`WFA_REJECTED`	Terminates workflow with status `WF_REJECTED`
`WFA_COMMENTED`	Adds a comment without changing workflow state
`WFA_ESCALATED`	Terminates workflow with status `WF_ESCALATED`
`WFA_REASSIGNED`	Reassigns the stage to a different user

After Action

Approved + next stage exists → new assignees are notified via in-app + email
Approved + final stage → workflow completed, initiator notified
Rejected → workflow terminated, initiator notified
Field updates → onApprove/onReject config on the stage is executed automatically

Seed Workflow Templates

POST /api/admin/seed-workflows

Requires SUPER_ADMIN or INSTITUTION_ADMIN role. Creates 5 pre-built workflow templates (inactive by default).

{
  "success": true,
  "created": ["Leave Request Approval", "Expense Approval", "Fee Concession Approval", "Admission Progression", "Hostel Gate Pass Approval"],
  "skipped": [],
  "message": "Created 5 workflows, skipped 0 (already exist)."
}