Quick Start Guide for the xMatters integration agent

Recently, a customer submitted a request to our Support forums, asking for a "simple explanation" of how the integration agent is set up and configured.

Well, our own inimitable Jeremy Brown has undertaken the impossible and done exactly that! Here is an overview of everything you need to know to quickly bring the integration agent up and and use it to submit a test notification to an xMatters user. There are no prerequisites aside from a working xMatters instance and a notifiable user (i.e., one with a working device).

Configure your xMatters instance

Before installing the integration agent, there are two configuration steps required in your xMatters instance.

Create a web services user

Log in to xMatters as a Company Administrator and click the Users tab. Create a web services user (the default name used by the integration agent is "ia_user") and assign them the following web services:

  • Register Integration Agent
  • Receive APXML
  • Submit APXML

You'll need the user ID and password for this web services user to configure the integration agent.

Create an integration service

Click the Developer tab, and then click Event Domains. On the Event Domains page, click the Generic event domain, and then add a new integration service named "generic".

Install and configure the integration agent

If you haven't already, download the latest version of the integration agent from the product page here.

(While you're at it, it's probably a good idea to grab the most up-to-date version of the integration agent guide, too. Never know when it might come in handy.)

Extract the integration agent

The first step is to unzip (or untar) the integration agent archive onto a suitable server or workstation.

Note: If you plan to use this integration agent for an integration with an existing software product, the simplest (and recommended) approach is to install the integration agent onto the same server as the product you want to integrate with.

The recommended installation folder for the integration agent is C:\xmatters or /opt/xmatters, depending on your operating system. Extracting the archive into this folder will create a subfolder named integrationagent-#.#.#, where #.#.# is the version number. For example:


This folder is referred to throughout the rest of this article (and the majority of the xMatters documentation suite) as <IAHOME>. (The remainder of this article will also default to Windows paths and commands; substitute the commands for your operating system wherever appropriate.)

Modify the integration agent configuration file

Navigate into your newly installed integration agent, and open the <IAHOME>\conf\IAConfig.xml file in a text editor.

Edit the following configuration settings:

  • In the web-services-auth section, replace the value in the user tags with the name of the web services user you created in xMatters, and replace the "Default Company" value in the company tags with the name of your company in xMatters. (Leave the password value for now; we'll get to that later.)
  • In the primary-servers section, change the localhost:8888 portion of the url value to point to the IP address (or hostname) and port of your xMatters web server.
  • If you don't have a secondary server, comment out the secondary-server sections.
  • In the service-gateway section, set the value for host to the IP address of the integration agent.
  • In the service-configs section, comment out all of the paths except for the "generic" integration service.

Save and close the file.

Create a password file

The password for the web services user is stored in an encrypted file in the same folder as the IAConig.xml file. Fortunately, the integration agent includes the encryption utility you need to create the file.

  1. Open a command window, and navigate to the <IAHOME>\bin folder
  2. Run the following command, but replace PASSWORD with the actual password of the web services user you created in xMatters:
 iapassword.bat --new PASSWORD --file conf/.wspasswd

Start the integration agent and check the connection

You can now start the integration agent and ensure that it's connecting to your xMatters instance.

In the command window, run the following command:


The command on non-Windows systems is: 


The console should start (hopefully with no errors), and display the following message:

Successfully completed Integration Agent bootstrap process. Integration Agent is running.

Now open another command prompt and navigate to <IAHOME>\bin, and run the following command:

iadmin get-status

You should see two indications that the connection to xMatters is valid:

  • The xMatters server should show "Connectivity status: PRIMARY ACCEPTED"
  • The generic integraton should show "Status: ACTIVE"

Send a test message

As a final confirmation, you can use the following command to send yourself a test message (replace BSMITH with your notifiable xMatters User ID):

apclient.bin --map-data generic 123 BSMITH test-message

Complete your configuration

You can now set up your integration services, integrations, and other configuration components in your functioning integration agent.

For additional information, consult the integration agent guide you already downloaded, or check out one of our many helpful, pre-built integrations.





xMatters internal reference: DTN-4578


Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk