Automation Schema Reference

This is the comprehensive, canonical reference for Stack9 Automation schemas and properties. This document is the single source of truth for all automation-related structures, derived directly from the AutomationValidator.

Complete Automation Structure

{
  "key": "string",              // Required - Must be token format (alphanumeric/underscore)
  "entityKey": "string",         // Conditionally required - See EntityKey Requirements
  "app": "string",               // Required - Application/module identifier
  "triggerType": "string",       // Required - See AutomationTriggerTypes
  "name": "string",              // Required - Human-readable name
  "triggerParams": {},           // Required - Schema varies by triggerType
  "actions": [],                 // Optional - Array of Action objects
  "conditionalActions": [],      // Optional - Array of ConditionalAction objects
  "module": "string"             // Optional - Module identifier
}

AutomationTriggerTypes

All valid trigger type values:

Trigger Type	Description	EntityKey Required
afterCreate	Fires after entity creation	Yes
afterUpdate	Fires after entity update	Yes
afterDelete	Fires after entity deletion	Yes
afterWorkflowMove	Fires after workflow state change	Yes
afterWorflowOwnershipTaken	Fires after workflow ownership taken	Yes
cronJob	Scheduled execution	No
webhook	HTTP webhook endpoint	No
mqHandler	Message queue handler	No

Note: There's a typo in the enum value afterWorflowOwnershipTaken (missing 'k' in Workflow) - this is the actual value in the system.

EntityRelatedAutomationTriggerTypes

These trigger types require the entityKey field:

• afterCreate
• afterUpdate
• afterDelete
• afterWorkflowMove
• afterWorflowOwnershipTaken

EntityKey Requirements

The entityKey field is:

• Required when triggerType is one of the EntityRelatedAutomationTriggerTypes
• Optional for other trigger types (cronJob, webhook, mqHandler)
• Must be in token format when provided

TriggerParams Schemas

The triggerParams field structure varies based on the triggerType:

cronJob TriggerParams

{
  "cronExpression": "string",  // Required - Must match regex: /^\S+ \S+ \S+ \S+ \S+$/
  "timeoutMs": number          // Optional - Timeout in milliseconds
}

Cron Expression Format: Five space-separated fields representing:

• Minute (0-59)
• Hour (0-23)
• Day of month (1-31)
• Month (1-12)
• Day of week (0-7, where 0 and 7 are Sunday)

Examples:

• "0 * * * *" - Every hour
• "0 2 * * *" - Every day at 2 AM
• "*/15 * * * *" - Every 15 minutes

mqHandler TriggerParams

{
  "queueName": "string",  // Required - Must be token format
  "timeoutMs": number     // Optional - Processing timeout in milliseconds
}

webhook TriggerParams

{
  "path": "string",    // Optional - Must be relative URI (e.g., "/my-webhook")
  "method": "string"   // Optional - Valid values: "all", "get", "post", "put"
}

Note: Method values are lowercase.

Entity-Related TriggerParams

For afterCreate, afterUpdate, afterDelete, afterWorkflowMove, and afterWorflowOwnershipTaken:

{}  // Empty object - no specific parameters required

Action Schema

Each action in the actions array must follow this structure:

{
  "key": "string",           // Required - Must be token format
  "name": "string",          // Required - Human-readable name
  "actionTypeKey": "string",  // Required - Must match registered action type
  "params": {}               // Optional - Parameters object (structure depends on action type)
}

Action Properties

Property	Type	Required	Description
key	string	Yes	Unique identifier in token format
name	string	Yes	Human-readable action name
actionTypeKey	string	Yes	References registered action type
params	object	No	Action-specific parameters

Conditional Actions Schema

Each item in the conditionalActions array follows this structure:

{
  "condition": {
    "rules": [],           // Array of rules or nested conditions
    "combinator": "string" // "and" or "or"
  },
  "actions": []           // Array of Action objects
}

Condition Structure

{
  "rules": [
    // Can contain ConditionalRule objects or nested Condition objects
  ],
  "combinator": "and" | "or"
}

Conditional Rule Structure

{
  "field": "string",    // Optional - Field to evaluate (can use template expressions)
  "value": "string",    // Optional - Value to compare (empty string allowed)
  "operator": "string"  // Optional - Comparison operator
}

Nested Conditions

Rules can contain nested conditions for complex logic:

{
  "condition": {
    "rules": [
      {
        "field": "{{trigger.entity.status}}",
        "value": "active",
        "operator": "equals"
      },
      {
        "rules": [
          {
            "field": "{{trigger.entity.tier}}",
            "value": "premium",
            "operator": "equals"
          },
          {
            "field": "{{trigger.entity.tier}}",
            "value": "enterprise",
            "operator": "equals"
          }
        ],
        "combinator": "or"
      }
    ],
    "combinator": "and"
  }
}

Combinator Values

Valid combinator values for conditional logic:

• "and" - All rules must match
• "or" - At least one rule must match

Note: Values are lowercase strings.

Webhook Method Values

Valid HTTP methods for webhook triggers:

