Upgrading to a new version of the Integration Agent

This article explains how to upgrade from a previous installation of the xMatters Integration Agent to the latest version, and how to migrate any existing integrations running on your existing version.

Note: For detailed system requirements, and installation instructions for new deployments, refer to the online documentation


This article uses the <IAHOME> placeholder to refer to the Integration Agent installation folder. For example, in a default Unix installation of the Integration Agent version 5.1.8, the IAConfig.xml file is located in /opt/xmatters/integrationagent-5.1.8/conf 

To simplify this reference and account for potential differences in the actual installation folder, the documentation would refer to the folder and file as <IAHOME>/conf/IAConfig.xml

Process overview

Because the xMatters Integration Agent does not include an installer, patching an existing Integration Agent installation requires only that you extract the latest version of the Integration Agent archive onto your server, and then migrate selected files from your existing deployment. This ensures that you will have a working Integration Agent to fall back on if you encounter complications while configuring the new version.

Incompatible versions

The following files have been modified in recent releases of the Integration Agent, and older versions of these files are incompatible with the 5.1.8 and later releases:

File Incompatible Versions
IAConfig.xml 5.1.2 and older
deduplicator-filter.xml 5.1.2 and older
mule-config.xml 5.1.6 and older
spring-config.xml 5.1.6 and older
wrapper.conf 5.1.2 and older

If you are upgrading from an older Integration Agent and have customized or modified these files, your changes must be manually migrated into the new files.

NOTE: This release of the Integration Agent includes changes to the mule.sh file. If you have modified this file, you will need to merge your changes with the file included in the patch.

Upgrade the Integration Agent

The following steps explain how to upgrade your Integration Agent.

It is strongly recommended that you complete these steps on a non-production or staging environment before attempting to upgraded your production deployment. You will need to repeat these steps for each Integration Agent in your deployment. 

