Triggers and execution

Trigger types

Workflows are initiated by triggers. MagOneAI supports multiple trigger types to fit different use cases and integration patterns.

API trigger

Start workflows via REST API call. Pass input data as JSON. Ideal for system-to-system integration and programmatic workflow execution. How it works:

Configure API trigger

Enable API trigger in workflow settings. MagOneAI generates a unique API endpoint and authentication token.

Make API call

Your system makes a POST request to the workflow endpoint with input data:

curl -X POST https://api.magone.ai/v1/workflows/{workflow_id}/trigger \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "CUST-12345",
    "document_url": "https://bucket.s3.com/document.pdf",
    "urgency": "high"
  }'

Workflow starts

The workflow execution begins immediately with the provided input data available as {{trigger.input}}.

Response returned

The API returns a workflow execution ID for tracking:

{
  "execution_id": "exec_abc123",
  "status": "running",
  "started_at": "2024-01-15T10:30:00Z"
}

Use cases:

Document processing

Trigger when documents are uploaded to your system

Event-driven automation

Respond to business events (new customer, transaction, support ticket)

Webhook handlers

Process webhooks from external services

Batch processing

Trigger individual workflow executions for each item in a batch

API trigger configuration:

{
  "trigger_type": "api",
  "authentication": {
    "type": "bearer_token",
    "token": "generated_automatically"
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": {"type": "string", "required": true},
      "document_url": {"type": "string", "required": true},
      "urgency": {"type": "string", "enum": ["low", "normal", "high"]}
    }
  },
  "rate_limiting": {
    "max_requests_per_minute": 100
  }
}

Schedule trigger

Run workflows on a cron schedule. Perfect for periodic tasks, reports, and maintenance operations. How it works:

Configure schedule

Define a cron expression for when the workflow should run:

# Every day at 9:00 AM UTC
0 9 * * *

# Every Monday at 8:00 AM UTC
0 8 * * 1

# Every hour
0 * * * *

# First day of every month at midnight
0 0 1 * *

Schedule activates

MagOneAI’s scheduler monitors the cron expression and triggers the workflow at the specified times.

Workflow executes

The workflow runs with optional static input data or with dynamically fetched data.

Use cases:

Daily reports

Generate and send daily summary reports

Periodic compliance checks

Run compliance audits on a schedule

Data synchronization

Sync data between systems periodically

Cleanup and maintenance

Archive old data, clean up temporary files

Schedule trigger configuration:

{
  "trigger_type": "schedule",
  "cron_expression": "0 9 * * *",
  "timezone": "Asia/Dubai",
  "input_data": {
    "report_type": "daily_summary",
    "recipients": ["[email protected]"]
  },
  "enabled": true
}

Common cron patterns:

Daily
Weekly
Monthly
Hourly/Frequent

# Every day at 9:00 AM
0 9 * * *

# Every day at midnight
0 0 * * *

# Every day at 2:30 PM
30 14 * * *

# Every Monday at 9:00 AM
0 9 * * 1

# Every Friday at 5:00 PM
0 17 * * 5

# Every Sunday at midnight
0 0 * * 0

# First day of month at 9:00 AM
0 9 1 * *

# Last day of month at 11:59 PM
59 23 L * *

# 15th of each month at noon
0 12 15 * *

# Every hour
0 * * * *

# Every 15 minutes
*/15 * * * *

# Every 6 hours
0 */6 * * *

Manual trigger

Start workflows manually from MagOneAI Studio. For testing, ad-hoc execution, and human-initiated processes. How it works:

Open workflow in Studio

Navigate to the workflow in MagOneAI Studio.

Click 'Run'

Click the “Run Workflow” button in the UI.

Provide input (optional)

Enter input data in a form or JSON editor:

{
  "customer_id": "CUST-12345",
  "document_url": "https://example.com/test-doc.pdf"
}

Workflow executes

The workflow runs immediately with real-time progress visibility in Studio.

Use cases:

Testing

Test workflows during development with sample data

Debugging

Run workflows with specific inputs to debug issues

Ad-hoc processing

Process individual cases manually as needed

Demo and training

Demonstrate workflow capabilities to stakeholders

Chat trigger

Start workflows from MagOneAI Hub conversation. Natural language initiates workflow execution. How it works:

User message in Hub

User types a message in MagOneAI Hub: “Please analyze the Q4 financial report and send me a summary”

Intent detection

MagOneAI Hub’s AI understands the intent and identifies the appropriate workflow to execute.

Extract parameters

The AI extracts parameters from the natural language request:

{
  "report_type": "financial",
  "period": "Q4",
  "action": "analyze_and_summarize"
}

Workflow executes

The workflow runs with the extracted parameters as input.

Results returned to chat

