These release notes are for the xMatters 5.1 release:
Release version: PATCH-510-001
Release date: March 6, 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.
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 001 (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 022 directly to xMatters version 5.1 patch 001 (for more information and complete migration tool instructions, refer to the xMatters 5.x Documentation ).
Features Added in this Release
This release adds full compliance with Avaya 6, and resolves all limitations previously identified in xMatters 5.0. For a complete list of supported and validated Avaya components, see the xMatters installation and administration guide.
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, refer to Appendix 1: Details For Issues Fixed In This Release:
|APO-7757||Commas allowed in phone numbers entered in the web user interface|
|APO-7770||Unable to import text phone devices via data sync when the system is in legacy mode|
|ARCH-1814||Scheduled Jobs getting stuck in the Acquired state|
|HOTH-2299||Error message window does not display the entire email domain white list|
|HOTH-2303||Web service user authentication failure|
|HOTH-2304||Cannot delete a user who is supervising a group|
|HOTH-2307||Quartz performing update check weekly and on startup|
|KAM-67||Developer IDE teminates when encountering a syntax error|
|SCO-4091||Auto-archive job does not check the status of notifications before delinking|
|XFO-4875||Errors not always reported for User Upload|
|XFO-4876||User Upload is case-insensitive when verifying, but case-sensitive when processing|
|XFO-4877||Users with 'Change Password' function cannot change web password|
|XFO-4878||Installer could install on two different databases|
|XFO-4879||FindWhoIsOnDuty web service call fails for old rotation teams|
|XFO-4880||Web user interface does not reflect recent international time zone changes|
|XFO-4930||Terminate Matching Event option disabled when switching between archive and runtime events|
|XFO-4946||Event log shows incorrect node name when a device engine is out of resources|
|XFO-4947||Cannot add Support User's device to a group|
|XFO-4949||Exporting group on Group Performance Report page returns no results|
|XFO-5013||Full access user is able to see groups in tenant company|
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 001. 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.1||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).
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).
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.1.jar file to .
3. Open a command prompt and navigate to <xMHOME>.
4. Do one of the following:
- To run the installer in GUI mode, run the following command (replace with i586 or x64, depending on your version of the installer):
java -jar xmatters-installer-<version>-5.1.1.jar
- To run the installer in console mode, run the following command:
java -jar xmatters-installer-<version>-5.1.1.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
Commas allowed in phone numbers entered in the web user interface
The validation process for voice device phone numbers in the web user interface was not recognizing commas as invalid characters, which could cause the user upload export/import process to fail. This issue has been addressed.
Unable to import text phone devices via data sync when the system is in legacy mode
An issue with the data synchronization feature was preventing text phone devices from being imported properly when the system was in legacy mode. This issue has been addressed.
Scheduled Jobs getting stuck in the Acquired state
Some customers reported an issue with the Scheduled Jobs feature where some jobs would not be processed after nodes were restarted. The jobs would become stuck in the "Acquired" state instead of running as scheduled. This issue has been addressed.
Error message window does not display the entire email domain white list
Some customers using Internet Explorer reported an issue with the error message window on the Email Device Details page where the email domain white list would not display the entire list of email domains. The pop-up dialog box has been adjusted to ensure that users can view the complete list of acceptable domains.
Web service user authentication failure
An issue was detected where deleting a web service user would not allow the creation of another web service user with the same name, but no error would occur until the user attempted to authenticate. This issue has been addressed.
Cannot delete a user who is supervising a group
An issue was identified where attempting to delete a user who was supervising a group would deny the deletion request. The system would wrongly identify the user as the last supervisor of a group, even if the group had other supervisors. This was traced to a minor error in the delete user request, and has been addressed.
Quartz performing update check weekly and on startup
A recent update to the scheduled jobs feature caused the underlying process to perform a check for updates at least once per week, and again after every node restart. The check has been disabled.
Developer IDE teminates when encountering a syntax error
An issue was identified with the Developer IDE where, upon encountering a specific type of syntax error, it would close, discarding all modifications. This issue was traced to the line continuation handling, and has been addressed.
Auto-archive job does not check the status of notifications before delinking
The auto-archive job did not check the status of notifications before issuing a DelinksNotificationsMessage command. This caused unnecessary duplication of commands and retrieval of notification objects from the database. This issue has been addressed.
Errors not always reported for User Upload
Under some conditions, the list of errors for a user upload job would not list all of the errors, even though the job was marked as processed. To resolve this issue, the logic for tracking the errors was improved and a new status, "processed with errors" was added.
User Upload is case-insensitive when verifying, but case-sensitive when processing
An issue was identified with the User Upload tool's validation feature. When validating the upload file, the tool would ignore case-sensitive errors, but then flag the errors when actually processing the upload job, causing a null pointer exception (but no stack trace. To address this issue, both the validation and the upload process are now case-insensitive.
Users with 'Change Password' function cannot change web password
To facilitate the creation of new roles and reduce the number of functions required to allow users to change their web passwords via the web user interface, the Change Password function has been updated to include all of the necessary permissions.
Installer could install on two different databases
In some cases, it was possible to accidentally install a single deployment on two different databases due to the way the installer stored its database creation settings for each installation. This issue has been addressed.
FindWhoIsOnDuty web service call fails for old rotation teams
An issue was identified where the FindWhoIsOnDuty web service call would fail when retrieving information for old rotation teams. This was traced to an issue with the way the database handled the rotation direction, and would not accept a null value. To address this issue, an null value for the rotation direction field will be set by default to SECOND_TO_FIRST.
Web user interface does not reflect recent international time zone changes
Some recent changes to the way several international time zones handle Daylight Savings Time were not being reflected in the web user interface. This issue has been addressed.
Terminate Matching Event option disabled when switching between archive and runtime events
An issue with the way user settings and preferences are retained in the web user interface led to the "Terminate Matching Event" option being disabled when it should have been available. This issue has been addressed.
Event log shows incorrect node name when a device engine is out of resources
An issue was noticed in the event logs where the incorrect node was identified when a device engine was out of resources. This issue was traced to the way the logs were identifing the node that created the error message instead of the one where the error actually occured, and has been addressed.
Cannot add Support User's device to a group
An issue was reported where a device belonging to the support user would not appear in the type-ahead field when attempting to add the device to a group (although the device could still be added via the Advanced Search page). This issue has been addressed.
Exporting group on Group Performance Report page returns no results
An issue was identified with the Group Performance Report page where exporting the results would not result in any exported data. This was due to missing decrypting instructions in the download handler, and has been addressed.
Full access user is able to see groups in tenant company
An issue was identified where a "Full Access User" could see groups in a tenant company. This was traced to an error with the checkObserverStatus method for groups, and 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:
- Add 'view.screen.WebLogin' permission to the 'Change Password' function if it does not already have it.
JDN-4613 Originally created by Don Clark