Example workflow: event triage

Have you ever wanted to forward an xMatters notification to another xMatters group? What if you could simply select the group name from the responses in your xMatters notification and send it off?

Well, you can, thanks to the power of our Integration Builder, which can take action when you respond to an xMatters notification. This workflow lets a single on-call person assign work to the appropriate team simply by responding to an xMatters alert. 

A simple use case: Help Desk Triage

We’ve put together a sample workflow that sets up a process where a help desk team leader receives a notification and can pick the group that receives the problem report as a response to that notification. 


In this example:

  1. A critical, overnight processing job has failed, so a concerned help desk engineer sends off an email to a special email address targeting an xMatters “email integration”. From the incoming email, xMatters creates an alert and notifies the primary on-duty person in the TeamLeads group.
  2. The primary on-duty person for the TeamLeads group reviews the alert and, by selecting a response option in the notification, alerts the DeltaDogs operations group, which is responsible for fixing the issue.
  3. xMatters notifies the on-call person for the DeltaDogs, who starts working on the issue.
  4. The on-duty member of the TeamLeads group receives a confirmation that the DeltaDogs have been notified.

How it works

Let’s look at the actual the workflow more closely.

1. The help desk engineer sends an email

In this scenario, the help desk engineer sees a problem and needs to get some help. The help desk engineer sends an email to a special xMatters email integration address:


The email address varies depending on your xMatters instance and integration name (we'll take a look at the address further down).

2. xMatters creates an alert in response

xMatters creates an alert from the incoming email and sends out this alert to the on-call person for the xMatters TeamLeads group, who determines which response option to choose:

  • Acknowledge and don't forward
  • DeltaDogs: Creates a notification for DeltaDogs
  • CuriousCats: Creates a notification for CuriousCats


3. The Team Lead selects which group should respond

The on-call person for the TeamLeads group, which triages help desk issues when the alerts arrive, clicks the response “DeltaDogs”, since that’s the best team to respond to this issue.

4. xMatters sends the alert to DeltaDogs

Now, the on-call person for the DeltaDogs receives the forwarded message in their xMatters app:


Meanwhile, the TeamLeads group receives a confirmation (this time, in their xMatters app) that the message was forwarded:


Setting up the Help Desk Triage sample workflow

There are a few steps for setting up the sample workflow to allow you to do this. First, import the sample workflow into xMatters, then we'll walk through the steps get this workflow up and running in your specific xMatters instance.

Step 1: Set up the groups used in the sample

Select the Groups tab and configure three groups with at least one member each:

  • TeamLeads
  • DeltaDogs
  • CuriousCats

See the xMatters On Demand help for information on configuring groups.

 Step 2: Import the sample workflow

The first step is to import the sample workflow into xMatters.

To import the sample workflow:

  1. In xMatters, click the Workflows tab, and then click Import Workflow.
  2. Click Choose File, and then locate the file you downloaded from this article.
  3. Click Import Workflow.
    • Once the import is finished, the workflow should be automatically enabled. If it isn't, click Disabled to enable it.

The workflow has a number of forms:

  • Team Leads Notification: This is the form for the initial notification. 
  • CuriousCats Alert: This is the form triggered if the Team Lead responds to the initial form with "CuriousCats".
  • DeltaDogs Alert: This is the form triggered if the Team Lead responds to the initial form with "DeltaDogs".
  • Team Leads FYI: This is the form triggered with either the CuriousCat or DeltaDog response, letting the TeamLead know the appropriate group has been notified.


It also has some inbound and outbound integrations. We'll explore these more in the next sections.

Step 3: Edit the settings of the Team Lead Notification form

In this sample use case, it is the initial email from the help desk engineer that sets off the process (you can also send a message from the Messaging tab to start it or the app). There are a few things you need to configure to make that happen.

  1. Click the Edit drop-down list for the workflow, and select Forms.
  2. Click the drop-down list beside the form name and make sure Enable for Email Initiation is selected (it should already be selected in the sample workflow).
  3. In the same drop-down list, click Set Up Email Initiation.
    Make note of the email address – you’ll use it later to trigger the notification.
  4. Check the email settings – these map an incoming email to the form’s Subject, Message and From properties:
  5. Still in the same drop-down, click Sender Permissions.
  6. In the dialog, set the form sender permissions to give permission to users or roles that you want to be able to initiate the triage message (in this example, the help desk engineer).
    • This is necessary whether the initial message is sent from the Messaging tab or using email initiation.

Step 4: configure the inbound integrations and constants

  1. Click the Integration Builder tab.
  2. Click the “3 Configured” link to expand the list of inbound integrations.
    • If you're making your own workflow, you’ll need an inbound integration for any form you want to be triggered by a response to the initial message. In this case, we have one each for the CuriousCats form, the DeltaDogs form and the TeamLeads FYI form.
  3. Click the name of the first inbound integration, scroll to the bottom and click Copy URL.
  4. Paste the URL into a table similar to this one so you don't have to go back and forth, removing the part of the URL before “/api”:
    Group Name Trigger constant URL
    n/a  TeamLeadsFYIIntegrationURL Copy the url from your instance 
    CuriousCats  GroupOneIntegrationURL Copy the url from your instance
    DeltaDogs GroupTwoIntegrationURL Copy the url from your instance
  5. Repeat for the remaining two inbound integrations.

Now we'll use the values from the table to populate the constants, which are then used by the outbound integration to forward the message appropriately.

  1. Next, click Edit Constants.
  2. First, copy the URL from the TeamLeads FYI form into the Value field of the  TeamLeadsFYIIntegrationURL constant and click Save Changes.
  3. Next, confirm that the Value field of the GroupOne constant is the name of your group one (in this example, CuriousCats), and then copy the URL for the CuriousCats form into the Value field of the GroupOneIntegrationURL constant and click Save Changes.
  4. Finally, confirm that the Value field of the GroupTwo constant is the name of your group two (in this example, DeltaDogs), and then copy the URL for the DeltaDogs form into the Value field of the GroupTwoIntegrationURL constant and click Save Changes.

Constants have also been provided for a third and fourth group here, just in case you want to add some additional groups to the choices.

Check out the outbound integration that triggers the message forward on a response

You don't need to actually change anything in the sample outbound integration, but if you need to tweak this sample in the future for your particular use case, it's good to know what's gone into it. 

You can click the outbound integration name (ForwardAnAlert, in this case) to view its setup.

  • Set your trigger: this outbound integration is triggered by Notification Responses on the Team Leads Notification form.
  • Choose an action: when this outbound integration is triggered, it runs a script in xMatters On-Demand (Cloud).
  • Name your integration: this, well, names the outbound integration (in this example, ForwardAnAlert).
  • Transform the content: this is the script indicated in Choose an action -- you can take a look at it if you know your way around JavaScript.


Try out the Help Desk Triage sample

Now you can try the Help Desk Triage workflow for yourself.

  1. Send an email to the TeamLeads group using the email address format you copied from the Set Up Email Initiation dialog. It'll look something like: 
  2. Respond to the email with the DeltaDogs response option.
  3. Click the Reports tab to check for new events and see the contents of the message and its recipients.

You can also initiate the message from the your xMatters mobile app or the Messaging tab in the xMatters web interface. To initiate from the web interface:

  1. Navigate to the Messaging tab and pick Team Leads Notification.
  2. Pick the “TeamLeads” group as recipients, fill in the Subject and Message fields and click Send.
  3. Respond to the email with the DeltaDogs response option.
  4. Click the Reports tab to check for new events and see the contents of the message and its recipients.

Download the sample workflow

Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk