9.1 KiB

Raw Blame History

Comprehensive Approval Workflow API

Overview

This document describes the new comprehensive API endpoint that creates approval workflows along with all their dependencies (client approval settings) in a single API call.

Endpoint Details

POST `/approval-workflows/with-client-settings`

Description: Creates a comprehensive approval workflow with workflow steps and client approval settings in a single transaction.

Authentication: Bearer token required

Request Body:

{
  "name": "Standard Article Approval",
  "description": "Standard approval workflow for articles",
  "isActive": true,
  "isDefault": true,
  "requiresApproval": true,
  "autoPublish": false,
  "steps": [
    {
      "stepOrder": 1,
      "stepName": "Editor Review",
      "requiredUserLevelId": 2,
      "canSkip": false,
      "autoApproveAfterHours": null,
      "isActive": true,
      "parentStepId": null,
      "conditionType": "always",
      "conditionValue": null,
      "isParallel": false,
      "branchName": null,
      "branchOrder": null
    },
    {
      "stepOrder": 2,
      "stepName": "Manager Approval",
      "requiredUserLevelId": 3,
      "canSkip": false,
      "autoApproveAfterHours": 24,
      "isActive": true,
      "parentStepId": null,
      "conditionType": "always",
      "conditionValue": null,
      "isParallel": false,
      "branchName": null,
      "branchOrder": null
    }
  ],
  "clientApprovalSettings": {
    "requiresApproval": true,
    "autoPublishArticles": false,
    "approvalExemptUsers": [],
    "approvalExemptRoles": [],
    "approvalExemptCategories": [],
    "requireApprovalFor": ["article", "news"],
    "skipApprovalFor": ["announcement"],
    "isActive": true
  }
}

Response:

{
  "success": true,
  "messages": ["Comprehensive approval workflow with client settings successfully created"],
  "data": {
    "workflow": {
      "id": 1,
      "name": "Standard Article Approval",
      "description": "Standard approval workflow for articles",
      "isActive": true,
      "isDefault": true,
      "requiresApproval": true,
      "autoPublish": false,
      "clientId": "uuid-here",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    },
    "clientSettings": {
      "id": 1,
      "clientId": "uuid-here",
      "requiresApproval": true,
      "defaultWorkflowId": 1,
      "autoPublishArticles": false,
      "approvalExemptUsers": [],
      "approvalExemptRoles": [],
      "approvalExemptCategories": [],
      "requireApprovalFor": ["article", "news"],
      "skipApprovalFor": ["announcement"],
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    },
    "message": "Comprehensive approval workflow with client settings created successfully"
  }
}

Features

1. Atomic Transaction

Creates workflow, workflow steps, and client approval settings in a single transaction
Automatic rollback if any step fails
Ensures data consistency

2. Comprehensive Validation

Validates workflow structure and steps
Checks for existing client approval settings
Validates multi-branch workflow logic
Ensures proper step ordering

3. Multi-Branch Support

Supports complex approval workflows with parallel branches
Conditional step execution
Parent-child step relationships
Branch naming and ordering

4. Client Settings Integration

Automatically links workflow to client approval settings
Sets default workflow if specified
Configures approval exemptions
Sets content type approval rules

5. Error Handling

Comprehensive error messages
Automatic cleanup on failure
Detailed logging for debugging
Graceful degradation

Request Structure Details

Workflow Fields

name: Workflow name (required)
description: Workflow description (required)
isActive: Whether workflow is active
isDefault: Whether to set as default workflow
requiresApproval: Whether workflow requires approval
autoPublish: Whether to auto-publish after approval

Step Fields

stepOrder: Order of the step in workflow
stepName: Name of the approval step
requiredUserLevelId: User level required for this step
canSkip: Whether this step can be skipped
autoApproveAfterHours: Auto-approve after specified hours
isActive: Whether step is active

Multi-Branch Fields

parentStepId: Parent step for branching
conditionType: Condition type (user_level, user_level_hierarchy, always, custom)
conditionValue: JSON condition value
isParallel: Whether step runs in parallel
branchName: Name of the branch
branchOrder: Order within branch

