InfraForge Docs

InfraNotes CORE · v1.35.9

Welcome

Select a document from the sidebar to read it.

InfraNotes Approval Workflow System - Frontend Implementation Guide

This guide provides detailed information on how to integrate with the InfraNotes approval workflow system API. It includes all available endpoints, their request/response formats, examples, and integration patterns.

Table of Contents

  1. System Overview
  2. Authentication
  3. Integration Points
  4. Workflow Management
  5. Workflow Steps
  6. Approval Operations
  7. Approval Instance Management
  8. Delegation Management
  9. Frontend Implementation Patterns
  10. Error Handling
  11. Permissions

System Overview

The approval workflow system enables organizations to implement customizable approval processes for invoices and expenses. It provides:

  • Configurable Approval Chains: Multi-step approval workflows with sequential steps
  • Multiple Approver Types: Support for individual users, roles, or team-based approvers
  • Delegation Support: Allow approvers to delegate their responsibility to others
  • Real-time Notifications: Automated notifications for pending approvals and status changes
  • Amount-based Thresholds: Automatic workflow selection based on entity amounts
  • Complete Audit Trail: Full history and tracking of approval processes

Integration Points

The approval workflow system integrates with:

  1. Invoice System: Primary integration with approval status tracking
  2. Expense System: Planned integration for expense approvals
  3. Activity Logging: Tracks all approval-related activities
  4. Notification System: Sends email and in-app notifications
  5. Permission System: Manages approval-related permissions
  6. User Management: Links approvers to users and teams

Authentication

All API endpoints require authentication using JWT Bearer tokens:

Authorization: Bearer your_jwt_token

Integration Points

Invoice Model Extensions

When working with invoices, these additional fields are available:

{
  "id": 123,
  "invoice_number": "INV-2025-001",
  "approval_status": "pending",
  "approval_workflow_id": 4,
  "requires_approval": true,
  "last_approval_action_at": "2025-05-23T16:25:12Z"
}

Approval Status Values

  • not_required: No approval needed
  • pending: Awaiting approval
  • approved: Fully approved
  • rejected: Rejected by an approver
  • canceled: Approval request canceled

Workflow Management

Create Workflow

Endpoint: POST /api/approval/workflows

Purpose: Create a new approval workflow template

Request Body:

{
  "name": "Invoice Approval - Finance",
  "description": "Standard workflow for finance department invoices",
  "entity_type": "invoice",
  "is_active": true,
  "min_amount_threshold": 1000.00,
  "max_amount_threshold": 10000.00,
  "is_default": false
}

Response:

{
  "id": 4,
  "name": "Invoice Approval - Finance",
  "description": "Standard workflow for finance department invoices",
  "is_active": true,
  "user_id": 2,
  "entity_type": "invoice",
  "min_amount_threshold": 1000.00,
  "max_amount_threshold": 10000.00,
  "is_default": false,
  "created_at": "2025-05-23T15:31:00Z",
  "updated_at": "2025-05-23T15:31:00Z"
}

List Workflows

Endpoint: GET /api/approval/workflows

Purpose: Retrieve workflows with filtering and pagination

Query Parameters:

  • entity_type: Filter by entity type (invoice, expense)
  • user_id: Filter by workflow owner
  • team_id: Filter by team
  • is_active: Filter by active status (true, false)
  • is_default: Filter by default status (true, false)
  • limit: Number of records (default: 25)
  • offset: Pagination offset (default: 0)

Example Request:

GET /api/approval/workflows?entity_type=invoice&is_active=true&limit=10

Response:

{
  "data": [
    {
      "id": 4,
      "name": "Invoice Approval - Finance",
      "description": "Standard workflow for finance department invoices",
      "is_active": true,
      "user_id": 2,
      "entity_type": "invoice",
      "min_amount_threshold": 1000.00,
      "max_amount_threshold": 10000.00,
      "is_default": true,
      "created_at": "2025-05-23T15:31:00Z",
      "updated_at": "2025-05-23T16:25:12Z"
    }
  ],
  "meta": {
    "limit": 10,
    "offset": 0,
    "total": 1
  },
  "status": "success"
}