When the workflow completes, results are displayed in the chat conversation.

Use cases:

Employee self-service

Employees trigger workflows through conversation

Customer support

Support agents trigger workflows during customer interactions

Data retrieval

Natural language queries trigger data fetch workflows

Approvals

Approve or reject workflows through chat commands

Chat trigger configuration:

{
  "trigger_type": "chat",
  "activation_phrases": [
    "analyze report",
    "process document",
    "generate summary"
  ],
  "parameter_extraction": {
    "report_type": {
      "type": "string",
      "extraction": "entity_recognition"
    },
    "period": {
      "type": "string",
      "extraction": "date_parsing"
    }
  },
  "confirmation_required": true
}

Execution monitoring

Track workflow execution in real-time with comprehensive observability.

Real-time status tracking

Monitor running workflows with live updates:

Execution status

Current state: Running, Completed, Failed, Waiting for Human Input

Current activity

Which node is currently executing in the workflow

Progress indicator

Percentage complete based on total activities

Duration

Elapsed time since workflow started

Activity-level progress

See detailed progress for each activity in the workflow: Visual workflow canvas:

[✓] Extract Document (completed - 12s)
  ↓
[✓] Compliance Check (completed - 8s)
  ↓
[⟳] Risk Assessment (running - 5s elapsed)
  ↓
[ ] Human Review (pending)
  ↓
[ ] Send Notification (pending)

Activity states:

Pending — Not yet started
Running — Currently executing
Completed — Successfully finished
Failed — Execution failed
Skipped — Skipped due to conditional logic
Waiting — Paused (e.g., waiting for human input)

Success/failure status

Track success and failure at both workflow and activity levels: Workflow-level status:

Success — All activities completed successfully
Partial Success — Some activities failed but workflow completed
Failed — Critical activity failed, workflow terminated
Timed Out — Workflow exceeded maximum execution time

Activity-level status:

{
  "activity_name": "compliance_check",
  "status": "completed",
  "success": true,
  "execution_time_ms": 8234,
  "attempts": 1,
  "output": {...}
}

Execution duration and timing

Detailed timing information for performance optimization: Overall timing:

{
  "workflow_execution_id": "exec_abc123",
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:32:45Z",
  "total_duration_ms": 165000,
  "activities_duration_ms": 142000,
  "overhead_ms": 23000
}

Per-activity timing:

{
  "activities": [
    {
      "name": "document_extractor",
      "duration_ms": 12234,
      "started_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:30:12Z"
    },
    {
      "name": "compliance_check",
      "duration_ms": 8456,
      "started_at": "2024-01-15T10:30:12Z",
      "completed_at": "2024-01-15T10:30:20Z"
    }
  ]
}

Performance insights:

Identify slow activities
Detect bottlenecks
Optimize expensive operations
Track improvements over time

Retry policies

Configure how the system handles activity and workflow failures.

Activity-level retries

Configure retries for individual activities:

{
  "activity": "document_extractor",
  "retry_policy": {
    "max_attempts": 3,
    "initial_interval": "5s",
    "backoff": "exponential",
    "max_interval": "60s",
    "retry_on": ["timeout", "rate_limit", "server_error"]
  }
}

Retry parameters:

max_attempts — Total attempts including the initial one (e.g., 3 = 1 initial + 2 retries)
initial_interval — Delay before first retry
backoff — Strategy for increasing delay: fixed, linear, exponential
max_interval — Maximum delay between retries
retry_on — Which error types trigger retries

Backoff strategies

Different strategies for delay between retries:

Fixed
Linear
Exponential

Same delay between all retries.

Attempt 1: Fail
Wait 5s
Attempt 2: Fail
Wait 5s
Attempt 3: Fail
Give up

Use for: Operations with consistent retry needs

Delay increases linearly.

Attempt 1: Fail
Wait 5s
Attempt 2: Fail
Wait 10s
Attempt 3: Fail
Wait 15s
Attempt 4: Fail
Give up

Use for: Gradual backoff when system might recover

Delay doubles each time.

Attempt 1: Fail
Wait 5s
Attempt 2: Fail
Wait 10s
Attempt 3: Fail
Wait 20s
Attempt 4: Fail
Wait 40s (capped at max_interval)
Give up

Use for: API rate limits, transient failures

Retry on error types

Specify which errors should trigger retries:

{
  "retry_on": [
    "timeout",           // Operation timed out
    "rate_limit",        // API rate limit hit
    "server_error",      // 5xx server errors
    "network_error",     // Network connectivity issues
    "temporary_failure"  // Transient errors
  ],
  "do_not_retry_on": [
    "invalid_input",     // Bad request data
    "authentication",    // Auth failures
    "not_found",         // Resource doesn't exist
    "permission_denied"  // Access denied
  ]
}