• "all" - Accept any HTTP method
• "get" - GET requests only
• "post" - POST requests only
• "put" - PUT requests only

Note: Values are lowercase strings.

Validation Rules

Key Validation

Fields that must be in token format (only alphanumeric characters and underscores):

• Automation key
• Action key
• entityKey (when provided)
• queueName in mqHandler triggerParams

Token format regex: /^[a-zA-Z0-9_]+$/

Required Fields by Context

Base Automation (Always Required)

• key
• app
• triggerType
• name
• triggerParams

Conditionally Required

• entityKey - Required only when triggerType is in EntityRelatedAutomationTriggerTypes

Action (Always Required)

• key
• name
• actionTypeKey

Complete Examples

Example: Entity Lifecycle Automation

{
  "key": "when_customer_created",
  "entityKey": "customer",
  "app": "crm",
  "triggerType": "afterCreate",
  "name": "When Customer Created",
  "triggerParams": {},
  "actions": [
    {
      "key": "send_welcome",
      "name": "Send Welcome Email",
      "actionTypeKey": "send_welcome_email",
      "params": {
        "customerId": "{{trigger.entity.id}}"
      }
    }
  ]
}

Example: Webhook Automation

{
  "key": "webhook_process_payment",
  "app": "payments",
  "triggerType": "webhook",
  "name": "Process Payment Webhook",
  "triggerParams": {
    "method": "post",
    "path": "/process-payment"
  },
  "actions": [
    {
      "key": "process",
      "name": "Process Payment",
      "actionTypeKey": "process_payment",
      "params": {
        "amount": "{{trigger.body.amount}}"
      }
    }
  ]
}

Example: Scheduled Job

{
  "key": "daily_cleanup",
  "app": "maintenance",
  "triggerType": "cronJob",
  "name": "Daily Cleanup",
  "triggerParams": {
    "cronExpression": "0 2 * * *",
    "timeoutMs": 300000
  },
  "actions": [
    {
      "key": "cleanup",
      "name": "Run Cleanup",
      "actionTypeKey": "cleanup_old_records",
      "params": {}
    }
  ]
}

Example: Message Queue Handler

{
  "key": "process_customer_sync",
  "app": "sync",
  "triggerType": "mqHandler",
  "name": "Process Customer Sync",
  "triggerParams": {
    "queueName": "customer_sync",
    "timeoutMs": 10000
  },
  "actions": [
    {
      "key": "sync",
      "name": "Sync Customer",
      "actionTypeKey": "sync_customer_data",
      "params": {
        "customerId": "{{trigger.message.body.customerId}}"
      }
    }
  ]
}

Example: Conditional Actions

{
  "key": "after_order_update",
  "entityKey": "sales_order",
  "app": "sales",
  "triggerType": "afterUpdate",
  "name": "After Order Update",
  "triggerParams": {},
  "actions": [],
  "conditionalActions": [
    {
      "condition": {
        "rules": [
          {
            "field": "{{trigger.entity.status}}",
            "value": "approved",
            "operator": "equals"
          },
          {
            "field": "{{trigger.entity.total_amount}}",
            "value": "1000",
            "operator": "greaterThan"
          }
        ],
        "combinator": "and"
      },
      "actions": [
        {
          "key": "notify_manager",
          "name": "Notify Manager",
          "actionTypeKey": "send_notification",
          "params": {
            "message": "High value order approved"
          }
        }
      ]
    }
  ]
}

Example: Workflow Move Automation

{
  "key": "after_subscription_workflow_move",
  "entityKey": "subscription",
  "app": "billing",
  "triggerType": "afterWorkflowMove",
  "name": "After Subscription Workflow Move",
  "triggerParams": {},
  "conditionalActions": [
    {
      "condition": {
        "rules": [
          {
            "field": "{{trigger.actionKey}}",
            "value": "approve",
            "operator": "equals"
          }
        ],
        "combinator": "and"
      },
      "actions": [
        {
          "key": "activate",
          "name": "Activate Subscription",
          "actionTypeKey": "activate_subscription",
          "params": {
            "subscriptionId": "{{trigger.entityId}}"
          }
        }
      ]
    }
  ]
}

Important Notes

1. Typo in Enum: The trigger type afterWorflowOwnershipTaken contains a typo (missing 'k' in Workflow). This is the actual value in the system and must be used as-is.

2. Case Sensitivity: All enum values (triggerType, method, combinator) are case-sensitive and must match exactly.

3. Token Format: Fields requiring token format can only contain alphanumeric characters and underscores.

4. Template Expressions: The params field in actions and field/value in conditions support template expressions using {{expression}} syntax.

5. Validation Order: The validator checks required fields first, then applies conditional requirements based on trigger type.

Source of Truth

This documentation is derived directly from:

• /packages/stack9-sdk/src/schema/validators/v2/AutomationValidator.ts
• /packages/stack9-sdk/src/models/core/S9Automation.ts
• /packages/stack9-sdk/src/models/core/S9AutomationActionType.ts

When in doubt, these source files contain the definitive schema definitions.