Welcome to the xMatters community!

We created this site for our customers and partners and we encourage you to explore, engage, and learn. To ensure that this community is fun and helpful, professional and respectful participation is expected... and troll-like behavior won't be tolerated.

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 communication plan 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:

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.

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.

xMatters notifies the on-call person for the DeltaDogs, who starts working on the issue.

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 communication plan

There are a few steps for setting up the sample communication plan to allow you to do this. First, import the sample communication plan into xMatters, then we'll walk through the steps get this plan 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:

Step 2: Import the sample communication plan

The first step is to import the sample communication plan into xMatters.

To import the sample communication plan:

In xMatters, click the Developer tab, and then click Import Plan.

Click Choose File, and then locate the plan you downloaded from this article.

Click Import Plan.

Once the import is finished, the plan should be automatically enabled. If it isn't, click Plan Disabled to enable the plan.

The communication plan 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.

Click the Edit drop-down list for the plan, and select Forms.

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 plan).

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.

Check the email settings – these map an incoming email to the form’s Subject, Message and From properties:

Still in the same drop-down, click Sender Permissions.

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

Click the Integration Builder tab.

Click the “3 Configured” link to expand the list of inbound integrations.

If you're making your own communication plan, 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.

Click the name of the first inbound integration, scroll to the bottom and click Copy URL.

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

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.

Next, click Edit Constants.

First, copy the URL from the TeamLeads FYI form into the Value field of the TeamLeadsFYIIntegrationURL constant and click Save Changes.

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.

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