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

# Checklist Workflows

> Configure multi-condition workflows with AND/OR logic and conditional visibility

## Overview

Checklist Workflows enable complex automation logic that evaluates multiple conditions across different checklist items. Unlike [Automations](/guides/workflows/automations) which trigger immediately on a single item, workflows execute when a submission is completed and all conditions are evaluated together.

**Key Characteristics:**

* **Multi-condition logic**: Combine conditions with AND/OR operators
* **Submission-level scope**: Evaluate across multiple items
* **Deferred execution**: Trigger on submission completion
* **Complex actions**: Create tasks, work orders, and multi-channel alerts

***

## Workflow vs Automation

| Feature             | Automations                  | Workflows              |
| ------------------- | ---------------------------- | ---------------------- |
| **Trigger timing**  | Immediate on answer          | On submission complete |
| **Condition scope** | Single item                  | Multiple items         |
| **Logic operators** | Single condition             | AND/OR combinations    |
| **Best for**        | Real-time alerts, follow-ups | Complex decision logic |

***

## Workflow Actions

| Action                            | Description                                          |
| --------------------------------- | ---------------------------------------------------- |
| `CREATE_TASK_FROM_TEMPLATE`       | Auto-create a task from a predefined template        |
| `CREATE_WORK_ORDER_FROM_TEMPLATE` | Auto-create a work order from template               |
| `SEND_ALERT`                      | Send notifications via email, SMS, push, or WhatsApp |

***

## Create a Workflow

Create a workflow with multiple conditions.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/workflows" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Critical Safety Alert",
      "description": "Alert when multiple safety items fail",
      "ChecklistId": "safety-template-uuid",
      "operator": "AND",
      "isActive": true,
      "conditions": [
        {
          "id": "condition-1-uuid",
          "ChecklistItemId": "fire-extinguisher-item-uuid",
          "conditions": {
            "logic": "eq",
            "value": "no"
          }
        },
        {
          "id": "condition-2-uuid",
          "ChecklistItemId": "emergency-exit-item-uuid",
          "conditions": {
            "logic": "eq",
            "value": "no"
          }
        }
      ],
      "actions": [
        {
          "type": "CREATE_TASK_FROM_TEMPLATE",
          "id": "action-1-uuid",
          "data": {
            "taskTemplateId": "safety-corrective-action-uuid",
            "when": "onSubmit"
          }
        },
        {
          "type": "SEND_ALERT",
          "id": "action-2-uuid",
          "data": {
            "email": {
              "when": "onSubmit",
              "enabled": true,
              "recipients": ["safety@example.com"]
            },
            "push": {
              "when": "onSubmit",
              "enabled": true,
              "recipients": ["safety-manager-uuid"]
            }
          }
        }
      ],
      "notification": {
        "roles": ["safety-manager-role-uuid"],
        "teams": [],
        "users": [],
        "emails": ["compliance@example.com"],
        "enable": true,
        "showSubmissionInEmail": true
      }
    }'
  ```
</CodeGroup>

**Request Body:**

| Field          | Type    | Required | Description                                                    |
| -------------- | ------- | -------- | -------------------------------------------------------------- |
| `name`         | string  | Yes      | Workflow name                                                  |
| `description`  | string  | No       | Workflow description                                           |
| `ChecklistId`  | string  | Yes      | Template this workflow applies to                              |
| `operator`     | string  | No       | `AND` (all conditions) or `OR` (any condition). Default: `AND` |
| `isActive`     | boolean | No       | Enable/disable workflow. Default: `true`                       |
| `conditions`   | array   | Yes      | Array of conditions (min 1)                                    |
| `actions`      | array   | Yes      | Array of actions (min 1)                                       |
| `notification` | object  | No       | Additional notification settings                               |

**Condition Object:**

| Field                | Type   | Required | Description                                                                                        |
| -------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `id`                 | string | Yes      | Unique condition identifier                                                                        |
| `ChecklistItemId`    | string | Yes      | Item to evaluate                                                                                   |
| `conditions.logic`   | string | Yes      | Operator: eq, not, lt, lte, gt, gte, btw, nbtw, contains, not\_contains, is\_empty, is\_not\_empty |
| `conditions.value`   | any    | Yes      | Value to compare against                                                                           |
| `conditions.context` | string | No       | Filter by `Locations` or `LocationGroups`                                                          |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "workflow-uuid",
    "name": "Critical Safety Alert",
    "description": "Alert when multiple safety items fail",
    "ChecklistId": "safety-template-uuid",
    "operator": "AND",
    "isActive": true,
    "conditions": [...],
    "actions": [...],
    "notification": {...},
    "createdAt": "2024-12-20T10:00:00Z"
  }
}
```