Client Settings Fields

requiresApproval: Global approval requirement
autoPublishArticles: Auto-publish after creation
approvalExemptUsers: User IDs exempt from approval
approvalExemptRoles: Role IDs exempt from approval
approvalExemptCategories: Category IDs exempt from approval
requireApprovalFor: Content types requiring approval
skipApprovalFor: Content types skipping approval
isActive: Whether settings are active

Usage Examples

Basic Workflow

curl -X POST "https://api.example.com/approval-workflows/with-client-settings" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Simple Approval",
    "description": "Two-step approval process",
    "isActive": true,
    "isDefault": true,
    "steps": [
      {
        "stepOrder": 1,
        "stepName": "Editor Review",
        "requiredUserLevelId": 2,
        "canSkip": false,
        "isActive": true
      },
      {
        "stepOrder": 2,
        "stepName": "Manager Approval",
        "requiredUserLevelId": 3,
        "canSkip": false,
        "isActive": true
      }
    ],
    "clientApprovalSettings": {
      "requiresApproval": true,
      "autoPublishArticles": false,
      "isActive": true
    }
  }'

Complex Multi-Branch Workflow

curl -X POST "https://api.example.com/approval-workflows/with-client-settings" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Complex Multi-Branch Approval",
    "description": "Complex workflow with parallel branches",
    "isActive": true,
    "isDefault": false,
    "steps": [
      {
        "stepOrder": 1,
        "stepName": "Initial Review",
        "requiredUserLevelId": 2,
        "canSkip": false,
        "isActive": true
      },
      {
        "stepOrder": 2,
        "stepName": "Technical Review",
        "requiredUserLevelId": 4,
        "canSkip": false,
        "isActive": true,
        "parentStepId": 1,
        "conditionType": "user_level",
        "conditionValue": "{\"minLevel\": 4}",
        "isParallel": true,
        "branchName": "technical",
        "branchOrder": 1
      },
      {
        "stepOrder": 2,
        "stepName": "Content Review",
        "requiredUserLevelId": 3,
        "canSkip": false,
        "isActive": true,
        "parentStepId": 1,
        "conditionType": "user_level",
        "conditionValue": "{\"minLevel\": 3}",
        "isParallel": true,
        "branchName": "content",
        "branchOrder": 2
      },
      {
        "stepOrder": 3,
        "stepName": "Final Approval",
        "requiredUserLevelId": 5,
        "canSkip": false,
        "isActive": true
      }
    ],
    "clientApprovalSettings": {
      "requiresApproval": true,
      "autoPublishArticles": false,
      "approvalExemptUsers": [1],
      "approvalExemptRoles": [1],
      "approvalExemptCategories": [1],
      "requireApprovalFor": ["article", "news", "blog"],
      "skipApprovalFor": ["announcement", "update"],
      "isActive": true
    }
  }'

Error Responses

Validation Error

{
  "success": false,
  "messages": ["Validation failed: [\"Workflow name is required\", \"Workflow must have at least one step\"]"],
  "data": null
}

Client Settings Already Exist

{
  "success": false,
  "messages": ["client approval settings already exist for this client"],
  "data": null
}

Authentication Error

{
  "success": false,
  "messages": ["clientId not found in auth token"],
  "data": null
}

Implementation Details

Files Modified/Created

app/module/approval_workflows/request/approval_workflows.request.go - Added comprehensive request structs
app/module/approval_workflows/service/approval_workflows.service.go - Added service method with transaction logic
app/module/approval_workflows/controller/approval_workflows.controller.go - Added controller method
app/module/approval_workflows/approval_workflows.module.go - Added route registration

Dependencies

Client Approval Settings Repository
Approval Workflow Steps Repository
Users Repository
Validation utilities
Response utilities

Transaction Safety

Automatic rollback on any failure
Comprehensive error handling
Detailed logging for debugging
Data consistency guarantees

This comprehensive API endpoint provides a single, atomic way to create complete approval workflows with all necessary dependencies, ensuring data consistency and providing a better developer experience.

9.1 KiB Raw Blame History