xMatters 5.1 patch 008 release notes

Contents

Document Overview

Release Overview

Installing This Patch

Appendices

Document Overview

These release notes are for the xMatters 5.1 release:

Release version: PATCH-510-008

Revision: 85915

Release date: December 22, 2015

To download the latest version, see the xMatters 5.x Product Suite page.

NOTE: This document is subject to change after the initial release. If you would like to be alerted when the document is modified, click Follow above this article.

Release Overview

This release of xMatters offers the following deployment options:

  • You can install this release as a new xMatters version 5.1 deployment (i.e., you do not need to install a previous version of xMatters);
  • You can use this release to patch an existing xMatters 5.x deployment up to xMatters version 5.1 patch 008 (in this case, this release should be applied to all xMatters application nodes, notification nodes, web servers, and to the Data Sync server, if applicable); or,
  • You can use the included database migration tool to upgrade from xMatters 4.1 patch 023 directly to xMatters version 5.1 patch 008 (for more information and complete migration tool instructions, refer to the xMatters 5.x Documentation).

Issues Fixed in This Release

The following table lists the issues addressed since the most recent patch release and included in this version of xMatters. To see details about an issue, click the related link in the Details column:

Reference Issue FixedDetails
APO-10128 The retrieveInteractionContext method logs a misleading audit message Details
ARCH-3569 Callout script fails on notification server if service call brokering enabled Details
HOTH-3586 Stack trace when retrieving recipient display name Details
XFO-6451 Notification stops when there is a failed message bus message Details
XFO-6452 Stack trace when a ProcessNotificationEventMessage fails three times Details
XFO-6460 Multiple, concurrent requests for the same phone number leads to unique constraint violations on SQL Server Details
XFO-6554 Node Health Monitor checks thows NullPointerException Details
XFO-6564 Misconfigured event domain causes Integration Agent registration failure Details
XFO-6565 400 error on Users and Groups pages in Firefox Details
XFO-6657 Number of lines reserved for incoming calls not being respected when creating SIP/PSTN threads Details

Installing This Release as a Patch

The following instructions describe how to use the installer to patch an existing xMatters 5.x deployment and upgrade it to version 5.1 patch 008. For information about installing a new xMatters 5.x deployment, see the xMatters 5.x Documentation.

Apply this patch to all xMatters application nodes, notification nodes and web servers (and any Data Sync installations, if applicable).

Installer files included with this release:

xmatters-installer-i586-5.1.8

For use on:

  • All Linux systems
  • Supported Microsoft Windows systems that require PSTN/Dialogic support

Note that this installer file also requires a 32-bit JRE.

xmatters-installer-x64-5.1.8

For use only on supported Microsoft Windows systems that are using a 64-bit JRE, and which will not require PSTN/Dialogic support.

Warning: Existing integrations

When applying an xMatters patch to an existing installation, the patch may overwrite some files that were already modified for an integration. This may cause the integration to stop working. If this occurs, using the integration documentation, re-apply the configuration changes and validate the integration. (See also Integration stops working after applying patch.)

Warning: Configuration file changes

When applying an xMatters patch, any changes you have made to the parameters in any of the configuration files may not be retained. The patch may overwrite modifications to some or all of the following files:

  • node\assets\resources\spring\integration\*.xml
  • webserver\webapps\cocoon\WEB-INF\classes\resources\spring\integration\*.xml
  • webserver\webapps\axis2\WEB-INF\classes\resources\spring\integration\*.xml
  • webserver\webapps\mobilegateway\WEB-INF\classes\resources\spring\integration\*.xml
  • node.sh
  • webserver.sh
  • node-start.conf
  • webserver-start.conf
  • c3p0.properties
  • c3p0-config.xml

Any changes you may have made according to the information in the xMatters installation and administration guide will need to be reapplied.

Warning: Database changes

If you are upgrading from an older version, be aware that this patch includes database changes that may impact your replication mechanism (consult with your database administrator for further details).

These patches may also include updates to the database audit tables that can take an extreme amount of time to adjust when applying the patch. It is highly recommended that you clear the audit data (i.e., archive all your runtime data by running the Clear Runtime/History job in the web user interface) before installing any xMatters patch to reduce the amount of time required for the patch to process the data.

Note that introducing new indexes to a database may cause an increase in the required storage space. This is a normal consequence of using indexes, and assists performance of the overall system.

Installation Steps

Before installing this patch:

  1. Shut down or stop all node processes.
  2. Shut down or stop all web server processes.
  3. Back up the xMatters Database.
  4. If you have made changes to the Template Company scripts, back up your script packages (see note about database changes, above.)

