> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Automations

> Configure item-level automations for immediate triggers and actions

## 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

<Note>
  For multi-condition logic that evaluates across multiple items, see [Checklist Workflows](/guides/workflows/checklist-workflows).
</Note>

***

## 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.

<CodeGroup>
  ```bash cURL theme={null}
  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"]
                }
              }
            }
          ]
        }
      ]
    }'
  ```
</CodeGroup>

**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:**

```json theme={null}
{
  "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.

```json theme={null}
{
  "type": "FLAG",
  "data": {
    "flagCategoryId": "category-uuid",
    "flagNote": "Auto-flagged: Non-compliant answer detected"
  }
}
```

### Notification Action

Send multi-channel notifications.

```json theme={null}
{
  "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.

```json theme={null}
{
  "type": "TASK",
  "data": {
    "taskTemplateId": "task-template-uuid",
    "priority": "High",
    "assignToSubmitter": true
  }
}
```

### Follow-up Question Action

Show additional questions based on answer.

```json theme={null}
{
  "type": "FOLLOW_UP_QUESTION",
  "data": {
    "questions": [
      {
        "id": "followup-item-uuid",
        "required": true
      }
    ]
  }
}
```

### Image Capture Action

Require photo documentation.

```json theme={null}
{
  "type": "IMAGE",
  "data": {
    "required": true,
    "minCount": 1,
    "maxCount": 5
  }
}
```

***

## Get Automations

### Get Automations for a Checklist

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
              }
            }
          ]
        }
      ]
    }'
  ```
</CodeGroup>

***

## Delete Automations

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

***

## Common Workflows

### Auto-Flag Safety Violations

```mermaid theme={null}
sequenceDiagram
    participant Inspector
    participant API as Xenia API
    participant Manager

    Inspector->>API: 1. Answer "Fire extinguisher inspected?" = No
    API->>API: 2. Automation triggers
    API->>API: 3. Create FLAG
    API->>Manager: 4. Send push notification
    Manager->>API: 5. View flagged items
```

### Conditional Follow-up Questions

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

```bash theme={null}
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.

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Use appropriate action combinations">
    Combine actions strategically. For critical issues, use FLAG + NOTIFICATION + TASK together to ensure visibility and action.
  </Accordion>

  <Accordion title="Keep conditions simple">
    Automations work best with single, clear conditions. For complex multi-condition logic, use [Checklist Workflows](/guides/workflows/checklist-workflows) instead.
  </Accordion>

  <Accordion title="Test automations before publishing">
    Create a test submission to verify automations trigger correctly before publishing the template to production.
  </Accordion>

  <Accordion title="Use flag categories for organization">
    Define clear flag categories to help managers quickly identify and prioritize issues.
  </Accordion>

  <Accordion title="Consider notification fatigue">
    Be selective with notifications. Over-notification can lead to alert fatigue and important issues being missed.
  </Accordion>

  <Accordion title="Document automation purposes">
    Maintain documentation of what automations exist and why, especially for complex templates with many triggers.
  </Accordion>
</AccordionGroup>

***

## Permissions

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

***

## Related Guides

* [Checklist Workflows](/guides/workflows/checklist-workflows) - Multi-condition logic
* [Template Management](/guides/workflows/template-management) - Create templates with automations
* [Corrective Actions](/guides/workflows/corrective-actions) - Handle flagged items
* [Submission Workflow](/guides/workflows/submission-workflow) - Complete inspections