Flow triggers

A trigger is the mechanism for kicking off a flow in xMatters. Flow Designer includes different types of triggers, which are initiated either when alert activities occur (such as an alert status change, a specific response, or an added comment), or when information is injected into xMatters by an incoming HTTP request or email. Each trigger populates outputs based on the type of trigger, which are available to downstream steps in a flow. Triggers can be easily identified on a canvas by their circular icon.

Triggers only fire if there are steps connected to them; for a flow to execute, it must have at least one trigger and one connected step. (The exception is any legacy Integration Builder triggers, which continue to execute the scripts associated with them.)

If you have existing outbound integrations for a form, they'll appear as triggers on the canvas. You can connect additional steps to these triggers to extend the current functionality of your outbound integrations.

The maximum number of requests you can submit within a one-minute period to xMatters is limited by your pricing plan. If you exceed this limit, your request will be rejected with a 429 error and will not be queued for processing.

Flow triggers

Alert activity triggers

Alert activity triggers kick off flows based on different alert lifecycle activities, including alert status updates, device delivery updates, responses, alert comments, escalations, and targeted recipient failures. Each of these different triggers include a common set of alert properties, and additional properties specific to the type of alert activity.

Activity triggers are associated with an xMatters alert. Depending on if you use a Create Alert step or a messaging form to create the alert, you access these triggers from different places in Flow Designer. Each alert activity trigger can only be used once, so when you add one of these triggers to the canvas, it disappears from the list of options; when you remove it from the canvas, it reappears and is available for you to use in future.

Create Alert step

You can add activity triggers to the Create Alert step by clicking + Activity Triggers below the step on the canvas:

Messaging forms

When you add a messaging form to your workflow, xMatters automatically creates a flow canvas with the same name as the form. Activity triggers for alerts created by the form are available on the Triggers tab of the palette for the associated form. If you've already built an outbound integration with the Integration Builder that uses the trigger, it appears on the canvas.

The Alert Activity section only appears in the palette of canvases associated with a messaging form.

How do I add activity triggers for alerts created by the Create Alert Using a Form step?

When you add a Create Alert Using a Form step to your flow, you select which messaging form to use for the alert. Alert Activity triggers for these alerts are available on the flow canvas associated with the selected messaging form.

Common properties

The common properties output by all alert activity triggers provide information identifying the alert in addition to its status and properties.

Common trigger output details

Property Description Example
event.id The unique identifier (UUID) of the alert.
 e930e32d-b863-4c55-a528-1d2829e3690e
event.eventId ID assigned to this alert by xMatters and used to track its progress through the system. (Also the number used to reference this alert in the Alerts and Tracking reports.) 889003
event.status The current status of the alert. ACTIVE
event.created Date and time the alert was created in xMatters in ISO-8601 format. 2019-01-15T18:03:16.580Z
event.priority The priority assigned to the notification in xMatters (LOW, MEDIUM, or HIGH). HIGH
event.targetedRecipients The recipients targeted for notification.

bjones

mmcbride|Work Email

CustomerCare
event.initiator The target name of the user who initiated the alert. integrationUser
event.properties A JavaScript object containing the property names and values included in the alert.
  • hierarchy property: "USA -> California -> Los Angeles"
  • text property: "High-level summary"
  • number property: 2346
  • combo box property: "Medium"
  • password property: "password123"
  • list property: "item A, item B"

Alert status updates trigger

The Alert Status Updates trigger initiates a flow when an alert is started, suspended, resumed, or terminated. Outputs include the status of the alert and the user who initiated the alert status change.

Examples of when to use this trigger:

  • Automatically update the record in your monitoring tool to add an annotation that the xMatters alert ended.
  • Post alert creation and termination updates to your reporting repository for analytics and observability initiatives.
  • Automatically close the ticket in the source system when the xMatters alert ends.
Alert status trigger outputs
Property Description Example
statusChanged.auditType The change to the alert status that triggered the flow. Can be one of: EVENT_ANNOTATED, EVENT_COMPLETED, EVENT_CREATED, EVENT_RESUMED, EVENT_SUSPENDED, or EVENT_TERMINATED EVENT_TERMINATED
statusChanged.at Date and time the alert status changed in ISO-8601 format. 2019-01-15T18:03:16.580Z
statusChanged.by.id The unique identifier (UUID) of the user who initiated the alert or changed the alert status, or null if it happened automatically (for example, by timeout). e1e427bb-770f-4d47-aa4d-efdd8b64089c
statusChanged.by.targetName The username of the user who initiated the alert or changed the alert status. mmcbride
statusChanged.by.firstName First name of the user who initiated the alert or changed the alert status. Mary
statusChanged.by.lastName Last name of the user who initiated the alert or changed the alert status. McBride

To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.

Device delivery updates trigger

The Device Delivery Updates trigger initiates a flow when a notification is delivered to a device, or when notification delivery fails. Outputs include the user and device that the message was sent to and whether the delivery was successful.

Examples of when to use this trigger:

  • Post details about who was notified and when into a ticket, alert, or chat application so the notification process is clearly visible (and documented).
  • Post details about device notification failures to a list so you can follow up with users who seem to be experiencing delivery issues.
Device delivery trigger outputs
Property Description Example
notification.deliveryStatus The delivery status: Delivered, Failed, or Unchanged. Delivered
notification.recipient.alertContext The alerting path followed to notify the recipient. Antares Service Support > Weekday AM
notification.recipient.id The unique identifier (UUID) of the device the notification was sent to. f51d0fa3-6712-4b4e-9da4-
b8a631f8b8c1
notification.recipient.name The name of the device the notification was sent to. Work Email
notification.recipient.targetName The target name of the device the notification was sent to. mmbride | Work Email
notification.recipient.owner.id Unique identifier (UUID) of the targeted user. e1e427bb-770f-4d47-aa4d-
efdd8b64089c
notification.recipient.owner.firstName First name of the targeted user. Mary
notification.recipient.owner.lastName Last name of the targeted user. McBride
notification.recipient.owner.targetName Username of the device's owner. mmcbride
deliveryStatusUpdated.at Date and time the delivery status was updated in ISO-8601 format. 2019-01-15T18:03:16.580Z
deliveryStatusUpdated.auditType The general category of the device delivery attempt that triggered the flow. Can be one of: NOTIFICATION_DELIVERED, NOTIFICATION_ESCALATED, NOTIFICATION_FAILED, NOTIFICATION_NO_RECIPIENT, or NOTIFICATION_UNCHANGED NOTIFICATION_DELIVERED
deliveryStatusUpdated.delivery
StatusType		 The detailed result or status of the delivery attempt that triggered the flow. A detailed list of delivery status types is available. LIVE_NOTIFICATION_
PROVIDER_DELIVERED
deliveryStatusUpdated.delivery
StatusMessage		 A description of the result of the delivery attempt, which may include error codes. Notification delivered

To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.

Responses trigger

The Responses trigger initiates a flow when a user responds to a message. Outputs include the user and device that made the response, their response choice, and comments added from the mobile app.

Examples of when to use this trigger:

  • Automatically assign an incident when a recipient responds with Accept (or Assign to me or whatever response you have configure for this).
  • Approve or reject change requests based on responses.
Responses trigger outputs
Property Description Example
response.response The response the recipient selected. Assign to me
response.deviceName Name of the device the recipient used when responding to the notification. Android Phone
respondedTo.at Date and time the recipient responded to the notification in ISO-8601 format. 2019-01-15T18:03:16.580Z
respondedTo.by.alertContext The alerting path followed to notify the recipient. Antares Service Support > Weekday AM
respondedTo.by.targetName Username of the person who responded. asamara
respondedTo.by.id The unique identifier (UUID) of the recipient who responded to the notification. 871d855c-1cce-45a2-97e7-f185f51ed753
respondedTo.by.firstName First name of the person who responded. Ali
respondedTo.by.lastName Last name of the person who responded. Samara
respondedTo.auditType The system action that triggered the flow (RESPONSE_RECEIVED) RESPONSE_RECEIVED

To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.

To use the responses trigger, you need the individual response options that you want to trigger flows. If response options are already configured on the messaging form, or were previously configured for a Create Alert step, they appear under the parent trigger when you add it to the canvas:

If there are no response options, you can add them right from within Flow Designer:

To add response options to a Responses trigger:
  1. Click + Add Response (or double-click the Responses parent) to add, remove, or edit response options.
  1. Configure the response options and drag them into the order you want them to appear on the canvas, then click Save. In our MIM scenario, we added "Create major incident" and moved it to the top of the list.

Each response appears as a step on the canvas. You can now connect the steps you want to run when a recipient selects that response.

A few things to know about existing integrations:

  • If you have an outbound integration that uses the Notification Responses trigger, it appears on the canvas but doesn't have the response options delineated since any actions based on different responses are handled in the outbound integration script.
  • Some integrations use response options that are determined at runtime. We've updated our built-in integrations but some packaged or custom integrations still use these. For the time being, you'll need to continue to use an outbound integration using the Notification Responses trigger.
  • For built-in integrations, you are unable to modify or delete the default response options included in the configuration; although you can add additional ones. To modify or delete built-in responses, you'll need to first convert the configuration to a workflow.

Alert comments trigger

The Alert Comments trigger initiates a flow when a user adds a comment from the mobile app, xMatters Inbox, email, Tracking Report, or xMatters REST API. Outputs include the user that made the comment and the content of their comment.

Examples of when to use this trigger:

  • Post each comment to a Slack channel or other chatops application.
  • Populate the free-form text closure details of a ticket or alert (in this case, you could actually perform your response logic in the Alert Comment trigger instead of the response trigger!)
  • Add the comments to a ticket or alert as annotations, recording the work performed on the alert, either for the next person in the resolution chain or for post-incident analysis.
Alert comments trigger output details
Property Description Example
annotation.comment The value of the comment added to the alert by the user. Investigating the root cause now
annotated.at Date and time the comment was added in ISO-8601 format. 2019-01-15T18:03:16.580Z
annotation.author.targetName The username of the user who added the comment. asamara
annotation.author.id The unique identifier (UUID) of the user who added a comment. 871d855c-1cce-45a2-97e7-f185f51ed753
annotation.author.firstName First name of the user who added the comment. Ali
annotation.author.lastName Last name of the user who added the comment. Samara
annotation.response.response The response the user selected when they added a comment, or null if they commented without selecting a response. Assign to me

To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.

Escalations trigger

The Escalations trigger initiates a flow when an escalation occurs in a group. Outputs include the group containing the shift with the escalation, the reason for the escalation, the user that escalated the alert (if it was escalated manually), the type of escalation, the recipients the alert escalated from, and the recipients the alert escalated to.

Examples of when to use this trigger:

  • Automatically launch a new alert that warns a manager when an alert has escalated to the point where an SLA (service level agreement) is in jeopardy.
  • Automatically update a chat room to warn team members when an alert is escalated.
Escalation trigger outputs
Property Description Example
escalation.reason Whether the escalation was triggered by an application or a person (ACTIVE) or by a timeout (PASSIVE). ACTIVE
escalation.escalationType The type of escalation: PEER, MANAGEMENT, or NONE PEER
escalated.at Date and time of the escalation in ISO-8601 format. 2019-01-15T18:03:16.580Z
escalated.by.id For active escalations, the unique identifier (UUID) of the recipient whose response manually escalated the alert. e1e427bb-770f-4d47-aa4d-efdd8b64089c
escalated.by.targetName For active escalations, the username of the recipient who manually escalated the alert. mmcbride
escalated.by.firstName For active escalations, the first name of the recipient who manually escalated the alert. Mary
escalated.by.lastName For active escalations, the last name of the recipient who manually escalated the alert. McBride
escalation.group.id Unique identifier (UUID) of the group in which the escalation occurred. afd56311-86cd-476f-a6ae-51e3d8cadbe0
escalation.group.targetName The name of the group in which the escalation occurred. Deneb Service Team
escalation.group.status The status of the group in which the escalation occurred. ACTIVE
escalation.from An array containing the id (UUID), recipientType, status, and targetName of each recipient at the escalation level from which the escalation occurred. Devices are reported as a person recipient type, corresponding to the device's owner. c68bfa2f-4539-40a9-9e96-
185b7ecde7ff
mmcbride
PERSON
escalation.to An array containing the id (UUID), recipientType, status, and targetName of each recipient at the escalation level to which the escalation occurred. Devices are reported as a person recipient type, corresponding to the device's owner. 98555e21-b7ff-479e-a264-
3e96815fb03d
NOC
GROUP

To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.

Targeted recipient failures trigger

The Targeted Recipient Failures trigger initiates a flow when none of the targeted recipients could be immediately notified for an alert. Outputs include the type of failure, the first 100 targeted recipients, and the total number of targeted recipients.

Examples of when to use this trigger:

  • Automatically notify a chat room that an alert isn’t currently routing to on-call resources.
Targeted recipient failures trigger output details
Property Description Example
targeted.triggerType The type of targeting attempt for which no recipients could be notified: INITIAL_EVENT, TIMED_ESCALATION, or MANUAL_ESCALATION TIMED_ESCALATION
targetingFailed.at Date and time of the targeting failure in ISO-8601 format. 2019-01-15T18:03:16.580Z
targeted.totalRecipients The total number of targeted recipients. 35
targeted.recipients An array containing the id (UUID), recipientType, status, and targetName of each recipient (up to the first 100 targeted recipients). Invalid recipients are returned with a status of "INVALID". f51d0fa3-6712-4b4e-9da4-b8a631f8b8c1
DEVICE
ACTIVE
mmcbride|Work Email

To see the payload behind the scenes, see the information for the equivalent trigger in the Integration Builder.

^ Back to top

 

App triggers

Flow Designer has built in triggers to receive and parse requests from common applications. See our App triggers section for information and instructions on the available triggers.

^ Back to top

 

Callable trigger

A callable trigger initiates a flow when a step in a different flow 'calls' it to run. Adding a callable trigger to the canvas automatically adds an associated callable flow step to the Tools tab of the palette. You can add the callable flow step to one or more flows on any of the canvases in your workflow. Whenever the callable flow step runs as part of a flow, it initiates the callable trigger to run the sequence of steps connected to it.

When you add a callable trigger to your canvas, you'll have to set up its associated callable flow step and define its inputs. The inputs of the callable flow step are available as outputs of the trigger. This allows you to pass information from the calling flow to the steps connected to the callable trigger.

What triggers it: When its associated callable flow step runs in another flow in your workflow.

What information is in the outputs: Inputs of the callable flow step are available as outputs of the callable trigger. This allows you to pass information from the calling flow (the flow containing the callable flow step) to steps connected to the callable trigger. Callable flow steps do not currently return any information from the flow they call, apart from the ID of the request that initiated the callable trigger.

