Document Overview

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

Release version: integrationagent-5.1.3

Revision: 73251

Download: Integration Agent for xMatters 5.x & xMatters on demand 

Release Date: March 25, 2014 

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 in the menu to the right of this document. 

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 patch 001 through 5.1 patch 002). 

Note that this version of the xMatters integration agent consolidates and replaces the 5.0 integration agent for premises deployments, and the 5.5.x version previously used for xMatters on demand. The 5.1.3 version of the integration agent can now be used for xMatters 5.0 and 5.1 deployments, and for xMatters on demand. 

Changes to patch contents

This patch introduces some changes to the installation procedures and addresses a known issue. Review the installation steps and known issue list carefully before installing. 

Updates and Features

This release of the integration agent includes the following update: 

Integration agent messages discarded after throttled send attempts

Recent changes to the integration agent moved the throttling mechanism to the xMatters server. A communication issue meant that the integration agent was treating repeated injection attempts that exceeded the throttling threshold as failures, and discarding the message after the configured number of retry attempts (default of three). 

To resolve this issue, the integration agent has been updated to recognize THROTTLE_EXCEEDED errors as being rejected by the throttling mechanism and not failures. The retry count will not be incremented for these messages, and the messages will remain on the queue until they can be processed by xMatters. Also, the message exchanger has been updated to temporarily adjust the exchange interval when a throttle exception is returned, preventing unnecessary network traffic between the integration agent and xMatters until the message can be processed.

(xMatters reference: XFO-5081) 

Included updates

The following changes, from the integration agent 5.1.2 patch, are also included with this update: 

Updated JRE

The JRE packaged with the integration agent has been upgraded to Java JRE 7. This includes the following changes:

• The Windows, Linux, and Solaris SPARC JREs have been updated toe Oracle Java 7u51 (December 2013).
• The HP-UX Itanium JRE has been updated to the Java 7.0.8 revision of HP's build of the JRE, and the AIX PPC JRE has been upgraded to revision 1 of IBM's build of the JRE. These are the latest builds provided (both dated December 2013) and may not be identical to revision 51 of the Oracle Java JRE
• HP-UX PA-RISC is no longer supported for the integration agent. The previous release of the integration agent (5.1 patch 001) is the last version that supports the PA-RISC architecture. (The 64-bit HP-UX Itanium architecture is still supported.)

This update also necessitated changes to the wrapper.conf file; for more information, see the "Installing" section, below. 

Note also that previous versions of the integration agent came with an embedded verison of IAUtils, but these utilities are also included in the integration packages, often with customized or required updates. The IAUtils included with the integration agent were out-of-date and no longer relevant to the standard installation, and have therefore been removed from the integration agent bundle.

(xMatters Reference: 4887) 

Logging Java runtime exceptions

Previously, certain exceptions that occurred were not being written to the integration agent log files. If the integration agent was running in console mode, these messages could be seen in the stderr stream, but were not available at all if the integration agent was running in service mode. While it was possible to configure the wrapper.conf file to write the message to a separate category of "apia*.txt" files, it was difficult to prevent the messages from being excessively verbose, and difficult to interpret. 

To address this issue, existing functionality from the xMatters node logging has been added to the integration agent. These runtime exceptions should now be logged in the integration agent log files, and be relatively easy to interpret.

(xMatters Reference: XFO-5005) 

OutOfMemory errors

Some customers reported an issue with the integration agent where it would periodically fail with an "OutOfMemory - cannot create thread" error, and require a restart. The error was traced to a conflict between scheduling the clean-up of outdated threads and creating a new thread, and has been addressed.

(xMatters Reference: XFO-5009) 

Installing

For detailed system requirements, and installation instructions for new deployments, refer to the xMatters 5.x Documentation. The following instructions explain how to apply this update as a patch to an existing deployment. 

Files included with this release:

integrationagent-5.1.3-<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 over your existing deployment. 

Updates to wrapper.conf

