A collection of 6 custom flow steps for working with xMatters Incidents in xMatters Flow Designer.
The steps come packaged in a workflow with a tester form called Run Flow Step. You can try out each step by filling in the appropriate section of a messaging form then view the output either directly in the flow's activity log or in an alert notification.
- Access to an xMatters instance with admin rights, e.g. Full Access User, Developer and/or Company Supervisor roles.
- If you don't have an xMatters instance, try one for free!
- xMattersIncidentFlowSteps.zip - an xMatters workflow zip containing 2 forms, 1 flow canvas and 6 custom flow steps. Do not inflate the zip file. See Installation instructions below.
The new flow steps are...
-
xM Get Incident With Properties
An enhanced version of the built-in Get Incident step. It outputs all the usual details of an xMatters Incident plus custom Incident properties and Incident Type, e.g. Application, Site, Platform, Region, Business Impact Asessment.
N.B. YOU MUST EDIT THE STEP DEFINITION TO ADD AN OUTPUT FOR EACH NAMED PROPERTY. AND OF COURSE, THE INCIDENT NEEDS TO HAVE THE PROPERTIES! For example, suppose you have defined an Incident Type called Scary Incident, and this Incident Type has custom properties called Incident Level, Region and Company:
Update the step configuration and add 3 new outputs called Incident Level, Region and Company.
Provided the Incident properties exist on the target Incident, you get them as named outputs, in addition to all the regular outputs you would expect from the built-in Get Incident step.
However, if you don't want to/can't add more outputs, all is not lost. You also get an output called propertiesObject which bundles all Incident properties into an object of key-value pairs. This is easy to parse in a subsequent custom flow step.
P.S. Learn about Incident Types in xMatters here
-
xM Search Incidents
Find one or more xMatters Incidents in your xMatters instance. A comprehensive step that lets you search for Incidents by many different propertiesm including Status (e.g In Progress), Severity (e.g. Critical), Incident ID, Summary, Description, Incident Type, Impacted Services, and custom property key/value pairs.
As you move down the options, they are AND'd together. We encourage you to read the API notes for xMAPI Get Incidents to understand how the various options work. N.B. After xMAPI returns data, the step filters the returned data API to further check for Incident Type and Incident Property key/value pairs. The step returns a list of Incident IDs and a count, which can be ordered as you wish.
-
xM Write Structured Work Note
Adds a structured timeline note to an xMatters incident in the format of key separator value, e.g. weather: rainy. The step avoids repetition, and will not enter a new work note if it matches the last note entered. This is to avoid the same work note appearing over and over again, e.g. weather: rainy followed soon after by another weather: rainy. A structured work note is good for storing data, e.g. links to external IDs. Unlike an Incident Property, it cannot be overwritten (accidentally or on-purpose) by a user via the UI. Of course, a new note could be manually entered in the same format if manual updates are required.
-
xM Get Structured Work Note
After writing a structured work note, you'll probably want to get it. Enter the key and the separator, and the previous value (if any) is returned.
-
xM Remove Service from Incident
Clears all Services from an xMatters Incident record. This is not possible via the built-in Update Incident step, in which an empty imput for Impacted Services results in no update to the Service.
-
xM Get Incident URL
Returns a URL to link directly to an xMatters Incident. Useful for including in Alerts, so resolvers can quickly find their way to the Incident console.
-
Log into xMatters as a user with either the Developer or Full Access User role. Navigate to Workflows, click the Import button on the top right and import the xMattersIncidentFlowSteps.zip file. This is what you will see in the list of workflows:
-
Navigate into the new workflow. You will see a list of two forms. Set Sender Permissions on the upper form, Run Flow Step. To do this, click the left most button. Ensure the form is accessible by selecting Web UI:
After, set Sender Permissions. Add users or roles who can access the form. We recommend allowing all those with Full Access User and Developer roles to use the form.
The lower form, Results, is triggered by the upper form. To deploy it, choose Enable For Web Service.
-
OPTIONAL. By default, only the user who imports the workflow has permission to use and modify the custom steps within the workflow. We recommend broadening permissions to allow all those with the Developer role to use and/or edit your new flow steps. To do this, highlight the FLOW DESIGNER tab to the right of FORMS. Open the Run Flow Step flow canvas:
-
To the right of the screen on the Palette, highlight the CUSTOM tab. Navigate to each new flow step in turn. Click the gear icon then Usage Permissions. In the pop-up window, grant ACCESS to other users/roles as required, e.g. select the Developer role and grant permission to Edit Step:
You can try out each new custom step via the Run Flow Step messaging form. Navigate to Messaging > xMatters Incident Flow Steps > Run Flow Step.
Choose which step to run in the first dropdown. Each step has it’s own corresponding form section with some demo values in it. You can use the demo values supplied or over-type with your own test values.
OPTIONAL: At the bottom of the form, if you want, you can set yourself as a Recipient. When you click Send Message, you will get an initial email notification confirming the flow has been started. A short while later, a second email will arrive with the step’s output values clearly shown. Alternatively, you can view the output either in the Alert Report:
Or in the Activity Log of the Run Flow Step canvas:
Navigate to xMatters Incident Flow Steps > Flow Designer tab > Run Flow Step canvas. You can see how the correct step is selected based on an initial Switch block. Each custom step outputs log notes. If a step fails, you can open the Activity Log and inspect the log messages.
You are also able to view the source of each step by opening it from the CUSTOM steps palette and selecting the step's SCRIPT tab. As with all xMatters custom steps, the scripting language is JavaScript but executed in the xMatters cloud environment rather than on your browser.