Flow triggers
The different triggers are initiated by different system activities. Each one populates outputs based on the type of trigger which, along with common event properties, can be used in the downstream steps.
If you have existing outbound integrations for a communication plan 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.
Common properties
The common properties output by all outbound triggers provide information identifying the event in addition to its status and properties.
Common trigger output details
| Property | Description | Example |
| event.id | The unique identifier (UUID) of the event. | e930e32d-b863-4c55-a528-1d2829e3690e |
| event.eventId | ID assigned to this event by xMatters and used to track its progress through the system. (Also the number used to reference this event in the Events and Tracking reports.) | 889003 |
| event.status | The current status of the event. | ACTIVE |
| event.created | Date and time the event 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. | mmcbride|Work Email |
| event.initiator | The target name of the user who initiated the event. | integrationUser |
| event.properties | A JavaScript object containing the property names and values included in the event. |
|
Event status updates trigger
What triggers it: An event is started, suspended, resumed, or terminated.
What information is in the outputs: The status of the event and the user who initiated the event status change.
Examples of when to use this trigger:
- Automatically update the record in your monitoring tool to add an annotation that the xMatters event ended.
- Post event creation and termination updates to your reporting repository for analytics and observability initiatives.
- Automatically close the ticket in the source system when the xMatters event ends.
Event status trigger output details
| Property | Description | Example |
| statusChanged.auditType | The change to the event 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 event 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 event or changed the event 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 event or changed the event status. | mmcbride |
| statusChanged.by.firstName | First name of the user who initiated the event or changed the event status. | Mary |
| statusChanged.by.lastName | Last name of the user who initiated the event or changed the event status. | McBride |
Check out the payload for the equivalent trigger in the Integration Builder.
Device delivery updates trigger
What triggers it: A notification is delivered to a device or notification delivery fails.
What information is in the outputs: 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 output details
| Property | Description | Example |
| notification.deliveryStatus | The delivery status: Delivered, Failed, or Unchanged. | Delivered |
| 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 |
Check out the payload for the equivalent trigger in the Integration Builder.
Responses trigger
What triggers it: A user responds to a message.
What information is in the outputs: 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 |
| response.comment | The annotation included with a response from the mobile app, or null if no annotation is included or if it was added using another method. | Investigating the root cause now. |
| respondedTo.at | Date and time the recipient responded to the notification in ISO-8601 format. | 2019-01-15T18:03:16.580Z |
| 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 |
Check out the payload for the equivalent trigger in the Integration Builder.
Event comments trigger
What triggers it: A user adds a comment from the mobile app, xMatters Inbox, email, Tracking Report, or xMatters REST API.
What information is in the outputs: 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 event comment trigger instead of the response trigger!)
- Add the comments to a ticket or alert as annotations, recording the work performed on the event, either for the next person in the resolution chain or for post-incident analysis.
Event comments trigger output details
| Property | Description | Example |
| annotation.comment | The value of the comment added to the event 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 to the event. | 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 |
Check out the payload for the equivalent trigger in the Integration Builder.
Escalations trigger
What triggers it: An escalation occurs in a group.
What information is in the outputs: The group containing the shift with the escalation, the reason for the escalation, the user that escalated the event (if applicable), the type of escalation, the recipients the event escalated from, and the recipients the event escalated to.
Examples of when to use this trigger:
- Automatically launch a new event that warns a manager when an event 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 event 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 event. | e1e427bb-770f-4d47-aa4d-efdd8b64089c |
| escalated.by.targetName | For active escalations, the username of the recipient who manually escalated the event. | mmcbride |
| escalated.by.firstName | For active escalations, the first name of the recipient who manually escalated the event. | Mary |
| escalated.by.lastName | For active escalations, the last name of the recipient who manually escalated the event. | 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 |
Check out the payload for the equivalent trigger in the Integration Builder.
Targeted recipient failures trigger
What triggers it: None of the targeted recipients could be immediately notified for an event.
What information is in the outputs: 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 event 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 |
Check out the payload for the equivalent trigger in the Integration Builder.