The wrapper.conf configuration file has been modified with this release to include the following line underneath wrapper.java.additional:

wrapper.java.additional.6=-Xbootclasspath/a:%INSTALL_DIR%/jre/lib/tools.jar

Upgrades to existing installations of the integration agent will require that you add this line to the wrapper.conf file to allow for dynamic compilation of integration scripts. If the number 6 specified in the line would clash with any other uncommented java.additional parameters, modify it accordingly, but ensure that no numbers are skipped or commented out in the sequence. Any parameters after a skipped or missing number will be ignored. 

Note also that on HP-UX Itanium, the number 6 is reserved, and the line must be modified to:

wrapper.java.additional.7=-Xbootclasspath/a:%INSTALL_DIR%/jre/lib/tools.jar

This applies to all users of HP-UX, not only those upgrading an existing installation. The included wrapper.conf file uses "6" for the sequence number and this must be modified on ALL HP-UX Itanium deployments. 

Before applying this patch, create a back up of your entire integration agent installation directory. 

To patch the integration agent:

1. Navigate to the <IAHOME>/conf directory, and back up the following files:
   • IAConfig.xml
   • log4j.xml
   • deduplicator-filter.xml
   • wrapper.conf
     
   • Any other files for which you have modified the default configuration.
2. If you have made any changes to the default files in the /integrationservices folder, back up the modified files.
   • Note that copying over the upgraded files will not overwrite or remove any additional files you may have created or installed for integrations.
3. Download the integrationagent-5.1.3 file appropriate for your operating system, and extract the archive file to a temporary folder.
4. Stop the integration agent you are upgrading.
5. If they exist, delete the following libraries from the integration agent installation folder. These files will be replaced by updated versions in the new installion, but the new versions may not be loaded properly if the integration agent loads an older version first.

On Windows:

• <IAHOME>\lib\mule-1.4.3\lib\opt\xstream-1.3.1.jar
• <IAHOME>\lib\mule-1.4.3\lib\opt\xpp3_min-1.1.3.4.O.jar

On Unix:

• <IAHOME>/lib/opt/xstream-1.3.1.jar
• <IAHOME>/lib/opt/xpp3_min-1.1.3.4.O.jar

6. Copy the contents of the extracted archive over your existing installation.
7. Restore the files you backed up in step 1.
   • If there were any files other than the three listed XML files for which you modified the configuration, you may need to compare them with their replacements to ensure that your configuration changes are applied to the patched integration agent.
8. Using a text editor, open the conf/deduplicator-filter.xml file.
9. Locate the <deduplicator> tag, and add xmlns="http://www.alarmpoint.com/schema" within the brackets. The tag should now resemble the following:

<deduplicator xmlns="http://www.alarmpoint.com/schema">

5. Save and close the file.
6. Restart the integration agent. 
7. Verify that the integration agent starts successfully.

• The following message should appear: "Successfully completed Integration Agent bootstrap process. Integration Agent is running."

NOTE: If you have an existing integration that relies on a specific version of the IAUtils package, the integration agent may not start properly. For more information, refer to Integration agent utilities.

Repeat the above steps for each integration agent in your deployment. 

After installing this patch

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

iadmin get-status 

  The following should be displayed:

            Version: 5.1.3  r73251 

Appendices 

Appendix 1: Known Issues 

IAUtils changes and updates

The integration agent may fail to start, or integration services may fail to communicate correctly with xMatters servers or management systems, if the integration agent utilities scripts and binary files are not updated as described in the above installation section.

For information on how to identify this issue, refer to Troubleshooting integration agent '"[xX][mM][lL]" is not allowed' errors.

(xMatters reference: SUP-8648)

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) 

The integration agent has an undocumented dependency on TCP port 61618

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

<transportConnector name="default" uri="tcp://localhost:61618"/>

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

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

java.lang.NullPointerException

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)

xMatters Reference

JDN-4628 Originally created by Don Clark