***

## Logic Operators

### AND Operator

All conditions must match for the workflow to trigger.

```json theme={null}
{
  "operator": "AND",
  "conditions": [
    {
      "ChecklistItemId": "item-1-uuid",
      "conditions": { "logic": "eq", "value": "fail" }
    },
    {
      "ChecklistItemId": "item-2-uuid",
      "conditions": { "logic": "lt", "value": 70 }
    }
  ]
}
```

**Triggers when:** Item 1 = "fail" **AND** Item 2 \< 70

### OR Operator

Any condition matching triggers the workflow.

```json theme={null}
{
  "operator": "OR",
  "conditions": [
    {
      "ChecklistItemId": "critical-item-1-uuid",
      "conditions": { "logic": "eq", "value": "no" }
    },
    {
      "ChecklistItemId": "critical-item-2-uuid",
      "conditions": { "logic": "eq", "value": "no" }
    }
  ]
}
```

**Triggers when:** Item 1 = "no" **OR** Item 2 = "no"

***

## Action Configuration

### Create Task from Template

```json theme={null}
{
  "type": "CREATE_TASK_FROM_TEMPLATE",
  "id": "action-uuid",
  "data": {
    "taskTemplateId": "task-template-uuid",
    "when": "onSubmit"
  }
}
```

### Create Work Order from Template

```json theme={null}
{
  "type": "CREATE_WORK_ORDER_FROM_TEMPLATE",
  "id": "action-uuid",
  "data": {
    "taskTemplateId": "work-order-template-uuid",
    "when": "onSubmit"
  }
}
```

### Send Alert

```json theme={null}
{
  "type": "SEND_ALERT",
  "id": "action-uuid",
  "data": {
    "email": {
      "when": "onSubmit",
      "enabled": true,
      "recipients": ["manager@example.com"]
    },
    "sms": {
      "when": "onSubmit",
      "enabled": true,
      "recipients": ["+1234567890"]
    },
    "push": {
      "when": "onSubmit",
      "enabled": true,
      "recipients": ["user-uuid"]
    },
    "whatsapp": {
      "when": "onSubmit",
      "enabled": false,
      "recipients": []
    }
  }
}
```

***

## List Workflows

### Get All Workflows

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/workflows" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Get Workflows for a Checklist

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/checklists/{checklistId}/workflows" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Get Items with Workflows

Find which checklist items have workflow conditions attached.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/checklists/{checklistId}/items-with-workflow" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Get Single Workflow

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/workflows/{workflowId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Update Workflow

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/workflows/{workflowId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Workflow Name",
      "isActive": false,
      "operator": "OR"
    }'
  ```
</CodeGroup>

***

## Bulk Create/Update Workflows

Create or update multiple workflows in a single request.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/workflows/bulk" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "workflows": [
        {
          "name": "Workflow 1",
          "ChecklistId": "template-uuid",
          "operator": "AND",
          "conditions": [...],
          "actions": [...]
        },
        {
          "id": "existing-workflow-uuid",
          "name": "Updated Workflow 2",
          "isActive": true
        }
      ]
    }'
  ```
</CodeGroup>

<Note>
  Include `id` to update an existing workflow. Omit `id` to create a new one.
</Note>

***

## Delete Workflows

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/workflows" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "workflowIds": ["workflow-uuid-1", "workflow-uuid-2"]
    }'
  ```
</CodeGroup>

***

## Conditional Visibility (Item Settings)

Control which checklist items are visible based on answers to other items.

### Get Item Settings

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/checklists/{checklistId}/checklist-item-settings" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Query Parameters:**

| Parameter  | Type   | Description             |
| ---------- | ------ | ----------------------- |
| `itemId`   | string | Filter by specific item |
| `contexts` | array  | Filter by context       |

### Create Item Settings

Show or hide items based on conditions.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/checklists/{checklistId}/checklist-item-settings" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "contextId": "trigger-item-uuid",
      "context": "checklistItem",
      "action": "show",
      "condition": {
        "logic": "eq",
        "value": "yes"
      },
      "itemIds": ["target-item-1-uuid", "target-item-2-uuid"]
    }'
  ```
</CodeGroup>

**Request Body:**

