Workflow Automation Guide

Automate document processing with triggers, steps, and integrations. See Workflows, the Workflows API, and Webhooks for event callbacks. Workflows can be scoped to Knowledge Bases.

Overview

Workflows automate repetitive document tasks. This guide walks through building effective automation.

Building Your First Workflow

Example: Invoice Processing

Goal: When a new PDF is uploaded to the “Invoices” knowledge base, extract data and notify via Slack.

Step 1: Create the Workflow


curl -X POST "/api/workflows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Invoice Auto-Processing",
    "description": "Automatically extract and notify on new invoices",
    "trigger_type": "event",
    "trigger_config": {
      "event": "document.uploaded",
      "filters": {
        "file_type": "pdf",
        "knowledge_base_id": "invoices-kb-uuid"
      }
    },
    "definition": {
      "steps": [
        {
          "id": "extract",
          "type": "extract",
          "config": {
            "schema_id": "invoice-schema"
          }
        },
        {
          "id": "notify",
          "type": "integration",
          "config": {
            "integration_id": "slack-integration-uuid",
            "template": "New invoice {{invoice_number}} for ${{total_amount}} from {{vendor_name}}"
          }
        }
      ]
    },
    "enabled": true
  }'

Step 2: Create the Integration


curl -X POST "/api/workflows/integrations" \
  -d '{
    "name": "Slack Notifications",
    "integration_type": "slack",
    "config": {
      "webhook_url": "https://hooks.slack.com/services/...",
      "channel": "#invoices"
    }
  }'

Step 3: Enable and Test

Upload a test invoice
Check workflow execution logs
Verify Slack notification

Trigger Types

Event Triggers

React to platform events:


{
  "trigger_type": "event",
  "trigger_config": {
    "eventType": "document.uploaded",
    "eventFilters": {
      "file_type": "pdf",
      "file_format": "pdf"
    }
  }
}

For extraction.completed, you can filter by confidence threshold:


{
  "trigger_type": "event",
  "trigger_config": {
    "eventType": "extraction.completed",
    "eventFilters": {
      "confidence_min": 0.8
    }
  }
}

Available events:

document.uploaded — includes document_id, knowledge_base_id, file_type, file_format
document.processed — includes document_id, file_type, file_format, status
extraction.completed — includes document_id, extraction_id, schema_id, confidence

Scheduled Triggers

Run on a schedule:


{
  "trigger_type": "scheduled",
  "trigger_config": {
    "cron": "0 9 * * 1-5",
    "timezone": "America/New_York"
  }
}

Common schedules:

0 9 * * * - Daily at 9 AM
0 9 * * 1-5 - Weekdays at 9 AM
0 0 1 * * - Monthly on the 1st

Webhook Triggers

Trigger from external systems via POST /api/workflows/webhook/{workflow_id}:


{
  "trigger_type": "webhook",
  "trigger_config": {
    "webhookSecret": "optional-validation-secret",
    "webhookPayloadFilters": {
      "type": "invoice",
      "source": "erp"
    }
  }
}

Use X-Webhook-Secret header if webhookSecret is set.
webhookPayloadFilters — only trigger when request body contains matching key-value pairs.

Manual Triggers

Run on-demand:


{
  "trigger_type": "manual"
}

Execute manually:


curl -X POST "/api/workflows/{id}/execute" \
  -d '{"trigger_data": {"document_id": "doc-uuid"}}'

Step Types

Parse Step

Parse documents to extract content:


{
  "id": "parse",
  "type": "parse",
  "config": {
    "agentic": false
  }
}

Extract Step

Extract structured data:


{
  "id": "extract",
  "type": "extract",
  "config": {
    "schema_id": "invoice-schema"
  }
}

Condition Step

Branch based on conditions:


{
  "id": "check_amount",
  "type": "condition",
  "config": {
    "condition": "extraction.total_amount > 10000",
    "true_branch": "high_value_process",
    "false_branch": "standard_process"
  }
}

Transform Step

Transform data:


