# Human-in-the-Loop (HITL) Node

The Human-in-the-Loop (HITL) node in Purple Fabric serves as a critical governance layer within an automated workflow. While AI and programmatic logic handle the bulk of data processing, the HITL node creates a Pause & Review state.

• Primary Objective: To ensure 100% data accuracy by routing uncertain or high-value extractions to a human expert
• Key Value: It bridges the gap between raw machine output and verified business-ready data
• User Behaviour: User needs to build their own UI for using the HITL through webhook

• Node Name: Click the editable label and provide a unique name for the node(e.g., Verify_Data). This is used to identify the step on the canvas and within audit logs.
• Description: A brief explanation of the node’s underlying business rules or logic triggers for better documentation.

The HITL node does not have its own built-in UI for reviewing; instead, it pushes data to an external interface via a Webhook.

• Channel Selection: Choose the destination platform as Webhook
• Webhook URL: Provide the specific endpoint (API address) that accepts the data packet

• HTTP Method:
  • Default: POST
• Authentication:
  • Function: Ensures only our platform can send data to your webhook
  • Options: Select from pre-saved API Keys, Basic Auth (Username/Password), or Bearer Tokens

• Function: Provides metadata to the receiving server
• Common Use Case: Setting Content-Type: application/json or passing a Tenant-ID for multi-client environments

• Dynamic Mapping: Instead of hardcoding values, you can map data dynamically from previous nodes. Click ‘+’ button to select values from the dropdown menu and insert those into your configuration
• Structured JSON Content:
  You can define a structured JSON object to map multiple data points simultaneously. This enables you to combine outputs from various nodes

Once the human clicks Submit in the external tool, the node receives an Answer back.

This field is used so that the other upstream node can select the output field and make use of it. The first field here is the mandatory field i.e Decision and the rest can be configured by clicking on Configure and the user can select the field required.

These fields have to be used by the upstream nodes.

• Field Name: decision

• Data Type: String (Text)
• Valid Values: Only Approved and Rejected
• Function: This field stores the human's choice so that Route nodes later in the flow can decide where to send the data next

• Timeout Duration (Numeric): The amount of time allowed for review (e.g., 48)
• Unit (Selection): Choose between Minutes, Hours, or Days
• Timeout Action (The Contingency):
  • Auto-Reject: If no human responds in durations told, the request is failed (High Security)
  • Auto-Approve: If no human responds, the system assumes the AI's guess was good enough (High Efficiency)
  • Fail Workflow: We stop the workflow/transaction

1. Triggering: The workflow reaches the HITL node because a rule was met or review was needed
2. Dispatch: The system bundles the Request Body and sends it via the Webhook URL
3. Human Interaction: The agent logs into the review portal, sees the extracted_name, and realizes it's misspelled. They fix it
4. Callback: The review portal sends a response back to the HITL node with decision - Approved and the corrected name
5. Resumption: The workflow continues to the next node with the corrected data

When the HITL node is triggered in a workflow, it dispatches a POST request to the configured Webhook URL. This request contains a structured JSON payload, an envelope that carries all the context the external review system needs to present the task to a human reviewer and send back a decision.

Sample Payload

{
  "callback_token": "7e888f54-b376-4c88-a779-9626f1bf389b",
  "callback_url": "https://api.intellectqacloud.com/magicplatform/v1/invokeasset/hitl/resume/7e888f54-b376-4c88-a779-9626f1bf389b",
  "workflow_id": "fa3c9ae9-c2cb-45b8-8898-1d9cbc8e27f0",
  "trace_id": "f07d41da-f6bf-4534-a9a6-2afd39991322",
  "selected_context": {
    "file": {
      "file_name": "image (12).png",
      "file_id": "411301f4-a2c1-4444-adcb-40d21aee151a",
      "mime_type": "image/png",
      "total_pages": 1,
      "normalized_file_name": "image _12_.png",
      "file_size": 203306,
      "field_name": "file",
      "path": "/MagicPlatform/working-storage/idx/f07d41da-f6bf-4534-a9a6-2afd39991322/image (12).png",
      "file_ref_id": "dms-idx-47b66a5c-4582-438b-a51f-f7bc1791031a"
    }
  },
  "expected_output_schema": {
    "decision": {
      "displayname": "Decision",
      "datatype": "string",
      "is_array": false,
      "mandatory": true,
      "description": "Review decision: APPROVED or REJECTED",
      "default_value": null
    }
  },
  "final_context": {
    "decision": "PENDING",
    "file": { ... }
  }
}

This section contains the actual data/file that the human reviewer needs to review. It is mapped from the Request Body configured in the HITL node on the canvas.

Example

"selected_context": {
  "file": {
    "file_name": "image (12).png",
    "file_id": "411301f4-a2c1-4444-adcb-40d21aee151a",
    "mime_type": "image/png",
    "total_pages": 1,
    "normalized_file_name": "image _12_.png",
    "file_size": 203306,
    "field_name": "file",
    "path": "/MagicPlatform/working-storage/idx/...",
    "file_ref_id": "dms-idx-47b66a5c-4582-438b-a51f-f7bc1791031a"
  }
}

This section tells the external system exactly what fields and format it must return when submitting the human's decision.

Example

"expected_output_schema": {
  "decision": {
    "displayname": "Decision",
    "datatype": "string",
    "is_array": false,
    "mandatory": true,
    "description": "Review decision: APPROVED or REJECTED",
    "default_value": null
  }
}

This reflects the live state of the HITL task at the time the payload was dispatched.

Example

