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 test has run and failed, or if there was a Live Traffic Alert match. Runscope builds a payload and sends it to the xMatters inbound integration URL configured in the webhook.
The integration includes the following inbound integrations:
- Test Results handles notifications about test results by notifying a recipient (an individual or a group) defined in the communication plan's form.
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 and ends the event in xMatters.
- Live Traffic Alerts creates an FYI event to notify a recipient or recipients configured in the corresponding plan's form when Runscope detects a Live Traffic Alert rules match. The notification includes a link the recipient can click to view the details and Acknowledge the match.
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.
NOTE: By default, only the response callback type is enabled for Test Results form.
Download the integration package
To begin, download the communication plan attached to this article; it contains everything you need for this integration.
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 injecting events.
This user needs to be able to work with events, but does not need to update administrative settings. While you can use the default Company Supervisor role to authenticate REST web service calls, the best method is to create a user specifically for this integration with the "REST Web Service User" role that includes the required permissions and capabilities.
Note: If you are installing this integration into an xMatters trial instance, you don't need to create a new user. Instead, locate the "Integration User" sample user that was automatically configured with the REST Web Service User role when your instance was created and assign them a new password. You can then skip ahead to the next section.
To create an integration user:
- Log in to the target xMatters system.
- On the Users tab, click Add.
- Enter the appropriate information for your new user. Because this user affects how messages appear for recipients and how events are displayed in the reports and Communication Center, you may want to identify the user as specific to Runscope; for example:
- First Name: Runscope
- Last Name: Integration
- User ID: runscope
- Assign the user to the REST Web Service User role.
- Depending on your deployment, you might need to add one of the following roles so you can log in as the integration user and access the Developer tab: Full Access User, Developer or Limited Developer.
- Set the password for the user.
- Make a note of the user ID and password details; you need them when configuring other parts of the integration.
- Click Add.
The integration notifies the groups or users defined as recipients in the communication plan's Live Traffic Alerts form. If the recipients are not defined, the xMatters event will not be created.
The next step is to import the communication plan.
To import the communication plan:
- In the target xMatters system, on the Developer tab, click Import Plan.
- Click Choose File, and then locate the downloaded communication plan (.zip file).
- Click Import Plan.
- Click the Edit drop-down list for the plan, and select Access Permissions.
- Add the integration user you created above, and then click Save Changes.
- In the Edit drop-down list, select Forms.
- For the Live Traffic Alerts form, in the Web Service Only drop-down list, click Sender Permissions.
- Enter the integration user you configured above, 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.
- Repeat steps 7-10 for the Test Results form.
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, select the Pre-emptive check box, and then enter valid credentials for Runscope.
You need to retrieve the URLs of the inbound integrations to configure Runscope.
To configure an inbound integration and retrieve its URL:
- In the Integration Builder, expand the list of inbound integrations.
- Click the name of the integration to view its details.
- Scroll down to How to trigger the integration at the bottom of the page, and select the integration user as the authenticating user (make sure the authentication method is set to URL authentication). 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:
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 and Alerts settings pages.
Runscope uses webhooks to initiate the web service calls when Runscope tests run or when Live Traffic rules are triggered. The latter are logical conditions that will vary from help desk to help desk.
Purpose: Injects an event into xMatters when a test fails.
- To configure a Test Results webhook, click the Tests tab, hover the mouse over the test and then click Edit:
- In the Test Editor, expand Test Settings, then click Notifications.
- Paste the URL from the "Test Results" inbound integration into the Callback URLs window, and then click Save:
Note the "Test Results" inbound integration URL.
Live Traffic Alerts
Purpose: Injects an event into xMatters when Live Traffic Alert rules have a match.
- To configure a Live Traffic Alerts webhook, click the Alerts tab, hover the mouse over the alert, and then click the Edit Alert icon (the pencil):
- In Edit Traffic Alert dialog, click Webhooks.
- Paste the URL for the "Live Traffic Alerts" inbound integration into the Callback URLs window, and then click Save:
Note the "Live Traffic Alerts" inbound integration URL.
To test the integration, run a test with a configured webhook and/or a test that will trigger the rules defined in the Live Traffic Alerts.
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 intended integration service, 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 Response Callback outbound integration.