Get Workflow

Endpoint: GET /api/approval/workflows/{id}

Purpose: Get specific workflow with all steps

Response:

{
  "id": 4,
  "name": "Invoice Approval - Finance",
  "description": "Standard workflow for finance department invoices",
  "is_active": true,
  "user_id": 2,
  "entity_type": "invoice",
  "min_amount_threshold": 1000.00,
  "max_amount_threshold": 10000.00,
  "is_default": true,
  "steps": [
    {
      "id": 1,
      "workflow_id": 4,
      "step_order": 1,
      "approver_type": "user",
      "approver_id": 5,
      "name": "Manager Approval",
      "description": "Department manager review",
      "is_required": true,
      "created_at": "2025-05-23T15:32:00Z",
      "updated_at": "2025-05-23T15:32:00Z"
    }
  ],
  "created_at": "2025-05-23T15:31:00Z",
  "updated_at": "2025-05-23T16:25:12Z"
}

Update Workflow

Endpoint: PUT /api/approval/workflows/{id}

Purpose: Update workflow properties

Request Body:

{
  "name": "Updated Invoice Approval Workflow",
  "description": "Updated description",
  "is_active": true,
  "min_amount_threshold": 500.00,
  "max_amount_threshold": 15000.00
}

Response: Updated workflow object with new updated_at timestamp

Delete Workflow

Endpoint: DELETE /api/approval/workflows/{id}

Purpose: Delete workflow and all associated steps

Response: HTTP 204 No Content

Set Default Workflow

Endpoint: PUT /api/approval/workflows/{id}/default

Purpose: Set workflow as default for its entity type

Response:

{
  "message": "Workflow 4 set as default for invoice entities",
  "status": "success"
}

Workflow Steps

Add Workflow Step

Endpoint: POST /api/approval/workflows/{id}/steps

Purpose: Add an approval step to a workflow

Request Body:

{
  "step_order": 1,
  "approver_type": "user",
  "approver_id": 456,
  "name": "Manager Approval",
  "description": "Department manager review",
  "is_required": true
}

Approver Types:

  • user: Individual user approval
  • role: Any user with specific role
  • team: Any user from specific team

Response:

{
  "id": 4,
  "workflow_id": 4,
  "step_order": 1,
  "approver_type": "user",
  "approver_id": 456,
  "name": "Manager Approval",
  "description": "Department manager review",
  "is_required": true,
  "created_at": "2025-05-23T15:32:47Z",
  "updated_at": "2025-05-23T15:32:47Z"
}

Update Workflow Step

Endpoint: PUT /api/approval/workflows/{workflowId}/steps/{stepId}

Purpose: Update existing workflow step

Request Body:

{
  "name": "Updated Manager Approval",
  "description": "Updated description for manager approval",
  "approver_type": "user",
  "approver_id": 456,
  "is_required": true
}

Response: Updated step object

Delete Workflow Step

Endpoint: DELETE /api/approval/workflows/{workflowId}/steps/{stepId}

Purpose: Remove step from workflow

Response: HTTP 204 No Content

Approval Operations

Request Approval

Endpoint: POST /api/approval/request

Purpose: Initiate approval process for an entity

Request Body:

{
  "entity_type": "invoice",
  "entity_id": 789,
  "workflow_id": 123,
  "notes": "Please approve this invoice for project XYZ"
}

Response:

{
  "id": 1,
  "workflow_id": 123,
  "entity_type": "invoice",
  "entity_id": 789,
  "status": "pending",
  "requester_id": 2,
  "requested_at": "2025-05-23T16:30:00Z",
  "current_step_index": 0,
  "notes": "Please approve this invoice for project XYZ",
  "workflow": {
    "id": 123,
    "name": "Invoice Approval - Finance"
  },
  "created_at": "2025-05-23T16:30:00Z",
  "updated_at": "2025-05-23T16:30:00Z"
}

Approve Request