"final_context": {
  "decision": "PENDING",
  "file": { ... }
}

Once the human reviewer makes a decision in the external UI, the system must POST back to the callback_url with the callback_token and the decision:

Example

POST https://api.intellectqacloud.com/magicplatform/v1/invokeasset/hitl/resume/7e888f54-b376-4c88-a779-9626f1bf389b

{
  "callback_token": "7e888f54-b376-4c88-a779-9626f1bf389b",
  "decision": "APPROVED"
}

On receiving this, the Purple Fabric resumes the paused workflow and routes it based on the decision value.

When the Purple Fabric platform triggers a Human-in-the-Loop (HITL) node, it sends a webhook payload to an external system for human review. This payload contains file metadata that can be used to download and preview the associated files. This guide covers how to authenticate, construct the download URL, handle different payload structures, and build a working file proxy to bypass browser CORS restrictions.

All API calls to the Purple Fabric platform require a Bearer token. The token is obtained via a dedicated authentication endpoint and must be included in every subsequent request.

GET https://<platform-base-url>/accesstoken/<realm>

Required Headers

Sample Response

{
  "result": "RESULT_SUCCESS",
  "active": true,
  "access_token": "eyJhbGci..."
}

The token is returned under the access_token key. Extract it for subsequent requests.

When a HITL node is triggered, the platform POSTs a JSON payload to your configured webhook URL. The payload always contains the following top-level fields:

Sample Payload

{
  "callback_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "callback_url": "https://<platform>/magicplatform/v1/invokeasset/hitl/resume/<token>",
  "workflow_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "trace_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "selected_context": {
    "file": {
      "file_name": "document.png",
      "file_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mime_type": "image/png",
      "file_size": 203306,
      "total_pages": 1
    }
  },
  "expected_output_schema": {
    "decision": {
      "displayname": "Decision",
      "datatype": "string",
      "mandatory": true,
      "description": "Review decision: APPROVED or REJECTED"
    }
  },
  "final_context": {
    "decision": "PENDING"
  }
}

Files are found inside selected_context. The structure can vary across different workflow configurations:

"selected_context": {
  "file": {
    "file_name": "image.png",
    "file_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "mime_type": "image/png",
    "file_size": 203306
  }
}

"selected_context": {
  "file": [
    {
      "file_name": "Aadhar Card.png",
      "file_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mime_type": "image/png",
      "file_size": 1781316
    },
    {
      "file_name": "Salary Slip.docx",
      "file_id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "file_size": 7471
    }
  ]
}

Once you have the file metadata, construct the download URL using three values from the payload:

GET https://<platform-base-url>/magicplatform/v1/invokeasset/{assetVersionId}/{traceId}/{fileId}/download-stream

Example

{
  "workflow_id": "fa3c9ae9-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "trace_id":    "f07d41da-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "selected_context": {
    "file": {
      "file_id": "411301f4-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }
}

The download URL becomes:

GET https://<platform>/magicplatform/v1/invokeasset/fa3c9ae9-.../f07d41da-.../411301f4-.../download-stream

Required Headers for File Download

Note: Do not include Content-Type: application/json on file download requests as it can interfere with the binary stream response.

After review, POST the decision back to the callback_url from the payload:

POST <callback_url>

Required Headers

Request Body

{
  "decision": "APPROVED"
}

Valid values for decision: APPROVED or REJECTED only.

Success Response

{ "status": "success" }

The Governance module provides a centralized view of all HITL tasks linked to specific transactions. Each task entry functions as an immutable system of record, capturing every detail of the human decision-point for compliance and tracking.

Each task entry acts as a detailed "black box" recording of the human intervention point.

Key Data Points Available:

• Input Snapshot: A read-only view of the exact data payload passed from upstream nodes into the HITL node
• Output Snapshot: Once actioned, this displays the specific data (decisions, comments, metadata) sent back to the workflow engine
• Audit Metadata: Action Taken: The specific resolution chosen
  • Reason: Any justification or comments provided by the reviewer
  • Timestamp: Exact time of creation and completion
  • Actioned By: The identity of the reviewer or system process that resolved the task

Every task must conclude with a specific resolution. This choice dictates the final status of the transaction and the direction of the workflow.

Since Purple Fabric acts as the orchestration layer, external systems interact with these tasks via API.

• Restricted Editing: Only fields explicitly marked as "Editable" during the HITL node configuration can be updated via API.
• Schema Validation: Any inbound data is strictly validated against your pre-defined JSON schema. If the data doesn't match, the update is rejected.
• RBAC Enforcement: The API enforces Role-Based Access Control. Only users or systems with the correct permissions stored in the Secure Vault can submit a resolution.
• Immutability: Once a resolution is submitted (e.g., "Resume" or "Abort"), the task is locked. Resolutions are final and cannot be overwritten.

To help track the impact of human intervention on your automated flows, the Governance dashboard now includes real-time metrics and export capabilities.

The platform automatically computes two key KPIs for every workflow:

• HITL Trigger Rate: The percentage of completed or failed transactions that required at least one human intervention.
• HITL Intensity: The average number of HITL events per transaction. This highlights which workflows are most "human-heavy."

You can now move your governance data into external BI tools (like Tableau or PowerBI) for deeper analysis:

• Flexible Formats: Export transaction summaries and full execution traces as analytics-friendly CSV files.
• Contextual Filtering: The export automatically matches the date range and filters currently set on your transaction screen.
• Secure & Compliant: All exports strictly enforce RBAC (Role-Based Access Control), ensuring users only export data they are authorized to see.