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):**
```json
{
  "requestTitle": "...",
  "requestDescription": "...",
  "requestingDepartment": "IT",
  "requestCategory": "PURCHASE_ORDER",
  "approvers": [
    { "email": "...", "tatHours": 24, "level": 1 }
  ]
}
```

**New Simplified Format:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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
```http
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)
```http
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
```http
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
```http
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