Step One: Install the new version 

  1. Download the latest version of the Integration Agent from the Integration Agent page and extract the contents.
  • If you are installing to a Unix environment, be sure to perform the extraction as the user that will be running the Integration Agent OR set the correct permissions to the folder and files in the Integration Agent directories.
  • Review the release notes for your new version; the 5.2 release notes can be viewed here
    • Note any known issues or other differences that may require additional changes to your current or new installation.

    NOTE: You may also want to create a backup of the new <IAHOME>/conf directory; you will be modifying the contents of some files in this folder in the following steps.

    Step Two: Install the latest Integration Agent utilities

    The Integration Agent Utilities bundle (IAUtils) is a collection of scripts and binary code that provides required functionality for many integrations. The bundle is distributed separately from the main Integration Agent installer, but must be installed at the same time. If the IAUtils package is not present when the Integration Agent is started, the start up may fail.

    1. Download the IAUtils package (integrationagent-utils-<version>.zip) from the Integration Agent page, and extract the contents to your new <IAHOME> directory.
    • Allow the extracted lib and integrationservices folders to merge with the ones created by the Integration Agent extraction in Step One. 

    For more information about the IAUtils, refer to the "Installation" chapter of the xMatters Integration Agent Guide.

    Step Three: Copy configuration files

    1. Copy the following files from the <IAHOME>/conf folder in your previous Integration Agent installation to the matching location in the new installation:
    • IAConfig.xml
    • deduplicator-filter.xml
    • log4j.xml
    • .wspasswd
  • If you have any other password files required for specific integrations, copy them from their locations in the old Integration Agent installation to the matching locations in the new installation.
  • Copy any other customized configuration files (for example, wrapper.conf) from the conf folder to the new installation.
  • Step Four: Copy integrations

    1. Navigate to the <IAHOME>/integrationservices folder in your previous Integration Agent installation.
    2. Copy each integration service folder (and all of its files) that you want to use in the new Integration Agent to the <IAHOME>/integrationservices folder.

    You can return to this step and copy integrations to the new Integration Folder after you have completed the upgrade, but remember to stop and restart the Integration Agent afterwards.

    Windows users only:  Remove the existing service, and ensure the new service is running prior to testing the integration.

    1. Open a command window and navigate to the bin folder in your existing installation directory and run remove_service.
    2. Navigate to the bin folder in the new installation directory and run install_service, then run start_service.

    Step Five: Test your integrations with the new Integration Agent

    To make sure that your configuration was correct and the Integration Agent was successfully upgraded, send and respond to a notification using one of your integrations. Once you've confirmed that the management system has received the updated, your upgrade is complete. 

    If the Integration Agent does not work as expected, you can revert to the previous version until the problem has been resolved. For help, contact xMatters Customer Support



    The Integration Agent fails to start, and the logs indicate a "Base64" error similar to the following:

    Cannot import "Base64" since a property by that name is already defined.


    This occurs because the Integration Agent version 5.1.8 uses Java 1.8, which offers new functionality, and includes a class called Base64. Previous Integration Agents used earlier versions of Java which did not include this class, and therefore had to explicitly import Base64 from another source.

    For complete instructions on how to resolve this error, refer to the article "Integration Agent will not start due to "Base64" exception".


    Attempting to get the status of the Integration Agent, returns an error similar to the following (line breaks added for legibility):

    ./iadmin.sh get-status

    The command could not be executed because of the following problem:
    The Integration Agents status could not be determined because of an exception.
    If this exception was thrown while executing a different command (e.g., suspend),
    then that command succeeded. Consult the log file for further details.


    You are running another instance of the Integration Agent that is using the ports required by the new Integration Agent. Make sure you have properly stopped ALL running Integration Agent processes or services, and then restart your Integration Agent. (For reference, the ports in question are defined in the IAConfig.xml file.)


    Starting the Integration Agent generates a stack trace similar to the following (line breaks added for legibility):

    2016-10-11 13:53:07,821 [WrapperSimpleAppMain] FATAL - Exit code 86: 
    The Mule configuration located at ./conf/mule-config.xml contains an error.
    Reason: MuleManager Failed to initialise (org.mule.config.ConfigurationException)
    com.alarmpoint.integrationagent.exceptions.ExitCodeException: Exit code 86:
    The Mule configuration located at ./conf/mule-config.xml contains an error....
    Caused by: org.dom4j.DocumentException:
    Error on line 15 of document : cvc-elt.1.a: Cannot find the declaration of element 'deduplicator'.
    Nested exception: cvc-elt.1.a: Cannot find the declaration of element 'deduplicator'.


    This is due to the deduplicator-filter.xml file not being up to date; i.e., it is from an Integration Agent prior to version 5.1.3. To confirm that your file is correct for this version, open it in a text editor and locate the following line (approximately line 14):

    <deduplicator xmlns="http://www.alarmpoint.com/schema"> 

    If this line does not exist, or contains a different value, you will need to replace it with the deduplicator filter supplied in the Integration Agent archive and manually transfer your filter settings from the deduplicator-filter.xml file in your previous installation.


    Attempting to connect the Integration Agent to xMatters On-Demand returns a registration error.


    This is likely due to a mismatch between your Integration Agent ID and the xMatters Access Control List (ACL). Repeat Step Six above, and ensure that xMatters Support has added your correct Integration Agent ID to the ACL.

    Additional resources

    Have more questions? Submit a request


    • 0
      Kim Jue

      Some integrations require integration specific libraries, just had an issue where Netcool updates were failing, in this case we do database updates, so you will want to copy the jar file from the old agent to the new one:




      Restart the new agent at this time to read in the library file

    • 0
      Kim Jue

      While on a webex today, the person mentioned that some step I asked him to follow are missing from the DOCs above.

      If you are on windows, and you install your agent in the folder that the zip puts it in


      you will want to CD to 

      your old IAHOME/bin

      and run remove_service

      cd to the new IAHOME/bin

      and run install_service

      then start_service


    • 0
      Jane Rizhanovsky

      Hi Kim,

      I've integrated your comments into the instructions.


    Please sign in to leave a comment.