Quick Start Guide for the xMatters Integration Agent


We have taken the best parts of this article (well, almost all of it, really) and incorporated it into our new and improved Integration Agent documentation.



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, click the Users tab, and then click Web Services Users. Create a new 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 user

Create a user account that has the "REST Web Service User" role. This is the account that the sample communication plan will use to send notification requests to xMatters; we'll refer to this user as the "integration user" to distinguish it from the web services user.

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 check out the most up-to-date version of the Integration Agent documentation, 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 hosted instance. (The result should be similar to:
  • 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 "applications/sample-relevance-engine" integration service.

Save and close the file.

Create a password file for the Web Services User

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

Configure the sample communication plan

To help test your connection once the set up is complete, install the sample communication plan that comes with the Integration Agent. 

To import the communication plan:

  1. In the extracted Integration Agent archive, locate the <IAHOME>integrationservices\applications\sample-relevance-engine\SampleRelevanceEngine.zip file and copy it to your local workstation.
  2. Log in to the target xMatters system, click the Developer tab, and then click Import Plan.
  3. Click Browse, and then locate the SampleRelevanceEngine.zip file.
  4. Click Import Plan.
    • Once the communication plan has been imported, it should be automatically enabled. If it isn't click Plan Disabled to enable the plan.
  5. Click the Edit drop-down list for the plan, and select Access Permissions.
  6. Add the integration user you created above, and then click Save Changes.
  7. In the Edit drop-down list, select Forms.
  8. For the Send Event form, in the  drop-down list, click the Web Service Only drop-down list, click Permissions.
  9. Enter the integration user you configured above, and then click Save Changes.
  10. Click the Web Service Only drop-down list again, and select Access Web Service URL.
  11. Copy the URL to the clipboard or into a text file.

You can now configure the Integration Agent to connect to the sample plan.

To configure the Integration Agent connection:

  1. Open the <IAHOME>integrationservices\applications\sample-relevance-engine\configuration.jsp file in a text editor and locate the following line:
WEB_SERVICE_URL = "Paste the Form Web Service URL here"
  1. Replace the words within the double quotes with the Web Service URL you copied from xMatters. (Make sure you keep the double quotes!)
  2. Now locate the following line:
INITIATOR = "admin"
  1. Replace admin with the name of the integration user account.
  2. Save and close the configuration.jsp file.

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.

Use RESTClient, cURL, PostMan or a similar utility to send an HTTP POST request to the Integration Agent, with the following parameters:


Request body (formatted here for clarity):

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
    <building>\"Building A\", \"Building B\"</building>
    <targetName>bsmith, devices: [\"Work Email\"]</targetName>

Replace bsmith in the request body with the name of a notifiable user account that exists in the xMatters instance, and replace in the URL with the IP address of your Integration Agent.

For example, if you use cURL, the command would be:

curl.exe -i -X POST -d "<?xml version=\"1.0\" encoding=\"UTF-8\"?><event><properties><building>\"Building A\", \"Building B\"</building><city>Victoria</city></properties><recipients><targetName>bsmith, devices: [\"Work Email\"]</targetName></recipients></event>"

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