Welcome to the integration guide for xMatters Monitoring Tool X. This document explains how to install and configure a sample integration to demonstrate the process of building and managing integrations in xMatters On-Demand.
To begin, download and extract the MonitoringToolXIntegration.zip file attached to this article; there should be three files inside the package:
- Monitoring Tool X Plan.zip: an exported workflow with a pre-configured integration and form; do NOT extract this .zip file - you'll import it directly into xMatters.
- Integration Script.txt: a pre-formatted HTTP POST request designed to trigger the integration
- README.txt: a brief explanation and pointer to this article
Ensure one of your devices (email or mobile phone) is attached to your xMatters account. If it is not, use the instructions in the online help to add a device.
Note: This demonstration uses an online HTTP client to send an HTTP request to xMatters and simulate the injection of an event from an external application. You can use your favorite online or installed HTTP POST tool or REST client instead, but you might need to adapt the steps slightly to suit.
Use the steps below to install and test your integration.
Step One: Import the workflow
Log in to xMatters and navigate to the Workflows tab. On the Workflows page, click Import and then upload the Monitoring Tool X Plan.zip file within the extracted archive.
Step Two: Add a recipient
Click Monitoring Tool X (the workflow name) to open the Forms tab. Click the Edit drop-down list for the New Incident form and select Layout. On the Layout tab, in the Recipients area, start typing your name in the field, and then select your device when it appears in the list (the integration will notify this device by default). Save your changes, and then click the Monitoring Tool X breadcrumb to return to the list of forms.
Step Three: Configure the HTTP request
On the Integration Builder tab, expand the Inbound integrations list. Click Transform Monitoring Tool X Webhooks to open the integration's configuration screen.
In Step 4, select the API Key authentication method, and then click Save.
At the bottom of the screen, under How to trigger this integration, click Copy URL:
Open Insomnia, some other REST client, or your favorite online HTTP tool, and set the Destination type to POST. Paste the integration URL you retrieved in the previous step into the Destination field:
Set the authentication to Basic, and then copy and paste the API key and secret from Step 4 of the integration configuration screen in xMatters into the username and password fields:
Make sure the header is set to “Content-Type” and “application/json”:
In the JSON (or request body) section, copy and paste the entire contents of the
Integration Script.txt file that you extracted from the integration archive.
Step Four: Inject an event and view the results
To inject an event, submit the HTTP POST. If the event is successful, you'll see an "Accepted" code in your REST client. xMatters then sends an alert to the device you added back in Step 2, so keep your eyes on your phone or email.
Respond to the event on your device, and then navigate back to the Activity Stream for your integration in xMatters. To do that, click the Monitoring Tool X breadcrumb on the top of the integration page. Click the gear icon beside Transform Monitoring Tool X Webhooks, and select Activity Stream.
You 'll see the the details of the event and confirm that the notification was successful.
Congratulations: your integration is working!