This is a cumulative release of the xMatters integration agent version 5.1, and should be applied to all existing 5.x integration agents in your deployment.

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.0 patch 007 version of the integration agent can still be used for xMatters 5.0 deployments.)

Features Added

The following features and fixes are included in this release:

Added support for basic, digest, and NTLM authentication for APXML traffic via proxy server

The integration agent has been updated to include configuration parameters for basic, digest and NTML authentication for integrations sending APXML traffic to the xMatters web server via a proxy server. The new configuration settings are contained in the IAConfig.xml file; when backing up and restoring this file during an upgrade (as described below), you will need to compare and merge your versions to ensure that the new settings are not overwritten by your existing configuration file. Note that this feature replaces the proxy configuration previously specified in the wrapper.conf file, as described in this knowledge base article: Connecting the integration agent to xMatters web servers via web server proxy

(xMatters reference: XFO-4831)

Updated JavaScript libraries

The JavaScript libraries included with the integration agent have been updated. The new libraries support parsing of JSON strings natively in integrations' JavaScript files; for example:

// Note: String formatted for display only
var jsonString = '{ "employees": [
                              {
                                  "firstName":"John",
                                  "lastName":"Doe"
                              },
                              {
                                  "firstName":"Anna",
                                  "lastName":"Smith"
                              },
                              {
                                  "firstName":"Peter",
                                  "lastName":"Jones"
                              }
                          ]}';

var myJSONObject = JSON.parse(jsonString);

// Add values from the JSON to the APXML object
apxml.setToken("testToken", myJSONObject.employees[0].firstName + " " + myJSONObject.employees[0].lastName);  // John Doe
apxml.setToken("testToken", myJSONObject.employees[1].firstName + " " + myJSONObject.employees[1].lastName);  // Anna Smith

(xMatters reference: XFO-4824)

Validation added for deduplicator filter

In some cases, a deduplication filter containing invalid XML would cause the integration service script to fail when the filter was applied. This issue was traced to a modification made to the deduplicator where the call to the filter was changed to include a try-catch block. Due to the frequency with which modifications are made to the deduplicator filter and the relative obscurity of the failure itself, the integration agent was updated to check the validity of the deduplicator filter at startup. If the filter is invalid, the process will log an error, and not continue.

(xMatters reference: APO-7246)

Default configuration (on Windows) not supporting extended characters

Some customers reported that their integration agent-based integrations did not preserve accented or other special characters in the content of events injected into xMatters from their management systems. This issue was described and a resolution provided in a knowledge base article here: Enabling the Western Latin Character Set on the integration agent . This release of the integration agent contains modified default configuration files that include the fixes described in the article.

(xMatters reference: XFO-4689)

Password authentication of APClient submissions not supported

A customer reported that enabling password authentication on the integration agent resulted in their APClient.bin submissions being rejected, even when the correct password was supplied. This was traced to an issue with the way the integration agent handled the data mapping, and being unable to access the password at the time the request was received. To address this issue, the authentication process for APClient.bin submissions has been upgraded to accept the apia_password parameter, which can refer to a password file encrypted using the iapassword utility.

(xMatters reference: XFO-4445)

Installing

For detailed system requirements and installation information, refer to the xMatters 5.x Documentation.

Files included with this release:

integrationagent-5.1.1-

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.

To patch the integration agent:

Navigate to the /conf directory, and backup the following files:
- IAConfig.xml
- log4j.xml
- deduplicator-filter.xml
- wrapper.conf
- Any other files for which you have modified the default configuration.
If you have made any changes to the default files in the /integrationservices folder, backup 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.
Download the integrationagent-5.1.1- file appropriate for your operating system, and extract the archive file to a temporary folder.
Stop the integration agent you are upgrading.
Copy the contents of the extracted archive over your existing installation.
Restore the files you backed up in step 1.
- If there were any files other than the ones listed in 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.
Restart the integration agent.

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

After installing this patch

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

iadmin get-status

The following should be displayed:

Version: 5.1.1 r72101

Appendices

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:

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.).

Document Overview

Release Overview