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 workflow. 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 workflow. However, you can use them as a guideline to configure any workflow.

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 alert 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 require a user who can authenticate REST web service calls when sending signals to xMatters.

This user needs to be able to work with alerts, 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 workflow

Next, you need to import that sample workflow 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 workflow 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!

You also need to download a JDK archive for your operating system.

Once you have those files, continue with the steps to extract that package to a suitable server or workstation to install the Integration Agent, add the necessary JDK files to <IA_home>, and configure and 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 validate 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 and click Submit Request.

Set up the sample workflow 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 workflow 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 workflow

You need to add the sample workflow 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 workflow integration further

There's much more you can do with the Integration Agent and workflows. The following sections give you some examples of how you can edit the sample workflow 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 alert, and take action based on the extracted properties. You can configure webhooks for alert status changes, notification deliveries, user responses, alert comments (annotations), escalations, and targeted recipient failures.

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 form.

Additional functions in the sample-plan.js file

Each integration service used by a 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 workflow, 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.