| Field       | Type   | Required | Description                          |
| ----------- | ------ | -------- | ------------------------------------ |
| `contextId` | string | Yes      | Item that triggers the condition     |
| `context`   | string | Yes      | Context type (e.g., `checklistItem`) |
| `action`    | string | Yes      | `show` or `hide`                     |
| `condition` | object | Yes      | Condition logic                      |
| `itemId`    | string | No       | Single target item                   |
| `itemIds`   | array  | No       | Multiple target items                |

**Example Use Case:** Show follow-up questions only when "Other" is selected.

```json theme={null}
{
  "contextId": "primary-question-uuid",
  "context": "checklistItem",
  "action": "show",
  "condition": {
    "logic": "eq",
    "value": "other"
  },
  "itemIds": ["other-details-uuid", "additional-notes-uuid"]
}
```

### Update Item Settings

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/checklists/{checklistId}/checklist-item-settings/{settingsId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "hide",
      "condition": {
        "logic": "eq",
        "value": "n/a"
      }
    }'
  ```
</CodeGroup>

### Delete Item Settings

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/checklists/{checklistId}/checklist-item-settings/{settingsId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Common Workflows

### Multi-Failure Alert

Alert when multiple critical items fail in the same inspection.

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

    Inspector->>API: 1. Complete inspection
    Inspector->>API: 2. Submit
    API->>Workflow: 3. Evaluate conditions
    Note right of Workflow: Check: Item1=fail AND Item2=fail
    Workflow->>API: 4. Conditions match
    API->>API: 5. Create task
    API->>Manager: 6. Send alert
```

### Location-Based Routing

Route alerts to different teams based on location.

```bash theme={null}
curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/workflows" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "North Region Safety Alert",
    "ChecklistId": "template-uuid",
    "operator": "AND",
    "conditions": [
      {
        "id": "condition-1",
        "ChecklistItemId": "safety-item-uuid",
        "conditions": {
          "logic": "eq",
          "value": "fail",
          "context": "LocationGroups"
        }
      }
    ],
    "actions": [
      {
        "type": "SEND_ALERT",
        "id": "action-1",
        "data": {
          "email": {
            "enabled": true,
            "recipients": ["north-safety@example.com"]
          }
        }
      }
    ]
  }'
```

### Score Threshold Workflow

Trigger actions when overall score falls below threshold.

```json theme={null}
{
  "name": "Low Score Alert",
  "ChecklistId": "template-uuid",
  "operator": "OR",
  "conditions": [
    {
      "ChecklistItemId": "section-1-score-uuid",
      "conditions": { "logic": "lt", "value": 70 }
    },
    {
      "ChecklistItemId": "section-2-score-uuid",
      "conditions": { "logic": "lt", "value": 70 }
    }
  ],
  "actions": [
    {
      "type": "CREATE_TASK_FROM_TEMPLATE",
      "data": { "taskTemplateId": "improvement-plan-template-uuid" }
    }
  ]
}
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use AND for strict requirements">
    When all conditions must be met before taking action, use AND. This prevents false positives from single-item failures.
  </Accordion>

  <Accordion title="Use OR for any-match scenarios">
    When any single condition should trigger action, use OR. Good for critical items where any failure is important.
  </Accordion>

  <Accordion title="Combine with automations strategically">
    Use Automations for immediate item-level responses (flags, notifications). Use Workflows for submission-level analysis and task creation.
  </Accordion>

  <Accordion title="Test workflows before production">
    Create test submissions to verify workflow logic triggers correctly. Complex AND/OR combinations can behave unexpectedly.
  </Accordion>

  <Accordion title="Keep condition count manageable">
    Workflows with too many conditions become hard to maintain. Consider splitting into multiple focused workflows.
  </Accordion>

  <Accordion title="Use conditional visibility sparingly">
    Too many show/hide rules can confuse inspectors. Keep forms as simple as possible while gathering necessary data.
  </Accordion>
</AccordionGroup>

***

## Permissions

| Action                  | Required Permission                                                     |
| ----------------------- | ----------------------------------------------------------------------- |
| View workflows          | `CAN_MANAGE_CHECKLIST` or `CHECKLIST_SUPER_ADMIN`                       |
| Create/Update workflows | `CAN_MANAGE_CHECKLIST` or `CHECKLIST_SUPER_ADMIN` + Active subscription |
| Delete workflows        | `CAN_MANAGE_CHECKLIST` or `CHECKLIST_SUPER_ADMIN`                       |

***

## Related Guides

* [Automations](/guides/workflows/automations) - Item-level triggers
* [Template Management](/guides/workflows/template-management) - Create templates with workflows
* [Submission Workflow](/guides/workflows/submission-workflow) - Complete inspections
* [Task Management](/guides/workflows/task-management) - Manage auto-created tasks