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.
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
Something happens to an alert or incident: it is created, accepted, commented on, resolved.
ilert looks up all enabled action for that entity kind, filter by their trigger events and condition expressions.
Suitable actions executed.
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.
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.
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
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.
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.
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.
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.
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
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
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) }}.whenandclassifyconditions are ICL, for examplesignal.type == 'alert.resolved'.
entity
The alert or incident, for example entity.summary, entity.status, entity.priority, entity.url, entity.source.name
twin
The object an earlier run created in the target system, for example twin.ref.issueId. nil until the first run creates it
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 '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 withtrue.
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 assteps.<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:CREATEif the step creates the object in the target system,UPDATEif 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 asresponses.<id>.method:GET,POST,PUT,PATCH,DELETEorHEAD.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, any2xxdenotes success.expect.condition: ICL condition on the response (last) that must also hold to denote success.retry:AUTO(default),SAFE(idempotent), orNEVER. UseNEVERfor 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: CREATEand areferenceWritecreates the twin when it completes.referenceWrite.externalIdis the object's ID in the target system and must be set on everyCREATEstep; otherwise the next run creates a second object.externalUrlis a link to the object that will be attached to ilert's alert.refholds any other values later steps need, such asissueIdandissueKey.Reading it. On later runs for the same alert or incident, steps read the stored values as
{{twin.ref.<field>}}. Before the firstCREATEstep completes there is no twin, andtwin == nilis true.Bidirectional setup (callbacks) use it too. When the target system calls back,
inbound.matchBy.externalIdis matched against the twin'sexternalIdto find the alert or incident. Callbacks about an object with no twin are ignored.
How steps run:
Every step whose
whenevaluates 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 inneedsare skipped. Action logs shows which step failed and the status the target system returned. A failed run is not retried later; only the request-levelretryapplies.
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:
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.
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.
Related pages
OverviewLast updated
Was this helpful?