This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with Runscope.
How it works
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 needed 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 the Add New User icon.
- Enter the appropriate information for your new user.
- Assign the user to the REST Web Service User role.
- Click Save.
- On the next page, set the web login ID and password.
The integration will notify the group or the user defined as a recipient in the communication plan's Live Traffic Alerts form. If the recipient is not defined, the xMatters event will not be created.
For more information about creating users and devices in xMatters, refer to the xMatters On-Demand help.
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 Browse, and then locate the downloaded communication plan (.zip file).
- Click Import Plan.
- Once the communication plan has been imported, click Plan Disabled to enable the plan.
- In the Edit drop-down list, select Forms.
- For the Live Traffic Alerts form, in the Not Deployed drop-down list, click Create Event Web Service.
- After you create the web service, the drop-down list label will change to Web Service Only.
- In the Web Service Only drop-down list, click Permissions.
- Enter the integration user you configured above, and then click Save Changes.
- Open Layout of the Live Traffic Alerts form, specify a recipient (a user or a group) for events, and then click Save Changes.
- Repeat steps 6-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 the valid credentials for Runscope.
Each integration service has its own URL that you can use to target it from Runscope.
To get a web service URL for an integration service:
- On the Integration Builder tab, expand the list of inbound integrations.
- Click the gear icon beside the integration service you want to target, and then select Integration URL.
You will need the URL for each integration service when configuring 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 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 has failed.
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 user replied with "Rerun", check the Activity Steam for the Response Callback outbound integration.