Document Overview

These release notes are for the following xMatters Integration Agent release: 

Release version: integrationagent-5.1.6

Revision: 85813

Download: Integration Agent for xMatters 5.x & xMatters On-Demand

Release Date: November 17, 2015 

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

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

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.6 version of the Integration Agent can now be used for xMatters 5.0 and 5.1 deployments, and for xMatters On-Demand.

Important notice about event throttling

If you are a premises customer, and have configured event throttling, note that this patch will cause the feature to become unresponsive.

To implement rate-limiting, you can modify IAConfig.xml and change the <apxml-exchange>::<size> and <apxml-exchange>::<interval> values. The <size> setting determines the maximum number of messages sent by the integration agent to xMatters in a single request. The <interval> setting determines how many seconds pass between requests. To set up a rate limit of max events per minute, the <size> and <interval> values should be modified so that:

<max events per minute> = (60 / <interval>) * <size>

Note: <interval> and <size> must be integer values.

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 updates: 

Updated HTTP handling for custom responses

The Integration Agent has been updated to support custom responses to incoming HTTP requests to an integration service. This update addresses the issue identified in this knowledge base article. For more information about implementing this feature, refer to the xMatters Integration Agent Guide.

(xMatters reference: COR-3655)

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.6-<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 onto your server, and then migrate selected files from your existing deployment. This ensures that you will have a working Integration Agent to fall back on if you encounter complications while configuring the new version.

Before applying this patch, create a back up of your entire Integration Agent installation directory. 

To patch the Integration Agent:

1. Extract the new Integration Agent folder from the archive to the root of your xMatters installation.
   • The result will be a new folder (typically c:\xmatters\integrationagent-5.1.6 or /opt/xmatters/integrationsagent-5.1.6, referred to in these release notes as <IAHOME>).
   • We will refer to the base folder of your old integration as <Old-IA>.
2. Navigate to the new <IAHOME>/conf directory, and backup the following files:
   • Copy IAConfig.xml to IAConfig.xml.orig.
   • Copy deduplicator-filter.xml to deduplicator-filter.xml.orig.
3. Open the above-named files with a text editor, and then copy any custom settings from the files in <IA-Old>/conf.
4. If you have customized any other files in your old integration agent's conf folder, merge the customizations over in the same way.
   
   Note: wrapper.conf, deduplicator-filter.xml, and IAConfig.xml were substantially changed for version 5.1.3, so be sure not to replace these files with ones from an earlier Integration Agent version.
   
   
5. Copy .wspasswd from <Old-IA>/conf.
6. Navigate to <IAHOME>/integrationservices and copy your integrations from <Old-IA>/integrationservices.
7. If you have made any changes to the default files in the /integrationservices folder (e.g., <IAHOME>/integrationservices/ping/ping.js), back up the new files before merging your modifications to them.
8. Stop any running Integration Agent processes or services.
9. Navigate to <IAHOME>/bin and start the Integration Agent (start_console.bat or ./start_console.sh).
10. 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.

After patching the Integration Agent:

1. Navigate to <IAHOME>/bin and run the following command:

• On Windows:

  iadmin get-status

• On Linux:

  ./iadmin.sh get-status

The following output should be displayed:

Version: 5.1.6 r85813

Repeat the above steps for each Integration Agent in your deployment. 

If the Integration Agent does not work as expected, you can revert to the previous version until the problem has been resolved. For help, contact xMatters Customer Support.

Appendices 

Appendix 1: Known Issues

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) 

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: BUG-2263, BUG-2264) 

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: BUG-1122)