For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

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.

Slack and Microsoft Teams integrations. They are ChatOps integrations with their own setup. See ChatOps.

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

1

Start a new action

Go to Actions in the sidebar and click Create new action.

2

Choose the type

Under Choose an action, pick an integration.

3

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.

4

Set the trigger

Under Trigger mode, choose Automatic or Manual (see 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.

5

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

6

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.

7

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.

8

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.

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.

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.

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, for example {{ entity.summary.orElse("ilert alert").truncate(240) }}.

  • when and classify conditions are ICL, 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

signal

The event that started this run, for example signal.type

execution

This run, for example execution.correlationId

actor

The user or system that made the change

config

The action's settings (see config)

tenant

Your account, for example tenant.ilertDomain

last

The response of the previous request: last.status, last.body

responses

Earlier responses in the current step, by request id

steps

Earlier steps in this run, for example steps.create-issue.status

twin

The object an earlier run created in the target system, for example twin.ref.issueId. nil until the first run creates it

map

Field-mapping results the template publishes by name

vendor

Constants ilert holds for the target system

@ilert

ilert objects looked up by id, for example @ilert.schedules.12.user.email

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.

Every variable and every field of steps and inbound is described as an OpenAPI 3.1 schema: see Template schema for the definition sections and Context schema for the variables. Absent fields are left out rather than set to null, so test them with != nil.

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.

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

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:

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.

The inbound section has its own variables:

Variable
Contains
Schema

payload

The callback body sent by the target system

config

The action's settings

vendor

Constants ilert holds for the target system

map

Value maps inverted for reading, external value to ilert value

last, <hydrate id>

Responses of the hydrate reads

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.

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.

Overview

Last updated

Was this helpful?