These release notes are for the xMatters 5.1 release:
Release version: PATCH-510-002
Release date: June 11, 2014
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 Following inon the Actions menu to the right of this document, and then select theInbox check box.
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 002 (in this case, this release should be applied to all xMatters Application Nodes, Notification Nodes, Web Servers, and to the DataSync 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 002 (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:
|ARCH-2231||Pressing Enter allows users to bypass validation errors when modifying an email device||Details|
|ARCH-2232||SMPP device engine cannot automatically recover from provider problem||Details|
|HOTH-2566||Included voice recording is not a professionally recorded version||Details|
|HOTH-2741||Events Activity report returns a stack trace when selecting the Attachments tab||Details|
|KAM-228||Incorrect Moscow time zone displayed on Site Details page||Details|
|KAM-285||Add device filters to the sample custom subscription panel||Details|
|KAM-288||isAnyRecipientNotifiable returns true for recipients that are not on duty||Details|
|KAM-289||Find Scenarios page does not show search criteria||Details|
|SCO-4683||Company Quotas screen allows a Max value lower than the In Use value||Details|
|XFO-4935||xMatters server does not process responses initiated by the Interaction script||Details|
|XFO-5020||FindWhoIsOnDuty returns a stack trace with StackOverflowError||Details|
|XFO-5078||French translation required for short code compliance text||Details|
|XFO-5079||Systems Notifications report could not execute query in SQL Server database||Details|
|XFO-5120||Notifications sent to members of expired or future coverages||Details|
|XFO-5144||Signing whole SAML response is not supported||Details|
|XFO-5150||Installer fails if the default language of SQL Server is set to UK English||Details|
|XFO-5152||All subscription web services should support device overrides at the device name level||Details|
|XFO-5239||GetOnCallMembers script method does not retrieve device recipients correctly||Details|
|XFO-5245||Notifications Report on a SQL Server system returns a LockAcquisitionException: could not execute query error||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 002. 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 DataSync installations, if applicable).
Installer files included with this release:
For use on:
Note that this installer file also requires a 32-bit JRE.
|xmatters-installer-x64-5.1.2||For use only on Microsoft Windows 2008 R2 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: Spring Configuration Changes
When applying an xMatters patch, any changes you have made to the parameters in spring configuration files may not be retained. The patch may overwrite modifications to some or all of the following files:
Warning: Database Changes
Be aware that this release also includes database changes that may impact your replication mechanism (consult with your database administrator for further details).
This patch includes 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 this 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.
For a full list of the database changes, see Appendix 4: DDL and DML Changes in This Release.
Before installing this patch:
- Shut down or stop all node processes.
- Shut down or stop all web server processes.
- Back up the xMatters Database.
- 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 ).
- On Linux, the default install directory is:
- On Windows, the default install directory is:
C:\Program Files (x86)\xMatters\
2. Save the
xmatters-installer-<version>-5.1.2.jar file to <xMHOME>/.
3. Open a command prompt and navigate to .
4. Do one of the following:
- To run the installer in GUI mode, run the following command (replace
x64, depending on your version of the installer):
java -jar xmatters-installer-<version>-5.1.2.jar
- To run the installer in console mode, run the following command:
java -jar xmatters-installer-<version>-5.1.2.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.)
After installing this patch:
- Start the Node processes.
- Start the web server processes.
- 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.
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 (4.1.x/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 (4.1.x/oracle/02.xml) . . . 2009-01-21 22:07:22,847 [AlarmPoint Node-main] WARN - - Package 8 of 8 (4.1.x/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.
Appendix 1: Details For Issues Fixed In This Release
Pressing Enter allows users to bypass validation errors when modifying an email device
When modifying the details for an email device, if users pressed the Enter key instead of clicking the Save button, the device details would be saved without checking for validation errors. This would allow users to create devices with invalid domain names or other errors that would prevent xMatters from being able to contact that device. This issue has been addressed.
SMPP device engine cannot automatically recover from provider problem
An issue was reported where failure to connect to an SMPP provider could result in the device engine being unable to recover the connection unless the device engine was restarted.This was traced to a problem with the way the device engine handled the heartbeat from the provider; this issue has been addressed.
Included voice recording is not a professionally recorded version
An issue was detected where the professionally recorded version of the resolved. vox voice recording was not included with the installation. This file has been updated and should now match the remainder of the included voice recordings.
Events Activity report returns a stack trace when selecting the Attachments tab
An issue was reported where selecting the Attachments tab on the Events report (if the event did not have attachments) would cause a stack trace. To address this issue, the attachments tab will now be displayed only when the event includes attachments.
Incorrect Moscow time zone displayed on Site details page
The Site details page in the web user interface was incorrectly displayed the time zone for Moscow as (UTC+0300). The page has been updated to display the correct time zone, (UTC+0400).
Add device filters to the sample custom subscription panel
The custom subscription panel did not include the device filter section, . The file has been updated to include this section.
isAnyRecipientNotifiable returns true for recipients that are not on duty
An issue was reported with the isAnyRecipientNotifiable method on the event script object where calling the method would return true even if no recipients were available. This was traced to an issue introduced in a previous change that inadvertently removed a check from the code. This issue has been addressed.
Find Scenarios page does not show search criteria
An issue was discovered with the Find Scenarios page where the search criteria were not displayed if there were fewer than two messaging domains. This issue was traced to a conditional clause that suppressed the criteria under certain conditions; this has been addressed.
Company Quotas screen allows a Max value lower than the In Use value
An issue was reported where a user could specify a lower Max value for a field on the Company Quotas screen than the number of components currently in use. Saving the quotas could then prevent further updates. This issue has been addressed.
xMatters server does not process responses initiated by the Interaction script
An issue was reported where the xMatters server would not process responses when initiated by the Interaction script. To address this issue, consumers were added to the SIP and Phone Engine inbound queues, and the transaction handling was updated.
FindWhoIsOnDuty returns a stack trace with StackOverflowError
An issue was discovered where two users replacing each other on the same day would cause the FindWhoIsOnDuty web service call to result in a stack trace. This issue has been addressed.
French translation required for short code compliance text
The French translation for the short code compliance text was missing; the necessary translation has been supplied.
Systems Notifications report could not execute query in SQL Server database
An issue was detected where attempting to access the System Notifications report would result in a blank page and a "Cannot read property 'q' of null" error. This was traced to a problem where attempts by the user interface to query the audit table while the node is creating audit events resulted in a deadlock in a high-volume system. This release includes fixes to help address this issue.
Notifications sent to members of expired or future coverages
In specific circumstances, members of 'inactive' coverages (i.e., coverages that had expired or that were not yet active) were sent notifications for events. The issue was traced to the way coverages handle resuming and suspending notifications for parent and child coverages. This handling has been adjusted, and notifications should no longer be created for team members of coverages that are not active.
Signing whole SAML response is not supported
The previous implementation of SAML authentication for version 5.x did not support whole response signing; only signing of the assertion portion was supported. This feature has been updated to support whole response signing.
Installer fails if the default language of SQL Server is set to UK English
An issue was reported with the xMatters installer failing if the language for the SQL Server system was set to use UK English. This was traced to the way the systems handles dates, specifically using a D-M-Y notation rather than the North American M-D-Y. This issue has been addressed.
All subscription web services should support device overrides at the device name level
The updateSubscription and createSubscription web services support setting device overrides at the device type level, rather than using device names (as supported by the querySubscription web service and the web user interface). The web services have been updated to support using device names rather than device types, providing more flexibility when setting overrides for subscriptions.
GetOnCallMembers script method does not retrieve device recipients correctly
An issue was reported with the GetOnCallMembers script method where the owner of a device recipient was returned, rather than the device itself. The method has been updated to return the target name of the device (e.g., bsmith|Work Email) instead of the person record. Note that if the device's owner has a temporary replacement, the replacement is returned instead of the device record.
Notifications Report on a SQL Server system returns a LockAcquisitionException: could not execute query error
An issue was reported with the Notifications Report on a SQL Server system throwing an error when a user repeatedly refreshed the report or clicked between different views. This was traced to a conflict in the database queries performed by the report; 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:
(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
This release includes the following DDL and DML changes:
- Drop Foreign Key constraint TIM_EV_EV_FK on the timing log
- Add NOTIFICATIONS_SUMMARY table, populate with data from the AUDIT_EVS_ALL and EVS tables
- Add trigger SYNC_NOTIFICATIONS_SUMMARY_TRG
JDN-4720 Originally created by Don Clark