{
  "id": "calculate_tax",
  "type": "transform",
  "config": {
    "expression": "extraction.subtotal * 0.0875"
  }
}

Integration Step

Send to external service:


{
  "id": "notify",
  "type": "integration",
  "config": {
    "integration_id": "slack-uuid",
    "template": "Processed {{document.name}}"
  }
}

Integrations

Slack


{
  "integration_type": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/...",
    "channel": "#documents"
  }
}

Email


{
  "integration_type": "email",
  "config": {
    "to": "team@company.com",
    "subject": "New Document Processed",
    "template": "Document {{document.name}} has been processed."
  }
}

Webhook


{
  "integration_type": "webhook",
  "config": {
    "url": "https://api.example.com/receive",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer token"
    }
  }
}

Template Variables

Use variables in templates:

Variable	Description
`{{document.name}}`	Document filename
`{{document.id}}`	Document ID
`{{extraction.field}}`	Extracted field
`{{workflow.name}}`	Workflow name
`{{trigger.timestamp}}`	Trigger time

Example:


Invoice {{extraction.invoice_number}}
Vendor: {{extraction.vendor_name}}
Amount: ${{extraction.total_amount}}
Due: {{extraction.due_date}}

Error Handling

Notification on Failure

Add a notification step for failures:


{
  "id": "notify_failure",
  "type": "integration",
  "config": {
    "integration_id": "slack-uuid",
    "template": "Workflow failed for {{document.name}}: {{error.message}}",
    "on_error": true
  }
}

Retry Configuration

Configure automatic retries:


{
  "settings": {
    "retry": {
      "max_attempts": 3,
      "backoff": "exponential"
    }
  }
}

Example Workflows

Contract Review


{
  "name": "Contract Review",
  "trigger_type": "event",
  "trigger_config": {
    "event": "document.uploaded",
    "filters": {"knowledge_base_id": "contracts-kb"}
  },
  "definition": {
    "steps": [
      {
        "id": "extract",
        "type": "extract",
        "config": {"schema_id": "contract-schema"}
      },
      {
        "id": "check_value",
        "type": "condition",
        "config": {
          "condition": "extraction.contract_value > 100000",
          "true_branch": "legal_review",
          "false_branch": "standard_notify"
        }
      },
      {
        "id": "legal_review",
        "type": "integration",
        "config": {
          "integration_id": "email-legal",
          "template": "High-value contract requires review: {{extraction.contract_value}}"
        }
      },
      {
        "id": "standard_notify",
        "type": "integration",
        "config": {
          "integration_id": "slack-contracts",
          "template": "New contract added: {{extraction.party_a}} - {{extraction.party_b}}"
        }
      }
    ]
  }
}

Daily Report


{
  "name": "Daily Processing Report",
  "trigger_type": "scheduled",
  "trigger_config": {
    "cron": "0 18 * * 1-5",
    "timezone": "America/New_York"
  },
  "definition": {
    "steps": [
      {
        "id": "generate_report",
        "type": "generate",
        "config": {
          "template_id": "daily-summary",
          "output_format": "pdf"
        }
      },
      {
        "id": "send_report",
        "type": "integration",
        "config": {
          "integration_id": "email-team",
          "template": "Daily document processing report attached.",
          "attachments": ["{{generate_report.output_url}}"]
        }
      }
    ]
  }
}

Monitoring

Execution Logs

View execution history:


curl -X GET "/api/workflows/{id}/executions"

Execution Details


{
  "id": "execution-uuid",
  "status": "completed",
  "started_at": "2024-01-15T10:00:00Z",
  "completed_at": "2024-01-15T10:00:30Z",
  "execution_log": [
    {
      "step_id": "extract",
      "status": "completed",
      "duration_ms": 5000
    },
    {
      "step_id": "notify",
      "status": "completed",
      "duration_ms": 500
    }
  ]
}

Best Practices

Start simple - Begin with basic workflows
Test thoroughly - Run manual tests first
Add error handling - Notify on failures
Monitor executions - Review logs regularly
Use conditions - Handle edge cases
Document workflows - Keep descriptions clear