323 lines
9.1 KiB
Markdown
323 lines
9.1 KiB
Markdown
|
# 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**:
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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**:
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": false,
|
||
|
|
"messages": ["Validation failed: [\"Workflow name is required\", \"Workflow must have at least one step\"]"],
|
||
|
|
"data": null
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### Client Settings Already Exist
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": false,
|
||
|
|
"messages": ["client approval settings already exist for this client"],
|
||
|
|
"data": null
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### Authentication Error
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": false,
|
||
|
|
"messages": ["clientId not found in auth token"],
|
||
|
|
"data": null
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Implementation Details
|
||
|
|
|
||
|
|
### Files Modified/Created
|
||
|
|
1. `app/module/approval_workflows/request/approval_workflows.request.go` - Added comprehensive request structs
|
||
|
|
2. `app/module/approval_workflows/service/approval_workflows.service.go` - Added service method with transaction logic
|
||
|
|
3. `app/module/approval_workflows/controller/approval_workflows.controller.go` - Added controller method
|
||
|
|
4. `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.
|