Skip to main content

Workflow Triggers

Triggers are the starting point of a workflow, determining when workflow execution begins. GeniSpace provides multiple trigger types, allowing you to automatically start workflows based on different conditions. This document covers the various trigger types, configuration methods, and best practices in detail.

Trigger Types​

Time Triggers​

Time triggers allow you to execute workflows based on schedules or timed settings.

Interval Trigger​

Execute a workflow at fixed time intervals:

{
  "type": "interval",
  "config": {
    "interval": 15,
    "unit": "minutes"  // seconds, minutes, hours, days
  }
}

Schedule Trigger​

Execute a workflow at specific points in time:

{
  "type": "schedule",
  "config": {
    "type": "daily",
    "time": "09:00",
    "timezone": "Asia/Shanghai"
  }
}

Cron Trigger​

Use Cron expressions to set up more complex execution schedules:

{
  "type": "cron",
  "config": {
    "expression": "0 0 9 * * 1-5",  // Monday to Friday at 9:00 AM
    "timezone": "Asia/Shanghai"
  }
}

Event Triggers​

Event triggers respond to specific internal or external system events.

WebHook Trigger​

Start a workflow via an HTTP request:

{
  "type": "webhook",
  "config": {
    "method": "POST",
    "authentication": {
      "type": "apiKey",
      "headerName": "X-API-KEY"
    },
    "responseTemplate": {
      "success": true,
      "workflowId": "{{workflowId}}"
    }
  }
}

The WebHook trigger generates a unique URL that you can integrate into third-party systems.

Database Trigger​

Monitor database changes and trigger a workflow:

{
  "type": "database",
  "config": {
    "connection": "main_database",
    "operation": "insert",  // insert, update, delete
    "table": "customers",
    "condition": "status = 'new'"
  }
}

File Trigger​

Monitor file system changes:

{
  "type": "file",
  "config": {
    "path": "/data/incoming",
    "pattern": "*.csv",
    "event": "created"  // created, modified, deleted
  }
}

Email Trigger​

Trigger a workflow based on received emails:

{
  "type": "email",
  "config": {
    "account": "support@example.com",
    "subjectPattern": "Order Confirmation",
    "fromFilter": "*@customer.com",
    "hasAttachment": true
  }
}

API Triggers​

REST API Trigger​

Start a workflow via a REST API call:

{
  "type": "api",
  "config": {
    "endpoint": "/api/v1/workflows/order-processor",
    "method": "POST",
    "authentication": {
      "type": "oauth2"
    },
    "inputSchema": {
      "type": "object",
      "properties": {
        "orderId": { "type": "string" },
        "customer": { "type": "object" }
      },
      "required": ["orderId"]
    }
  }
}

Message Queue Trigger​

Receive messages from a message queue and trigger a workflow:

{
  "type": "queue",
  "config": {
    "provider": "rabbitmq",  // rabbitmq, kafka, sqs
    "queue": "order-events",
    "messageType": "order.created",
    "batchSize": 10,
    "connection": "mq_main"
  }
}

Condition Triggers​

Data Condition Trigger​

Trigger a workflow when data meets specific conditions:

{
  "type": "condition",
  "config": {
    "source": {
      "type": "database",
      "connection": "analytics_db",
      "query": "SELECT COUNT(*) as count FROM errors WHERE severity = 'high' AND created_at > NOW() - INTERVAL '1 hour'"
    },
    "condition": "count > 10",
    "checkInterval": 300  // seconds
  }
}

Composite Condition Trigger​

A complex trigger that combines multiple conditions:

{
  "type": "compositeCondition",
  "config": {
    "operator": "AND",  // AND, OR
    "conditions": [
      {
        "source": "database",
        "query": "SELECT COUNT(*) as pending FROM orders WHERE status = 'pending'",
        "condition": "pending > 50"
      },
      {
        "source": "api",
        "endpoint": "https://api.example.com/system-status",
        "condition": "response.status === 'normal'"
      }
    ],
    "checkInterval": 600
  }
}

Manual Triggers​

User Interface Trigger​

Allows users to manually start a workflow via the UI:

{
  "type": "manual",
  "config": {
    "inputForm": {
      "fields": [
        {
          "name": "reportType",
          "label": "Report Type",
          "type": "select",
          "options": ["Sales", "Inventory", "Customer"]
        },
        {
          "name": "dateRange",
          "label": "Date Range",
          "type": "daterange",
          "required": true
        }
      ]
    },
    "permissions": ["report_manager", "admin"]
  }
}