Examples of when to use this trigger: If you want to reuse the same sequence of steps in multiple flows and make your flows more readable and easier to maintain.

  1. Drag the Callable Trigger from the palette onto the canvas (available from Triggers > Utility).
  2. Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
    • If prompted, click to Save Changes to the canvas.
  3. Click Create Callable Flow Step to create the step which you can use to call your trigger.
  4. On the Settings tab, give your callable flow step a name, description, and icon.
    • This helps people looking at the step on the Tools tab understand what the callable flow step does if they add it to their flows.
  5. On the Inputs / Outputs tab, define the inputs of the callable flow step, which will also be available as outputs the callable flow trigger.
    1. When you add the callable flow step to a flow, you can pass information from the previous steps of that flow to the steps connected to the associated callable trigger.
  6. Click Save.
  7. Click Close to return to the trigger configuration screen. The Settings tab of your trigger displays information about its associated callable flow step.
    • Click Open Step Configuration if you want to make further updates to the callable flow step's settings or inputs.
    • Click Show Step in Palette to view the location of the callable flow step on the Tools tab.
  8. If you want to limit who can initiate the trigger, modify the Usage Permissions of its associated callable flow step, available from the step's Settings menu (the gear icon) on the Tools tab of the palette.
  9. You can manage the trigger's flood control settings on the Flood Control tab, or in Workflows > Workflow Tools > Flood Control.

You're now ready to connect the series of steps to your callable trigger, and to add the trigger's associated callable flow step to your flows. Once you've added the callable flow step to one or more flows, the Settings tab of your trigger will include a Usage list of the locations (Canvas > Trigger Name) where the callable flow step is used.

^ Back to top

 

Email Initiation trigger

An Email Initiation trigger initiates a flow when you send an email to the trigger. When the trigger receives an email from a valid sender, it initiates the corresponding flow and uses information from the email to set values for outputs of the trigger, available as inputs to later steps in a flow. Outputs include the email sender, headers, addressees, subject, and body.

If you have an existing integration using the legacy email initiation, we automatically converted to a flow consisting of an Email Initiation trigger and a Create Alert Using a Form step.

Examples of when to use this trigger:

  • To inject information from any external system capable of sending an email message; this might include custom applications or almost any cloud-based application, monitoring system, social media platform, e-commerce platform, or customer relationship management tool.
Email Initiation trigger output details
Property Description Example
email.to

All the email addresses included in the To: field of the email that triggered the flow.

[0]: mmcbride@hq54b.example.com

[1]: DatabaseAdmins@hq54b.example.com
email.sender The user ID of the email initiator. integrationUser
email.subject The subject of the email message. IT Alert: Database Unavailable
email.htmlBody The content of the email sent as HTML. <html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40"> <head> ... </html>
email.plaintextBody The content of the email sent as plain text. The Oracle Database is not available.
email.headers A JavaScript object containing the headers of the email.
  • date: Wed, 5 Jun 2019 21:51:31 +0000
  • content-language: en-US
  • from: admin <admin@example.com>
  • MIME-version: 1.0
  • etc.
email.senderIp IP address of the email initiator. 192.0.2.132
email.recipients Target names of users or groups included in the To: field of the email that triggered the flow. mmcbride,DatabaseAdmins

If you want to pull out information from the email body to make the details available as inputs to steps downstream, you can create a custom email parser step. Check out the instructions on our support site.

The unique email address that you use to initiate a flow is created from a target name, the trigger ID, and hostname of your xMatters deployment in the following syntax: <name>@<triggerID>.<hostname>

  • <name>: The name can be the user ID of a specific user or the name of a group. For example, mmcbride@hr54b.mycompany.xmatters.com or DatabaseAdmins@hr54b.mycompany.xmatters.com. If a group name includes spaces, you can enclose it in double quotes; however, we recommend not using spaces in group names because many popular email clients do not permit spaces in email addresses.
  • <triggerID>: By default, the trigger ID is a randomly generated combination of alphanumeric characters. You may want to change the trigger ID to be more readable, or you may want to change it to something hard to guess for security purposes. The trigger ID must be unique within your company.
  • <hostname>: The URL that you use to access the xMatters web user interface without the "https://". For example, the hostname for https://mycompany.xmatters.com is mycompany.xmatters.com

If your hostname includes a regional or specific instance indicator, do not include it in the target email format. For example, if the URL you use to access xMatters is mycompany.na1.xmatters.com, do not include the na1 portion of the URL in the email address. Use just mycompany.xmatters.com.

You can find the target ID and sample email address for an Email Initiation trigger on its configuration screen in Flow Designer.

Understanding how Flow Designer uses trigger email recipients

Email Initiation triggers in Flow Designer do not create an alert in xMatters when they are initiated. The target name of the user or group named in the initiation email is mapped to the email.recipients output of the trigger, which you can use as an input to later steps in your flow, such as for the recipients of a Create Alert Using a Form step. To include more than one target name in the email.recipients output, add multiple addresses to the To: line of the email (one for each user or group), using the format described above.

For example, if the To: field of your trigger email includes the following user and group:

To: mmcbride@hr54b.mycompany.xmatters.com; DatabaseAdmins@hr54b.mycompany.xmatters.com; AllEmployees@hr54b.mycompany.xmatters.com

Then the email.recipients output would include this comma-separated list of target names you could use directly as input to the recipient field of an xMatters alert step:

mmcbride,DatabaseAdmins,AllEmployees

Flow Designer email triggers accept 9 and 10 character BATV-encoded email addresses. Be aware that even though spaces are allowed in email addresses, many popular email clients do not permit them, even when enclosed in quotation marks. We recommend not using spaces in group names if you plan to include them on a trigger initiation email and use them as recipients inputs on another step in a flow.

The Email Initiation trigger lets you select whether initiation emails can be sent from any email address or are only accepted when they are sent from an email address assigned to a device in xMatters.

For example, lets say Mary McBride has a work email device configured in xMatters with the address mmcbride@your-company.com. She also has a personal maryrocks@cloud-email.com address, but it's not assigned to a device in xMatters.

If the trigger is set to allow initiation from any address, Mary could send an email from her maryrocks@cloud-email.com address to initiate the Email Initiation trigger and execute the connected flow. The flow authenticates using the Authenticating User selected in the trigger settings (which may or may not be Mary).

If the trigger is set to only allow initiation from an address associated with an email device in xMatters, Mary has to send the email using her mmcbride@your-company.com email; emails from maryrocks@cloud-email.com are rejected. When Mary sends an email from a valid email address, the trigger is initiated and the flow executed using her credentials.

  1. Drag the trigger from the palette onto the canvas.
  2. Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
  3. Change the Trigger Label if you'd like to customize the trigger's name for your flow.
  4. Select the authentication method:
    • Send from any email: An email sent from any email address will trigger the flow. The flow runs using the credentials of the user selected in the Authenticating User field.
    • Send from an xMatters email device: Only emails sent from an address associated with a valid xMatters device will trigger the flow. The flow runs using the credentials of the user associated with the email address.
  5. Optionally, customize the Trigger ID. You may want to change the trigger ID to be more readable, or you may want to change it to something hard to guess for security reasons.
  6. Click Copy Address to copy the trigger's email address to your clipboard, so that it's available when you're configuring an external system to email Flow Designer, or to share with other users who want to initiate the flow by email.
    1. The sample email address shows how to initiate the trigger with your target name. When you initiate the trigger by email, you can replace your user ID with a different user ID or group name.
  7. If you'd like, you can also click Test Email to automatically open your default email program so that you can send a test email to your trigger's email address and see if it triggers your flow (if you selected Send from an xMatters email device, make sure your default email is associated with an email device).
  8. Click the Flood Control tab to edit the trigger's default flood control settings. For more information about these settings, see Trigger Flood Control.
  9. Click OK.

To give you the flexibility to trigger a flow without creating an alert, the email doesn't automatically initiate an alert in xMatters. If you want to create an alert when the Email Initiation trigger is initiated, simply add a Create Alert step to your flow, either right after the Email Initiation trigger or after additional steps that gather more information to enrich the alert notification.

How can I assign an external system a valid email address in xMatters?

This is only applicable if you want to limit the trigger initiation to addresses associated with an email device in xMatters.

To enable xMatters to recognize emails from your external system, do one of the following:

  • Add the external system email address as a device for a user that is already authorized to initiate the form.
  • Create a new user in xMatters to represent the external system. Give this user permission to access to the flow, and create a device for the external system email address.
  • Use a service that can receive an email message from your external system and resend it using an email address that is authorized to initiate the flow.

Check the Devices screen in a user's profile to confirm that the email address that you are sending the initiation email from matches the address for one of their email devices.

If your system does not have the ability to send email messages, check out services like Zapier, which can be used to send email messages from a wide range of popular applications.

What happens if I use the Cc: or Bcc: lines instead of the To: line?

The Cc: and Bcc: fields are treated the same as the To: field. You can initiate alerts by including email addresses in the Cc: and Bcc: fields. Users or groups added to the Cc: and Bcc: fields are also included in the email.recipients output.

The sample email address shows how to inject my own target name with the email. How can I add other uses or groups to the To: field so they're included in the email.recipients output?

  • To add another user instead of yourself, use their user ID before the @ symbol in the trigger email address.
  • To send to a group, use the group name before the @ symbol. (Spaces or quotation marks in the name of the group are not recommended.)
  • To target multiple recipients, use multiple addresses on the To: line.
Can the name of a group in the To: line contain spaces if enclosed in double quotes?

Even though spaces are allowed in email addresses, many popular email clients do not permit them. Some email clients may accept names with spaces if they are enclosed in quotation marks (for example, "Database Admins"@hr54b.mycompany.xmatters.com). As a best practice, if you plan to include a group or dynamic group on a trigger initiation email and use them as recipients inputs on another flow, we recommend renaming them to not include spaces.

If you do not want to rename your group or dynamic group to remove spaces, you can use its UUID instead. You can acquire the UUID using the xMatters REST API or from the URL when viewing the group overview. For example, if the URL when you are on the Overview tab of your group is https://mycompany.xmatters.com/xmatters/ui/groups/d6a58757-2448-44f4-aa63-e62169a7be8a/overview, then the UUID would is d6a58757-2448-44f4-aa63-e62169a7be8 and you can include it in the To: line as d6a58757-2448-44f4-aa63-e62169a7be8@hr54b.mycompany.xmatters.com. Alternatively, you could create a new group without any spaces in its name and include the original group as a nested group with a 24x7 shift, and then include the new group in the To: line instead.

What happens if I put email addresses for different flows in the same email?

Flow Designer will trigger each flow that you provided a trigger email address for in the To: field of the email, as if you had emailed the trigger addresses separately.

What happens if you include "regular" (non-trigger) email addresses in the To: line?

If you include an additional email address not associated with a flow trigger in the To: line along with one or more trigger email addresses, you'll send that email address a copy of the email. The flow is triggered but that email is not included in the trigger outputs. Email addresses must follow the trigger email initiation format to be included in outputs of the trigger.

What happens if my email server changes the To: address when sending?

Some email servers have a feature called "CNAME expansion" enabled that can alter the "To:" address of an email to include routing information. So an email sent to mmcbride@traveladvisory.example.xmatters.com might be changed during transit through your email server to something more like mmcbride@us1-west-1.mail_traveladvisory.example.xmatters.com.

To address this problem, you'll need to work with your IT team to disable the CNAME expansion feature or setting on your SMTP email server.

^ Back to top

 

Scheduled Trigger

Scheduled Triggers let you automatically trigger flows on a specific schedule. You can set a Scheduled Trigger to query another system on a daily or hourly basis and process the information without the need for additional complexity in your flows. You can view all scheduled triggers in your system on the Triggers report.

What triggers it: The trigger runs a flow on a set schedule.

What information is in the outputs: The time when the trigger was scheduled to run in epoch, UTC, and ISO with time zone formats.

Examples of when to use this trigger:

  • To check the status of a specific service.
  • To integrate with a tool via API that cannot send signals to Flow Designer.

Scheduled trigger output details

Property Description Example
Scheduled Date Time (epoch)

Time when the trigger was scheduled to run using epoch format.

1715786816
Scheduled Date Time (UTC) Time when the trigger was scheduled to run in UTC using ISO format. 2024-05-15T15:26:56Z
Scheduled Date Time (Time Zone) Time in the configured time zone when the trigger was scheduled using ISO format. 2024-05-15T11:26:56-04:00
  1. Drag the Scheduled Trigger from the palette onto the canvas. It is located under the Utility section of the Triggers tab.
  2. Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
  3. On the Setup tab, click the pencil icon next to the step's name to modify its label on the canvas (optional).

  4. Select the user whose credentials you'd like to use to trigger the flow. Click the list to display users who can authenticate the trigger, or start typing a name into the search field to filter the list (two characters are required). Alternatively, you can create an integration user to use as the authenticating user.
  5. Set the time zone in which the scheduled trigger should run. If no time zone is selected, the time zone of the authenticating user is used.
  6. Use the date and time pickers to set the first occurrence of the trigger.
  7. Set how often the trigger should repeat, by selecting either Hourly or Daily and entering a value into the field.
  8. To add an optional End Date, click Add End Date, select On Date and user the calendar to set the end date.
  9. Review the information box to confirm that the trigger will fire on the schedule you want.

At this point, you can either enable the trigger and click Done to save your changes, or save the changes leaving the trigger disabled. You can create Scheduled triggers and leave them disabled until you're ready to use them. When you're ready to run the Scheduled Trigger, click Enable.

The number of schedule triggers that can be enabled at one time is determined by your plan type. If you have more scheduled triggers on your canvas than your plan type allows, when you save the canvas, the maximum number of scheduled triggers are enabled, and the rest are left as disabled. You can then manually enable and disable the triggers as required.

Once your scheduled trigger is on your canvas and configured, you have the following options available on the canvas: 

  • View the next occurrence of when the trigger will run.
  • Manually run the trigger.
View the next scheduled occurrence

Hover over the trigger to view the next occurrence of any Scheduled Trigger. A tool tip appears displaying the next time the trigger will run.

Manually run the trigger

When you have a trigger on the canvas, you can test the configuration to ensure the everything works as you expect. Rather than re-configure the trigger to test it, expand the options menu and select Trigger Now. The trigger immediately runs based on its current configuration settings.

^ Back to top

 

HTTP Request trigger

HTTP Request triggers initiate a flow when they receive a POST request sent to the trigger's URL. The HTTP trigger parses the payload from the incoming HTTP request, then extracts information from the payload and maps it to user-defined outputs of the trigger to be available as inputs to later steps in a flow.

What triggers it: The trigger receives an incoming HTTP request from an external system to the trigger's URL.

What information is in the outputs: Properties or information from the request mapped to outputs by the user that created the trigger.

Examples of when to use this trigger:

  • To inject information into Flow Designer from any system capable of sending a POST request.

HTTP request trigger output details

HTTP triggers do not have a standard set of outputs because the outputs, and mapping of request properties to these outputs, are defined by the user that created the trigger.

Each HTTP trigger is authenticated independently, using the authentication method set by the trigger creator (unless the creator set the trigger to allow all methods).

Depending on the allowed authentication methods, you might need to select the authenticating user that should be used to authenticate requests. Regardless of the method chosen, any requests submitted to the trigger URL have the same permissions in xMatters as the authenticating user, whether that user was set in the step or their credentials were included in the request.

