Automations

Overview

Automations are item-level triggers that execute immediately when a checklist item is answered. They enable real-time responses to inspection findings without waiting for submission completion. Key Characteristics:

Immediate execution: Triggers fire as soon as an answer matches conditions
Item-level scope: Each automation is attached to a specific checklist item
Single condition: Evaluates one condition per automation
Multiple actions: Can trigger multiple actions from a single condition

For multi-condition logic that evaluates across multiple items, see Checklist Workflows.

Action Types

Automations support five action types:

Action	Description	Use Case
`FOLLOW_UP_QUESTION`	Show additional questions based on answer	Drill-down questions for “No” answers
`FLAG`	Create a flag/issue automatically	Mark safety violations for review
`TASK`	Auto-create a task	Immediate corrective actions
`NOTIFICATION`	Send alerts (email, SMS, push, WhatsApp)	Alert managers of critical findings
`IMAGE`	Require photo capture	Document evidence for flagged items

Condition Operators

Operator	Description	Example
`eq`	Equals	Answer equals “No”
`not`	Not equals	Answer is not “Pass”
`lt`	Less than	Score less than 70
`lte`	Less than or equal	Score at most 50
`gt`	Greater than	Temperature above 100
`gte`	Greater than or equal	Rating at least 4
`btw`	Between (inclusive)	Value between 10 and 20
`nbtw`	Not between	Value outside 10-20 range
`contains`	Contains substring	Notes contain “urgent”
`not_contains`	Does not contain	Notes don’t contain “N/A”
`is_empty`	Is null/empty	No answer provided
`is_not_empty`	Has value	Answer was provided

Create Automations

Create one or more automations for checklist items.

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/automations" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "automations": [
      {
        "EntityId": "checklist-item-uuid",
        "ChecklistId": "template-uuid",
        "entityType": "checklistItem",
        "conditions": [
          {
            "logic": "eq",
            "value": "no"
          }
        ],
        "actions": [
          {
            "type": "FLAG",
            "data": {
              "flagCategoryId": "safety-violation-category-uuid"
            }
          },
          {
            "type": "NOTIFICATION",
            "data": {
              "email": {
                "enabled": true,
                "recipients": ["safety-manager@example.com"]
              },
              "push": {
                "enabled": true,
                "recipients": ["manager-user-uuid"]
              }
            }
          }
        ]
      }
    ]
  }'

Request Body:

Field	Type	Required	Description
`automations`	array	Yes	Array of automation configurations
`automations[].EntityId`	string	Yes	Checklist item ID to attach automation to
`automations[].ChecklistId`	string	Yes	Template ID
`automations[].entityType`	string	Yes	Type identifier (use `checklistItem`)
`automations[].operator`	string	No	Logic operator for multiple conditions (`AND`/`OR`)
`automations[].conditions`	array	Yes	Trigger conditions
`automations[].conditions[].logic`	string	Yes	Condition operator
`automations[].conditions[].value`	any	Yes	Value to compare against
`automations[].actions`	array	Yes	Actions to execute
`automations[].actions[].type`	string	Yes	Action type
`automations[].actions[].data`	object	No	Action-specific configuration

Response:

{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": "automation-uuid",
      "EntityId": "checklist-item-uuid",
      "ChecklistId": "template-uuid",
      "entityType": "checklistItem",
      "conditions": [...],
      "actions": [...],
      "createdAt": "2024-12-20T10:00:00Z"
    }
  ]
}

Action Configuration Examples

Flag Action

Automatically flag items for review.

{
  "type": "FLAG",
  "data": {
    "flagCategoryId": "category-uuid",
    "flagNote": "Auto-flagged: Non-compliant answer detected"
  }
}

Notification Action

Send multi-channel notifications.

{
  "type": "NOTIFICATION",
  "data": {
    "email": {
      "enabled": true,
      "recipients": ["manager@example.com", "safety@example.com"]
    },
    "sms": {
      "enabled": true,
      "recipients": ["+1234567890"]
    },
    "push": {
      "enabled": true,
      "recipients": ["user-uuid-1", "user-uuid-2"]
    },
    "whatsapp": {
      "enabled": false,
      "recipients": []
    }
  }
}

Task Action

Auto-create a corrective action task.

{
  "type": "TASK",
  "data": {
    "taskTemplateId": "task-template-uuid",
    "priority": "High",
    "assignToSubmitter": true
  }
}

Follow-up Question Action

Show additional questions based on answer.

{
  "type": "FOLLOW_UP_QUESTION",
  "data": {
    "questions": [
      {
        "id": "followup-item-uuid",
        "required": true
      }
    ]
  }
}

Image Capture Action

Require photo documentation.

{
  "type": "IMAGE",
  "data": {
    "required": true,
    "minCount": 1,
    "maxCount": 5
  }
}

Get Automations

Get Automations for a Checklist

curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/checklists/{checklistId}/automations" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Response:

{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": "automation-uuid-1",
      "EntityId": "item-uuid-1",
      "ChecklistId": "template-uuid",
      "entityType": "checklistItem",
      "conditions": [
        {
          "id": "condition-uuid",
          "logic": "eq",
          "value": "no"
        }
      ],
      "actions": [
        {
          "id": "action-uuid",
          "type": "FLAG",
          "data": {...}
        }
      ]
    },
    {
      "id": "automation-uuid-2",
      "EntityId": "item-uuid-2",
      "ChecklistId": "template-uuid",
      "entityType": "checklistItem",
      "conditions": [...],
      "actions": [...]
    }
  ]
}