Note: If you are installing on Windows, you must run the installer as an administrator.

To install this patch:

1. Back up the xMatters installation directory (referred to as <xMHOME>).

  • On Linux, the default install directory is:

/opt/xmatters/

  • On Windows, the default install directory is:

C:\Program Files (x86)\xMatters\

2. Save the xMatters installer file to your local machine.

3. Open a command prompt and navigate to the directory containing the installer file.

4. Do one of the following:

  • To run the installer in GUI mode, run the following command (replace <version> with i586 or x64, depending on your version of the installer):

java -jar xmatters-installer-<version>-5.1.8.jar     

  • To run the installer in console mode, run the following command (replace <version> with i586 or x64, depending on your version of the installer):

java -jar xmatters-installer-<version>-5.1.8.jar -console

5. The installer displays a welcome message; press Enter (console installation) or click Next (GUI installation) to continue.

6. Specify the location on the machine where the xMatters components are installed, and then press Enter or click Next to continue.

  • The installer will inspect the current installation and determine whether the patch needs to be applied.

7. Next, the installer offers the following options:

  • Back up the installation folder: Selecting this option will create a backup copy of the existing xMatters installation directory (by default, saved to /opt/xmatters.bak.1/)
  • Remove old application log files and temporary folder: Selecting this option will remove the temporary folders and log files from the existing installation's web server cache.

8. Select the options you want, and then press Enter or click Next to continue.

9. The installer then checks the disk to determine whether there is enough space to continue with the installation; press Enter or click Next to continue.

10. Next, the installer displays a summary of your selected options and the components included in the patch process; press Enter or click Next to continue.

  • The installer will then patch your installation. When it is complete, it displays a summary page, and gives you an option to generate an automatic installation script so you can patch other components using the same options. (For more information about the automatic installation script, see the xMatters installation and administration guide.)

Post-Installation Steps

After installing this patch:

  1. Start the Node processes.
  2. Start the web server processes.

Important:

  • Database upgrades may take place after this patch is applied (i.e., during startup of xMatters components). The first component to be started will cause the database upgrades to be applied. This means that the subsequent startup of web servers and nodes may be delayed while they wait for the database updates to be completed. To monitor the progress of the updates, see "Determining the status of database updates", below.

Determining the status of database updates

To determine the current status of database updates, open the log file(s) associated with the first xMatters component being restarted. The default locations are shown; only one log will include the MUTEX entries. Note also the log level indicated in the messages below; if your logging level is not detailed enough, you will not see the log messages.

Node

<xMHOME>/logs/AlarmPoint.txt

Web Server

<xMHOME>/webserver/webapps/axis2/WEB-INF/logs/AlarmPoint_WebApp.log

<xMHOME>/webserver/webapps/cocoon/WEB-INF/logs/AlarmPoint_WebApp.log

<xMHOME>/webserver/webapps/mobilegateway/WEB-INF/logs/AlarmPoint_WebApp.log

During component restart, you will see log entries similar to the following:

2009-01-21 22:07:02,251 [AlarmPoint Node-main] WARN - - Acquiring patch update MUTEX.  
2009-01-21 22:07:21,685 [AlarmPoint Node-main] WARN - - Acquired patch update MUTEX.  
2009-01-21 22:07:22,356 [AlarmPoint Node-main] WARN - - Package 1 of 8 (apod/oracle/01.xml)  
2009-01-21 22:07:22,356 [AlarmPoint Node-main] WARN - - Statement 1 of 2: Executing SQL Statement.  
2009-01-21 22:07:22,506 [AlarmPoint Node-main] WARN - - Statement 2 of 2: Executing SQL Statement.  
2009-01-21 22:07:22,516 [AlarmPoint Node-main] WARN - - Package 2 of 8 (apod/oracle/02.xml)  
.  
.  
.  
2009-01-21 22:07:22,847 [AlarmPoint Node-main] WARN - - Package 8 of 8 (apod/oracle/finalize.sql)  
2009-01-21 22:07:22,936 [AlarmPoint Node-main] WARN - - The database update scripts have been successfully processed and deleted.  
2009-01-21 22:07:22,936 [AlarmPoint Node-main] WARN - - Patch update MUTEX released.1  

After the message "Patch update MUTEX released" appears in the log, the database update has completed.

Note: If the log shows that the process has not proceeded from "Acquiring patch update MUTEX" to "Acquired patch update MUTEX" in a timely manner, ensure that there are no locks on the ORGS database table.

Appendices

Appendix 1: Details For Issues Fixed In This Release

The retrieveInteractionContext method logs a misleading audit message

