Get up and running with the Integration Agent

Follow along as we walk you through how to quickly set up the Integration Agent and send a test notification to an xMatters user, using our sample communication plan. The only thing you need is a working xMatters instance with a notifiable user (in other words, a user with a working device).

These instructions are tailored for the sample plan. However, you can use them as a guideline to configure any integration based on a communication plan.

Configure your xMatters instance

First, there are a couple of things you need to do in xMatters: create a web service user and an integration user.

Create a web service user

This is a user with specific permissions in xMatters to receive user responses and notifications about event status changes for the Integration Agent. ("Web service users" are a specific type of user in xMatters that can work with the SOAP web services used by the Integration Agent; this means you can't just use a regular user and assign them a specific role or permission – you have to create a dedicated user.)

Create an integration user

Integrations using a communication plan require a user who can authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but doesn't 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 and assign that user to the "REST Web Service User" role, which includes the necessary permissions and capabilities.

This is the account that is used to send notification requests to xMatters – we'll refer to this user as the "integration user" to distinguish it from the web services user.

Import and configure the sample communication plan into xMatters

Next, you need to import that sample plan into xMatters, do some basic configuration and copy the URL for the inbound integration.

You can now install and configure the Integration Agent then set up the sample plan to send a test message.

Install and configure the Integration Agent

If you haven't already, download the latest version of the Integration Agent and the Integration Agent Utilities (IA_Util) from the product page. Make sure you're getting the right file for your operating system!

Once you have those files, extract that package to a suitable server or workstation to install the Integration Agent, then you can configure and, finally, start the Integration Agent

Add your Integration Agent to our Access Control List

When you deploy the Integration Agent, you need to ask us to add it to the access control list (ACL). This allows us to whitelist your Integration Agent so it can talk to your xMatters On-Demand instance. For more information or to add your Integration Agent to the ACL, go to the xMatters Support site at support.xmatters.com and click Submit Request.

Set up the sample plan files on the Integration Agent machine

The final step before sending a test message is to set up the files used by the particular integration. To do this you need to create a password file for your web service and integration users then configure the sample-plan integration's configuration.js file.

Create the encrypted password files

The passwords for the web service user and the integration user are stored in encrypted files in the same folder as the IAConfig.xml file. Fortunately, the Integration Agent includes an encryption utility to create the file.

Configure the Integration Agent connection to the sample plan

You need to add the sample plan integration service to the IAConfig.xml file and change a couple settings in the integration's configuration.js file.

Start the Integration Agent and check the connection

You can now start the Integration Agent and make sure it's connecting to your xMatters instance.

We recommend that you start the Integration Agent in the console the first time, so you can see the console output. If you see errors when starting the Integration Agent, check out our troubleshooting tips.

You can also start the Integration Agent as a Windows service or Linux daemon. When running the Integration Agent as a Windows service or Linux daemon, there is no console output. This means that you must use the log files to monitor agent activities.

Send a test message

The final step is to check that things are indeed up and running. To do this you can send yourself a test message, using HTTP or the command line.

Explore the sample-plan integration further

There's much more you can do with the Integration Agent and communication plans. The following sections give you some examples of how you can edit the sample-plan files.

Configure outbound integration webhooks

Outbound integration webhooks (formerly and sometimes currently known as "callbacks") allow web applications and integrations to extract information from an xMatters event, and take action based on the extracted properties. You can configure webhooks for event status changes, notification deliveries, user responses, and event comments (annotations).

Mapped input parameters

When you pass in parameter values using the command line, the Integration Agent transforms them into a correctly-formatted REST API call (a JSON object) that generates notifications using the targeted communication plan.

Additional functions in the sample-plan.js file

Each integration service used by a communication plan form requires a Javascript file to properly transform the injected parameters into a post JSON body for the REST API. The included sample-plan.js file is pre-configured to work with the sample communication plan, but it also includes examples of all the necessary components and functions used to transform the data so you can use it as a template when building other integrations.