xMatters Integration Agent 5.2 Release Notes

Document Overview

These release notes have been updated for the following xMatters Integration Agent release: 

Release version: integrationagent-5.2.0

Revision: 87543

Download: Integration Agent for xMatters On-Demand

Release Date:  June 28, 2018

NOTE: This document is subject to change after the initial release of this product. If you would like to be alerted when the document is modified, click Follow above. 

Release Overview

This is a cumulative release of the xMatters Integration Agent, incorporating all updates and patches for the Integration Agent version 5.x (all releases from 5.0.1 through 5.2.0).

NOTE: This version of the xMatters Integration Agent consolidates and replaces the Integration Agent for all xMatters On-Demand deployments.

For premises deployments, see the release notes for information. 

Changes to patch contents

Previous patches introduced some changes to the installation procedures and addressed a known issue. If you are upgrading from a version prior to 5.1 patch 007, it is highly recommended that you review the patch notes for that release before proceeding. 

Updates and Features

This release of the Integration Agent includes the following updates: 

Integration Agent security updates

We've reviewed all of the libraries included with or used by the Integration Agent for known security vulnerabilities, and updated or removed libraries as necessary.

Updated to use the xMatters REST API

The JavaScript libraries now use the xMatters REST API, rather than our previous API (which we will be deprecating). 

Better log file names

The log files for the Integration Agent now match the name of the product -  no more AlarmPoint.txt files! You can now find the much more sensibly named Integration Agent logs at <IAHOME>/logs/IntegrationAgent.txt

Sample integrations and documentation updated

We updated the sample integrations bundled with the Integration Agent installation to match changes in terminology and other feature enhancements. These new versions of the sample integrations are meant to help guide you through integrating using the most up-to-date best practices.

The instructions have also been updated to guide you through the latest recommendations for using the Integration Agent with xMatters On-Demand, improving the flow and cleaning out some of the dead wood, making it easier to find the information you need. We've also put the most important or useful information online, and structured it to help new and returning users get their Integration Agents up and running quickly. We've even added information on when to use the newer xMatters Agent, and when you might still need to use the Integration Agent.

(Power users can still find all the really advanced, technical details in the updated Integration Agent Guide pdf, available for download from the Integration Agent downloads page.)

Improved commenting in the Integration Agent files

Comments throughout the Integration Agent files have been updated to make the function of the various components and settings easier to understand and tailor to your situation.


To download the required files, see Integration Agent for xMatters On-Demand.

For detailed system requirements, and installation instructions for new deployments, see the Integration Agent section of the On-Demand Help

The following instructions explain how to apply this update as a patch to an existing deployment.

Configuration file changes

The following files have been modified in this or other recent releases of the Integration Agent, and older versions of these files are incompatible with the current release:

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.

Files included with this release:

integrationagent-5.2.0-<platform>.[zip | tgz]

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.

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.

