laxmanhalaki/Re_Backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
17485a9cca
Re_Backend/API_SIMPLIFIED_FORMAT.md

12 KiB
Raw Blame History

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

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

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

Response:

{
  "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:

{
  "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

{
  "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

{
  "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

{
  "success": true,
  "message": "Workflow created successfully",
  "data": {
    "requestId": "uuid",
    "requestNumber": "REQ-2025-12-0001",
    "title": "...",
    "status": "PENDING",
    ...
  }
}

❌ Error: Invalid Email

{
  "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

{
  "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

{
  "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

{
  "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)

{
  "approvalLevels": [
    {
      "levelNumber": 1,
      "levelName": "Manager Approval",
      "approverId": "uuid-123",
      "approverEmail": "manager@example.com",
      "approverName": "John Doe",
      "tatHours": 24,
      "isFinalApprover": false
    }
  ]
}

✅ New Simplified Format

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "success": false,
  "error": "Failed to add spectator",
  "details": "User is already a participant in this request"
}

❌ Invalid Level:

{
  "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

POST /api/v1/auth/login
Body: { "email": "user@example.com", "password": "pass" }

2. Create Workflow (Simplified)

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)

POST /api/v1/workflows/:requestId/approvers/at-level
Body: {
  "email": "director@example.com",
  "tatHours": 48,
  "level": 2
}

4. Add Spectator

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