Integration Builder

The Integration Builder, in combination with the other elements of the xMatters integration platform (including the REST API, xMatters Agent, and Flow Designer), allows you to easily add an automated, closed-loop integration to address any business interruption.

You can use the Integration Builder to create an integration between xMatters and another application. You can create multiple integrations for a single workflow.

How it works

Flow Designer and the Integration Builder

When a trigger is added to a canvas in Flow Designer, an integration is also added to the Integration Builder list. This lets you see all the triggers and outbound integrations for a workflow in one list so you can quickly enable or disable them or view activity updates (for example, if you're doing some troubleshooting). But any management of the flow should be done in Flow Designer. It even has its own easy-to-use Activity panel that provides information for each step in a flow, letting you see in more detail what went wrong and where. You can access the Activity panel directly from an integration to view logs in detail.

Inbound integrations

Inbound integrations are primarily used to create an alert in xMatters. The transformation script for an inbound integration can receive an incoming HTTP request, parse and modify its data, enrich the data using additional web requests, and finally create an alert to send notifications.

Create an inbound integration to have an external application create an alert or take action in xMatters.

Outbound integrations

Outbound integrations are triggered when actions take place in xMatters. The outbound services can make web requests to any API accessible over the Internet. You can use outbound integrations to update the originating alert with status changes or response information. You can also configure webhooks to create new alerts in xMatters; for example, to start a conference bridge or send additional notifications to recipients based on their actions.

Create an outbound integration to have xMatters send out response or alert information to take action in another application.

Transformation script editor

The Integration Builder includes a full-featured, browser-based script editor that allows you to create and modify your transformation script within the xMatters web user interface. Transformation scripts for the Integration Builder are written in JavaScript (ECMAScript 5.1).

  • Want to get starting creating a request? Check out the request object details in the Integration Builder scripting reference.

HTTP Endpoints

Each web request you want to make using the Integration Builder is represented in the transformation scripts by HTTP request to an endpoint. Each endpoint is configured with a base URL, a name, and optional configuration parameters, such as the request method (GET, POST, etc.), a specific path to append to the base URL of the endpoint, and any request headers, parameters, or body data.

How to use the Integration Builder

We go into detail on creating inbound and outbound integrations elsewhere, but here's some basic information on using the Integration Builder.

  1. In xMatters, click the Workflows tab.
    1. xMatters displays a list of existing workflows.
  2. Click the workflow for which you want to build an integration and select the Integration Builder tab.

To edit an inbound or outbound integration:
  1. In xMatters, access the Integration Builder tab in the workflow that contains the integration you want to edit.
  2. Click the link that displays how many integrations are configured to expand a list of integrations.
  3. Click the name of the integration to open its configuration screen and edit the integration.
  4. Click Save.

To make changes to an integration that runs on an xMatters Agent, you must be a registered user of that agent. If you have access to the integration but are not a registered user of the agent it runs on, xMatters displays a read-only view of the integration.

To delete an inbound or outbound integration:
  1. In xMatters, access the Integration Builder tab in the workflow that contains the integration you want to delete.
  2. Click the link that displays how integrations are configured to expand a list of integrations.
  3. Click the 'X' symbol to the right of the integration to delete it.

Integrations you create using the Integration Builder are automatically included when you export and import workflows. You do not need to import them separately. For more information about exporting and importing workflows, see Import and export workflows.

For 'Send to Integration Agent' outbound integrations, if the integration service name or Integration Agent ID does not exist in the xMatters system that the workflow is being imported to, the values for these fields are not imported. The workflow import status dialog displays a message importing these values was unsuccessful.

Legacy callbacks

If you are importing a workflow that was exported before the Task Force X quarterly release (Sept 2016), Integration Builder callbacks defined as part of a form will be migrated to 'Run a script' outbound integrations in the Integration Builder. Integration Agent and HTTP callbacks are not included in exported workflows and are not imported, but HTTP callbacks will be automatically migrated to Send a webhook outbound integrations as part of the quarterly release update process.