Building a custom flow for initiating scenarios

Updated April 17, 2023 17:49

Emily Sait

Question

My workflow contains scenarios that my team uses to send detailed messages about certain situations in just a few clicks. Is it possible to initiate these scenarios using a chat bot and the xMatters REST API?

Environment

All versions of xMatters

Answer

Yes! The xMatters REST API has endpoints that can facilitate this operation, but it requires multiple endpoints and coding to pull it all together. However, you can create a new flow to initiate any scenario by name.

Below, we'll use the following steps to teach you how to build a custom flow for initiating scenarios:

Create the workflow
Design messaging forms
Add message content
Create scenarios
Use the xMatters API
Use Flow Designer
Add an HTTP trigger
Design a custom step
Connect the Create Alert Using a Form step
Next steps

Let's create the workflow

In this example, our mission critical system is a space station. There are several very important cases that need to be taken into account:

Spaceflight sickness incident
Cosmic bug infestation
Meteoroid & orbital debris approaching
Alien attack!
Death Star located

In order to create a scenario, we need to create a form; in order to create a form, we need to create a workflow...

In xMatters, go to Workflows > Workflows.
Click Create.
From the drop-down menu, choose Create Custom Workflow.
Create your custom workflow.

Designing messaging forms

Now that we have our workflow, it's time to design a messaging form.

Click Create Form.
Add a Name and optional Description.
For the Form Type, select Messaging.
Click Create.

Next, we can edit the layouts. Next to the form, click Edit and select Layout:

We need to add the following new properties for the message:

Area
Status
Risk Type
Action
Incident Type

Click the + to create a new property.
From the drop-down menu, select the type of property you want to add:
- Text: Area
- Combo Box: Status, Risk Type, Action, and Incident Type
Give each property a Name and optional Description.
- The Combo Box properties also need Values. For example:
Once you've configured each property, click Save Changes.

Now that we've created our form properties, drag the Devices section onto the form.

Then, configure the type of devices you want the message to target.

Adding message content

Okay, let's work on the message content. To get started, click the Messages tab:

Next to Email / App, click Edit.
Using the editor, we can create the message we want to send when an incident occurs. Use text and the properties we just created to craft the message:
Click Save.

Once we've created our message, we can define the response options for the message.

On the Responses tab, click Create Response.
For our form, the most important responses to add are Assign to User and End (the flow).
Click Save Changes.

Now we can head back to the main workflow page to create the scenarios.

Creating scenarios

Scenarios let us to save versions of the form with predefined values for common or anticipated situations so it's easier to send messages quickly.

Next to the form name, click the Edit drop down-menu and select Scenarios.
For our workflow, we need to add 5 different scenarios:
For each scenario you need to define the default values. For example, the first one could be filled out like this:
The defaults from the base form are already populated in the scenario, but you can change these by selecting a different option from the drop down menu.
Click Save.

Once you've added the scenarios and enabled your workflow, you can manually test the new scenarios from the Messaging tab of your xMatters instance. (We recommend doing this ahead of automating the flow.)

Using the xMatters REST API

A key part of this workflow will be using API calls to GET information we need to complete the alert.

The required calls are:

POST /oauth2/token: to get an access token to use for the subsequent calls
GET /forms: to get forms and plans ids (search for the one needed based on the workflow created)
GET /plans/{planId}/forms/{formId}/scenarios?embed=properties: to get scenarios for a form

The Plan ID and Form ID will be used in our workflow later on.

Using Flow Designer

To get to Flow Designer, on the Flow Designer tab of the workflow, click Create Flow Canvas.

In this section we're going to show you how to create a flow that supports the following steps:

The chat bot will be POSTing the scenario name, via an HTTP trigger, into the flow.

Adding an HTTP trigger

To kick off the flow, we need to create an HTTP Trigger.

From the Triggers tab of the palette, click Create HTTP Trigger.
Add a Name for your trigger and change the Icon (if desired).
Next, we need to map the incoming POST to an output which can be used elsewhere in our flow. On the Outputs tab, click + Add Step Output.
Name the output Scenario.
Click Save and then Close.
Your new trigger is now available in the palette. Find and drag the trigger onto the canvas:

Hover over the trigger and click the pencil icon to edit its configuration.
On the Settings tab, you can use the URL from the Initiation section to trigger the flow:

At this point, we recommend testing the endpoint with a program like Postman to map the body of the request to the output of the HTTP trigger. If the test is successful, you should see the request in Flow Designer's Activity panel as completed:

Designing a custom step

Next, we need to design some custom steps for our flow to define which scenario is used.

On the Custom tab in the Flow Designer palette, click Create a custom step to open the New Custom Step dialog box.
On the Settings tab, give your step a Name.
Enable Include Endpoint and select xMatters from the drop-down list of options.
Add an Endpoint Label.
On the Inputs tab, add three inputs for "Scenario Name", "Plan ID" and "Form ID.
On the Outputs tab, add all the properties used by the scenarios:
On the Script tab, expand the Inputs and Outputs drop-down menus to view the available values.

In the code view, paste the following cod to call the scenarios endpoint and to find the scenario by name:

var request = http.request({
  "endpoint": "xMatters", 
  "path": "/api/xm/1/plans/" + input['Plan ID'] + "/forms/" + input['Form ID'] + "/scenarios?embed=properties",
  "method": "GET"
});

var response = request.write();

if (response.statusCode == 200 ) {
  json = JSON.parse(response.body);
  for (var i in json.data) {
    if (json.data[i].name == input['Scenario Name']) {
      output['Scenario ID'    ] = json.data[i].id;
      output['Scenario Name'  ] = json.data[i].name;
      output['Recipients'     ] = json.data[i].recipients.data[0].targetName;
      output['Area'     ] = json.data[i].properties['Area'];
      output['Status'         ] = json.data[i].properties.Status;
    output['Risk Type'         ] = json.data[i].properties.RiskType;
     output['Action'         ] = json.data[i].properties.Action;
    output['Incident Type'         ] = json.data[i].properties.IncidentType;
      break;
    }
  }
}

The outputs will be set to the value of the JSON as displayed when interrogating the xMatters REST API. Here' we’ve defaulted the recipient to the first in the array, but this can be changed later.

Once you're happy with your changes, click Save.

You can now select the step from the palette and connect it to the canvas.

Connect the HTTP trigger to the custom step:

Hover over the custom step and click the pencil icon to edit the step's configuration.
In the sidebar, click the name of your trigger to expand and display its outputs, then drag the Scenario output into the Scenario Name field.
Copy and paste the Plan ID and Form Id from the previous scenarios API call.
Click Done.

You can test the steps together using the same method as before.

Connecting the Create Alert Using a Form step

Finally, we need to add a Create Alert Using a Form step to our flow to initiate an alert when the flow is triggered.

On the Tools tab of the palette, select and drag the Create Alert Using a Form step onto the canvas.
Connect your custom step to the Create Alert Using a Form step.
Hover over the step and click the pencil icon to edit its configuration.
Select the form we previously created:
Add the necessary variables by dragging from the custom step created earlier. These variables will contain the values from the scenario.
Select and drag the properties into the relevant field.
Click Done to complete the flow.

Now, when the HTTP endpoint is triggered it should pass the scenario name through to the search to retrieve the properties and add them to the notification.