These release notes are for the following xMatters integration agent patch release:
Patch version: PATCH-410-005-APIA
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.
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.
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
(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
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
(xMatters Reference: INTA-1159)
(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:
- 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:
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:
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.
JDN-2981 Originally created by Cameron Stewart