Authentication methods

When creating an HTTP trigger, you can allow only one of these methods to be used or select the Allow all methods option to allow any of them to be used. It's recommended that you choose the most secure method the calling system supports

URL Authentication

The system generates an API key unique to the authenticating user selected when the trigger is configured and appends that API key to the trigger URL. Any requests submitted to this URL have the same permissions in xMatters as the authenticating user. The URL does NOT grant permission to log into the xMatters web user interface.

URL authentication is the least secure method of authentication because anyone with access to the URL can trigger the flow. This authentication method is not recommended unless the flow does not need to be secured.
Basic Authentication

Basic authentication requires the calling system to store the credentials of an xMatters user with permissions to access the workflow the trigger belongs to. If the user resets their password in xMatters, you must also update the calling system with the new password for it to continue to be able to trigger the flow.

You cannot use API key credentials to trigger a flow that is set to require Basic authentication; you must provide an xMatters user ID and password.
API Key Authentication

API Key authentication uses a randomly generated API key and secret which are then stored in the calling system. To authenticate a request using API key authentication, use basic authentication with the API key as the username and the secret as the password.

An API key credential has the same permissions within xMatters as the associated user, and can authenticate any request as that user, including to trigger a flow, submit requests to the xMatters REST API, or initiate an integration. You cannot use the API key and secret to log into the xMatters web user interface. If your account does not have an API key credential, you can create a new set of API Key credentials in your profile (or the profile of a specific integration user).

You can view your API key credentials or the credentials for any user you supervise on the API Keys tab within the user profile.
OAuth Authentication

OAuth authentication requires you to provide the OAuth credentials of an xMatters user to trigger the integration. For more information about using OAuth with xMatters, see OAuth authentication.

Once you create and share an HTTP trigger, you can reuse it in any flow. You can also create new versions of the trigger as your needs change.

Step 1: Create the HTTP trigger

When you create a new custom HTTP trigger, the first thing to do is set up how it appears in the palette: the name, description, and icon.

  1. On the Triggers tab of the palette, click Create HTTP Trigger. This opens the New HTTP Trigger dialog box.
  2. On the Settings tab, give the trigger a name and description. These appear in the palette, and help people know what this trigger does and if it's something they should use. People can give the trigger a different label when they add it to the canvas.
  3. To change the icon used for the trigger, click Select Image. This opens an image library with a selection of icons, including a few default ones and any icons you've already added for your organization.
  4. Click an icon in the library to select it. To add a new icon to the image library, click the Choose a file to upload link and browse to the file you want to use.
    1. For the best appearance on the canvas, we recommend using images that are 36 x 36 pixels. The maximum file size is 250 KB, and you can use a variety of common image formats: jpg, jpeg, gif, and png.
  5. Once you've selected your image in the Image Library, click Select to go back to the step settings.
  6. Set the step state and version information.
  7. Select the Run Location where the step is allowed to run. Allowing the step to run on an xMatters agent lets it update and retrieve information from systems behind your corporate firewall.
    • Cloud: The step can only run in the cloud.
    • xMatters Agent: The step can only run on an xMatters agent.
    • Both: The person using the step in a flow can select where the instance of the step will run when they configure it.
  8. Select the authentication method you want to allow the step to use. You can also select Allow all methods if you want users to be able to pick the method used when they configure the trigger.
  9. If the trigger requires a specific payload, click + Add Configuration Payload and then enter it in the Configuration Payload field. Make sure to use the same format as the source application so users of the trigger can copy and paste it when they're configuring the webhook.
  10. Click Close to return to the New HTTP Trigger configuration screen.
  11. Click Save.

Step 2: Create the outputs

When you define the outputs, you're deciding what information this trigger should provide to steps further downstream. For properties from the request to be available to steps later in the flow, you need to use the script to map them to the outputs of the trigger (see the next step).

  1. On the Outputs tab, click Add Step Output to create a new output.
  2. Enter a name for the output. This name can be used to reference it in the script editor, and appears in the step setup screen where people can drag it into the input of a connected step.
  3. Click Add Step Output for each additional output you'd like to create. To delete an output, click the 'x' icon next to the output.
  4. When you're done adding outputs, click Save.

Step 3: Map the outputs

The Script tab is where you define the internal logic that takes the HTTP request from another application, transforms the incoming information, and maps it to the outputs. When you create a new HTTP trigger, the script only brings what is included in the payload. Properties of the form associated with your flow canvas are not available as outputs because HTTP triggers do not use the form to create an alert in xMatters. You need to map properties from the request to outputs of the trigger to use these properties in steps in your flow.

The Script tab includes an example script showing how to parse the payload from an incoming HTTP request, then extract information from the payload and map it to outputs. You can use it as a template and customize it to work with your flow. The trigger's built-in request object enables you to access elements of the request, including the payload contained in the request body and any URL parameters.

The following instructions describe how to add and configure an HTTP trigger in your flow.

HTTP trigger authentication

Each HTTP trigger is authenticated independently, using the authentication method set by the trigger creator (unless the creator set the trigger to allow all methods).

How to configure an HTTP trigger

  1. On the Triggers tab of the palette, under HTTP Request, drag the custom HTTP trigger you'd like to use onto the canvas.
    • You can filter the HTTP triggers by triggers you own, triggers others have shared with you, or all triggers you have permission to use.
  2. Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
  3. Change the Trigger Label if you'd like to customize the trigger's name for your flow.
  4. If the step allows any authentication method, select the method you want to use in the Initiation settings.
  5. If required by the authentication method, select whose credentials you'd like to use to trigger the flow. Click the list to display users who can authenticate the trigger, or start typing a username into the search field to filter the list (two characters are required).
    • Users only appear in this list if you supervise them (or are a company supervisor) and they are assigned the REST Web Services role.
  6. Copy the trigger URL and Configuration Payload, if one is provided – you'll use these to configure the HTTP POST request that will be sent to the trigger.
  7. Click Run Location to set where the trigger runs. This tab only appears if the trigger is allowed to run on an xMatters agent.
  8. Select the location where you want this step to run: Cloud or xMatters Agent.
    • If you set it to xMatters Agent, select one or more agents from the list of available agents. To select an agent from the list, you must be a registered user of the agent and it must be version 1.4.1 or later. If you don't have any agents configured, click Add an xMatters Agent to go to the Agents page, which has instructions for installing the agent.
  9. Click the Flood Control tab to edit the trigger's default flood control settings. For more information about these settings, see Trigger Flood Control.

To initiate the trigger, send a POST request to the trigger URL using the requirements of the configured authentication method:

  • URL Authentication: Send an HTTP POST request to the trigger URL.
  • Basic Authentication: Send an HTTP POST request to the trigger URL using basic authentication and an xMatters username and password.
  • API Key Authentication: Authenticate the request using basic authentication and set the username to the API key and the password to the secret.
  • OAuth Authentication: Include an access token in the request header. A client ID is required to obtain and refresh access tokens in the xMatters REST API. You can find the client ID for your company under Workflows > OAuth. For more information about using OAuth with xMatters, see OAuth authentication.

You can also click View Instructions for instructions on how to trigger the flow.

If you want to view the results of the trigger initiation in the Activity panel, make sure you've connected steps to the trigger. If the trigger isn't connected to anything, no activity information appears.