Workflow-level retry

Retry entire workflows on failure:

{
  "workflow_retry_policy": {
    "enabled": true,
    "max_attempts": 2,
    "retry_delay": "5m",
    "retry_on_activity_failure": ["critical_activity_1", "critical_activity_2"]
  }
}

Error handling

Comprehensive error handling ensures workflows fail gracefully.

Activity-level error handling

Handle errors at the activity level: Fallback activities:

Activity: "Primary API Call"
├─ Success: Continue workflow
└─ Failure:
    → Fallback Activity: "Alternative API Call"
    ├─ Success: Continue workflow
    └─ Failure:
        → Fallback Activity: "Manual Queue"

Error capture:

{
  "activity": "document_extractor",
  "on_error": {
    "capture_error": true,
    "continue_workflow": true,
    "set_variables": {
      "extraction_failed": true,
      "error_message": "{{error.message}}"
    }
  }
}

Error propagation

Control whether errors stop the workflow or allow continuation: Stop on error (default):

Activity fails → Workflow stops → Status: Failed

Continue on error:

Activity fails → Error captured → Workflow continues

Conditional continuation:

Activity fails → Check error type
├─ Retryable error: Retry
├─ Critical error: Stop workflow
└─ Non-critical error: Continue with fallback

Workflow failure

When a workflow fails:

Failure captured

The failure reason, failed activity, and error details are recorded.

Execution stops

No further activities execute (unless error handling specifies otherwise).

Status updated

Workflow status set to “Failed” with failure reason.

Notifications sent

Alert notifications sent to configured recipients.

Manual retry available

Users can manually retry from the failed activity or from the beginning.

Manual retry of failed executions

Retry failed workflow executions: Retry from beginning:

Failed execution → Click "Retry" → New execution starts from trigger

Retry from failed activity:

Failed execution → Click "Resume" → Execution continues from failed activity

Retry with modified input:

Failed execution → Click "Retry with changes" → Modify input → New execution

Execution history

View comprehensive history of all workflow executions.

Past executions

Access complete execution history: Execution list:

┌─────────────┬─────────────────────┬──────────┬──────────┬───────────┐
│ Execution   │ Started At          │ Status   │ Duration │ Triggered │
├─────────────┼─────────────────────┼──────────┼──────────┼───────────┤
│ exec_001    │ 2024-01-15 10:30:00 │ Success  │ 2m 45s   │ API       │
│ exec_002    │ 2024-01-15 11:00:00 │ Failed   │ 1m 12s   │ Schedule  │
│ exec_003    │ 2024-01-15 11:30:00 │ Running  │ 45s      │ Manual    │
│ exec_004    │ 2024-01-15 12:00:00 │ Success  │ 3m 20s   │ API       │
└─────────────┴─────────────────────┴──────────┴──────────┴───────────┘

Filtering and search

Filter execution history by various criteria: Filter by status:

Status: [Completed] [Failed] [Running] [Waiting]

Filter by date range:

Date: Last 7 days | Last 30 days | Custom range

Filter by trigger type:

Trigger: [All] [API] [Schedule] [Manual] [Chat]

Search:

Search: execution_id, input data, customer_id

Drill into individual executions

Detailed view of any execution: Execution overview:

{
  "execution_id": "exec_abc123",
  "workflow_name": "Document Processing",
  "workflow_version": "v2.3",
  "status": "completed",
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:32:45Z",
  "duration_ms": 165000,
  "triggered_by": "api",
  "trigger_source": "document_upload_service"
}

Activity-level logs:

[10:30:00] Workflow started
[10:30:00] Activity: document_extractor - Started
[10:30:12] Activity: document_extractor - Completed (12.2s)
[10:30:12] Activity: compliance_check - Started
[10:30:20] Activity: compliance_check - Completed (8.4s)
[10:30:20] Activity: risk_assessment - Started
[10:31:05] Activity: risk_assessment - Completed (45.1s)
[10:31:05] Activity: human_review - Started (waiting for input)
[10:32:30] Activity: human_review - Completed (85.0s)
[10:32:30] Activity: send_notification - Started
[10:32:45] Activity: send_notification - Completed (15.2s)
[10:32:45] Workflow completed successfully

Variable store at each step: View the variable store state after each activity completes. Essential for debugging.

Token usage and cost tracking

Track LLM costs for each execution: Per-execution costs:

{
  "execution_id": "exec_abc123",
  "total_tokens": 15420,
  "total_cost_usd": 0.42,
  "activity_breakdown": [
    {
      "activity": "document_extractor",
      "model": "gpt-4-vision",
      "tokens": {
        "input": 2500,
        "output": 800
      },
      "cost_usd": 0.18
    },
    {
      "activity": "risk_assessment",
      "model": "claude-3-opus",
      "tokens": {
        "input": 8000,
        "output": 4120
      },
      "cost_usd": 0.24
    }
  ]
}