Endpoint: POST /api/approval/instances/{id}/approve

Purpose: Approve a pending approval request

Request Body:

{
  "notes": "Approved - within budget and properly documented"
}

Response:

{
  "message": "Approval processed successfully",
  "status": "success",
  "instance": {
    "id": 1,
    "status": "approved",
    "current_step_index": 1,
    "updated_at": "2025-05-23T16:35:00Z"
  }
}

Reject Request

Endpoint: POST /api/approval/instances/{id}/reject

Purpose: Reject a pending approval request

Request Body:

{
  "notes": "Rejected - missing supporting documentation"
}

Response: Similar to approve response with status "rejected"

Delegate Request

Endpoint: POST /api/approval/instances/{id}/delegate

Purpose: Delegate approval to another user

Request Body:

{
  "delegate_id": 789,
  "notes": "Please review this invoice while I'm on vacation"
}

Response: Updated approval instance with delegation information

Cancel Request

Endpoint: POST /api/approval/instances/{id}/cancel

Purpose: Cancel pending approval request

Request Body:

{
  "notes": "Canceling due to invoice error"
}

Response: Updated approval instance with status "canceled"

Approval Instance Management

List Approval Instances

Endpoint: GET /api/approval/instances

Purpose: Get approval instances with filtering

Query Parameters:

  • entity_type: Filter by entity type (invoice, expense)
  • entity_id: Filter by specific entity ID
  • workflow_id: Filter by workflow ID
  • status: Filter by status (pending, approved, rejected, canceled)
  • requester_id: Filter by requester ID
  • limit: Number of records (default: 25)
  • offset: Pagination offset (default: 0)

Example Request:

GET /api/approval/instances?entity_type=invoice&status=pending&limit=10

Response:

{
  "data": [
    {
      "id": 1,
      "workflow_id": 123,
      "entity_type": "invoice",
      "entity_id": 789,
      "status": "pending",
      "requester_id": 2,
      "requested_at": "2025-05-23T16:30:00Z",
      "current_step_index": 0,
      "notes": "Please approve this invoice for project XYZ",
      "created_at": "2025-05-23T16:30:00Z",
      "updated_at": "2025-05-23T16:30:00Z"
    }
  ],
  "meta": {
    "limit": 10,
    "offset": 0,
    "total": 1
  },
  "status": "success"
}

Get Approval Instance

Endpoint: GET /api/approval/instances/{id}

Purpose: Get specific approval instance details

Response:

{
  "id": 1,
  "workflow_id": 123,
  "entity_type": "invoice",
  "entity_id": 789,
  "status": "pending",
  "requester_id": 2,
  "requested_at": "2025-05-23T16:30:00Z",
  "current_step_index": 0,
  "notes": "Please approve this invoice for project XYZ",
  "workflow": {
    "id": 123,
    "name": "Invoice Approval - Finance",
    "steps": [
      {
        "id": 1,
        "step_order": 1,
        "approver_type": "user",
        "approver_id": 5,
        "name": "Manager Approval"
      }
    ]
  },
  "created_at": "2025-05-23T16:30:00Z",
  "updated_at": "2025-05-23T16:30:00Z"
}

Get Pending Approvals

Endpoint: GET /api/approval/pending

Purpose: Get pending approvals for the current user

Query Parameters:

  • limit: Number of records (default: 25)
  • offset: Pagination offset (default: 0)

Response:

{
  "data": [
    {
      "id": 1,
      "workflow_id": 123,
      "entity_type": "invoice",
      "entity_id": 789,
      "status": "pending",
      "requester_id": 2,
      "requested_at": "2025-05-23T16:30:00Z",
      "current_step_index": 0,
      "notes": "Please approve this invoice for project XYZ"
    }
  ],
  "meta": {
    "limit": 25,
    "offset": 0,
    "total": 1
  },
  "status": "success"
}

Delegation Management

Add Delegate

Endpoint: POST /api/approval/delegates

Purpose: Add approval delegation

Request Body:

