xMatters integration agent 4.1 patch 7 Release Notes


Document Overview

Release Overview



Document Overview

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

Patch version: PATCH-410-007-APIA

Build: 1829

Revision: 56504

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

Features added in patch 007

Security enhancements

To help guard against cross-site scripting attacks, any scripting code that is reflected back to a user is encoded to prevent it from being executed. This will prevent any malicious code appended onto a URL targeting the integration agent from being executed in a user's environment.

(xMatters Reference: XFO-3334)

Features added in patch 006

This is a maintenance release of the xMatters integration agent intended to improve the robustness of the heartbeat, message exchange, and message processing behavior of the integration agent. The following entries describe the improvements. 

The integration agent automatically recovers after a failure/restart of the xMatters Web Server

During normal operation, the integration agent periodically registers its state with an xMatters web server. Prior to this patch, in some cases a failure of this registration process (e.g., transient/database network errors or a restart of the web server) caused the integration agent to stop registering until it was restarted. An integration agent that stopped registering could appear to be processing inbound events, but the xMatters web server would eventually report it as FAILED in the Component Status Report and stop forwarding requests/responses. Now, the integration agent's registration process will automatically recover from such failures.

(xMatters Reference: ARCH-427) 

The integration agent continues to exchange messages with xMatters after process interuption

During normal operation, the integration agent regularly submits outbound APXML messages to the xMatters web server with which it is currently registered.  APXML requests/responses from xMatters are also received by the integration agent during this message exchange process.  Prior to this patch, in some cases a failure of this message exchange process (e.g., transient/database network errors or a restart of the web server) caused the integration agent to stop exchanging messages until it was restarted. The integration agent sometimes continued to register with xMatters and appeared ACTIVE in the Component Status Report, but iadmin get-status indicated that the outbound queues were constantly growing. Now, the integration agent's message exchange process will automatically recover from such failures.

(xMatters Reference: ARCH-427) 

The integration agent continues processing inbound messages after a request time out

During normal operation, the integration agent processes messages from the inbound queues of its ACTIVE integration services. If the processing of a message takes longer than the configured request-timeout, the integration agent logs a warning and continues processing new messages. Prior to this patch, in some cases detection of the time out caused the integration agent to prematurely stop all inbound message processing until it was restarted. Now, the integration agent will continue processing inbound messages after a time out.

(xMatters Reference: ARCH-589) 

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-007-APIA.zip or PATCH-410-007-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-007-APIA.zip file to the installation directory and overwrite the existing files.
  • On Unix, run the following commands on the PATCH-410-007-APIA.tar.gz file and overwrite the existing files:

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

          tar -xvf PATCH-410-007-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 1829 r56504 


Appendix 1: Known Issues 

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) 

The integration agent has an undocumented dependency on TCP port 61618

The integration agent's conf/activemq.xml file contains the following element:

Because of this setting, during startup, the integration agent will attempt to bind a socket listener to port 61618.  If another process is using this port, the integration agent will fail to start with a "JVM Bind" error.  To restart the integration agent, either stop the process that is using port 61618 or change the transportConnector setting to refer to an unused port.

(xMatters Reference: BUG-2185) 

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 continues 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 AlarmPointIAdmin.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: 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. 

You can learn more about why we changed our name here

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-3369 Originally created by Don Clark

Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk