TGM Manager includes a comprehensive workflow automation system for managing approval processes, escalation rules, and automated notifications.

Overview¶

The workflow system supports:

• Multi-step approval workflows with configurable approvers
• Automatic escalation based on time rules
• Delegation of approval authority
• Status tracking and audit trails
• Dashboard analytics for workflow metrics

Workflow Types¶

Workflow Statuses¶

REST API¶

Workflow Management¶

Create Workflow¶

POST /workflows
Content-Type: application/json

{
  "workflowType": "WORK_ORDER_APPROVAL",
  "entityType": "WorkOrder",
  "entityId": 123,
  "title": "Emergency Pump Repair - Unit A",
  "description": "Request approval for emergency repair of pump P-101",
  "approverIds": [5, 8, 12]
}

Parameters:

Required Role: ADMIN, MANAGER, or OPERATOR

Get Workflow¶

GET /workflows/{workflowId}

Response:

{
  "data": {
    "id": 1,
    "workflowType": "WORK_ORDER_APPROVAL",
    "entityType": "WorkOrder",
    "entityId": 123,
    "title": "Emergency Pump Repair - Unit A",
    "status": "PENDING",
    "currentStep": 1,
    "totalSteps": 3,
    "requesterId": 10,
    "submittedAt": "2024-01-15T10:30:00",
    "escalationLevel": 0,
    "steps": [
      {
        "stepNumber": 1,
        "approverId": 5,
        "status": "PENDING",
        "assignedAt": "2024-01-15T10:30:00"
      }
    ]
  }
}

Get Workflow Steps¶

GET /workflows/{workflowId}/steps

Approval Actions¶

Approve Workflow¶

POST /workflows/{workflowId}/approve
Content-Type: application/json

{
  "comments": "Approved. Proceed with repairs."
}

Reject Workflow¶

POST /workflows/{workflowId}/reject
Content-Type: application/json

{
  "reason": "Budget not available for this quarter."
}

Request More Information¶

POST /workflows/{workflowId}/request-info
Content-Type: application/json

{
  "questions": "Please provide the cost breakdown and timeline estimate."
}

Delegate Approval¶

Delegate your approval authority to another user.

POST /workflows/{workflowId}/delegate
Content-Type: application/json

{
  "delegateToUserId": 15,
  "reason": "Out of office until next week"
}

Required Role: ADMIN or MANAGER

Escalate Workflow¶

Manually escalate a workflow to the next level.

POST /workflows/{workflowId}/escalate
Content-Type: application/json

{
  "reason": "Urgent - requires immediate attention"
}

Required Role: ADMIN or MANAGER

Cancel Workflow¶

POST /workflows/{workflowId}/cancel
Content-Type: application/json

{
  "reason": "Work order no longer needed"
}

Required Role: ADMIN or MANAGER

Query Endpoints¶

Get My Pending Approvals¶

GET /workflows/my-pending?page=0&size=20

Returns workflows waiting for the current user's approval.

Get My Requests¶

GET /workflows/my-requests?page=0&size=20

Returns workflows submitted by the current user.

Get By Status¶

GET /workflows/by-status?status=PENDING&page=0&size=20

Required Role: ADMIN or MANAGER

Get By Type¶

GET /workflows/by-type?workflowType=WORK_ORDER_APPROVAL&page=0&size=20

Required Role: ADMIN or MANAGER

Get By Entity¶

GET /workflows/by-entity?entityType=WorkOrder&entityId=123

Returns workflow for a specific entity.

Get Escalated Workflows¶

GET /workflows/escalated?minEscalationLevel=1

Required Role: ADMIN or MANAGER

Get Overdue Workflows¶

GET /workflows/overdue

Required Role: ADMIN or MANAGER

Dashboard¶

GET /workflows/dashboard

Returns workflow analytics and metrics.

Response:

{
  "data": {
    "pendingCount": 15,
    "approvedToday": 8,
    "rejectedToday": 2,
    "escalatedCount": 3,
    "overdueCount": 5,
    "avgApprovalTimeHours": 4.5,
    "byType": {
      "WORK_ORDER_APPROVAL": 10,
      "PURCHASE_REQUEST": 5
    },
    "byStatus": {
      "PENDING": 15,
      "APPROVED": 45,
      "REJECTED": 5
    }
  }
}

Required Role: ADMIN or MANAGER

Escalation Rules¶

List Escalation Rules¶

GET /workflows/escalation-rules

Response:

{
  "data": [
    {
      "id": 1,
      "workflowType": "WORK_ORDER_APPROVAL",
      "triggerAfterHours": 24,
      "escalateToUserId": 8,
      "escalateToRole": "MANAGER",
      "notifyRequester": true,
      "isActive": true
    }
  ]
}

Create Escalation Rule¶

POST /workflows/escalation-rules
Content-Type: application/json

{
  "workflowType": "PURCHASE_REQUEST",
  "triggerAfterHours": 48,
  "escalateToUserId": 12,
  "notifyRequester": true,
  "isActive": true
}

Required Role: ADMIN

Update Escalation Rule¶

PATCH /workflows/escalation-rules/{ruleId}
Content-Type: application/json

{
  "triggerAfterHours": 72,
  "isActive": false
}

Required Role: ADMIN

Delete Escalation Rule¶

DELETE /workflows/escalation-rules/{ruleId}

Required Role: ADMIN

Admin Actions¶

Process Auto-Escalations¶

Manually trigger the auto-escalation processor.

POST /workflows/process-escalations

Required Role: ADMIN

Send Pending Reminders¶

Manually trigger reminder notifications.

POST /workflows/send-reminders

Required Role: ADMIN

Enums Reference¶

Get Workflow Statuses¶

GET /workflows/enums/statuses

Get Workflow Types¶

GET /workflows/enums/types

Usage Examples¶

Creating an Approval Workflow¶

# Create a work order approval
curl -X POST http://localhost:1337/workflows \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowType": "WORK_ORDER_APPROVAL",
    "entityType": "WorkOrder",
    "entityId": 456,
    "title": "Preventive Maintenance - Conveyor Belt",
    "description": "Scheduled PM for conveyor belt system",
    "approverIds": [5, 8]
  }'

Approving a Workflow¶

curl -X POST http://localhost:1337/workflows/1/approve \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"comments": "Approved - budget allocated"}'

Checking Pending Approvals¶

curl -X GET "http://localhost:1337/workflows/my-pending?page=0&size=10" \
  -H "Authorization: Bearer $JWT"

Setting Up Escalation¶

# Create an escalation rule for purchase requests
curl -X POST http://localhost:1337/workflows/escalation-rules \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowType": "PURCHASE_REQUEST",
    "triggerAfterHours": 24,
    "escalateToUserId": 12,
    "notifyRequester": true,
    "isActive": true
  }'

Workflow Lifecycle¶

┌─────────┐     ┌─────────┐     ┌──────────┐
│ Created │────▶│ Pending │────▶│ Approved │
└─────────┘     └────┬────┘     └──────────┘
                     │
                     ├──────────▶ Rejected
                     │
                     ├──────────▶ Cancelled
                     │
                     ├──────────▶ Info Requested
                     │                    │
                     │                    ▼
                     │              ┌─────────┐
                     └──────────────│ Pending │
                                    └─────────┘
                     │
                     ▼
               ┌───────────┐
               │ Escalated │
               └───────────┘

Best Practices¶

1. Define clear approval chains - Order approvers by authority level
2. Set reasonable escalation times - Balance urgency with approver workload
3. Use descriptive titles - Help approvers understand requests quickly
4. Include relevant context - Link to related entities
5. Monitor the dashboard - Track bottlenecks and delays

Notifications¶

The workflow system sends notifications for:

• New approval requests assigned
• Workflows approved/rejected
• Information requests
• Escalation alerts
• Reminder for pending approvals