During the processing of a phone call made by xMatters, one of the methods involved logged an audit message that could be easily misinterpreted, due to the wording of the message and the order in which it was listed in the logs. The message has been removed to help clarify call progression and delivery status.

Callout script fails on notification server if service call brokering enabled

An issue was identified with the callout scripts on the xMatters notification server node where the script would fail if the service call brokering feature was enabled between the application server node and the notification server node. This was due to a problem with the way the script variable parameters were handled during the brokerage; this issue has been addressed.

Stack trace when retrieving recipient display name

A customer reported receiving a stack trace when attempting to retrieve the display name for a recipient from the message bus after a message had exceeded the number of available retries. This was traced to a problem with the way the process was initialized in the underlying code; the issue has been addressed.

Notification stops when there is a failed message bus message

An issue was identified where a notification would stop if a message bus message threw an exception while the message was being discarded. The problem was traced to code that was attempting to log an audit message during a notification processing failure. The code surrounding the handling of database and other exceptions has been updated to allow the message bus messages to be discarded as intended.

Stack trace when a ProcessNotificationEventMessage fails three times

An issue was identified where a ProcessNotificationEventMessage that failed three times would result in a stack trace. This was caused by the underlying code attempting to retrieve the display name from a recipient object; the code has been updated to get the name from a service call instead.

Multiple, concurrent requests for the same phone number leads to unique constraint violations on SQL Server

An issue was identified on deployments using SQL Server where repeated executions of the same database query would cause multiple processes to generate the same simple response codes for the same phone number, leading to unique constraint violations. The stored procedure has been updated to include an UPDATE statement that takes out an update lock to resolve this issue.

Node Health Monitor checks thows NullPointerException

An issue was reported where the node health monitor message would throw a null pointer exception if the URL in the message could not find a matching node. While upgrading the node fixed this issue in the specific case, the health monitor message has been updated with new code to handle the situation if it should occur again.

Misconfigured event domain causes Integration Agent registration failure

An issue was reported where a misconfigured event domain would cause the Integration Agent to fail to register. This was caused by the system throwing an error and preventing the Integration Agent from being able to register. The system has been updated to log the misconfigured data, and set the status of the integration to FAILED.

400 error on Users and Groups pages in Firefox

An issue was reported with the Firefox web browser where attempting to view the Users or Groups pages would display a "400 Error" page. This was due to change in the way Firefox version 41 and 42 handle older versions of GWT's history implementation. A workaround has been implemented to allow the pages to display correctly.

Number of lines reserved for incoming calls not taken into account when creating SIP/PSTN threads

An issue was reported where the SIP and PSTN device engines were not respecting the configured number of lines reserved for incoming calls when creating threads. This issue has been addressed.

Appendix 2: Known Issues

xMatters 5.0 patch 007 included an upgrade to the included Java version from Java 6 to Java 7. The Automated-Speech-Recognition (ASR) functionality is currently not compatible with Java 7. If an xMatters deployment includes scripts that use ASR, the node will crash. The following are examples of script calls that use ASR:

@phone::getVoice("alphabetic","")
@phone::getVoice("digit","")
@phone::getVoice("digits")
@phone::getVoice("grammar","yesno")

(xMatters Reference: XFO-3472)

Some flavors of Linux with SELinux enabled will not run Java 7. After installing xMatters and trying to start the node, users may encounter an issue where Java fails to start, and an error similar to the following appears in log files:

Error: dl failure on line 864
Error: failed /opt/xmatters/staging/jre/lib/i386/server/libjvm.so, because /opt/xmatters/staging/jre/lib/i386/server/libjvm.so:
cannot restore segment prot after reloc: Permission denied

This is due to an issue with SELinux identifying the Java 7 libraries as a possible security threat. To resolve this issue, you must edit the /etc/selinux/config file and disable SELlinux.
(xMatters Reference: DTN-3158)

On Linux, serial modem Device Engines (TAP, GSM, etc.) that have experienced a connection failure due to a modem power failure (or deliberate power down) do not recover after the modem is powered on. Instead, to resolve the problem the node must be restarted. NOTE: this issue occurs only when Flow Control is set to "hardware".
(xMatters Reference: PRE-4832)

The xMatters Installer does not remove the Windows Services (i.e., the xMatters Webserver and the xMatters Node) when uninstalling. Instructions on how to manually remove the services have been added to the xMatters installation and administration guide, or are available on the Microsoft Windows Support site.
(xMatters Reference: XFO-2013, DTN-2960)

Appendix 3: DDL and DML Changes in This Release

DDL Changes

  • Update simp_sms_resp_query for SQL Server to take out an update lock on the phone number to prevent unique constraint violations.

 

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk