Human in The Loop (HITL) Module by FlowMattic

What is Human in The Loop?

Human in The Loop (HITL) is a powerful FlowMattic feature that introduces manual approval steps into automated workflows. This module allows you to pause workflow execution at critical points and wait for human approval or rejection before proceeding. It bridges the gap between full automation and human oversight, ensuring important decisions remain under human control while still benefiting from workflow automation.

Think of HITL as a smart pause button in your workflows that sends approval requests via email, waits for a response, and then continues the workflow based on whether the request was approved or rejected.

Key Features

Core Capabilities

• Email-based Approval Requests: Send beautifully formatted HTML emails with approve/reject buttons
• Time-bound Requests: Set expiration times for approval requests (minutes, hours, or days)
• Smart Timeout Actions: Configure what happens when requests expire
• Round-Robin Assignment: Distribute approval requests evenly among team members
• Request Reassignment: Automatically or manually reassign requests to other approvers
• User Response Messages: Approvers can add optional messages when responding
• Request Tracking: Full audit trail of all approval requests and responses

Visual Status Indicators

The HITL module provides clear visual feedback in the Task History:

• Green checkmark: Request approved

• Yellow hourglass: Waiting for response

• Red hourglass: Request expired/timed out

• Red Exclamation: Request rejected

Getting Started

Step 1: Add HITL to Your Workflow

1. Open your workflow in the FlowMattic editor
2. Click “Add New Step” where you want the approval point
3. Select “Human in the Loop” from the applications list
4. Choose “Get Approval on Email” as the action

Step 2: Basic Configuration

Configure these essential fields:

• Sender Name: The name that appears in the approval email (e.g., “Sales Team”)
• Email Subject: Subject line for the approval email
• Approval Headline: Main heading in the email body
• Approval Message: Detailed message explaining what needs approval
• Assignee Email: Email address of the person who needs to approve

Configuration Options

Timeout Settings

Control how long the workflow waits for approval:

• Max Wait Time: Number value (1-999)
• Timeout Unit: Choose from:
  • Minutes
  • Hours
  • Days

Timeout Actions

Define what happens when a request expires:

1. Skip and Continue (Default)

   • Workflow continues as if approved
   • Status marked as “approved_with_timeout”
   • Useful for non-critical approvals where proceeding is safe

2. End Workflow

   • Stops workflow execution completely
   • Status marked as “timeout_ended”
   • Use for critical approvals that must not proceed without human input

3. Reassign

   • Sends request to a backup approver
   • Specify reassignment email in configuration
   • Maximum 3 reassignment attempts for round-robin, 1 for custom assignee
   • If all reassignment attempts expire, workflow stops

Assignment Types

Custom Assignment

Direct assignment to a specific email address. This is the simplest approach for single approvers.

Assignee Type: Custom
Assignee Email: [email protected]

Round-Robin Assignment

Distributes approval requests evenly among team members:

1. Select “Round Robin” as assignee type
2. Choose a user role (e.g., “Administrator”, “Editor”)
3. Optionally filter by user meta key/value
4. System automatically tracks and assigns to least recently assigned user

Optional Fields

• Email Subject: Custom subject line (defaults to “Approval Requested: [Headline]”)
• Reassign Email: Backup approver for timeout reassignments
• User Meta Filters: For round-robin, filter eligible users by custom meta data

Understanding the Approval Process

The Approval Flow

1. Request Creation

   • Unique request ID generated
   • Request saved to database
   • Approval email sent to assignee

2. Email Receipt

   • Assignee receives HTML email with:
     • Clear approval message
     • Workflow name and sender info
     • Three action buttons: Approve, Reject, View Details
     • Expiration time warning

3. Response Options

   • Approve: Workflow continues with approved status
   • Reject: Workflow stops execution (rejection is logged in task history)
   • View Details: Opens detailed view with optional message field

4. Workflow Behavior

   • If Approved: Workflow continues with approval data
   • If Rejected: Workflow stops, rejection is recorded in task history
   • If Timeout: Behavior depends on timeout action setting:
     • Skip and Continue: Workflow continues
     • End Workflow: Workflow stops
     • Reassign: Request sent to backup approver

The View Details Page

When clicking “View Details”, approvers see:

• Complete request information
• Full approval message
• Option to add a response message
• Approve/Reject buttons
• Request expiration time
• Request history and status

Task History Indicators

The Task History provides visual indicators for HITL status:

Status Icons

• Green Checkmark: Request approved successfully
• Yellow Hourglass: Currently waiting for response
• Red Exclamation: Request was rejected
• Red Hourglass: Request expired without response

Status Details

Each HITL step in Task History shows:

• Current approval status
• Request creation time
• Assignee information
• Expiration time
• Response details (if responded)

Database Cleanup Settings

To maintain optimal performance, FlowMattic includes automatic cleanup for expired HITL requests.

Configuring Cleanup

1. Navigate to FlowMattic > Settings
2. Find the “Human in the Loop” section
3. Configure these options:

Clean Human in the Loop Data?

• Yes: Enable automatic cleanup
• No: Disable cleanup (keeps all data)

Human in the Loop Cleanup (Days)

• Enter number of days (1-365)
• Default: 90 days
• Requests older than this are automatically deleted

How Cleanup Works

• Runs daily via WordPress cron
• Deletes requests where expiration date is older than specified days
• Maintains database performance
• Preserves recent history for auditing

Real-World Examples

Example 1: Purchase Order Approval

Scenario: Automatically approve purchase orders under $500, but require manager approval for higher amounts.

Workflow Setup:

1. Trigger: New purchase order submitted
2. Router: Check if amount > $500
3. If Yes: HITL approval step
4. If Approved: Process order
5. If Rejected: Workflow stops (consider sending rejection notification before HITL step)

HITL Configuration:

Sender Name: Purchasing Department
Approval Headline: Purchase Order Approval Required
Approval Message: 
  Order #{{order_number}}
  Amount: ${{order_amount}}
  Vendor: {{vendor_name}}
  Items: {{item_list}}
  
  Please review and approve this purchase order.
  
Max Wait Time: 24
Timeout Unit: Hours
Timeout Action: Reassign
Assignee Email: {{manager_email}}
Reassign Email: {{finance_director_email}}

Example 2: Content Publishing Approval

Scenario: Blog posts need editorial review before publishing.

Workflow Setup:

1. Trigger: New post created in WordPress
2. HITL: Send to editor for review
3. If Approved: Publish post and notify author
4. If Rejected: Workflow stops (post remains in draft)

HITL Configuration:

Sender Name: Content Team
Approval Headline: New Article Ready for Review
Approval Message:
  Title: {{post_title}}
  Author: {{author_name}}
  Category: {{post_category}}
  Word Count: {{word_count}}
  
  Preview URL: {{preview_link}}
  
  Please review this article for publication.

Assignee Type: Round Robin
User Role: Editor
Max Wait Time: 4
Timeout Unit: Hours
Timeout Action: Skip and Continue

Example 3: Customer Refund Processing

Scenario: Refund requests above $100 need manual approval.

Workflow Setup:

1. Trigger: Refund request form submission
2. Condition: Check refund amount
3. HITL: Manager approval for high-value refunds
4. If Approved: Process refund
5. If Rejected: Workflow stops (no refund processed)

HITL Configuration:

Sender Name: Customer Service
Email Subject: Urgent: Refund Approval Needed
Approval Headline: Customer Refund Request
Approval Message:
  Customer: {{customer_name}}
  Order ID: {{order_id}}
  Refund Amount: ${{refund_amount}}
  Reason: {{refund_reason}}
  
  Customer History:
  - Total Orders: {{total_orders}}
  - Customer Since: {{customer_since}}
  
Max Wait Time: 2
Timeout Unit: Hours
Timeout Action: End Workflow
Assignee Email: {{customer_service_manager}}

Example 4: Employee Leave Approval

Scenario: Vacation requests need manager approval with automatic delegation.

Workflow Setup:

1. Trigger: Leave request form submission
2. HITL: Send to direct manager
3. If Approved: Update HR system and notify employee
4. If Rejected: Workflow stops (consider separate workflow for rejection notifications)

HITL Configuration:

Sender Name: HR System
Approval Headline: Leave Request
Approval Message:
  Employee: {{employee_name}}
  Leave Type: {{leave_type}}
  Start Date: {{start_date}}
  End Date: {{end_date}}
  Days Requested: {{total_days}}
  
  Current Leave Balance: {{leave_balance}}
  Team Coverage: {{coverage_plan}}

Assignee Type: Custom
Assignee Email: {{manager_email}}
Max Wait Time: 48
Timeout Unit: Hours
Timeout Action: Reassign
Reassign Email: {{hr_manager_email}}

Best Practices

1. Clear and Actionable Messages

• Write concise approval headlines
• Include all necessary context in the message
• Use dynamic data to personalize requests
• Highlight critical information

2. Appropriate Timeout Settings

• Urgent requests: 1-4 hours
• Standard approvals: 24-48 hours
• Non-urgent reviews: 3-7 days
• Consider business hours and time zones

3. Smart Timeout Actions

• Use “Skip and Continue” for non-critical approvals
• Use “End Workflow” for compliance-critical decisions
• Use “Reassign” for time-sensitive but important approvals

4. Round-Robin Considerations

• Ensure all users in the role are trained
• Set up user meta filters for specialized approvals
• Monitor distribution for fairness

5. Understanding Workflow Continuation

Important: Workflow behavior depends on the response:

• Approved: Workflow continues to next steps
• Rejected: Workflow stops immediately (no further steps execute)
• Timeout with “Skip and Continue”: Workflow continues
• Timeout with “End Workflow”: Workflow stops
• Timeout with “Reassign”: Waits for new approver

For rejection notifications, consider:

• Setting up a separate workflow triggered by HITL rejection events
• Sending a preliminary notification email before the HITL step
• Using webhooks to notify external systems of rejections

6. Testing Recommendations

• Test with short timeout periods first
• Verify email delivery to all assignees
• Test all three response scenarios
• Check timeout actions work correctly

Troubleshooting

Common Issues and Solutions

Approval emails not received:

• Check spam/junk folders
• Verify email address is correct
• Check WordPress email configuration
• Test with a different email provider

Requests expiring too quickly:

• Review timeout settings
• Consider timezone differences
• Extend timeout period if needed
• Use reassignment for backup

Round-robin not distributing evenly:

• Check user role assignments
• Verify all users are active
• Review user meta filters
• Check last assignment timestamps

Workflow not continuing after approval:

• Verify workflow is still active
• Check for errors in subsequent steps
• Review workflow logs
• Ensure proper error handling

View Details page showing errors:

• Check REST API is accessible
• Verify permalink settings
• Clear cache if using caching plugin
• Check for plugin conflicts

Database Maintenance

For large-scale operations:

• Regular cleanup reduces database size
• Set appropriate retention periods
• Monitor database performance
• Consider archiving old approval data

Advanced Tips

Using Dynamic Data

Leverage FlowMattic’s dynamic data system:

Approval Message: 
  Order from {{customer_name}}
  Total: ${{order_total}}
  Items: {{order_items}}

Conditional Reassignment Logic

For complex reassignment scenarios, use a Router step before HITL:

1. Add Router to check conditions (e.g., amount > 1000)
2. Create separate HITL steps for each condition
3. Configure different assignees based on the condition
   • Route 1: Amount > 1000 → HITL with CFO as assignee
   • Route 2: Amount <= 1000 → HITL with Manager as assignee

This approach gives you full control over conditional approval routing.

Integration with Other Apps

HITL works seamlessly with:

• CRM systems for customer approvals
• Project management for task approvals
• Accounting software for financial approvals
• HR systems for employee requests

Security Considerations

• Approval URLs are unique and unguessable
• Requests expire after set time
• Each request can only be actioned once
• Database entries are automatically cleaned
• No sensitive data in URL parameters

Summary

The Human in The Loop module transforms FlowMattic workflows by adding intelligent approval gates. It ensures critical decisions receive human oversight while maintaining automation efficiency. With flexible timeout options, round-robin assignment, and comprehensive tracking, HITL provides enterprise-grade approval management for businesses of all sizes.

Whether you’re processing purchase orders, reviewing content, or managing employee requests, HITL ensures the right person reviews the right information at the right time, all while keeping your workflows running smoothly.

Need Help?
For additional support or questions about the Human in The Loop module, please contact FlowMattic support or visit our community forums.

Version History

• v5.3.0: Initial release of Human in The Loop module
• Includes email-based approvals, round-robin assignment, and automatic cleanup features