The Integration Builder, in combination with the other elements of the xMatters integration platform (including the REST API, xMatters Agent, Integration Agent, and email integration), allows you to easily add an automated, closed-loop communication plan to address any business interruption.
You can use the Integration Builder within the xMatters On-Demand web user interface to create an integration between your communication plan and another application. You can create multiple integrations for a single communication plan.
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 communication plan 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 stream that provides information for each step in a flow, letting you see in more detail what went wrong and where.
Inbound integrations are primarily used to create an event in xMatters using a communication plan. 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 event to send notifications.
Create an inbound integration to have an external application create an event or take action in xMatters.
- Need an example? Here's a step-by-step description of a working inbound integration.
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 event with status changes or response information. You can also configure webhooks to create new events 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 event information to take action in another application.
- Need an example? Here's a step-by-step description of a working outbound integration.
Transformation script editor
- Want to get starting creating a request? Check out the request object details in the Integration Builder scripting reference.
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.
The Integration Builder includes an Activity Stream that records request activity and displays it within the web user interface.
Integrations you create using the Integration Builder are automatically included when you export and import a communication plan. You do not need to export or import them separately.
How to use the Integration Builder
- In xMatters, click the Developer tab.
- On the left menu, under Communication Plan Builder, click Manage Communication Plans.
- xMatters displays a list of existing communication plans.
- Beside the communication plan for which you want to build an integration, click Edit >Integration Builder.
- You can also access the Integration Builder from within a communication plan that you are editing by clicking the Integration Builder tab.
To edit an inbound or outbound integration:
- In xMatters, access the Integration Builder tab in the communication plan that contains the integration you want to edit.
- Click the link that displays how many integrations are configured to expand a list of integrations.
- Click the name of the integration to open its configuration screen and edit the integration.
- 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:
- In xMatters, access the Integration Builder tab in the communication plan that contains the integration you want to delete.
- Click the link that displays how integrations are configured to expand a list of integrations.
- Click the 'X' symbol to the right of the integration to delete it.
You can copy an existing integration to duplicate the settings and scripts you've already created. You can clone any inbound or outbound integration created using the Integration Builder (you can't clone integrations that are added when a trigger is added to a flow). You can then use it as a basis for a new configuration, modify it to access a different part of your external system, or to handle a different kind of callback.
To copy an existing integration:
- On the Integration Builder tab, expand the list of inbound or outbound integrations.
- Click the Settings drop-down list (the gear icon) beside the integration you want to copy, and then select Copy Integration.
- In the Copy Integration dialog box, type a name for the new integration, and then click Copy Integration.
- xMatters adds the copy as a new integration in the list:
The new integration is disabled by default to help avoid conflicts with the original. It is recommended that you edit or modify the new version before enabling it.
Integrations you create using the Integration Builder are automatically included when you export and import communication plans. You do not need to import them separately. For more information about exporting and importing communication plans, see Export and import communication plans.
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 communication plan is being imported to, the values for these fields will not be imported. The communication plan import status dialog will display a message importing these values was unsuccessful.
If you are importing a communication plan 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 communication plans 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.