Re_Backend/POSTMAN_COLLECTION_UPDATES.md

Postman Collection Updates - Simplified API

✅ Updated Endpoints

The Postman collection has been updated to use the simplified API format. Here's what changed:

---

1. Create Workflow (JSON) - Simplified ✨

Old Format (REMOVED):

{
  "requestTitle": "...",
  "requestDescription": "...",
  "requestingDepartment": "IT",
  "requestCategory": "PURCHASE_ORDER",
  "approvers": [
    { "email": "...", "tatHours": 24, "level": 1 }
  ]
}

New Simplified Format:

{
  "templateType": "CUSTOM",
  "title": "Purchase Order Approval for Office Equipment",
  "description": "Approval needed for purchasing new office equipment...",
  "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"
    }
  ]
}

What Backend Does Automatically:

• ✅ Finds/creates users from Okta/AD
• ✅ Generates level names from designation/department
• ✅ Auto-detects final approver (last level)
• ✅ Sets proper permissions

---

2. Create Workflow (Multipart with Files) - Simplified ✨

Updated Form Data:

Key	Value
payload	{"templateType":"CUSTOM","title":"...","description":"...","priority":"STANDARD","approvalLevels":[{"email":"manager@royalenfield.com","tatHours":24}],"spectators":[{"email":"hr@royalenfield.com"}]}
files	Select file(s)
category	SUPPORTING (optional)

Changes:

• ❌ Removed: requestTitle, requestDescription, requestingDepartment, requestCategory
• ❌ Removed: Complex approver format with level numbers
• ✅ Added: Single payload field with simplified JSON
• ✅ Simplified: Only email and tatHours per approver

---

3. Add Approver at Level - Simplified 🆕

NEW Endpoint Added!

Method: POST
URL: {{baseUrl}}/workflows/:id/approvers/at-level

Body:

{
  "email": "newapprover@royalenfield.com",
  "tatHours": 24,
  "level": 2
}

What Backend Does:

• ✅ Finds/creates user from Okta/AD
• ✅ Generates smart level name
• ✅ Shifts existing levels if needed
• ✅ Updates final approver flag
• ✅ Sends notifications

---

4. Add Spectator - Simplified 🆕

NEW Endpoint Added!

Method: POST
URL: {{baseUrl}}/workflows/:id/participants/spectator

Body:

{
  "email": "spectator@royalenfield.com"
}

What Backend Does:

• ✅ Finds/creates user from Okta/AD
• ✅ Sets spectator permissions (view + comment)
• ✅ Sends notification

---

📋 Complete Workflow Example

Step 1: Login

POST {{baseUrl}}/auth/login
Content-Type: application/json

{
  "email": "user@royalenfield.com",
  "password": "your-password"
}

Response: Save the token from response

---

Step 2: Create Workflow (Simplified)

POST {{baseUrl}}/workflows
Authorization: Bearer <token>
Content-Type: application/json

{
  "templateType": "CUSTOM",
  "title": "Purchase Order - Office Equipment",
  "description": "Approval for office equipment purchase",
  "priority": "STANDARD",
  "approvalLevels": [
    {
      "email": "manager@royalenfield.com",
      "tatHours": 24
    }
  ]
}

Response: Save the requestId or requestNumber

---

Step 3: Add Additional Approver

POST {{baseUrl}}/workflows/REQ-2024-0001/approvers/at-level
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "director@royalenfield.com",
  "tatHours": 48,
  "level": 2
}

---

Step 4: Add Spectator

POST {{baseUrl}}/workflows/REQ-2024-0001/participants/spectator
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "hr@royalenfield.com"
}

---

🎯 Key Benefits

Before (Old Format):

• ❌ Required user IDs, names manually
• ❌ Complex payload structure
• ❌ Manual level naming
• ❌ Manual final approver detection

After (New Simplified Format):

• ✅ Only email required
• ✅ Simple, clean JSON
• ✅ Auto-generated level names
• ✅ Auto-detected final approver
• ✅ Auto user creation from Okta/AD
• ✅ Clear error messages

---

🔧 Environment Variables

Make sure to set these in Postman:

Variable	Value	Example
baseUrl	Backend API URL	http://localhost:5000/api/v1
token	Auth token from login	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

---

📝 Notes

1. Backward Compatible: The backend still accepts the old format, but the new format is recommended
2. Auto User Creation: If a user exists in Okta/AD but not in the database, they will be created automatically
3. Smart Level Names: Level names are generated from:
   • User's designation (e.g., "Manager Approval")
   • User's department (e.g., "Finance Approval")
   • Fallback: "Level N Approval"
4. Final Approver: Last approval level is automatically marked as final approver
5. Error Messages: Clear, actionable error messages for invalid emails or users not found in AD

---

❓ Troubleshooting

Error: "User not found in organization directory"

• Cause: Email doesn't exist in Okta/AD
• Solution: Verify email address is correct and user has an active account

Error: "Duplicate approver email found"

• Cause: Same email used for multiple approval levels
• Solution: Each approver must have a unique email

Error: "Invalid initiator"

• Cause: Auth token is invalid or user doesn't exist
• Solution: Re-login to get a fresh token

---

🚀 Quick Start

1. Import Collection: Import Royal_Enfield_API_Collection.postman_collection.json into Postman
2. Set Environment: Configure baseUrl and token variables
3. Login: Call the login endpoint to get your token
4. Create Workflow: Use the simplified "Create Workflow (JSON) - Simplified" endpoint
5. Test: Try adding approvers and spectators using the new simplified endpoints

---

Updated: December 2, 2025
Version: 2.0 - Simplified API Format