{
  "delegate_id": 789,
  "workflow_id": 123,
  "valid_from": "2025-05-23T00:00:00Z",
  "valid_until": "2025-05-30T23:59:59Z"
}

Response: Created delegation record

List Delegates

Endpoint: GET /api/approval/delegates

Purpose: List current user's delegates

Response: Array of delegate records

Remove Delegate

Endpoint: DELETE /api/approval/delegates/{id}

Purpose: Remove delegation

Response: HTTP 204 No Content

Frontend Implementation Patterns

Dashboard Integration

For approval dashboard implementation:

  1. Pending Approvals Widget:

    // Get count of pending approvals
GET /api/approval/pending?limit=1
// Use meta.total for count display

  2. Recent Activity:

    // Get recent approval instances
GET /api/approval/instances?limit=5&requester_id={currentUserId}

  3. Workflow Status Indicators:

    // Display approval status in invoice lists
// Use approval_status field from invoice responses

Invoice Integration

When creating/editing invoices:

  1. Check if Approval Required:

    // Based on invoice amount and available workflows
GET /api/approval/workflows?entity_type=invoice&is_default=true

  2. Request Approval Button:

    // Show when invoice.requires_approval === false
// Hide when invoice.approval_status === 'pending'

  3. Approval Status Display:

    const statusLabels = {
  'not_required': 'No Approval Needed',
  'pending': 'Pending Approval',
  'approved': 'Approved',
  'rejected': 'Rejected',
  'canceled': 'Canceled'
};

Workflow Management UI

For admin workflow configuration:

  1. Workflow Builder:

    • Create workflow form with entity type selection
    • Add/remove/reorder steps interface
    • Set default workflow toggle

  2. Step Configuration:

    • Approver type selection (user/role/team)
    • Approver picker based on type
    • Required/optional step toggle

  3. Workflow Testing:

    • Preview workflow flow
    • Test with sample entities

Error Handling

Common Error Responses

Validation Errors:

{
  "error_code": "validation_failed",
  "message": "Validation errors occurred",
  "details": [
    {
      "field": "name",
      "message": "Name is required"
    },
    {
      "field": "entity_type",
      "message": "Invalid entity type"
    }
  ]
}

Authorization Errors:

{
  "error_code": "insufficient_permissions",
  "message": "You don't have permission to approve this request"
}

Business Logic Errors:

{
  "error_code": "invalid_state",
  "message": "Cannot request approval on inactive workflow"
}

HTTP Status Codes

  • 200: Success with data
  • 201: Created successfully
  • 204: Success with no content
  • 400: Bad request/validation error
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Resource not found
  • 409: Conflict (business rule violation)
  • 500: Internal server error

Permissions

Required Permissions

Workflow Management:

  • approval:workflow:view: View workflows
  • approval:workflow:create: Create workflows
  • approval:workflow:update: Update workflows
  • approval:workflow:delete: Delete workflows
  • approval:workflow:step:manage: Manage workflow steps
  • approval:workflow:set:default: Set default workflows

Approval Operations:

  • invoice:approval:request: Request invoice approval
  • invoice:approval:approve: Approve invoices
  • invoice:approval:reject: Reject invoices
  • invoice:approval:cancel: Cancel approval requests

Delegation:

  • approval:delegate:manage: Manage approval delegates

Viewing:

  • approval:actions:view: View approval actions
  • approval:instances:view: View approval instances

Permission Checking

Frontend should check permissions before showing UI elements:

// Check if user can create workflows
if (user.permissions.includes('approval:workflow:create')) {
  showCreateWorkflowButton();
}

// Check if user can approve
if (user.permissions.includes('invoice:approval:approve')) {
  showApproveButton();
}

Conclusion

This approval workflow system provides a comprehensive foundation for implementing approval processes in your application. The API is designed to be flexible and extensible, supporting various approval scenarios while maintaining security and auditability.

Key implementation considerations:

  • Always check permissions before showing UI elements
  • Implement proper error handling for all states
  • Use real-time updates for approval status changes
  • Provide clear visual indicators for approval states
  • Include comprehensive audit trails for compliance