Cost analytics:

Total cost per workflow
Cost trends over time
Most expensive activities
Cost optimization opportunities

Viewing logs

Comprehensive logging for debugging and auditing.

Activity-level input and output logs

See exactly what each activity received and produced: Activity input:

{
  "activity": "compliance_check",
  "input": {
    "document_text": "...",
    "document_type": "invoice",
    "customer_id": "CUST-12345"
  }
}

Activity output:

{
  "activity": "compliance_check",
  "output": {
    "is_compliant": true,
    "risk_score": 0.3,
    "findings": [...]
  },
  "metadata": {
    "execution_time_ms": 8234,
    "model_used": "gpt-4",
    "tokens": {"input": 1200, "output": 450}
  }
}

Agent reasoning traces

See the AI’s step-by-step reasoning: Agent trace:

Agent: compliance_check

[Reasoning]
1. Analyzing document structure...
   - Document contains all required sections
   - Formatting is standard

2. Checking compliance requirements...
   - Verified VAT registration number
   - Confirmed payment terms are within policy
   - Validated authorized signatory

3. Assessing risk factors...
   - Amount: AED 50,000 (medium threshold)
   - Vendor: Approved vendor (low risk)
   - Historical data: 12 previous transactions, all successful

[Decision]
Status: Compliant
Risk Score: 0.3 (Low)
Recommendation: Approve for payment

[Confidence]
Overall confidence: 0.95

Tool call logs

See all tool calls with parameters and responses: Tool call log:

{
  "tool": "send_email",
  "called_by": "notification_agent",
  "timestamp": "2024-01-15T10:32:30Z",
  "parameters": {
    "to": "[email protected]",
    "subject": "Document Processing Complete",
    "body": "Your document has been successfully processed...",
    "attachments": ["report.pdf"]
  },
  "response": {
    "success": true,
    "message_id": "msg_xyz789",
    "sent_at": "2024-01-15T10:32:45Z"
  },
  "execution_time_ms": 15234
}

Execution timeline visualization

Visual timeline of the entire execution:

Timeline: Document Processing (exec_abc123)

10:30:00 |════════════════════════════════════════════════════| 10:32:45 (2m 45s)

10:30:00 |████| document_extractor (12s)
10:30:12      |██| compliance_check (8s)
10:30:20          |███████████| risk_assessment (45s)
10:31:05                       |█████████████| human_review (85s)
10:32:30                                             |█| notify (15s)

Legend:
████ Activity executing
▓▓▓▓ Waiting for input
     Idle time

Total: 165s
Activities: 165s (100%)
Overhead: <1s

Next steps

Workflow overview

Understand the complete workflow lifecycle

Memory system

See how trigger input flows through the variable store

Human task node

Learn about workflows waiting for human input

Sub Use Case

Monitor parent and child workflow executions

Getting Started

Platform Guide

Agents

Workflow Builder

Tools & Integrations

Models & Providers

Cookbooks

Security & Administration

​Trigger types

​API trigger

Document processing

Event-driven automation

Webhook handlers

Batch processing

​Schedule trigger

Daily reports

Periodic compliance checks

Data synchronization

Cleanup and maintenance

​Manual trigger

Testing

Debugging

Ad-hoc processing

Demo and training

​Chat trigger

Employee self-service

Customer support

Data retrieval

Approvals

​Execution monitoring

​Real-time status tracking

Execution status

Current activity

Progress indicator

Duration

​Activity-level progress

​Success/failure status

​Execution duration and timing

​Retry policies

​Activity-level retries

​Backoff strategies

​Retry on error types

​Workflow-level retry

​Error handling

​Activity-level error handling

​Error propagation

​Workflow failure

​Manual retry of failed executions

​Execution history

​Past executions

​Filtering and search

​Drill into individual executions

​Token usage and cost tracking

​Viewing logs

​Activity-level input and output logs

​Agent reasoning traces

​Tool call logs

​Execution timeline visualization

​Next steps

Workflow overview

Memory system

Human task node

Sub Use Case

Trigger types

API trigger

Schedule trigger

Manual trigger

Chat trigger

Execution monitoring

Real-time status tracking

Activity-level progress

Success/failure status

Execution duration and timing

Retry policies

Activity-level retries

Backoff strategies

Retry on error types

Workflow-level retry

Error handling

Activity-level error handling

Error propagation

Workflow failure

Manual retry of failed executions

Execution history

Past executions

Filtering and search

Drill into individual executions

Token usage and cost tracking

Viewing logs

Activity-level input and output logs

Agent reasoning traces

Tool call logs

Execution timeline visualization

Next steps