Human in the Loop

Overview

The Human in the Loop node enables you to pause workflow execution and request human intervention at critical decision points. This node is essential when you need human judgment, approval, or additional data that automated systems cannot provide.

When your workflow reaches this node, it pauses and sends a custom form to designated users via email or other channels. Once the user completes and submits the form, the workflow automatically resumes with the submitted data available for use in downstream nodes.

Why Use the Human in the Loop Node?

Bridge Automation with Human Intelligence Not every decision can or should be automated. The Human in the Loop node intelligently pauses workflows when human expertise, judgment, or approval is required, ensuring critical decisions receive proper oversight.

Customizable Data Collection Create dynamic forms with 7 different field types, validation rules, and conditional logic to collect exactly the data you need. Forms are delivered directly to assignees with full workflow context.

Automated Follow-ups Configure automatic reminders and escalation paths to ensure timely responses. Set timeout periods, reminder intervals, and escalation assignees to prevent bottlenecks in your workflows.

Multi-Channel Delivery Send task notifications via Email, WhatsApp, Slack, Microsoft Teams, or custom webhooks. Choose the channel that works best for your team's communication style.

How It Works

1. Workflow Pauses: When execution reaches the Human in the Loop node, the workflow pauses and enters a waiting state
2. Task Created: A unique task is generated with a secure access token and form URL
3. Notification Sent: The designated assignee receives a notification via their chosen channel containing the task details and form link
4. User Completes Form: The assignee opens the form, reviews context data, and fills out the required fields
5. Workflow Resumes: Upon form submission, the workflow automatically resumes with the submitted data available in the node's output
6. Downstream Processing: Subsequent nodes can access form responses to make decisions, route data, or trigger actions

When to Use This Node

• Approval Workflows: Purchase orders, expense reports, leave requests, or content publishing requiring managerial sign-off
• Quality Assurance: Human review of AI-generated content, data validation, or accuracy verification before proceeding
• Exception Handling: Flag unusual transactions, errors, or edge cases for manual investigation and resolution
• Compliance Reviews: Legal approval, regulatory compliance checks, or audit trail documentation
• Data Enrichment: Collect additional information that automated systems cannot obtain, such as customer feedback or clarifications
• Customer Service Escalation: Route complex issues to human agents with full context and structured response capture

Configuration Steps

Step 1: Task Information

Configure the basic details that appear in notifications and task interfaces.

Task Title

• Short, descriptive title shown in task lists and email notifications
• Supports dynamic expressions to include workflow data
• Example: Approve Purchase Order #{{workflow.order_id}}

Task Description

• Detailed explanation of what the assignee needs to do
• Provides context, instructions, or background information
• Supports markdown formatting for better readability

Assigned To

• Email address or identifier of the person who should receive this task
• Supports expressions for dynamic assignment: {{workflow.manager_email}}
• Can reference outputs from previous nodes: {{previous_node.approver}}

Assignment Type Select the notification channel for task delivery:

• Email: ✅ Send task link via email (Available)
• WhatsApp: 🔜 WhatsApp notification (Coming Soon)
• Slack: 🔜 Slack channel or DM (Coming Soon)
• Microsoft Teams: 🔜 Teams chat (Coming Soon)
• Webhook: 🔜 POST to custom URL (Coming Soon)

Step 2: Timeout & Reminders

Configure automatic follow-ups to ensure timely responses.

Timeout Hours (1-168 hours)

• Maximum time allowed for task completion
• Default: 24 hours
• After timeout expires, escalation rules are triggered (if configured)
• Countdown timer displayed on the task form

Reminder Count (0-10)

• Number of automatic reminder notifications to send
• Default: 2 reminders
• Reminders are distributed evenly across the timeout period
• Example: 24-hour timeout with 2 reminders sends notifications at 8h and 16h

Escalation Configuration Define what happens when tasks timeout without completion:

• Escalation Email: Email address to notify when the original assignee times out (typically a manager or team lead)
• Escalation Timeout: Additional time given to the escalation assignee (1-168 hours, default: 48)
• Escalation Reminder Count: Number of reminders for the escalation assignee (0-10, default: 1)

Step 3: Form Builder

Design custom forms to collect the exact data you need from users.

Form Title

• Main heading displayed at the top of the form
• Example: "Purchase Order Approval Form"

Form Description

• Optional detailed instructions or context
• Appears below the form title

Available Field Types

Field Configuration

For each form field, configure:

• Field Name: Internal identifier (use snake_case like approval_decision)
• Label: Display text shown to users
• Field Type: Select from the 7 available types
• Placeholder: Hint text shown in empty fields
• Required Field: Toggle to make field mandatory
• Validation Rules: Type-specific rules (min/max length, value ranges, etc.)

Select Field Options

When using dropdowns, configure the available choices:

• Option Label: User-facing text (e.g., "Approved", "Rejected")
• Option Value: Internal value stored in workflow (e.g., "approved", "rejected")

Step 4: Context Data

Provide relevant workflow information to help assignees make informed decisions.

Context data is displayed as key-value pairs at the top of the task form, before the input fields. This gives users the background information they need without requiring them to input it.

Adding Context Items

• Context Key: Label for the information (e.g., "Customer Name", "Order Total")
• Context Value: The actual data, can be static text or dynamic expressions
  • Static: "High Priority"
  • Dynamic: {{workflow.customer_name}}
  • Formatted: ${{workflow.order_total}}

Expression Examples

Key: Order ID
Value: {{workflow.order_id}}

Key: Customer Name
Value: {{workflow.customer.full_name}}

Key: Total Amount
Value: ${{workflow.order_total}}

Key: Request Date
Value: {{workflow.created_at}}

Step 5: Preview & Test

Live Form Preview The Preview tab shows exactly how your form will appear to task assignees:

• Real-time updates as you modify fields
• Full visual styling matching the production form
• Mock task information (Task ID, Workflow ID, Priority, Due Date)
• Context data display with proper formatting
• All field types rendered with correct controls

Test Execution Create real tasks to test the complete end-to-end flow:

1. Click "Execute Test" button
2. System creates a real task with a unique Task ID
3. Form URL is generated and displayed
4. Email notification sent to the assigned email
5. Open the form URL to test the user experience
6. Submit the form and verify data appears in node outputs

Test Results Display

• Task ID: Unique identifier for the test task
• Form URL: Direct link to open the form
• Access Token: Security token for authentication
• Status: Real-time task status (pending, in_progress, completed, expired)
• Created At: Timestamp of task creation

Advanced Features

Expression Mode for Schema

Instead of building forms manually, use expressions to generate form schemas dynamically at runtime.

When to Use:

• Forms that vary based on workflow conditions
• Schemas stored in databases or external systems
• Complex conditional field logic
• A/B testing different form layouts

Example Expression:

{
  title: "Dynamic Approval Form",
  description: `Approval for ${workflow.request_type}`,
  fields: {
    decision: {
      name: "decision",
      type: "select",
      label: "Decision",
      required: true,
      options: [
        { value: "approve", label: "Approve" },
        { value: "reject", label: "Reject" }
      ]
    },
    comments: {
      name: "comments",
      type: "textarea",
      label: "Comments",
      required: false
    }
  }
}

Template Management

Save time and ensure consistency by creating reusable form templates.

Saving Templates:

1. Configure your form fields and validation rules
2. Click "Save as Template"
3. Enter template name and description
4. Choose visibility: Private (only you) or Public (team-wide)
5. Click "Save Template"

Importing Templates:

1. Click "Import Template"
2. Search for templates by name or description
3. Preview template fields before importing
4. Select template and click "Import"
5. Imported fields are added to your current configuration

Output Data

When a task is completed, the node outputs structured data for use in downstream nodes.

Output Schema Example:

{
  "task_id": "TASK-2024-12345",
  "status": "completed",
  "submitted_at": "2024-01-15T14:30:00Z",
  "submitted_by": "user@example.com",

  // Your form field outputs
  "approval_decision": "approved",
  "comments": "Budget approved for Q1 initiative",
  "approved_amount": 15000,
  "completion_date": "2024-02-01",

  // Metadata
  "completion_time_hours": 2.5,
  "reminder_count_sent": 1,
  "escalated": false
}

Using Output Data:

// Check approval decision
{{human_in_the_loop.approval_decision}} === "approved"

// Use in conditional routing
if ({{human_in_the_loop.approval_decision}} === "approved") {
  // Route to approval branch
} else {
  // Route to rejection branch
}

// Reference in text
The request was {{human_in_the_loop.approval_decision}}

Common Use Cases

Purchase Order Approval

Scenario: Purchase orders over $5,000 require manager approval before processing.

Configuration:

• Task Title: "Approve Purchase Order #{{workflow.po_number}}"
• Assigned To: {{workflow.approver_email}}
• Timeout: 48 hours with 2 reminders
• Form Fields: Decision (Select), Comments (Textarea), Approved Amount (Number), Budget Code (Text)
• Context Data: PO Number, Vendor, Requested Amount, Requestor, Department

Workflow Flow:

1. Workflow triggers when PO is created
2. If amount > $5000, route to Human in the Loop node
3. Manager receives email with form link
4. Upon approval, workflow continues to payment processing
5. Upon rejection, workflow sends rejection notice to requestor

Content Moderation

Scenario: AI flags potentially inappropriate user-generated content for human review.

Configuration:

• Task Title: "Content Moderation Review"
• Timeout: 4 hours with 3 reminders
• Form Fields: Moderation Decision (Select), Violation Type (Select), Moderator Notes (Textarea), User Warning (Checkbox)
• Context Data: Content ID, User, AI Confidence Score, Flag Reason, Content Preview

Workflow Flow:

1. AI content filter flags suspicious content
2. Human in the Loop node pauses for human review
3. Moderator reviews context and makes decision
4. Based on decision, workflow either publishes, removes, requests edits, or escalates

Exception Handling

Scenario: Orders with inventory mismatches require warehouse manager intervention.

Configuration:

• Task Title: "Resolve Inventory Mismatch - Order {{workflow.order_id}}"
• Assigned To: warehouse_manager@company.com
• Timeout: 2 hours with escalation to inventory director
• Form Fields: Resolution (Select), Actual Quantity (Number), Root Cause (Select), Action Notes (Textarea)
• Context Data: Order ID, Product, System Qty, Physical Qty, Customer, Priority

Workflow Flow:

1. Inventory check finds mismatch
2. Human in the Loop node pauses order processing
3. Warehouse manager investigates and provides resolution
4. Workflow continues based on resolution (update inventory, cancel order, partial fulfillment, or hold)

Best Practices

Form Design

• Keep forms simple - only request essential information
• Use appropriate field types for the data being collected
• Provide clear labels and help text to guide users
• Test forms before deploying to production
• Order fields logically with most important items first

Timeout Configuration

• Set realistic timeouts considering business hours and time zones
• Add 20-30% buffer to expected response times
• Use 2-8 hours for urgent approvals, 24-72 hours for routine reviews
• Always configure escalation for critical workflows
• Consider weekend coverage when setting timeouts

Assignment Strategy

• Use dynamic expressions to route to the right person based on context
• Configure fallback assignees through escalation settings
• Balance workload by rotating assignments among team members
• Assign complex decisions to senior staff, routine tasks to juniors

Context Data

• Include all information needed for informed decision-making
• Format values appropriately (currencies, dates, percentages)
• Order context items by importance
• Avoid overwhelming users with too much information
• Use clear, non-technical labels

Troubleshooting

Security Considerations

Task Authentication

• All task forms require secure access tokens
• Tokens expire after the configured timeout period
• One-time use: forms cannot be resubmitted after completion
• Unique tokens per task prevent unauthorized access

Data Privacy

• Task data encrypted in transit and at rest
• Form submissions logged with full audit trail
• Assignee identity verified via authentication channel
• Sensitive fields should use appropriate protection

Access Control

• Only assigned users can access task forms
• Escalation assignees receive new unique tokens
• Workflow owners can view task status but cannot modify submissions
• Templates respect environment and tenant permissions

Related Nodes

• Router Node - Use for conditional branching based on approval decisions
• HTTP Request - Send custom notifications or webhook calls after form submission
• Loop Node - Process approved data in batch operations
• Set Data - Transform and map form output data for downstream use