Update Automations

To update existing automations, include the id field in the automation object.

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/automations" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "automations": [
      {
        "id": "existing-automation-uuid",
        "EntityId": "checklist-item-uuid",
        "ChecklistId": "template-uuid",
        "entityType": "checklistItem",
        "conditions": [
          {
            "logic": "eq",
            "value": "fail"
          }
        ],
        "actions": [
          {
            "type": "FLAG",
            "data": {
              "flagCategoryId": "updated-category-uuid"
            }
          }
        ]
      }
    ]
  }'

Delete Automations

curl -X DELETE "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/automations" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "automationIds": ["automation-uuid-1", "automation-uuid-2"]
  }'

Response:

{
  "status": "success",
  "code": 200,
  "message": "2 automations deleted successfully"
}

Execute Automation (Internal)

When a checklist item is answered, automations are executed automatically. This endpoint is typically called internally but can be used for testing.

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/automations/checklist-items/{submissionId}/run" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "checklistItem": {
      "id": "item-uuid",
      "answer": "no",
      "type": "yes_no"
    },
    "attachment": [],
    "checklistDefaultLocationId": "location-uuid"
  }'

Common Workflows

Auto-Flag Safety Violations

Conditional Follow-up Questions

When an inspector answers “No” to a compliance question, show follow-up questions to gather more details.

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/automations" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "automations": [{
      "EntityId": "compliance-question-uuid",
      "ChecklistId": "template-uuid",
      "entityType": "checklistItem",
      "conditions": [{
        "logic": "eq",
        "value": "no"
      }],
      "actions": [{
        "type": "FOLLOW_UP_QUESTION",
        "data": {
          "questions": [
            {"id": "reason-question-uuid", "required": true},
            {"id": "corrective-action-question-uuid", "required": true}
          ]
        }
      }, {
        "type": "IMAGE",
        "data": {
          "required": true,
          "minCount": 1
        }
      }]
    }]
  }'

Temperature Alert System

Alert managers when temperature readings exceed thresholds.

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/automations" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "automations": [{
      "EntityId": "temperature-item-uuid",
      "ChecklistId": "food-safety-template-uuid",
      "entityType": "checklistItem",
      "conditions": [{
        "logic": "gt",
        "value": 40
      }],
      "actions": [{
        "type": "FLAG",
        "data": {
          "flagCategoryId": "temperature-violation-uuid"
        }
      }, {
        "type": "NOTIFICATION",
        "data": {
          "sms": {
            "enabled": true,
            "recipients": ["+1234567890"]
          },
          "email": {
            "enabled": true,
            "recipients": ["food-safety@example.com"]
          }
        }
      }, {
        "type": "TASK",
        "data": {
          "taskTemplateId": "temperature-corrective-action-uuid",
          "priority": "High"
        }
      }]
    }]
  }'

Best Practices

Use appropriate action combinations

Combine actions strategically. For critical issues, use FLAG + NOTIFICATION + TASK together to ensure visibility and action.

Keep conditions simple

Automations work best with single, clear conditions. For complex multi-condition logic, use Checklist Workflows instead.

Test automations before publishing

Create a test submission to verify automations trigger correctly before publishing the template to production.

Use flag categories for organization

Define clear flag categories to help managers quickly identify and prioritize issues.

Consider notification fatigue

Be selective with notifications. Over-notification can lead to alert fatigue and important issues being missed.

Document automation purposes

Maintain documentation of what automations exist and why, especially for complex templates with many triggers.

Permissions

Action	Required Permission
Create/Update automations	`CAN_MANAGE_CHECKLIST`
Get automations	— (read-only)
Delete automations	`CAN_MANAGE_CHECKLIST`

Checklist Workflows - Multi-condition logic
Template Management - Create templates with automations
Corrective Actions - Handle flagged items
Submission Workflow - Complete inspections

Getting Started

Workflows

Integrations

Overview

Action Types

Condition Operators

Create Automations

Action Configuration Examples

Flag Action

Notification Action

Task Action

Follow-up Question Action

Image Capture Action

Get Automations

Get Automations for a Checklist

Update Automations

Delete Automations

Execute Automation (Internal)

Common Workflows

Auto-Flag Safety Violations

Conditional Follow-up Questions

Temperature Alert System

Best Practices

Permissions

​Overview

​Action Types

​Condition Operators

​Create Automations

​Action Configuration Examples

​Flag Action

​Notification Action

​Task Action

​Follow-up Question Action

​Image Capture Action

​Get Automations

​Get Automations for a Checklist

​Update Automations

​Delete Automations

​Execute Automation (Internal)

​Common Workflows

​Auto-Flag Safety Violations

​Conditional Follow-up Questions

​Temperature Alert System

​Best Practices

​Permissions

​Related Guides

Overview

Action Types

Condition Operators

Create Automations

Action Configuration Examples

Flag Action

Notification Action

Task Action

Follow-up Question Action

Image Capture Action

Get Automations

Get Automations for a Checklist

Update Automations

Delete Automations

Execute Automation (Internal)

Common Workflows

Auto-Flag Safety Violations

Conditional Follow-up Questions

Temperature Alert System

Best Practices

Permissions

Related Guides