To patch the Integration Agent:

  1. Extract the new Integration Agent folder from the archive to the root of your xMatters installation.
    • The result will be a new folder (typically c:\xmatters\integrationagent-5.2.0 or /opt/xmatters/integrationsagent-5.2.0, referred to in these release notes as <IAHOME>).
    • We will refer to the base folder of your old integration as <Old-IA>.
  2. Navigate to the new <IAHOME>/conf directory, and backup the following files:
    • Copy IAConfig.xml to IAConfig.xml.orig.
    • Copy deduplicator-filter.xml to deduplicator-filter.xml.orig.
  3. Open the above-named files with a text editor, and then copy any custom settings from the files in <IA-Old>/conf.
  • If you have customized any other files in your old integration agent's conf folder, merge the customizations over in the same way.
  • If you are not using the sample communication plan or sample integrated properties, comment out the references in the IAConfig.xml file (the paths including sample-relevance-engine.xml and sample-integrated-properties.xml).
  • Copy .wspasswd from <Old-IA>/conf.
  • Navigate to <IAHOME>/integrationservices and copy your integrations from <Old-IA>/integrationservices.
  • If you have made any changes to the default files in the /integrationservices folder (for example, <IAHOME>/integrationservices/applications/ping-plan/ping-plan.js), back up the new files before merging your modifications to them.
  • Stop any running Integration Agent processes or services.
  • Navigate to <IAHOME>/bin and start the Integration Agent (start_console.bat or ./start_console.sh).
  • Verify that the Integration Agent starts successfully.
    • The following message should appear: "Successfully completed Integration Agent bootstrap process. Integration Agent is running."
  • 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.

    Downloading the IAUtils

    You can download the IAUtils package (integrationagent-utils.jar) from the same Integration Agent page.

    Note: If you are using an integration that requires a specific version of the IAUtils, follow the instructions in the integration guide for that integration.

    To install the IAUtils, extract the integrationagent-utils.zip archive file to <IAHOME>, and allow the extracted lib and integrationservices folders to merge with the ones created by the Integration Agent installer.

    For more information about the IAUtils, see Get up and running with the Integration Agent in the On-Demand help.

    Verifying the Integration Agent version

    After patching and starting the Integration Agent:

    Navigate to <IAHOME>/bin and run the following command:

    • On Windows:
      iadmin get-status
    • On Linux:
      ./iadmin.sh get-status

    The following output should be displayed:

    Version: 5.2.0 r87543

    Repeat the above steps for each Integration Agent in your deployment

    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.

    Appendix: Known Issues

    Base64 exception

    The Integration Agent will not start if an integration script is loaded that uses the Base64 function imported from Apache. For more information and solution details, see "Integration Agent will not start due to Base64 exception". 

    Windows installation paths

    On Windows systems, the dynamic compilation feature of the Integration Agent will fail if the path contains spaces. If you use or are planning to use this feature, ensure that the integration agent is installed in a path that contains no spaces.

    (xMatters Reference: BUG-5168) 

    Reloading integration service via iadmin reload command causes all web service endpoints to fail

    After a single integration service is reloaded by running the iadmin reload command, all web service endpoints for all integration services (not just the service being reloaded) may stop working. This affects the functionality of mobile access requests, direct external service requests, and custom web service requests to all integration services. NOTE: issuing a subsequent  iadmin reload all restores the web service endpoints.

    (xMatters Reference: BUG-2206) 

    Messages may continue to be processed after the inbound queues are purged

    The iadmin purge command deletes all messages from the inbound/outbound queues of the specific (or all) integration services. Messages that are "in-process" during the purge (e.g., delayed after a retriable exception or actively being processed by input/response action scripting), may remain in the inbound queues and continue to be (re)processed. To work around this issue, either stop the integration agent or suspend the integration service prior to the purge, followed by a restart/resume.

    (xMatters Reference:  BUG-2180) 

    Messages may be reprocessed after an integration service is suspended and resumed

    Messages that are actively being processed by input/response action scripting during an iadmin suspend are allowed to complete without interruption. However, when a suspended integration service is resumed (either after an iadmin resume command or restart), messages that were being processed during the suspension may be reprocessed. Integrations are designed to handle reprocessing, but this may result in redundant updates (depending on the integration).

    (xMatters Reference: BUG-2181) 

    iadmin purge may periodically fail if the Integration Agent is not running

    The iadmin purge command sometimes fails to work when the Integration Agent is not running. This failure is indicated by an entry similar to the following in IntegrationAgentIAdmin.txt>:

    2012-08-09 10:00:46,502 [main] DEBUG - The command could not be executed because of the following problem:


    at org.apache.activemq.broker.jmx.BrokerView.getQueues(BrokerView.java:185)

    NOTE: re-issuing the iadmin purge command often succeeds, as the failure cause is transient.

    (xMatters Reference: BUG-2205) 

    Although APClient.bin reports non-connection related network errors, it does not write the failed submissions to the recovery log.

    (xMatters Reference: BUG-2263, BUG-2264) 

    Enabling password-authentication prevents event injections for all Integration Services using APClient.bin.

    Setting the parameter in the IAConfig.xml file to "true" will prevent any event injections for all Integration Services using APClient.bin. Note that password-authentication is typically not enabled out-of-the-box for integrations, so the impact of this issue should be very limited.

    (xMatters Reference: BUG-1122)

    Was this article helpful?
    0 out of 0 found this helpful



    Please sign in to leave a comment.