539 lines
12 KiB
Markdown
539 lines
12 KiB
Markdown
# Simplified Workflow API - Postman Guide
|
|
|
|
## ✅ Updated Simplified Format
|
|
|
|
The API has been updated to make workflow creation much simpler. You now only need to provide **email** and **tatHours** for approvers, and **email** for spectators. The backend automatically handles:
|
|
|
|
- User lookup/creation from Okta/Azure AD
|
|
- Fetching user details (name, department, designation)
|
|
- Auto-generating level names based on designation/department
|
|
- Auto-detecting final approver (last level)
|
|
- Proper validation with clear error messages
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
### Login
|
|
```http
|
|
POST {{baseUrl}}/auth/login
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"email": "your-email@example.com",
|
|
"password": "your-password"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
"user": { "userId": "...", "email": "...", ... }
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Create Workflow - Simplified Format
|
|
|
|
### Example 1: Simple Workflow (JSON)
|
|
|
|
**POST** `{{baseUrl}}/workflows`
|
|
|
|
**Headers:**
|
|
```
|
|
Content-Type: application/json
|
|
Authorization: Bearer <your_token>
|
|
```
|
|
|
|
**Body:**
|
|
```json
|
|
{
|
|
"templateType": "CUSTOM",
|
|
"title": "Purchase Order Approval - Office Equipment",
|
|
"description": "Approval needed for purchasing new office equipment including laptops and monitors. Total budget: $50,000",
|
|
"priority": "STANDARD",
|
|
"approvalLevels": [
|
|
{
|
|
"email": "manager@royalenfield.com",
|
|
"tatHours": 24
|
|
},
|
|
{
|
|
"email": "director@royalenfield.com",
|
|
"tatHours": 48
|
|
},
|
|
{
|
|
"email": "cfo@royalenfield.com",
|
|
"tatHours": 72
|
|
}
|
|
],
|
|
"spectators": [
|
|
{
|
|
"email": "hr@royalenfield.com"
|
|
},
|
|
{
|
|
"email": "finance@royalenfield.com"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Example 2: Express Priority with Final Approver Flag
|
|
|
|
```json
|
|
{
|
|
"templateType": "CUSTOM",
|
|
"title": "Urgent: Server Infrastructure Upgrade",
|
|
"description": "Critical server infrastructure upgrade required immediately",
|
|
"priority": "EXPRESS",
|
|
"approvalLevels": [
|
|
{
|
|
"email": "it-manager@royalenfield.com",
|
|
"tatHours": 8
|
|
},
|
|
{
|
|
"email": "cto@royalenfield.com",
|
|
"tatHours": 16,
|
|
"isFinalApprover": true
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Example 3: With Custom Level Names
|
|
|
|
```json
|
|
{
|
|
"templateType": "CUSTOM",
|
|
"title": "Vendor Contract Approval",
|
|
"description": "New vendor contract for manufacturing components",
|
|
"priority": "STANDARD",
|
|
"approvalLevels": [
|
|
{
|
|
"email": "procurement@royalenfield.com",
|
|
"tatHours": 24,
|
|
"levelName": "Procurement Review"
|
|
},
|
|
{
|
|
"email": "legal@royalenfield.com",
|
|
"tatHours": 48,
|
|
"levelName": "Legal Compliance"
|
|
},
|
|
{
|
|
"email": "vp@royalenfield.com",
|
|
"tatHours": 72,
|
|
"levelName": "Executive Approval",
|
|
"isFinalApprover": true
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Example 4: Multipart with Files
|
|
|
|
**POST** `{{baseUrl}}/workflows/multipart`
|
|
|
|
**Headers:**
|
|
```
|
|
Authorization: Bearer <your_token>
|
|
```
|
|
|
|
**Body (form-data):**
|
|
| Key | Type | Value |
|
|
|-----|------|-------|
|
|
| `payload` | Text | `{"templateType":"CUSTOM","title":"Budget Request 2025","description":"Annual budget request","priority":"STANDARD","approvalLevels":[{"email":"finance-manager@royalenfield.com","tatHours":48},{"email":"cfo@royalenfield.com","tatHours":72}]}` |
|
|
| `files` | File | Select PDF/Excel file(s) |
|
|
| `category` | Text | `SUPPORTING` |
|
|
|
|
---
|
|
|
|
## Field Reference
|
|
|
|
### Required Fields
|
|
|
|
| Field | Type | Description | Example |
|
|
|-------|------|-------------|---------|
|
|
| `templateType` | string | Workflow type | `"CUSTOM"` or `"TEMPLATE"` |
|
|
| `title` | string | Request title (max 500 chars) | `"Purchase Order Approval"` |
|
|
| `description` | string | Detailed description | `"Approval needed for..."` |
|
|
| `priority` | string | Request priority | `"STANDARD"` or `"EXPRESS"` |
|
|
| `approvalLevels` | array | List of approvers (min 1, max 10) | See below |
|
|
|
|
### Approval Level Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `email` | string | ✅ Yes | Approver's email address |
|
|
| `tatHours` | number | ✅ Yes | Turn-around time in hours (positive number) |
|
|
| `isFinalApprover` | boolean | ❌ No | Explicitly mark as final approver (auto-detected if last level) |
|
|
| `levelName` | string | ❌ No | Custom level name (auto-generated if not provided) |
|
|
|
|
**Auto-generated `levelName` logic:**
|
|
- If approver has **designation**: `"{Designation} Approval"` (e.g., "Manager Approval")
|
|
- If approver has **department**: `"{Department} Approval"` (e.g., "Finance Approval")
|
|
- Otherwise: `"Level {N} Approval"` (e.g., "Level 1 Approval")
|
|
|
|
### Spectator Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `email` | string | ✅ Yes | Spectator's email address |
|
|
|
|
---
|
|
|
|
## Validation & Error Handling
|
|
|
|
The backend automatically validates and provides clear error messages:
|
|
|
|
### ✅ Successful Response
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Workflow created successfully",
|
|
"data": {
|
|
"requestId": "uuid",
|
|
"requestNumber": "REQ-2025-12-0001",
|
|
"title": "...",
|
|
"status": "PENDING",
|
|
...
|
|
}
|
|
}
|
|
```
|
|
|
|
### ❌ Error: Invalid Email
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Failed to create workflow",
|
|
"details": "Approver email 'invalid@example.com' not found in organization directory. Please verify the email address."
|
|
}
|
|
```
|
|
|
|
### ❌ Error: Duplicate Email
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Failed to create workflow",
|
|
"details": "Duplicate approver email found: manager@example.com. Each approver must have a unique email."
|
|
}
|
|
```
|
|
|
|
### ❌ Error: Invalid Initiator
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Failed to create workflow",
|
|
"details": "Invalid initiator: User with ID '...' not found. Please ensure you are logged in with a valid account."
|
|
}
|
|
```
|
|
|
|
### ❌ Error: Validation Failed
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Validation failed",
|
|
"details": "approvalLevels.0.email: Valid email is required; approvalLevels.0.tatHours: TAT hours must be positive"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## What Happens Behind the Scenes
|
|
|
|
When you create a workflow, the backend:
|
|
|
|
1. **Validates Initiator**: Ensures the logged-in user exists
|
|
2. **Enriches Approval Levels**:
|
|
- Searches for each approver in the local database
|
|
- If not found, fetches from Okta/Azure AD
|
|
- Creates user record if they exist in AD but not in DB
|
|
- Extracts: `userId`, `displayName`, `designation`, `department`
|
|
- Auto-generates `levelName` if not provided
|
|
- Auto-detects `isFinalApprover` (last level = true)
|
|
3. **Enriches Spectators**:
|
|
- Same lookup/creation process as approvers
|
|
- Sets default permissions (view + comment, no download)
|
|
4. **Creates Workflow**:
|
|
- Saves workflow request
|
|
- Creates approval levels
|
|
- Creates participants
|
|
- Sends notifications
|
|
- Logs activity
|
|
|
|
---
|
|
|
|
## Migration from Old Format
|
|
|
|
### ❌ Old Format (No Longer Required)
|
|
```json
|
|
{
|
|
"approvalLevels": [
|
|
{
|
|
"levelNumber": 1,
|
|
"levelName": "Manager Approval",
|
|
"approverId": "uuid-123",
|
|
"approverEmail": "manager@example.com",
|
|
"approverName": "John Doe",
|
|
"tatHours": 24,
|
|
"isFinalApprover": false
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### ✅ New Simplified Format
|
|
```json
|
|
{
|
|
"approvalLevels": [
|
|
{
|
|
"email": "manager@example.com",
|
|
"tatHours": 24
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**The backend handles everything else automatically!**
|
|
|
|
---
|
|
|
|
## Tips & Best Practices
|
|
|
|
1. **Use Valid Email Addresses**: Ensure all approver/spectator emails exist in your Okta/Azure AD
|
|
2. **TAT Hours**: Set realistic turn-around times based on priority:
|
|
- STANDARD: 24-72 hours per level
|
|
- EXPRESS: 8-24 hours per level
|
|
3. **Final Approver**: Last level is automatically marked as final approver (you can override with `isFinalApprover: true` on any level)
|
|
4. **Level Names**: Let the system auto-generate based on designation/department, or provide custom names
|
|
5. **Spectators**: Add users who need visibility but not approval authority
|
|
6. **Documents**: Use `/multipart` endpoint for file uploads
|
|
|
|
---
|
|
|
|
## Testing in Postman
|
|
|
|
1. **Set Environment Variables**:
|
|
- `baseUrl`: `http://localhost:5000/api/v1`
|
|
- `token`: Your auth token from login
|
|
|
|
2. **Login First**:
|
|
- Call `POST /auth/login`
|
|
- Copy the `token` from response
|
|
- Set as environment variable
|
|
|
|
3. **Create Workflow**:
|
|
- Use simplified format
|
|
- Only provide email + tatHours
|
|
- Backend handles the rest
|
|
|
|
4. **Check Response**:
|
|
- Verify `requestNumber` is generated
|
|
- Check `approvalLevels` are enriched with user data
|
|
- Confirm `participants` includes spectators
|
|
|
|
---
|
|
|
|
## Add Approver/Spectator After Request Creation
|
|
|
|
These endpoints allow adding approvers or spectators to an existing request. They follow the same simplified pattern - just provide email, and the backend handles user lookup/creation.
|
|
|
|
### Add Approver at Specific Level
|
|
|
|
**POST** `{{baseUrl}}/workflows/:requestId/approvers/at-level`
|
|
|
|
**Headers:**
|
|
```
|
|
Authorization: Bearer <your_token>
|
|
Content-Type: application/json
|
|
```
|
|
|
|
**Body:**
|
|
```json
|
|
{
|
|
"email": "newapprover@royalenfield.com",
|
|
"tatHours": 24,
|
|
"level": 2
|
|
}
|
|
```
|
|
|
|
**What Happens:**
|
|
- ✅ Finds user by email in DB, or syncs from Okta/AD if not found
|
|
- ✅ Auto-generates levelName based on designation/department
|
|
- ✅ Shifts existing levels if needed
|
|
- ✅ Updates final approver flag
|
|
- ✅ Sends notification to new approver
|
|
- ✅ Logs activity
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Approver added successfully",
|
|
"data": {
|
|
"levelId": "uuid",
|
|
"levelNumber": 2,
|
|
"levelName": "Manager Approval",
|
|
"approverId": "uuid",
|
|
"approverEmail": "newapprover@royalenfield.com",
|
|
"approverName": "John Doe",
|
|
"tatHours": 24,
|
|
"status": "PENDING"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Add Simple Approver (General)
|
|
|
|
**POST** `{{baseUrl}}/workflows/:requestId/participants/approver`
|
|
|
|
**Headers:**
|
|
```
|
|
Authorization: Bearer <your_token>
|
|
Content-Type: application/json
|
|
```
|
|
|
|
**Body:**
|
|
```json
|
|
{
|
|
"email": "approver@royalenfield.com"
|
|
}
|
|
```
|
|
|
|
*Note: This adds them as a general approver participant, not at a specific level.*
|
|
|
|
---
|
|
|
|
### Add Spectator
|
|
|
|
**POST** `{{baseUrl}}/workflows/:requestId/participants/spectator`
|
|
|
|
**Headers:**
|
|
```
|
|
Authorization: Bearer <your_token>
|
|
Content-Type: application/json
|
|
```
|
|
|
|
**Body:**
|
|
```json
|
|
{
|
|
"email": "spectator@royalenfield.com"
|
|
}
|
|
```
|
|
|
|
**What Happens:**
|
|
- ✅ Finds user by email in DB, or syncs from Okta/AD if not found
|
|
- ✅ Sets spectator permissions (view + comment, no download)
|
|
- ✅ Sends notification to new spectator
|
|
- ✅ Logs activity
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"participantId": "uuid",
|
|
"userId": "uuid",
|
|
"userEmail": "spectator@royalenfield.com",
|
|
"userName": "Jane Doe",
|
|
"participantType": "SPECTATOR",
|
|
"canComment": true,
|
|
"canViewDocuments": true,
|
|
"canDownloadDocuments": false
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Error Handling for Add Operations
|
|
|
|
**❌ User Not Found in AD:**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Failed to add approver",
|
|
"details": "Approver email 'invalid@example.com' not found in organization directory. Please verify the email address."
|
|
}
|
|
```
|
|
|
|
**❌ User Already a Participant:**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Failed to add spectator",
|
|
"details": "User is already a participant in this request"
|
|
}
|
|
```
|
|
|
|
**❌ Invalid Level:**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Failed to add approver at level",
|
|
"details": "Cannot add approver at level 1 - level has already been completed"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Complete Flow Example
|
|
|
|
### 1. Login
|
|
```bash
|
|
POST /api/v1/auth/login
|
|
Body: { "email": "user@example.com", "password": "pass" }
|
|
```
|
|
|
|
### 2. Create Workflow (Simplified)
|
|
```bash
|
|
POST /api/v1/workflows
|
|
Body: {
|
|
"templateType": "CUSTOM",
|
|
"title": "Purchase Order",
|
|
"description": "Office equipment",
|
|
"priority": "STANDARD",
|
|
"approvalLevels": [
|
|
{ "email": "manager@example.com", "tatHours": 24 }
|
|
]
|
|
}
|
|
```
|
|
|
|
### 3. Add Additional Approver (After Creation)
|
|
```bash
|
|
POST /api/v1/workflows/:requestId/approvers/at-level
|
|
Body: {
|
|
"email": "director@example.com",
|
|
"tatHours": 48,
|
|
"level": 2
|
|
}
|
|
```
|
|
|
|
### 4. Add Spectator
|
|
```bash
|
|
POST /api/v1/workflows/:requestId/participants/spectator
|
|
Body: { "email": "hr@example.com" }
|
|
```
|
|
|
|
---
|
|
|
|
## Need Help?
|
|
|
|
If you encounter any issues:
|
|
1. Check the error message - it will tell you exactly what's wrong
|
|
2. Verify emails exist in your organization directory
|
|
3. Ensure you're logged in with a valid token
|
|
4. Check backend logs for detailed error information
|
|
|