If you have permissions to edit a custom HTTP trigger, you can edit the configuration or create a new version of the trigger, share the trigger, or delete it (as long as it's not used in a flow). Click the settings menu for the trigger (the gear icon) and select Edit, Usage Permissions, or Delete.

^ Back to top

 

Simple Webhook - Alerts trigger

A Simple Webhook - Alerts trigger initiates a flow so you can create an alert and send notifications. Send an HTTP Post request to the trigger URL using the provided configuration payload. Outputs of the trigger include information about the alert and its intended recipients. Connect a Create Alert step to the trigger to generate the notifications.

Examples of when to use this trigger: As an easy way to set up a simple flow that alerts your users when you send a webhook to the trigger URL using a provided payload.

What triggers it: The trigger receives an incoming HTTP request to the trigger's URL from an external system.

What information is in the outputs: The outputs of the trigger include information about the alert and its intended recipients, as defined in the configuration payload sent by the source application.

Simple Webhook - Alerts trigger outputs

Output Description Example
Recipients Target names of users or groups to target as recipients of the alert. mmcbride,akaur
Summary A brief summary of important information to use as the subject of the notifications. An alert was triggered
Description Additional details to include in the body of the notifications. The alert's impacted area
Priority Priority level of the alert in xMatters (HIGH, MEDIUM, or LOW). MEDIUM
  1. Drag the Simple Webhook - Alerts trigger from the palette onto the canvas. It is located under the Utility section of the Triggers tab.
  2. Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
  3. On the Settings tab, click the pencil icon next to the step's name to modify its label on the canvas (optional).
  4. Select the authentication method you want to allow the trigger to use. You can select Allow all methods if you want the trigger to accept any of the available authentication methods.
  5. Select the user whose credentials you'd like to use to trigger the flow. Click the list to display users who can authenticate the trigger, or start typing a username into the search field to filter the list (two characters are required). Alternatively, you can create an integration user to use as the authenticating user.
  6. Copy the URL and Configuration Payload and use them to set up the webhook in the source application.
  7. Click the Flood Control tab to edit the trigger's default flood control settings. For more information about these settings, see Trigger Flood Control.
  8. Click Done.
  9. Drag the Create Alert step from the palette onto the canvas and connect the trigger to it. It is located under xMatters on the Tools tab.
  10. Double-click the Create Alert step to open its configuration screen (or select it and click the pencil icon) and do the following:
    1. On the Setup tab, drag the Recipients output of the trigger into the Recipients field.
    2. Use the Message Templates to define the Email / App, Text, and Voice notifications for your alert, using the Summary and Description outputs of the trigger in the message subject and content.
    3. On the Handling & Overrides tab, expand the Alert Handling drop-down and select Use Output or Constant Value for the Priority field, then drag the Priority output from the trigger into this field.
  11. Define the response options, device settings, and other options for your alerts. For detailed instructions, see our Create Alert step documentation.
  12. Click Done.
  13. Save the canvas.

^ Back to top

 

Simple Webhook - Incidents trigger

A Simple Webhook - Incident trigger initiates a flow when you send an HTTP POST request to xMatters so you can initiate an incident and engage resolvers. Outputs of the trigger include information about the incident and its intended resolvers. Connect an Initiate Incident step to your flow to initiate an incident in xMatters, and use a Create Alert step to generate the notifications.

Examples of when to use this trigger: As an easy way to set up a simple flow that initiates an incident and alerts users when you send a webhook to the trigger URl using a provided payload.

What triggers it: The trigger receives an incoming HTTP request to the trigger's URL from an external system.

What information is in the outputs: The outputs of the trigger include information about the incident and its intended resolvers, as defined in the configuration payload sent by the source application.

Simple Webhook - Incidents trigger outputs

Output Description Example
Summary A brief summary of important information to help responders quickly triage the incident. An incident was detected.
Description Additional details to help responders diagnose and resolve the problem. There is a problem that was detected that triggered this incident.
Severity The importance of resolving the incident relative to other issues. MEDIUM
Impacted Services Business, technical, or external services impacted by the incident. API,Webstore
Resolvers Names of users or groups to target as resolver of the incident. mmcbride,Proxy,Web Team
Incident ID ID of the incident that can be used to look up whether an alert with a matching incident ID already exists. INC-1234
Incident Commander Target name of the user assigned as Incident Commander. If no one is specified, the user who initiated the flow is assigned this role. mmcbride
  1. Drag the Simple Webhook - Incidents trigger from the palette onto the canvas. It is located under the Utility section of the Triggers tab.
  2. Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
  3. On the Settings tab, click the pencil icon next to the step's name to modify its label on the canvas (optional).
  4. Select the authentication method you want to allow the trigger to use. You can select Allow all methods if you want the trigger to accept any of the available authentication methods.
  5. Select the user whose credentials you'd like to use to trigger the flow. Click the list to display users who can authenticate the trigger, or start typing a username into the search field to filter the list (two characters are required). Alternatively, you can create an integration user to use as the authenticating user.
  6. Copy the URL and Configuration Payload and use them to set up the webhook in the source application.
  7. Click the Flood Control tab to edit the trigger's default flood control settings. For more information about these settings, see Trigger Flood Control.
  8. Click Done.
  9. Drag the Initiate Incident step from the palette onto the canvas and connect the trigger to it. It is located under xMatters on the Tools tab.
  10. Double-click the Initiate Incident step to open its configuration screen (or select it and click the pencil icon).
  11. Drag outputs of the trigger into their corresponding fields on the Setup tab of the Initiate Incident step.
  12. Click Done.
  13. Drag the Create Alert step from the palette onto the canvas and connect the Initiate Incident step to it. It is located under xMatters on the Tools tab.
  14. Double-click the Create Alert step to open its configuration screen (or select it and click the pencil icon) and do the following:
    1. On the Setup tab, drag the Recipients output of the trigger into the Resolvers field.
    2. Use the Message Templates to define the Email / App, Text, and Voice notifications for your alert, using outputs of the trigger in your message subject or content.
  1. Define the response options, device settings handling options, and other options for your alerts. For detailed instructions, see our Create Alert step documentation.
    1. Note that only responses with a Positive contribution value will display the responder as "Engaged" in the Resolvers list in the Incident Console.
  2. Click Done.
  3. Save the canvas.

^ Back to top

 

Incident Initiation trigger

The incident initiation trigger (formerly known as the form trigger) lets you and your team initiate incidents by filling out and submitting a Flow Trigger form (you need a form of this type in your workflow to configure an initiate incident trigger). This lets you initiate an incident without sending notifications if your process doesn't require it.

Examples of when to use this trigger: This step is primarily used when you want to initiate an incident within a custom incident management workflow.

What triggers it: When the associated flow trigger form is submitted. An Initiate Incident step must also be connected to the initiate incident trigger.

What information is in the outputs: Properties and parameters defined in the layout of the associated flow trigger form. The values at runtime depend on what's defined on the form layout and what's entered when the form is submitted.

  1. Drag the Incident Initiation trigger from the palette onto the canvas. It is located under the Incidents section of the Triggers tab.
  2. Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
  3. Select the form to use for initiating the flow and click Next.
    • You can also create a form from the trigger configuration screen if you don't have any existing flow trigger forms available to use, or if the available forms don't suit your needs. You can customize the new form's layout later.
    • You can't switch the form used by the step after you click Next; if you decide you want to target a different form, delete this instance of the step from the canvas and add a new incident initiation trigger.
    • The step takes its label from the associated form.
  4. In the Flow Trigger Form section, click Customize Form to open the associated form's Layout page in a new tab — you can customize the form there.
  5. In the Enable Trigger section, choose whether to enable this trigger in the Web UI and Mobile App — this allows people to use the form to initiate an incident from the Incidents list and widget on the dashboard, the xMatters mobile app, and from within chat apps connected to xMatters.
    • Sender permissions and enabling the form can also be set on the associated form.
    • Enabling the form for mobile also controls if the form is available to initiate incidents from the xMatters bot in Slack and Microsoft Teams.
  6. In the Permissions section, click Edit Permissions to allow additional users to submit the associated form.
    • You can select either users or roles; if you select a role, any users assigned that role can submit the form (for example, "Incident Managers"). If your flow includes a Create Alert Using a Form step, make sure you also set the same sender permissions on its associated messaging form, otherwise the flow might encounter errors at runtime.
  7. Click the Flood Control tab to edit the trigger's default flood control settings. For more information about these settings, see Trigger Flood Control.
  8. Click Done.

^ Back to top

 

Incident Automation trigger

The incident automation trigger lets you and your team automate a flow from the Incident Console or on an incident service dependencies map. To configure an incident automation trigger, you need to associate it with a Flow Trigger form in your workflow. The name of the associated flow trigger form will be the name of your automation, which you can run from an incident or an impacted service without leaving your incident resolution process.

The ability to create and run automations is available in Base and Advanced plans.

Examples of when to use this trigger: This step is primarily used by incident commanders and resolvers to run an automated process that can help to mitigate the effects of an incident or even resolve an issue. While they are viewing an incident or looking at an incident's impacted service, they can easily initiate flows (for example: send an alert, notify resolvers, or roll back a deployment) without navigating away from the incident or service.

What triggers it: When you select the automation on the Incident Console or on a service dependencies map. It is triggered when you submit the flow trigger form associated with the incident automation trigger.

What information is in the outputs:

  • Form Properties: Properties and parameters defined in the layout of the associated flow trigger form. The values at runtime depend on what's defined on the form layout and what's entered when the form is submitted.
  • Automation Context: Details of the incident from which the automation was triggered. The values at runtime represent the state of the incident when the automation was run.

Automation Context output details

Property Description Example
Incident ID The unique ID of the related incident. INC-123
Summary The summary of the related incident. Website is down
Description The description of the related incident. Customers can't access website
Severity The severity assigned to the related incident in xMatters. CRITICAL
Severity Level The severity level assigned to the related incident in xMatters. 500 (critical)
Status The status assigned to the related incident. In Progress
  1. Drag the Incident Automation trigger from the palette onto the canvas. It is located under the Incidents section of the Triggers tab.
  2. Double-click the trigger to open its configuration screen (or select it and click the pencil icon).
  3. Select the form to use for initiating the flow and click Next.
    • You can also create a form from the trigger configuration screen if you don't have any existing flow trigger forms available to use, or if the available forms don't suit your needs. You can customize the new form's layout later.
    • You can't switch the form used by the step after you click Next; if you decide you want to target a different form, delete this instance of the step from the canvas and add a new incident automation trigger.
    • The step takes its label from the associated form.
  4. In the Flow Trigger Form section, click Customize Form to open the associated form's Layout page in a new tab — you can customize the form there.
  5. In the Enable Trigger section, choose whether to enable this trigger and allow people to run the automation on the Incident Console and on incident service dependencies maps.
    • Sender permissions and enabling the trigger can also be set on the associated form.
  6. In the Permissions section, click Edit Permissions to allow additional users to run the automation.
    • You can select either users or roles; if you select a role, any users assigned that role can submit the form (for example, "Incident Managers"). If your flow includes a Create Alert Using a Form step, make sure you also set the same sender permissions on its associated messaging form, otherwise the flow might encounter errors at runtime.
  7. In the Permissions section, toggle on 'Share this automation for use in other workflows.' to allow other workflows to use this automation.
    • If the toggle is turned on, it will indicate how many workflows are using the shared automation. To add the shared automation to a workflow, select Manage Shared Automations from the workflow settings on the main Workflows page.
    • If you decide to turn off the toggle and stop sharing the automation, a modal will pop up with a list of the workflows that are using it and may potentially break if you disable sharing.
  8. In the Associated Service section, you can select a service to associate with the automation or leave this field blank. Note that you can only choose one service to associate with an automation. Associating a service with an automation will enable these features:
    • If you sort by ‘Most Relevant’ in the Automation section of the Incident Console, the automation will be grouped together with other automations associated with the same service.
    • You will be able to run the automation by selecting the associated service from the Impacted Services section of the Incident Console and the service dependencies map of the incident.
    • Associating a service with an automation enables a checkbox option where you can choose to limit the usage of the automation to the members and supervisors of the group that owns the associated service. Note that if you select this checkbox, you still need to ensure that the group members and supervisors can run the automation under the Permissions section.
  9. Click the Flood Control tab to edit the trigger's default flood control settings. For more information about these settings, see Trigger Flood Control.
  10. Click Done.

^ Back to top

 

Incident activity triggers

The Initiate Incident step includes built-in triggers that you can use to trigger flows when certain conditions change or a particular action is taken on an incident, including status changes, severity changes, and notifications to engage as incident resolvers. These triggers include a common set of incident context outputs, plus additional outputs specific to the type of trigger.

Incident activity triggers are associated with an xMatters incident. You can add incident activity triggers to the Initiate Incident step by clicking + Add Triggers below the step on the canvas.

Incident trigger context

Incident activity triggers share a common set of 'Incident trigger context' outputs with details about the incident at the time the trigger fired. You can use these outputs to pass current incident details to steps further along in your flow.

Incident trigger context outputs
Output Description Example
Incident ID Unique ID of the related incident. INC-47
Incident UUID UUID of the related incident in xMatters. e930e32d-b863-4c55-a528-1d2829e3690e
Summary Summary of the related incident. Web Server Down
Description Description of the related incident. The web server is down. We've got 30 min to get it back up.
Severity Severity assigned to the related incident in xMatters (CRITICAL, HIGH, MEDIUM, LOW, or MINIMAL). MEDIUM
Severity Level Numeric severity level assigned to the related incident in xMatters (CRITICAL - 500, HIGH - 400, MEDIUM - 300, LOW - 200, or MINIMAL - 100). 300

Status

 Status assigned to the related incident. In Progress
Incident Commander First Name First name of the incident commander in xMatters. Aarohi

Incident Commander Last Name

 Last name of the incident commander in xMatters. Kaur
Incident Commander User ID ID of the incident commander in xMatters. akaur
Initiator First Name First name of the xMatters user who initiated the incident. Ali
Initiator Last Name Last name of the xMatters user who initiated the incident. Samara
Initiator User ID ID of the xMatters user who initiated the incident. asamara
Impacted Services Comma-separated list of the services reported as impacted by the incident. API,Customer Quota,Proxy
Stakeholders Target names of users or groups included as stakeholders of the incident. mmcbride,DatabaseAdmins
Incident properties specific to incident type Includes any incident properties defined for this type of incident and their values.  

Status Change trigger

The Status Change trigger initiates a flow when an incident's status in xMatters changes to a specified value. Outputs include the new status, old status, the name of the user who changed the status, the note the user added when the status was changed, and context about the incident at the time the trigger was initiated.

Examples of when to use this trigger:
  • Automatically update a chat room to notify resolvers when an incident’s status is updated.
  • Automatically update external applications to note when the incident's status is updated.
  • Automatically close a ticket in external applications when an incident's status is changed to resolved in xMatters.
  • Automatically send a new notification to resolvers when an incident's status has changed so appropriate action can be taken.
Status Change trigger outputs
Output Description Example
New Status New status assigned to the incident. Resolved
Previous Status Previous status of the incident. In Progress
User ID ID of the xMatters user who updated the incident's status. mmcbride
User First Name First name of the xMatters user who updated the incident's status. Mary
User Last Name Last name of the xMatters user who updated the incident's status. McBride
Note Reason for the change in status, if provided by the user. The incident has been resolved.
  1. Under the Initiate Incident step, click + Add Triggers.
  2. Hover over Status Change and select the status level you want to create a flow for. You can select each level once, so when you add one of the available status change triggers to the canvas, it disappears from the list of options; when you remove it from the canvas, it reappears and is available for your use in future.

  1. Once added, the Status Change triggers are displayed below the step and can be connected to separate flows.

Status Change triggers are displayed in a predefined order on the canvas (Open to Rejected), and below any connected Notify to Engage and Severity Change triggers.

Severity Change trigger

The Severity Change trigger initiates a flow when an incident's severity in xMatters changes to a specified value. Outputs include the new severity, old severity, the name of the user who changed the severity, the note the user added when the severity was changed, and context about the incident at the time the trigger was initiated.

Examples of when to use this trigger:
  • Automatically update a chat room to notify resolvers when an incident’s severity is updated.
  • Automatically update external applications to note when the incident's severity is updated.
  • Automatically send a new notification to resolvers when an incident's severity has changed so teams can escalate or deescalate the incident response.
Severity Change trigger outputs
Output Description Example
New Severity New severity level assigned to the incident. Critical
Previous Severity Previous severity level of the incident. High
User ID ID of the xMatters user who updated the incident's severity. mmcbride
User First Name First name of the xMatters user who updated the incident's severity. Mary
User Last Name Last name of the xMatters user who updated the incident's severity. McBride
Note Reason for the change in status, if provided by the user. The incident is causing a significant business impact.
  1. Under the Initiate Incident step, click + Add Triggers.
  2. Hover over Severity Change and select the severity level you want to create a flow for. You can select each level once, so when you add one of the available severity change triggers to the canvas, it disappears from the list of options; when you remove it from the canvas, it reappears and is available for your use in future.


  1. Once added, the selected Severity Change triggers are displayed below the step and can be connected to separate flows.

Severity Change triggers are displayed in a predefined order on the canvas (Critical to Minimal), below the Notify to Engage trigger and above any connected Status Change triggers.

^ Back to top

Notify to Engage trigger

The Notify to Engage trigger initiates a flow whenever someone selects 'Notify to Engage' to add resolvers to incidents created by the Initiate Incident step the trigger is connected to. The main purpose of the trigger is to modify the default message that's sent to resolvers when you invite them to engage in the incident.

When you add the trigger to the canvas, Flow Designer automatically connects a Create Alert step to the trigger with a version of the default message that you can customize to suit your organization's needs. The presence of the Notify to Engage trigger on your canvas signals Flow Designer to initiate the trigger and run any flow attached to it instead of sending resolvers the system's built-in notification to engage in the incident.

When to use this trigger: To customize the design and content of the default messages sent to resolvers when they're notified to engage in an incident, or to trigger a custom flow when resolvers are notified to engage in an incident.

What triggers it: When someone selects 'Notify to Engage' and adds resolvers from the Resolvers section of the Incident Console, or when someone selects 'Notify to Engage' to notify a service owner from the service info card in the console or incident service dependencies map.

What information is in the outputs:

  • Incident Trigger Context: Details of the incident from which the trigger was initiated. The values at runtime represent the state of the of the incident when the trigger was initiated.
  • Outputs: Recipients selected in the form that's presented when someone selects 'Notify to Engage' for an incident
Notify to Engage outputs
Output Description Example
Resolvers Target names of users, groups, or services included as recipients on the form that triggered the flow. mmcbride,DatabaseAdmins
  1. On your Flow Designer canvas, click Add Triggers below an Initiate Incident step.
  2. Select Notify to Engage.
    • The trigger is added to the canvas below the Initiate Incident step with a Create Alert step automatically attached to the trigger.
  3. Double-click the Create Alert step (or select it and click the pencil icon) to edit the default Email / App, Text, and Voice messages that are sent to resolvers when they're notified to engage in the incident.
    • In the Setup tab, set the Incident Function field to 'Resolver Notification'.
  4. Optionally, add additional steps before or after the Create Alert step.

Manually adding a Create Alert step from the palette and connecting it to your flow does not automatically populate the step's message content and settings. If you delete the Create Alert step that's created with the trigger, you can click 'Add Create Alert step' from the trigger's Setup tab to add a new one to your flow that includes the default messages.

While you do not need to include the Create Alert step in the flow attached to the Notify to Engage trigger, only recipients of a Create Alert step are added to the Resolvers section of the Incident Console – and those resolvers only display an 'Engaged' status when they respond to the message with a positive response option.

^ Back to top

Stakeholder Update trigger

The Stakeholder Update trigger initiates a flow whenever an update is sent to the stakeholders of incidents created by the Initiate Incident step the trigger is connected to. The main purpose of the trigger is to modify the default message sent to stakeholders when an incident's severity is changed, or when you want to send an ad hoc update to stakeholders. You can optionally associate the trigger with a Flow Trigger form in your workflow to add more details to the stakeholder message in addition to outputs from previous steps in the flow.

When you add the trigger to the canvas, Flow Designer automatically connects a Create Alert step to the trigger with a version of the default message that you can customize to suit your organization's needs. The presence of the Stakeholder Update trigger on your canvas signals Flow Designer to initiate the trigger and run any flow attached to it instead of sending incident stakeholders the system's built-in stakeholder update message.

When to use this trigger: To customize the design and content of the default messages sent to stakeholders when they're updated about the incident, or to trigger a custom flow when an update is sent to stakeholders.

What triggers it: When someone sends an update to stakeholders about the incident. A stakeholder message can be sent by selecting the 'Notify stakeholders about this update' checkbox when changing the severity of an incident, or by clicking 'Send Update' on the Stakeholders section of the Incident Console. If you choose to associate a Flow Trigger form with the trigger, the default stakeholder message preview will be replaced with the flow trigger form layout.

What information is in the outputs:

  • Incident Trigger Context: Details of the incident from which the trigger was initiated. The values at runtime represent the state of the of the incident when the trigger was initiated.
  • Default outputs: The outputs of the trigger if there is no flow trigger form associated with it.
Stakeholder Update default outputs
Output Description Example
Progress Statement as Text Message sent to update stakeholders about the incident, in text format. We are currently experiencing a full outage of our primary identity provider. To work around the issue, use your backup email login workflow.
Progress Statement as HTML Message sent to update stakeholders about the incident, in HTML format. <b>We are currently experiencing a full outage of our primary identity provider.</b> To work around the issue, use your backup email login workflow.
  1. On your Flow Designer canvas, click Add Triggers below an Initiate Incident step.
  2. Select Stakeholder Update.
    • The trigger is added to the canvas below the Initiate Incident step with a Create Alert step automatically attached to the trigger.
  3. Double-click the Stakeholder Update trigger to associate a flow trigger form with the trigger. Selecting a flow trigger form is optional. If you want to use the trigger's default outputs, leave the drop-down option as Use default stakeholder message details. If you select a form, the trigger's outputs will be replaced with the associated form's outputs.

  4. Double-click the Create Alert step (or select it and click the pencil icon) to edit the default Email / App, Text, and Voice messages that are sent to stakeholders when they're updated about the incident.
    • In the Setup tab, set the Incident Function field to 'Stakeholder Update' to send the message to stakeholders. The recipients of the alert will be added as stakeholders in the incident's console.
  5. Optionally, add additional steps before or after the Create Alert step.

Manually adding a Create Alert step from the palette and connecting it to your flow does not automatically populate the step's message content and settings. If you delete the Create Alert step that's created with the trigger, you can click 'Add Create Alert step' from the trigger's Setup tab to add a new one to your flow that includes the default messages.

^ Back to top