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

# Automation definition

> The fields an automation definition takes, and what each one accepts.

An automation definition is a trigger and an ordered list of steps. The Automation Builder writes one for you when you describe what you want in chat. Write one yourself when you build automations over the API or an MCP client.

## Required fields

| Field          | Type   | Notes                                                                     |
| -------------- | ------ | ------------------------------------------------------------------------- |
| `name`         | string | 1 to 200 characters                                                       |
| `trigger_type` | string | What starts the automation. See [Choosing a trigger](#choosing-a-trigger) |
| `steps`        | array  | 1 to 50 steps. See [Step types](/automations/step-types)                  |

## Optional fields

| Field             | Type    | Notes                                                                             |
| ----------------- | ------- | --------------------------------------------------------------------------------- |
| `description`     | string  | What the automation does, for people reading it later                             |
| `summary`         | string  | One line shown on the automation card                                             |
| `instructions`    | string  | Extra guidance for agent-callable automations. Up to 2000 characters              |
| `destructive`     | boolean | Marks the automation as making changes that cannot be undone. Defaults to `false` |
| `schedule_config` | object  | Required when `trigger_type` is `SCHEDULE`, and rejected otherwise                |
| `input_schema`    | object  | Required when `trigger_type` is `function`                                        |

## Choosing a trigger

`trigger_type` takes one of three kinds of value.

A **project event** fires the automation when something happens in your store, such as `ORDER_CREATED` or `CUSTOMER_UPDATED`. Browse them in [Events](/apps/colossal-app/events). Connection webhooks use the connection's own event id, such as `shopify/orders/paid`.

**`SCHEDULE`** runs the automation on a clock. Pair it with `schedule_config`, whose fields are in [Scheduled](/automations/events/scheduled-events):

```json theme={null}
{
  "trigger_type": "SCHEDULE",
  "schedule_config": { "schedule_type": "cron", "cron_expression": "0 9 * * MON" }
}
```

**`function`** makes the automation callable by an agent rather than fired by an event. Declare what the caller passes in `input_schema`:

```json theme={null}
{
  "trigger_type": "function",
  "input_schema": {
    "type": "object",
    "properties": { "order_id": { "type": "string" } },
    "required": ["order_id"]
  }
}
```

## Referencing data

Steps read values with `{{...}}` templates rather than literals. [Data access](/automations/data-access) covers the rules; the namespaces are:

| Namespace                                      | Reads                                                  |
| ---------------------------------------------- | ------------------------------------------------------ |
| `{{<field>}}`                                  | A field of the trigger's own payload, by its bare name |
| `{{trigger_data.payload.*}}`                   | The same payload through its envelope                  |
| `{{steps.<id>.*}}`                             | An earlier step's output                               |
| `{{iteration.item.*}}`                         | The current item inside a `map` step                   |
| `{{now}}`, `{{workspace.*}}`, `{{platform.*}}` | Run context the engine supplies                        |

There is no `{{payload.*}}` namespace. A `function` trigger's inputs are trigger payload
fields like any other, so an `input_schema` property named `order_id` is `{{order_id}}`.

## A complete definition

This automation runs every Monday morning, asks for last week's revenue, and posts it to Slack.

```json theme={null}
{
  "name": "Weekly revenue summary",
  "description": "Posts last week's revenue to Slack every Monday.",
  "trigger_type": "SCHEDULE",
  "schedule_config": {
    "schedule_type": "cron",
    "cron_expression": "0 9 * * MON"
  },
  "steps": [
    {
      "id": "revenue",
      "type": "insights",
      "description": "Read last week's revenue",
      "question": "What was total revenue and order count for the last 7 days?",
      "output_schema": {
        "type": "object",
        "properties": {
          "revenue": { "type": "number" },
          "orders": { "type": "integer" }
        },
        "required": ["revenue", "orders"]
      },
      "next": "post"
    },
    {
      "id": "post",
      "type": "action",
      "description": "Post the summary to Slack",
      "action": "slack/send_message",
      "parameters": {
        "channel": "#general",
        "text": "Last week: {{steps.revenue.revenue}} across {{steps.revenue.orders}} orders."
      }
    }
  ]
}
```

Each step type takes its own fields on top of `id` and `type`. [Step types](/automations/step-types) lists them, and marks which are required.

## Checking a definition

Validate a definition before you create it. The checker runs the same rules the platform runs on create, over a whole definition or a single step, so what it accepts is what the platform accepts. See the [MCP server](/developer-tools/mcp) for the tools that expose it.