The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.
This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with Runscope.
Runscope provides cloud-based and hybrid on-premises solutions that allow businesses to monitor, test, and debug web service APIs. Runscope API tests can be used to test against services available in the public cloud, running on a private network behind a firewall, or running on a local development environment.
Coupled with the power of xMatters alerts, the integration:
- Quickly identifies and notifies the on-call resource on a variety of devices.
- Allows for voice, SMS, and push messages to users.
- Allows users to reply with "Rerun" from their device to run the test again.
Event injection is initiated when a Runscope runs a test. Runscope builds a payload and sends it to xMatters.
When the test passes, nothing else happens. When the test fails, the integration notifies a recipient (an individual or a group) defined in xMatters. Recipients can respond with "Acknowledge", which causes xMatters to stop notifying other users but keeps the event alive, or "Rerun", which causes the integration to trigger another test run in Runscope, ending the current event in xMatters.
If a Runscope test fails while there is a related active event in xMatters, a new event is not created. If a Runscope test has run and passed, the integration terminates all active events related to the test.
Download the integration package
To begin, download the communication plan attached to this article; it contains everything you need for this integration. Don't unzip it – you'll import the zip file into xMatters.
The first step in setting up your integration is to configure xMatters.
This integration requires a user who can authenticate REST web service calls when working with events – these permissions are provided by the "REST Web Service User" role in xMatters. See Create an integration user for more information.
Note: Make sure you keep the user ID and password of this user handy. You'll need them when configuring other parts of this integration.
The integration notifies the groups or users defined as recipients in the communication plan's Test Results form. If the recipients are not defined, the xMatters event is not be created.
The next step is to import the communication plan.
To import the communication plan:
- In the target xMatters system, go to the Developer tab and click Import Plan.
- Click Choose File, and then locate the downloaded communication plan (.zip file).
- Click Import Plan.
- Click the Edit beside the plan, and select Access Permissions.
- Add the integration user, and then click Save Changes.
- In the Edit dropdown list, select Forms.
- For the Test Results form, click Web Service and select Sender Permissions.
- Enter the integration user, and then click Save Changes.
- Click Edit beside the form and select Layout.
- In the Recipients area, specify a recipient (a user or a group) for events, and then click Save Changes.
After you have imported the communication plan, you need to set the authentication for the Runscope endpoint.
- On the communication plan, click the Integration Builder tab, and then click the Endpoints button to display the endpoints for the integration.
- Update the Runscope endpoint to use Basic authentication and enter a valid username and password for Runscope.
- Select the Pre-emptive checkbox and then click Save Changes.
You need to retrieve the URLs of the inbound integrations to configure Runscope.
To configure an inbound integration and retrieve its URL:
- Go to the Integration Builder tab and expand the list of inbound integrations.
- Click the name of the Test Results integration to view its details.
- Scroll down to How to trigger the integration at the bottom of the page, set the authentication method to URL Authentication, and then select the integration user as the authenticating user. The URL trigger is updated to reflect the new user.
- To be able to select the integration user, you need to be a supervisor of that user and the user needs to be assigned to the REST Web Services role.
- Click Copy beside the Trigger field – you'll need this to configure Runscope:
Now that you've configured xMatters, you can configure Runscope to integrate with xMatters. The following sections require you to log into Runscope and access the Tests settings page.
Runscope uses webhooks to initiate the web service calls when Runscope tests run.
Purpose: Injects an event into xMatters when a test fails.
- To configure a Test Results webhook, click the Tests tab.
- Hover over the test and click the Edit button that appears.
- In the Editor, expand Test Settings, and then click Webhooks.
- Paste the URL from the "Test Results" inbound integration into the URL field, and then click Save:
After you set up the webhook, the best way to check that the integration is working is to configure the Runscope test so it will fail. Before you do, make sure you have access to the device configured for a targeted recipient then run the test.
You should receive a notification from xMatters that the test failed. You can select Acknowledge, which keeps the xMatters event active but stops notifying other recipients, or Rerun, which terminates the event and reruns the test in Runscope. If you select Rerun, you should see a new run of the test in Runscope. If that test also fails, another event is initiated.
There are several places you can inspect when troubleshooting why an event doesn't seem to make it over to xMatters.
Inbound to xMatters
The first place to look is the Integration Builder Activity Stream. While on the Integration Builder tab, expand the Inbound integrations section, click the gear icon beside the inbound integration, and then click Activity Stream.
The Activity Stream contains the incoming (and for outbound integrations, the outgoing) request, any logging statements as well as the final event creation messages.
Outbound from xMatters
For the two-way integration from xMatters to Runscope, the primary source of logging is the Integration Builder Activity Stream for that particular integration.
For example, if you are troubleshooting why a test was not run again after a user replied with "Rerun", check the Activity Steam for the Test Result Callbacks outbound integration.