xMatters integration agent 4.1 patch 5 Release Notes


Document Overview

Release Overview



Document Overview

These release notes are for the following xMatters integration agent patch release: 

Patch version: PATCH-410-005-APIA

Build: 263

Revision: 50911

Download: xMatters Integration Agent 4.1.0 Patches 

NOTE: This document is subject to change after the initial release of this patch. If you would like to be alerted when the document is modified, click Receive email notifications on the Actions menu to the right of this document.

Release Overview

This is a cumulative patch for xMatters integration agent 4.1, and should be applied to all existing integration agents in your deployment.

Features Added in patch 005

Shared Persistent Queue

The shared persistent queue provides a recovery mechanism when an integration agent fails and is unrecoverable. For details, see the new "Configuring the Shared Persistent Queue" section in the xMatters integration agent guide

Service-to-Service Requests

In some cases when authoring an integration, it may be desirable to encapsulate integration points as separate Integration Services. To have these Integration Services communicate, you can now configure Service-to-Service requests. Requests can be made to another service within the same integration agent without having to create an IntegrationServiceRequest. The Service-to-Service request sends an APXML message into a targeted service's inbound queue. For details, see the new "Service-to-Service Requests" section in the xMatters integration agent guide

Errors and Retries

You can now define APXML processing retry strategies for integration services. When processing an APXML message, integration services can detect anticipated errors (e.g., network failures when communicating back to a management system) and instruct the integration agent to reprocess the message after a configurable delay, and with a maximum attempt limit. This allows integration services to be resilient to transient exceptions. For details, see the new "Errors and Retries While Processing Inbound Queue" section in the xMatters integration agent guide

Auto Recovery of APClient.bin Messages

When APClient.bin is executed but a connection cannot be made to the integration agent, the message is saved in the APClient.log file. The --recover-file parameter to APClient.bin can be used to resubmit these messages, or the file can be placed in the recovery directory and the integration agent will recover those APClient.bin messages. When auto recovery is enabled, APClient.bin processes messages on a first-in first-out basis. This means that messages queued while the integration agent is unavailable will be processed before any new messages submitted after the integration agent starts. For details, see the new "Configuring Auto Recovery of APClient.bin Messages on integration agent Startup" section in the xMatters integration agent guide

Updated beanshell libraries

This patch includes updated beanshell libraries for integrations running in legacy mode. 

Features added in patch 004

Updated the HTTP endpoint to support RESTful path parameters that can be handled in the javascript hook for the mule HTTP Connector

(xMatters Reference: INTA-1547) 

Added HTTPClient 4.1 support in the IA to support the different HTTP methods for outbound communication from the IA scripts to RESTful services

(xMatters Reference: INTA-1413) 

Added support for SSL communication over HTTP using self-signed and signed certificates

(xMatters Reference: INTA-1594) 

Added multi-company support to the out of box Ping integration as an  example for the xMatters 4.1 Patch 08 multi-company support

(xMatters Reference: PRE-6607) 

Updated the ActiveMQ persistence adapter to use the recommended KahaDB persistence store

(xMatters Reference: INTA-1562) 

Update to the EventDeduplicator code to support UNIX systems out of the box

(xMatters Reference: INTA-1487) 

Features added in patch 003

Added new feature for lifecycle support to allow scripts to be run on start, stop, pause, resume and terminate events within the Integration Agent scripts

(xMatters Reference: INTA-1276) 

Bug fix for message loss in the Integration Agent SubmitAPXML

(xMatters Reference: INTA-1273) 

Bug fix for SOAP libraries to ensure consistent handling when escaping/unescaping XML special characters.

(xMatters Reference: INTA-1204)

Features added in patch 002

Added new jar file for Rhino to provide support for E4X in javascript

The js.jar requires xbean.jar to be deployed in the same folder for E4X support.

(xMatters Reference: INTA-1159) 

Added SOAP layer to provide a set of utility classes that can be accessed

from the javascript files to make SOAP requests to external systems.

(xMatters Reference: INTA-1159) 

Javascript Debugger to enable the debugging of the input action scripts so it is possible to trouble shoot issues in real time

(xMatters Reference: PRE-4097) 


For detailed system requirements and installation information, refer to the xMatters integration agent guide

Note: If you are installing the xMatters integration agent on an Intel Itanium-based server running HP-UX, refer to the following article for important post-installation steps: Installing the xMatters integration agent on an Intel Itanium-based server running HP-UX

Files included with this patch



Before installing this patch

Shut down the xMatters integration agent being patched. 

To install this patch:

1. Back up the xMatters integration agent installation directory.

  • On Windows, the default install directory is:

          C:\Program Files\AlarmPointSystems\IntegrationAgent 

  • On Unix, the default install directory is:


2. Save the PATCH-410-005-APIA.zip or PATCH-410-005-APIA.tar.gz file to the xMatters integration agent installation directory.

3. Do one of the following:

  • On Windows, extract (i.e., unzip) the PATCH-410-005-APIA.zip file to the installation directory and overwrite the existing files.
  • On Unix, run the following commands on the PATCH-410-005-APIA.tar.gz file and overwrite the existing files:

          gunzip PATCH-410-005-APIA.tar.gz

          tar -xvf PATCH-410-005-APIA.tar 

After installing this patch

1. Restart the xMatters integration agent process.

2. Run the following command from the xMatters integration agent's bin directory: 

          iadmin get-status 

  The following should be displayed: 

            Version: 4.1.0 263 r50911 



Appendix 1: Known Issues 

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

(xMatters Reference: INTA-1912, INTA-1914) 

No error message is thrown when messages are injected in APClient.bin with SSL enabled on apclient-gateway.

When SSL is enabled and a message is injected using APClient.bin, no error message is displayed in the user interface informing the user that APClient.bin does not support SSL. APClient.bin supports only HTTP communication with the integration agent, even if the value of the --http-post parameter is an https URL (however, the integration agent can communicate back to the Management System using any of the secure protocols supported by the Management System's API.).

(xMatters Reference: XFO-1705) 

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: XFO-1676) 

Appendix 2: Notice of Name Change

AlarmPoint Systems, Inc. is now xMatters, inc. This change extends to how we name our products: the AlarmPoint Integration Agent is now the xMatters integration agent; AlarmPoint Enterprise is now xMatters enterprise; and so on. 

During the ongoing transition to the new naming conventions, legacy corporate and product names will still appear in some parts of our products, such as directory paths, logs, and messages. This document reflects the new names whenever possible, while respecting the need for clarity when referring to older products, legacy issues, existing knowledge base articles, etc. 

For more information (including instructions on how to switch between the AlarmPoint and xMatters interfaces), see Common questions about rebranding from AlarmPoint to xMatters.

xMatters Reference

JDN-2981 Originally created by Cameron Stewart

Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk