Automations

Automations are workflows that execute actions based on triggers. They connect your triggers (when) with your actions (what) and conditions (if).

Concept

An automation combines:

Trigger — When to run (schedule, webhook, event)
Conditions — Whether to run (filters, guards)
Actions — What to execute (one or more, in sequence or DAG)

Component	Examples
Trigger	`schedule: "0 6 * * *"`, `webhook: /orders`, `event: action.completed`
Conditions	`order.total > 100`, `status = "new"`, `region in ["US", "CA"]`
Actions	`dlt_extract`, `insight_delegate`, `web_search`

Trigger Types

Schedule Triggers

Run automations on a cron schedule:

Schedule	Cron Expression	Description
Every hour	`0 * * * *`	Top of every hour
Daily at 2am	`0 2 * * *`	Once per day
Every 6 hours	`0 /6 * *`	4 times per day
Weekdays at 9am	`0 9 * * 1-5`	Monday-Friday
Monthly	`0 0 1 * *`	First of month

{
  "trigger": {
    "type": "schedule",
    "schedule": "0 6 * * *",
    "timezone": "America/New_York"
  }
}

Webhook Triggers

Trigger from external HTTP requests:

{
  "trigger": {
    "type": "webhook",
    "path": "/hooks/shopify-orders",
    "secret": "whsec_..."
  }
}

This creates an endpoint at:

https://vai-dev.virtuousai.com/webhooks/{org_id}/hooks/shopify-orders

Webhook URLs are unique per automation. The secret is used to verify requests are authentic.

Event Triggers

React to events within VirtuousAI:

{
  "trigger": {
    "type": "event",
    "eventType": "action.completed",
    "filters": {
      "actionKind": "dlt_extract"
    }
  }
}

Event types include:

action.completed, action.failed
connection.data_available, connection.error
automation.completed, automation.failed

Automation Lifecycle

Status	Description	Triggers Fire?
`active`	Automation enabled and ready	Yes
`paused`	Temporarily disabled	No
`error`	Configuration issue detected	No

Conditions

Add conditions to filter when automations actually execute:

Condition Operators

Operator	Description	Example
`eq`, `ne`	Equals, not equals	`status eq "new"`
`gt`, `gte`, `lt`, `lte`	Numeric comparisons	`orderTotal gt 100`
`contains`	String contains	`email contains "@company.com"`
`startsWith`, `endsWith`	String prefix/suffix	`sku startsWith "PROD-"`
`in`, `notIn`	Array membership	`region in ["US", "CA", "MX"]`

{
  "conditions": [
    {
      "field": "event.data.orderTotal",
      "operator": "gt",
      "value": 100
    }
  ]
}

{
  "conditions": [
    {
      "field": "event.data.status",
      "operator": "eq",
      "value": "new"
    },
    {
      "field": "event.data.region",
      "operator": "in",
      "value": ["US", "CA"]
    }
  ]
}

All conditions must pass (AND logic)

{
  "conditions": [
    {
      "field": "event.data.customer.tier",
      "operator": "eq",
      "value": "enterprise"
    }
  ]
}

Use dot notation for nested fields

Automation Runs

Each trigger creates an automation run that tracks execution:

Field	Description
`runId`	Unique identifier for this run
`automationId`	Parent automation
`triggeredBy`	What triggered it (schedule, webhook, event, manual)
`startedAt`	When execution began
`completedAt`	When execution finished
`status`	`running`, `completed`, `failed`, `cancelled`
`actionRuns`	List of action executions with results

Multi-Action Workflows

Automations can execute multiple actions:

Sequential Execution

Actions execute in order. If any action fails, the workflow stops:

{
  "actions": [
    { "kind": "dlt_extract", "definition": {...} },
    { "kind": "transform", "definition": {...} },
    { "kind": "notify", "definition": {...} }
  ]
}

DAG Execution

For complex workflows, define dependencies between steps:

{
  "actions": [
    { "key": "extract", "kind": "dlt_extract", "definition": {...} },
    { "key": "transform", "kind": "duckdb", "dependsOn": ["extract"], "definition": {...} },
    { "key": "load", "kind": "export", "dependsOn": ["transform"], "definition": {...} },
    { "key": "notify", "kind": "webhook", "dependsOn": ["load"], "definition": {...} }
  ]
}

Failure Behavior

By default, if any action fails, the automation stops and marks the run as failed. Subsequent actions are skipped.

Creating Automations

{
  "name": "Daily Order Sync",
  "description": "Sync Shopify orders every day at 2am ET",
  "trigger": {
    "type": "schedule",
    "schedule": "0 2 * * *",
    "timezone": "America/New_York"
  },
  "actions": [
    { "kind": "dlt_extract", "definition": { "source": "shopify", "resources": ["orders"] } }
  ],
  "enabled": true
}

{
  "name": "Process New Data",
  "description": "Transform data when extraction completes",
  "trigger": {
    "type": "event",
    "eventType": "action.completed",
    "filters": { "kind": "dlt_extract" }
  },
  "conditions": [
    { "field": "event.data.recordCount", "operator": "gt", "value": 0 }
  ],
  "actions": [
    { "kind": "transform", "definition": {...} }
  ],
  "enabled": true
}

{
  "name": "External Trigger",
  "description": "Run sync when triggered by external system",
  "trigger": {
    "type": "webhook",
    "path": "/external/sync",
    "secret": "whsec_your_secret_here"
  },
  "actions": [
    { "kind": "dlt_extract", "definition": {...} }
  ],
  "enabled": true
}

Best Practices

Start simple — Begin with single-action automations, add complexity gradually
Use conditions wisely — Filter early to avoid unnecessary action executions
Monitor runs — Check automation run history regularly, set up failure alerts
Test with manual triggers — Use the trigger endpoint to test before enabling schedules
Use descriptive names — Include frequency and purpose (e.g., "Daily 2am - Sync Orders")
Consider time zones — Always specify timezone for scheduled automations

OpenAPI Reference

For detailed endpoint schemas, request/response formats, and authentication:

Automation Endpoints

Full OpenAPI documentation for automation management

Automations

View Automation Flow

View Workflow Patterns

Automation Endpoints

On this page