Batch Action Trigger​

Process batch-selected items:

{
  "type": "batchAction",
  "config": {
    "targetEntity": "orders",
    "actionName": "Batch Process Orders",
    "minItems": 1,
    "maxItems": 100
  }
}

Advanced Configuration​

Trigger Condition Filtering​

You can add additional filter conditions to any trigger:

{
  "type": "webhook",
  // ... basic configuration ...
  "filter": {
    "conditions": [
      {
        "field": "payload.status",
        "operator": "equals",
        "value": "new"
      },
      {
        "field": "payload.amount",
        "operator": "greaterThan",
        "value": 1000
      }
    ],
    "operator": "AND"  // AND, OR
  }
}

Throttling and Rate Limiting​

Prevent workflows from executing too frequently:

{
  "type": "webhook",
  // ... basic configuration ...
  "rateLimit": {
    "maxExecutions": 10,
    "perTimeWindow": 60,  // seconds
    "exceedingStrategy": "queue"  // queue, discard, error
  }
}

Trigger Context and Data​

Each trigger provides context data that can be used within the workflow:

{
  "trigger": {
    "type": "webhook",
    "id": "trig_12345",
    "received_at": "2023-05-15T09:23:51Z"
  },
  "data": {
    // Trigger-specific data
  },
  "metadata": {
    "source_ip": "192.168.1.1",
    "headers": {
      "user-agent": "..."
    }
  }
}

Trigger Debugging and Monitoring​

Trigger Logs​

Each trigger event generates a log entry that includes:

  • Receive time
  • Match status (whether it passed filter conditions)
  • Workflow start status
  • Complete input data

You can view this information on the "Workflows > Triggers > Logs" page.

Trigger Testing​

GeniSpace provides testing tools to verify trigger configurations:

  1. Configure the trigger
  2. Click the "Test Trigger" button
  3. Provide test input data
  4. See how the trigger processes the test data
  5. Check whether the workflow would be started (without actually executing)

Trigger Monitoring​

Monitor trigger health and performance:

  • Activity status (Active / Disabled)
  • Last trigger time
  • Trigger frequency
  • Error rate
  • Average response time

Security and Access Control​

Authentication and Authorization​

Methods for securing trigger endpoints:

  1. API Keys - Set up keys for WebHook and API triggers
  2. IP Allowlisting - Restrict which IP addresses can invoke triggers
  3. OAuth2 - Use OAuth2 for more advanced authentication
  4. Shared Secrets - Include a signature in requests for verification

Data Validation​

Validate input data to prevent invalid triggers:

  1. JSON Schema - Define the structure and types of input data
  2. Input Validation Rules - Set custom validation rules
  3. Content Security Policies - Filter potentially malicious content

FAQ​

Details

Can a trigger start multiple workflows? Yes, the same trigger event can start multiple different workflows. In the trigger configuration, you can link multiple workflows, or create multiple independent triggers that listen for the same event.

Details

How do I handle missed trigger events? GeniSpace provides several strategies for handling missed events:

  1. Replay Feature - For certain trigger types, historical events can be replayed from the UI
  2. Persistent Queues - Use message queue triggers to ensure messages are not lost
  3. Compensation Logic - Implement additional data checks in workflows to handle potentially missed events
Details

How do I handle duplicate triggers? To avoid issues caused by duplicate triggers, you can:

  1. Enable Deduplication - Configure the trigger to ignore duplicate events within a specific time window
  2. Use Idempotent Operations - Design workflows so they can be safely executed multiple times
  3. Implement Transaction IDs - Use unique transaction IDs to track processed events

Best Practices​

Choosing the Right Trigger Type​

  • Use Time Triggers for periodic tasks such as report generation and data backups
  • Use Event Triggers to respond to real-time events such as new orders or user registrations
  • Use Condition Triggers to monitor system states such as inventory levels or error rates
  • Use Manual Triggers for processes requiring human decision-making

Optimizing Trigger Frequency​

  • Avoid excessively frequent checks to reduce system load
  • Set reasonable time intervals for batch processing tasks
  • Use queues to consolidate multiple similar events
  • Consider business hours and user activity patterns

Exception Handling​

  • Configure trigger failure notifications
  • Implement trigger health checks
  • Set up fallback trigger mechanisms
  • Log and monitor all trigger anomalies

Next Steps​