Building Automations

Automations connect triggers to actions, enabling event-driven workflows. When something happens (trigger), VirtuousAI automatically does something (action).

Prerequisites

VirtuousAI account with CLI installed
At least one connection configured
Understanding of Actions

Automation Anatomy

Every automation has three parts:

Component	Description	Examples
Trigger	What starts the automation	Schedule, webhook, event
Config	How the automation behaves	Concurrency, retries, conditions
Action	What gets executed	Extract data, call API, transform

Creating Your First Automation

Let's create an automation that extracts Shopify data every morning:

vai automations create \
  --name "Daily Shopify Sync" \
  --description "Extract orders and products every morning" \
  --trigger-type schedule \
  --config '{
    "schedule": "0 6 * * *",
    "timezone": "America/New_York",
    "action": {
      "kind": "dlt_extract",
      "definition": {
        "source": "shopify",
        "resources": ["orders", "products"],
        "incremental": true
      }
    }
  }'

curl -X POST https://vai-dev.virtuousai.com/api/v1/automations \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Shopify Sync",
    "description": "Extract orders and products every morning",
    "triggerType": "schedule",
    "config": {
      "schedule": "0 6 * * *",
      "timezone": "America/New_York",
      "action": {
        "kind": "dlt_extract",
        "definition": {
          "source": "shopify",
          "resources": ["orders", "products"],
          "incremental": true
        }
      }
    }
  }'

Trigger Types

Schedule Triggers

Run automations on a cron schedule:

{
  "triggerType": "schedule",
  "config": {
    "schedule": "0 */4 * * *",
    "timezone": "UTC"
  }
}

Common schedules:

Schedule	Meaning
`0 6 * * *`	Daily at 6 AM
`0 /4 * *`	Every 4 hours
`0 0 * * 1`	Weekly on Monday
`/15 * * *`	Every 15 minutes

Webhook Triggers

Trigger automations from external webhooks:

{
  "triggerType": "webhook",
  "config": {
    "path": "/hooks/shopify-orders",
    "secret": "whsec_..."
  }
}

VirtuousAI generates a unique webhook URL:

https://vai-dev.virtuousai.com/webhooks/org_abc123/hooks/shopify-orders

Manual Triggers

Automations can always be triggered manually:

vai automations trigger auto_abc123

This is useful for testing before enabling scheduled triggers.

Monitoring Automations

View Automation Status

vai automations list
# ID              NAME                    STATUS    TRIGGER     LAST RUN
# auto_abc123     Daily Shopify Sync     active    schedule    2h ago
# auto_def456     Lead Enrichment        paused    webhook     1d ago

View Run History

vai automations runs auto_abc123 --limit 10
# RUN ID          STATUS      STARTED             DURATION
# run_123         completed   2026-01-22 06:00    45s
# run_124         completed   2026-01-21 06:00    42s
# run_125         failed      2026-01-20 06:00    12s

View Run Details

vai automation-runs get run_123
# Status: completed
# Trigger: schedule
# Started: 2026-01-22 06:00:00 UTC
# Duration: 45 seconds
# Actions executed: 1

Error Handling

Automatic Retries

Configure retry behavior in your automation:

{
  "config": {
    "retries": {
      "maxAttempts": 3,
      "backoffMultiplier": 2,
      "initialDelay": 60
    }
  }
}

This retries failed actions up to 3 times with exponential backoff.

Failure Notifications

Set up alerts for failed runs:

{
  "config": {
    "notifications": {
      "onFailure": {
        "type": "webhook",
        "url": "https://hooks.slack.com/services/..."
      }
    }
  }
}

Concurrency Control

Prevent overlapping runs with concurrency keys:

{
  "config": {
    "concurrencyKey": "shopify-sync",
    "concurrencyPolicy": "skip"
  }
}

Policy	Behavior
`skip`	Skip new run if one is already running
`queue`	Queue new run to execute after current
`cancel`	Cancel running and start new

Pausing and Resuming

Pause an automation to stop scheduled runs:

vai automations update auto_abc123 --status paused

Resume when ready:

vai automations update auto_abc123 --status active

Pausing an automation doesn't cancel runs that are already in progress.

Automation Lifecycle

State	Description
active	Automation runs on schedule or responds to triggers
paused	Automation is temporarily disabled
archived	Automation is permanently disabled

Example: Multi-Step Workflow

Create a workflow that extracts data, transforms it, and loads to a warehouse:

vai automations create \
  --name "ETL Pipeline" \
  --trigger-type schedule \
  --config '{
    "schedule": "0 2 * * *",
    "actions": [
      {
        "name": "Extract",
        "kind": "dlt_extract",
        "definition": {"source": "shopify", "resources": ["orders"]}
      },
      {
        "name": "Transform",
        "kind": "duckdb_transform",
        "definition": {"sql": "SELECT * FROM orders WHERE status = '\''completed'\''"}
      },
      {
        "name": "Notify",
        "kind": "web_search",
        "definition": {"url": "https://hooks.slack.com/...", "method": "POST"}
      }
    ]
  }'

Actions execute sequentially, and the workflow stops if any action fails.

Next Steps

Webhook Integration

Set up webhooks to trigger automations from external events

Automations Reference

Complete API documentation for automations

Events & Observability

Monitor and debug your automations

Building Automations

Webhook Integration

Automations Reference

Events & Observability

On this page