Skip to main content

Automation Engine

Capture trigger, match, condition, and effect patterns along with operational guardrails for the automation subsystem.

Automation Rule Execution Flow​

Automation Rule Lifecycle​

What is Automation?​

Automation rules allow you to automatically respond to events in Terragnos Core. Each rule consists of:

  • Trigger – What event starts the rule (object created, workflow transition, schedule, webhook)
  • Match – Which objects or conditions must be met
  • Condition – Additional logic that must be true
  • Effect – What action to take (update objects, call webhook, send notification)

Creating an Automation Rule​

Via API​

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auto-approve-low-risk",
    "displayName": "Auto-approve Low Risk Items",
    "trigger": {
      "type": "object.created",
      "objectTypeId": "inspection-request"
    },
    "match": {
      "type": "attribute",
      "path": "$.riskLevel",
      "operator": "equals",
      "value": "low"
    },
    "condition": {
      "type": "and",
      "rules": [
        {
          "type": "attribute",
          "path": "$.status",
          "operator": "equals",
          "value": "pending"
        }
      ]
    },
    "effect": {
      "type": "workflow.transition",
      "targetState": "approved",
      "metadata": {
        "reason": "Auto-approved: low risk"
      }
    }
  }' \
  https://core.example.com/v1/automation/rules

Triggers​

Object Events​

Trigger when objects are created, updated, or deleted:

{
  "trigger": {
    "type": "object.created",
    "objectTypeId": "inspection-request"
  }
}

Workflow Transitions​

Trigger when an object transitions to a specific state:

{
  "trigger": {
    "type": "workflow.transition",
    "workflowId": "inspection-workflow",
    "targetState": "review"
  }
}

Scheduled​

Trigger on a schedule (cron expression):

{
  "trigger": {
    "type": "schedule",
    "cron": "0 9 * * 1"  // Every Monday at 9 AM
  }
}

Webhook​

Trigger via external webhook:

{
  "trigger": {
    "type": "webhook",
    "slug": "external-system-notification"
  }
}

Call the webhook:

curl -X POST \
  -H "Authorization: Bearer <webhook-token>" \
  -H "Content-Type: application/json" \
  -d '{"event": "inspection-completed", "objectId": "..."}' \
  https://core.example.com/v1/automation/triggers/external-system-notification

Match Conditions​

Match conditions filter which objects the rule applies to:

{
  "match": {
    "type": "and",
    "rules": [
      {
        "type": "attribute",
        "path": "$.priority",
        "operator": "greaterThan",
        "value": 5
      },
      {
        "type": "spatial",
        "operator": "within",
        "geometry": {...}
      }
    ]
  }
}

Effects​

Update Objects​

{
  "effect": {
    "type": "object.update",
    "updates": {
      "status": "processed",
      "processedAt": "{{now}}"
    }
  }
}

Workflow Transition​

{
  "effect": {
    "type": "workflow.transition",
    "targetState": "approved"
  }
}

Call Webhook​

{
  "effect": {
    "type": "webhook",
    "url": "https://external-system.com/webhook",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{webhook-secret}}"
    },
    "body": {
      "objectId": "{{object.id}}",
      "event": "auto-processed"
    }
  }
}

Rule Lifecycle​

  1. Draft – Create and edit the rule
  2. Sandbox – Test with sample data
  3. Published – Rule is ready but not active
  4. Active – Rule is executing
  5. Inactive – Rule is disabled but can be re-enabled

Activating a Rule​

curl -X POST \
  -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/automation/rules/{ruleId}/activate

Monitoring Execution​

View recent rule executions:

curl -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/automation/rules/{ruleId}/runs

View detailed execution log:

curl -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/automation/rules/{ruleId}/runs/{runId}

Best Practices​

  1. Test in sandbox – Always test rules with sample data before activating
  2. Use specific matches – Narrow match conditions to avoid unintended executions
  3. Handle failures – Consider what happens if webhooks fail or effects error
  4. Monitor execution – Track success/failure rates and execution times
  5. Version carefully – Published rules are immutable
  6. Document triggers – Clearly document when and why rules execute
  7. Use idempotency – Design effects to be safe if executed multiple times