xMatters integration agent 4.1 patch 8 Release Notes


Document Overview

Release Overview



Document Overview

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

Patch version: PATCH-410-008-APIA

Build: 2682

Revision: 66047

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

The following features and fixes are included in this release:

Plain text passwords removed from integration agent logs

In xMatters, custom password fields are encrypted when they are stored in the database. The field values can be accessed and decrypted from the scripting language. This patch adds a new flag to the getCustomFieldValue method that allows the action scripts to send requests to the integration agent with an encrypted password. This allows integrations to decrypt the password and authenticate with management systems and still keep passwords from being recorded in the integration agent logs as plain text. (Note that the default setting will not interfere with existing integrations.) For more information about this method, refer to the xMatters Online Developer's Guide, or see the article Updating integrations to encrypt password values.

(xMatters reference: ARCH-1305)

Integration agent regex parser not accepting valid hostnames

An error was identified in the IAConfig.xsd file, which contains the hostname entity regex, that was preventing the integration agent from recognizing valid hostnames when parsing the SMTP-relay hostname in the IAConfig.xml file. This issue has been addressed.

(xMatters reference: APO-6922)

Integration agent not sending queued messages on restart

The integration agent's outbound queue consumer, used to pull messages out of the outbound queue for forwarding to xMatters, was being created the first time a message was added to the outbound queue. Until the message was added, no consumer existed, and therefore messages would remain queued and not sent. The integration agent has been updated to create the outbound queue consumer on startup.

(xMatters reference: APO-6909)

Integration agent extremely slow to send messages to xMatters

In some very rare cases, the ActiveMQ broker in the integration agent could cause the message exchanger to submit messages at a greatly restricted rate. This was traced to an issue with the spring-config.xml file, which contained different settings for two separate ActiveMQ connection factories. The spring-config.xml file has been updated to address this issue, and the xMatters integration agent guide has been updated to include the necessary changes.

(xMatters reference: XFO-3941)

Retry attempts counted incorrectly

An issue was identified where the integration agent would count any attempts to resend a problematic message to xMatters as retry attempts for all messages in the outbound queue. This was due to the way the delivery counter was being incremented for all messages in a batch, rather than for each individual message. This issue has been addressed.

(xMatters reference: APO-6898)


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

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

          tar -xvf PATCH-410-008-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-4213 Originally created by Don Clark

Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk