> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/integrations/actions.md).

# Actions

Run work in other systems when an alert or incident changes: open a ticket, call a webhook, send an email. Automatically, or when a user starts it.

{% hint style="info" %}
**Rolling out.** Actions supersede **Alert actions**. New accounts have actions, and older accounts generally still have alert actions. The sidebar shows whichever your account has, never both.
{% endhint %}

An action calls another system when something happens to an alert or an incident. It can open a Jira issue when an alert is created, post to a webhook when an incident is resolved, or reroute an alert. Most actions authenticate with a **connector**, which holds the credentials for the target system.

Actions are the outbound integrations of ilert.

## How actions work

1. Something happens to an alert or incident: it is created, accepted, commented on, resolved.
2. ilert looks up all enabled action for that entity kind, filter by their **trigger events** and **condition** expressions.
3. Suitable actions executed.
4. The result is recorded in the **Action logs**. The first run can link the alert or incident to the object it created, for example a Jira issue, so later runs update that issue instead of creating a new one.
5. Some actions support bidirectional integration. When enabled and configured in the target systems, third-party changes will affect the state of ilert's entity. For example, a Jira issue moved to *Done* will resolve the alert.

{% hint style="info" %}
**Slack and Microsoft Teams integrations.** They are ChatOps integrations with their own setup. See [ChatOps](https://docs.ilert.com/chatops/overview.md).
{% endhint %}

## Acting Entity: Alert or Incident

Every action runs on exactly one kind of entity: **alerts** or **incidents**. Most of integrations support both. You choose the kind when the action is created, and you cannot change it afterwards.

* An **alert action** reacts to the alert lifecycle: `PENDING` → `ACCEPTED` → `RESOLVED`, plus escalations, reroutes, responders and comments.
* An **incident action** reacts to the incident lifecycle: opened, status changes, postmortems, resolved, responders and comments.

## Create an action

{% stepper %}
{% step %}

### Start a new action

Go to **Actions** in the sidebar and click **Create new action**.
{% endstep %}

{% step %}

### Choose the type

Under **Choose an action**, pick an integration.
{% endstep %}

{% step %}

### Choose a connection

Under **Choose an existing connection configuration or create a new one**, select a connector or enter new credentials and click **Save credentials**. Actions that need no credentials, such as Email or Reroute alert, skip this step. See [Connectors](#connectors).
{% endstep %}

{% step %}

### Set the trigger

Under **Trigger mode**, choose **Automatic** or **Manual** (see [Automatic and manual actions](#automatic-and-manual-actions)). For an automatic action, pick the **Trigger events** to run on. Select nothing to run on every event of this kind.
{% endstep %}

{% step %}

### Limit what it runs for

Under **Run this action for**, choose the scope:

* **All alert sources**: every alert, including alerts from sources created later. **Admins only**.
* **My teams**: alerts or incidents owned by your teams.
* **Specific sources**: only the alert sources you pick.
* **Specific services**: only incidents affecting the services you pick.

To narrow it further, turn on **Execute only for items that meet the following conditions** and add filters, for example on priority or summary. Click **Edit code** to write advanced expressions in [ICL](https://docs.ilert.com/developer-docs/icl-ilert-condition-language) directly.
{% endstep %}

{% step %}

### Configure the action

Give the action a name, fill in the settings, and possibly **assign the action to teams**. Click **Verify** to check the configuration, then **Complete setup**.
{% endstep %}

{% step %}

### Turn on bidirectional syncronization (optional)

For actions that can report back (Jira, Autotask, GitHub, Zendesk, Zammad, Zapier), you can turn on **Accept callbacks** and use the **Callback URL** in the target system's webhook settings. See [Callbacks](#the-inbound-section).
{% endstep %}

{% step %}

### Check that it can run

Trigger a matching event, for example create a test alert. Then open the action and check **Action logs**: every run is listed with the status.
{% endstep %}
{% endstepper %}

## Who can create actions

Admins can create actions for every alert or incident in the account.

Normal users must restrict each action to entities they have access to. For alert actions, the condition must limit it to their teams or to specific alert sources. For incident actions, the condition must limit it to their teams or to specific services. The **My teams**, **Specific sources** and **Specific services** scopes do this for you.

{% hint style="warning" %}
**The restriction has to hold in every branch of the ICL condition for non-admins.** A condition like `entity.teamIds contains_any [12] or entity.priority == "HIGH"` is rejected, because the second branch would match high-priority alerts from every team. Saving it will fail.
{% endhint %}

## Automatic and manual actions

**Automatic** actions that will be launched whenever a matching trigger event happens to an alert or incident.

**Manual** actions run when a user attachs them to a particular alert or incident. The action will appear in the **Actions** card on the alert or incident page, and only on entities that match its condition.

Running the manual action will attach it to the lifecycle of the entity. So not only the immediate state of the entity will be reflected in the target system like Jira but also subsequent state transitions like alert acceptance or resolution will trigger the attached action automatically.

Using **Run again** the action can be triggered once more, without waiting for a status change.

And the **Stop auto-run** can be used to temporary prevent further executions for this entity.

{% hint style="warning" %}
Only users with write permissions can trigger manual actions.
{% endhint %}

## Trigger events

An automatic action runs on the events you select under **Trigger events**. If you select none, it runs on every event of its kind.

**Alert events**

| Trigger event               | Identifier in templates   | Default |
| --------------------------- | ------------------------- | ------- |
| **Alert created**           | `alert.created`           | Yes     |
| **Alert accepted**          | `alert.accepted`          | Yes     |
| **Alert resolved**          | `alert.resolved`          | Yes     |
| **Alert rerouted**          | `alert.rerouted`          |         |
| **Alert escalated**         | `alert.escalated`         |         |
| **Alert escalation ended**  | `alert.escalation_ended`  |         |
| **Alert priority raised**   | `alert.priority_raised`   |         |
| **Alert responder added**   | `alert.responder_added`   |         |
| **Alert responder removed** | `alert.responder_removed` |         |
| **Alert comment added**     | `alert.comment_added`     | Yes     |
| **Alert channel attached**  | `alert.channel_attached`  |         |
| **Alert channel detached**  | `alert.channel_detached`  |         |

**Incident events**

| Trigger event                  | Identifier in templates      | Default |
| ------------------------------ | ---------------------------- | ------- |
| **Incident opened**            | `incident.opened`            | Yes     |
| **Incident updated**           | `incident.updated`           | Yes     |
| **Incident status changed**    | `incident.status_changed`    | Yes     |
| **Incident resolved**          | `incident.resolved`          | Yes     |
| **Incident deleted**           | `incident.deleted`           |         |
| **Incident responder added**   | `incident.responder_added`   |         |
| **Incident responder removed** | `incident.responder_removed` |         |
| **Incident responder updated** | `incident.responder_updated` |         |
| **Incident comment added**     | `incident.comment_added`     | Yes     |
| **Incident channel attached**  | `incident.channel_attached`  |         |
| **Incident channel detached**  | `incident.channel_detached`  |         |
| **Incident postmortem linked** | `incident.postmortem_linked` |         |

Some events cover more than one change. Use the condition to tell them apart:

* **Incident status changed** fires for every move between *Investigating*, *Identified* and *Monitoring*. To react to one status only, filter on `entity.status`.

## Connectors

A connector stores how ilert reaches a target system: the base URL and the secret it authenticates with. You can create a connector once and reuse it in as many actions as you need, for example one Jira connector for every Jira action in your account.

Create a connector in the **Connection** step of the action wizard, or ahead of time under **Settings** → **Connectors**.

* Connector's secrets are write-only are stored encrypted. The API and the UI never return them after you save them.
* For a webhook-like integrations (Discord, Mattermost, Zapier) the URL path is extracted and encrypted.

## Custom Behavior (advanced topic)

Most of actions are based on YAML templates that completely defines their behavior. You can override the following parts of a template: **`config`**, **`steps`** and **`inbound`**.

To customize the definition, open the action and click **Edit**. Under **Action definition**, click **Take over the definition** to edit it as **Action definition (YAML)**.

Values in the definition use two languages:

* **`{{ … }}`** placeholders are [ITL](https://docs.ilert.com/developer-docs/itl-ilert-template-language), for example `{{ entity.summary.orElse("ilert alert").truncate(240) }}`.
* **`when`** and **`classify`** conditions are [ICL](https://docs.ilert.com/developer-docs/icl-ilert-condition-language), for example `signal.type == 'alert.resolved'`.

| Variable             | Contains                                                                                                                     | Schema                                                                                                                                                           |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity`             | The alert or incident, for example `entity.summary`, `entity.status`, `entity.priority`, `entity.url`, `entity.source.name`  | [alert](https://docs.ilert.com/integrations/actions/context/entity-alert.md), [incident](https://docs.ilert.com/integrations/actions/context/entity-incident.md) |
| `signal`             | The event that started this run, for example `signal.type`                                                                   | [signal](https://docs.ilert.com/integrations/actions/context/signal.md)                                                                                          |
| `execution`          | This run, for example `execution.correlationId`                                                                              | [execution](https://docs.ilert.com/integrations/actions/context/execution.md)                                                                                    |
| `actor`              | The user or system that made the change                                                                                      | [actor](https://docs.ilert.com/integrations/actions/context/actor.md)                                                                                            |
| `config`             | The action's settings (see [config](#the-config-section))                                                                    | [config](https://docs.ilert.com/integrations/actions/context/config.md)                                                                                          |
| `tenant`             | Your account, for example `tenant.ilertDomain`                                                                               | [tenant](https://docs.ilert.com/integrations/actions/context/tenant.md)                                                                                          |
| `last`               | The response of the previous request: `last.status`, `last.body`                                                             | [last](https://docs.ilert.com/integrations/actions/context/last.md)                                                                                              |
| `responses`          | Earlier responses in the current step, by request id                                                                         | [responses](https://docs.ilert.com/integrations/actions/context/responses.md)                                                                                    |
| `steps`              | Earlier steps in this run, for example `steps.create-issue.status`                                                           | [steps](https://docs.ilert.com/integrations/actions/context/steps.md)                                                                                            |
| `twin`               | The object an earlier run created in the target system, for example `twin.ref.issueId`. `nil` until the first run creates it | [twin](https://docs.ilert.com/integrations/actions/context/twin.md)                                                                                              |
| `map`                | Field-mapping results the template publishes by name                                                                         | [map](https://docs.ilert.com/integrations/actions/context/map.md)                                                                                                |
| `vendor`             | Constants ilert holds for the target system                                                                                  | [vendor](https://docs.ilert.com/integrations/actions/context/vendor.md)                                                                                          |
| `@ilert`             | ilert objects looked up by id, for example `@ilert.schedules.12.user.email`                                                  | [ilert](https://docs.ilert.com/integrations/actions/context/ilert.md)                                                                                            |
| `credential.hostUrl` | The connector's base URL. Allowed only at the start of a URL                                                                 |                                                                                                                                                                  |

The `inbound` section sees a different set of variables, listed in [The 'inbound' section](#the-inbound-section).

{% hint style="info" %}
**Every variable and every field of `steps` and `inbound` is described as an OpenAPI 3.1 schema**: see [Template schema](https://docs.ilert.com/integrations/actions/template.md) for the definition sections and [Context schema](https://docs.ilert.com/integrations/actions/context.md) for the variables. Absent fields are left out rather than set to null, so test them with `!= nil`.
{% endhint %}

### The 'config' section

`config` holds the values behind the action's settings: the Jira project, the issue type, which updates to push. Normally the wisard writes them for you. In YAML, you set only the keys you want to change; every other key keeps the template's default.

```yaml
config:
  project: OPS
  issueType: Incident
  labels: ["ilert", "on-call"]
  pushComments: false
```

* Values reach the steps as strings, so compare switches with `config.pushComments == 'true'`, not with `true`.

### The 'steps' section

`steps` define a sequence of HTTP requests. Steps can have conditions and can depend on each other (cyclic dependencies are not allowed). Full schema: [steps](https://docs.ilert.com/integrations/actions/template/steps.md).

**Required step fields**

* `id`: name of the step. Other steps can refer to it as `steps.<id>`.
* `requests`: the HTTP requests to send, in order.

**Optional step fields**

* `when`: ICL condition. The step runs only when it is true.
* `needs`: step IDs that must finish successfully before this step runs.
* `operation`: `CREATE` if the step creates the object in the target system, `UPDATE` if it changes one, `NOOP` (default) otherwise.
* `referenceWrite`: defines how the information about the entity in the target system is stored (a nested structure).
* `authoredId`: ITL template referring to the ID of an entity this step created. For example, `{{ last.body.id }}`. Use to prevent echo in the bidirectional setup.

**Required request fields**

* `id`: name of the request. Later requests read its response as `responses.<id>`.
* `method`: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` or `HEAD`.
* `url`: can be an ITL template, in this case should start with `{{ credential.hostUrl }}` to use the connector.

**Optional request fields**

* `headers`: map of headers (ITL supported). Do not add authentication headers - the connector adds them.
* `body`: usually JSON (ITL supported).
* `expect.successStatus`: status codes that count as success. Without it, any `2xx` denotes success.
* `expect.condition`: ICL condition on the response (`last`) that must also hold to denote success.
* `retry`: `AUTO` (default), `SAFE` (idempotent), or `NEVER`. Use `NEVER` for requests that must not be sent twice, such as adding a comment.

**The twin**

The twin is the link between an ilert entity (alert or incident) and the object in the target system, such as a Jira issue.

* **Creating it.** A step with `operation: CREATE` and a `referenceWrite` creates the twin when it completes. `referenceWrite.externalId` is the object's ID in the target system and must be set on every `CREATE` step; otherwise the next run creates a second object. `externalUrl` is a link to the object that will be attached to ilert's alert. `ref` holds any other values later steps need, such as `issueId` and `issueKey`.
* **Reading it.** On later runs for the same alert or incident, steps read the stored values as `{{twin.ref.<field>}}`. Before the first `CREATE` step completes there is no twin, and `twin == nil` is true.
* **Bidirectional setup (callbacks) use it too.** When the target system calls back, `inbound.matchBy.externalId` is matched against the twin's `externalId` to find the alert or incident. Callbacks about an object with no twin are ignored.

How steps run:

* **Every step whose `when` evaluates to true runs**, in order of definition and dependency.
* A request fails when the response is outside `expect`. The run is then marked as failed, and steps that list the failed step in `needs` are skipped. **Action logs** shows which step failed and the status the target system returned. A failed run is not retried later; only the request-level `retry` applies.

As an example, here is the subset of the Jira template:

```yaml
steps:
  - id: create-issue
    when: "twin == nil"
    operation: CREATE
    requests:
      - id: post
        method: POST
        url: "{{ credential.hostUrl }}/rest/api/2/issue/"
        headers: { "Content-Type": "application/json" }
        body: |
          { "fields": {
              "project":   { "key":  "{{ config.project }}" },
              "issuetype": { "name": "{{ config.issueType }}" },
              "summary":   "{{ entity.summary.orElse("ilert alert").truncate(240) }}" } }
        expect: { successStatus: [200, 201] }
    referenceWrite:
      externalId: "{{ last.body.id }}"
      externalUrl: "{{ credential.hostUrl }}/browse/{{ last.body.key }}"
      ref:
        issueId: "{{ last.body.id }}"
        issueKey: "{{ last.body.key }}"

  - id: add-comment
    when: >-
      twin.ref.issueId != nil and signal.type == 'alert.comment_added'
    operation: UPDATE
    requests:
      - id: post
        method: POST
        url: "{{ credential.hostUrl }}/rest/api/2/issue/{{ twin.ref.issueId }}/comment"
        headers: { "Content-Type": "application/json" }
        body: |
          { "body": "{{ entity.comment.content.orElse("-") }}" }
        expect: { successStatus: [200, 201] }
        retry: NEVER
    authoredId: "{{ last.body.id }}"
```

### The 'inbound' section

The `inbound` describes how ilert handles callbacks: requests the target system sends to the action's **Callback URL** when something changes on its side. It exists only on bidirectional templates, and only takes effect when **Accept callbacks** setting is on. Full schema: [inbound](https://docs.ilert.com/integrations/actions/template/inbound.md).

The `inbound` section has its own variables:

| Variable               | Contains                                                       | Schema                                                                    |
| ---------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `payload`              | The callback body sent by the target system                    | [payload](https://docs.ilert.com/integrations/actions/context/payload.md) |
| `config`               | The action's settings                                          | [config](https://docs.ilert.com/integrations/actions/context/config.md)   |
| `vendor`               | Constants ilert holds for the target system                    | [vendor](https://docs.ilert.com/integrations/actions/context/vendor.md)   |
| `map`                  | Value maps inverted for reading, external value to ilert value | [map](https://docs.ilert.com/integrations/actions/context/map.md)         |
| `last`, `<hydrate id>` | Responses of the `hydrate` reads                               | [hydrate](https://docs.ilert.com/integrations/actions/context/hydrate.md) |

The **Callback URL** contains a secret key. Treat it like a password. If it leaks, rotate it on the action. The old URL stops working immediately, so update it in the target system right away.

| Field                    | Required | Meaning                                                                                                                                                                                  |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `matchBy.externalSystem` | Yes      | The target system, for example `jira`.                                                                                                                                                   |
| `matchBy.externalId`     | Yes      | ITL template that extracts the object's ID from the callback (`payload`). ilert uses it to find the alert or incident linked to that object.                                             |
| `echoBy`                 | No       | ITL template for the ID of the changed item. If ilert wrote that item itself (see `authoredId`), the callback is ignored, so a comment ilert posted does not come back as a new comment. |
| `classify`               | Yes      | Ordered list of `when` / `then` rules. **The first match wins.**                                                                                                                         |
| `fields`                 | No       | Values to extract for the chosen verb, for example `comment`.                                                                                                                            |
| `hydrate`                | No       | Read-only `GET` or `HEAD` requests to fetch details the callback does not include.                                                                                                       |

`classify` verbs:

| `then`    | Effect in ilert                     |
| --------- | ----------------------------------- |
| `ACCEPT`  | Accepts the alert.                  |
| `RESOLVE` | Resolves the alert or incident.     |
| `COMMENT` | Adds `fields.comment` as a comment. |
| `REROUTE` | Reroutes the alert.                 |
| `DROP`    | Ignores the callback.               |

A rule without `when` matches everything and must come last. End the list with one, usually `then: DROP`, so callbacks you did not plan for change nothing.

This is the Jira template's `inbound` block. A new comment becomes an alert comment, an issue moved to a *Done* status resolves the alert, and an issue moved to an *In Progress* status accepts it.

```yaml
inbound:
  matchBy:
    externalSystem: jira
    externalId: "{{ payload.issue.id }}"
  echoBy: "{{ payload.comment.id }}"
  classify:
    - when: "payload.webhookEvent == 'comment_created'"
      then: COMMENT
    - when: "payload.issue.fields.status.statusCategory.key == 'done'"
      then: RESOLVE
    - when: "payload.issue.fields.status.statusCategory.key == 'indeterminate'"
      then: ACCEPT
    - then: DROP
  fields:
    comment: "{{ payload.comment.body }}"
```

## Monitor an action

Open an action to see:

* **Configuration**: the action's current settings.
* **Attached to**: the alerts and incidents the action is currently attached to. Detach one with **Stop auto-run**.
* **Action logs**: every run, the step that ran, and what came back from the target system.

Use **Disable** to pause an action without deleting it. A disabled action does not run and is not offered on alerts or incidents for manual execution.

## Related pages

{% content-ref url="/pages/Npg15Cyo3s3rlfgmriRx" %}
[Overview](https://docs.ilert.com/chatops/overview.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ilert.com/integrations/actions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
