These release notes are for the xMatters 5.1 release:
Release version: xMatters 5.1
Release date: December 5, 2013
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 in on the Actions menu to the right of this document, and then select the Inbox 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.0 patch 010 deployment up to xMatters version 5.1 (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 021 directly to xMatters version 5.1 (for more information and complete migration tool instructions, refer to the xMatters installation and administration guide.
Features Added in this Release
The following features were introduced in this release; note that xMatters version 5.1 also includes all of the features and fixes introduced in xMatters 5.0 patches 001 through 010.
Improved Platform Support
The main feature set introduced for the xMatters 5.1 release is the following additional platform support, not available in version 5.0:
- SQL Server 2012
- Linux Red Hat 6
- Cisco Universal Communications Manager (formerly CallManager) 9
Improved User Search Filters
What was previously known as the "Health Check" section on supervisors' and administrators' home pages has been moved, and incorporated with the Users page. You can now use the Filters drop-down list to quickly locate Users with inactive, untested, or missing Devices, along with the rest of the powerful search tools available on the Users page.
Ignore Email Subjects When Processing Responses
You can now use the Ignore Subjects on Responses check box on the Email Device Engines details pages (SMTP, MAPI, and Notes) to exclude the content of the Subject field on email responses. This will help Users respond more quickly when using online email providers that often conceal or lock the subject line when replying to a message.
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:
|APO-7450||Event is terminated when source notification is published and all recipients are inactive||Details|
|APO-7653||HTTPClient Device Engine forwards response using the HTTP Proxy if one is defined||Details|
|ARCH-1664||Stack trace occurs when adding a Team on the Schedule Details page||Details|
|ARCH-1665||Health Monitor sends alerts for blocked/unblocked audit events||Details|
|ARCH-1720||Event Throttling setting throttles events and messages||Details|
|ARCH-1799||Node unable to establish bidirectional communication||Details|
|ARCH-1801||Stack trace when adding a Group as a Team member||Details|
|ARCH-1857||Database patching requires a dedicated database connection||Details|
|ARCH-1860||When creating a Team, a non-visible field causes validation to fail||Details|
|HOTH-1866||Database connection leak when checking supported DBMS||Details|
|HOTH-1878||Registration expiration value using wrong parameters in web user interface||Details|
|HOTH-1880||Voice Device validation marks notifications targeted for other Devices as delivered||Details|
|HOTH-1881||Unable to delete custom Roles||Details|
|HOTH-2114||Response options not available in subscription notifications for Advanced Messaging||Details|
|HOTH-2217||Stacktrace while filtering report data through "UserID" in Security Audit Report.||Details|
|SCO-3859||Invalid terms shown in property search result when property name contains special characters||Details|
|SCO-4004||Search results are multiplied when navigating in Reports||Details|
|XFO-4438||Add New Group not available due to changes to Permissions||Details|
|XFO-4440||Some settings appear to be discarded when saving a Scheduled Job||Details|
|XFO-4442||SMPP Providers should disable split message configuration fields when using Message Payload||Details|
|XFO-4524||Email Device name cannot be locked for externally-owned Device||Details|
|XFO-4564||Large User Upload job stuck in validating state||Details|
|XFO-4595||Installer fails if the database user password contains special characters||Details|
|XFO-4603||Updating a User Device via SOAP API does not reset the Device validation state||Details|
|XFO-4604||Unable to delete failed User Upload jobs||Details|
|XFO-4616||Password field on the xMatters Login page is too short||Details|
|XFO-4687||Upgrading to 5.0 from a 4.1 system in legacy mode causes invalid text phone Devices||Details|
|XFO-4694||Incorrect recipient notified when rotation Coverage starts||Details|
Installing This Release as a Patch
The following instructions describe how to use the installer to patch an existing xMatters 5.0 deployment and upgrade it to version 5.1. For information about installing a new xMatters 5.1 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.0||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).
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.0.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.0.jar
- To run the installer in console mode, run the following command:
java -jar xmatters-installer-<version>-5.1.0.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 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
Event is terminated when source notification is published and all recipients are inactive
An error was detected where a subscription recipient was not notified because another subscription related to the same event did not have any active recipients. This was due to the originating event being terminated before the active recipient was identified; this issue has been addressed.
HTTPClient Device Engine forwards response using the HTTP Proxy if one is defined
When forwarding requests to the web server using the "Response URL" defined for the HTTPClient Device Engine, xMatters would use the HTTP Proxy if one was defined. This issue has been addressed.
Stack trace occurs when adding a Team on the Schedule Details page
When creating a new Team using the Schedule Details page, the system would return a stack trace instead of adding the new Team. This was due to the system retaining the incorrect session version for the default Coverage; this issue has been addressed.
Health Monitor sends alerts for blocked/unblocked audit events
Some customers reported that they would occasionally receive a burst of alerts from the Health Monitor regarding blocked and unblocked audit events. This was due to way the server would process audit events for unconsumed messages on the bus. The settings for this feature have been updated, and while alerts for blocked/unblocked audit events will still be sent, duplicate messages will be filtered out.
Event Throttling setting throttles events and messages
The NUMBER_OF_SECONDS_PER_EVENT setting for the Event Throttling feature was being mistakenly applied to all messages being posted via the web server; this resulted in delivery delays when notifying large groups of Devices over HTTP. This issue has been addressed.
Node unable to establish bidirectional communication
A rare error was identifed where two previously-stable nodes were unable to establish bidirectional communication. This was traced to an issue with the timing used to reestablish connections after a node disconnected, and has been addressed.
Stack trace when adding a Group as a Team member
When adding a Group to a Team, the system would return a stack trace instead of adding the Group. This was due to the system retaining the incorrect session version for the default Coverage; this issue has been addressed.
Database patching requires a dedicated database connection
Some customers reported that the database patching process would time-out during the patch. This was due to the patching process using the node or web server's existing connection properties; the database patching process will now use a dedicated database connection.
When creating a Team, a non-visible field causes validation to fail
When adding a Team, it was possible to inadvertently create a Basic Team that required the Start Date parameter to be set as though for a Rotation Coverage Team, even though the Start Date field is not visible when creating a Basic Team. This would cause the validation process to fail (if the Start Date was not set to a date in the future), resulting in the Team not being added, although no error appeared in the web user interface. To address this issue, the validation has been updated.
Database connection leak when checking supported DBMS
An error was identified in the getCurrentDBMS method that could cause a stack trace to appear in the web server log, indicating that a checked-out resource was overdue and would be destroyed. This issue has been addressed.
Registration expiration value using wrong parameters in web user interface
Two calls within the SIP handling components of the web user interface were incorrectly retrieving the registration timeout value instead of the session timeout value. This issue has been addressed.
Voice Device validation marks notifications targeted for other Devices as delivered
An error in the voice interaction scripts was incorrectly marking validation notifications for other Devices as "delivered" when Users validated their voice Devices. The scripts have been updated to compare the notifications with the voice Device, and to not modify them or count them as delivered unless they match the Device in use.
Unable to delete custom Roles
A number of issues with the way custom Roles were stored in the database and imported via the Upload Users job resulted in it being difficult to delete the Roles once they were no longer in use. These issues have been addressed.
Response options not available in subscription notifications for Advanced Messaging
An issue was identified where subscriptions based on Advanced Messaging Scenarios would not include response options, even when the responses were configured correctly in the web user interface. This was traced to an issue in the presentation scripts, which have been updated.
Stacktrace while filtering report data through "UserID" in Security Audit Report.
A stack trace was reported when attempting to filter report data using User IDs. This was due to the report using an incorrect comparison method; this issue has been addressed.
Invalid terms shown in property search result when property name contains special characters
An issue was reported with searching for Group and Person Properties when the name of the property contained special characters, such as <, >, &, or ". The search result would attempt to treat the characters as operators, and introduce additional search terms; this issue has been addressed.
Search results are multiplied when navigating in Reports
An issue with the "sticky settings" feature resulted in some search results being multiplied when navigating between the various Reports. This issue has been addressed.
Add New Group not available due to changes to Permissions
Recent upgrades to the Groups page inadvertently changed the Permission used to control whether the logged-in User could access the Add New Group feature. This meant that Users that were previously able to add Groups could not use the feature; the original permission used to control access has been restored.
Some settings appear to be discarded when saving a Scheduled Job
Some customers reported experiencing some confusion with the schedule and occurrence settings for Scheduled Jobs, specifically when selecting which days of the week the job should run after selecting the "Every Day" option. Saving the job appears to discard the selected days, when in effect the settings were irrelevant. To reduce confusion, the logic on the page has been improved to reduce the ability to make irrelevant selections; for example, days of the week check boxes are now not available when the "Every Day" option is selected.
SMPP Providers should disable split message configuration fields when using Message Payload
For the SMPP Protocol Provider configuration settings, the "Split Long Message" and "Split Size" fields do not apply when the "Split Method" is set to "Message Payload". These fields should now be disabled unless they actually affect notifications sent to the provider. Note that the "Maximum Message Length" setting will still apply, and truncate any messages that exceed the specified value.
Email Device name cannot be locked for externally-owned Device
An issue was identified where it was possible to edit the name of an externally-owned email Device using the web user interface. This issue has been resolved.
Large User Upload job stuck in validating state
Changes to the User Upload feature (introduced to support the 1.2 version format) resulted in some unexpected performance degredation, and some larger files became stuck in validation, and could not be uploaded. This was due to the session size increasing and not being cleared before the job could complete; this issue has been addressed.
Installer fails if the database user password contains special characters
An issue was reported where the installer would fail if the database user's password contained a special character; this issue has been addressed.
Updating a User Device via SOAP API does not reset the Device validation state
An issue was detected with the web services where updating a Device via the SOAP API would not reset the Device's validation status to "Untested", as a similar change would if performed using the web user interface. Changes to a Device's area code, phone number, or other property via web services should now reset the validation state of the Device.
Unable to delete failed User Upload jobs
An issue was detected where, if a User Upload job failed due to an exception, the job would become stuck in the "Validating" state and not complete. The job could then not be removed, stopped, or deleted; this issue has been addressed.
Password field on the xMatters Login page is too short
By default, the Password field on the xMatters Login page could accept passwords up to 30 characters long. While this limit would not affect Users with "Native" login passwords, which are limited to a maximum of 30 characters, some LDAP systems allow or require much longer passwords. The 30-character limit has been removed.
Upgrading to 5.0 from a 4.1 system in legacy mode causes invalid text phone Devices
An issue was detected with the 4.1 to 5.0 upgrade process where 4.1 systems running in legacy mode would create invalid text phone Devices in 5.0 once the upgrade was complete. This would result in an error on a User's home page indicating an Unknown Server Error; the upgrade process will now skip phone number verification if it detects the legacy mode on an upgraded system.
Incorrect recipient notified when rotation Coverage starts
When a live notification was escalated to another Coverage where the rotation start time had not yet occurred, the system would notify the recipient that was on call in the previous schedule. The system has been updated to check whether the Team needs to be rotated, and rotate it if required, before sending the notification.
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 since xMatters 5.0 patch 010:
- Updated delete option from NO ACTION to DELETE CASCADE on FK_NEW_USER_ROLES_ROLE constraint on the IMPORT_JOB_NEW_USER_ROLES table
- Renamed the IDX_RECIPIENTS_DEL_ID_ORG_ID index to idx_recips_deleted_id_org_id from the RECIPIENTS table
- Added new IDX_RECIPS_DELETED_ID_ORG_ID index on (deleted_id, norg_id) to the RECIPIENTS table
- Added new IDX_GENERATOR_ROLE index on (role_id) to the ALERT_GENERATOR table
- Removed the ‘view.screen.UserHealthCheck’ permission as this is no longer used by the new User Health Check screen
JDN-4387 Originally created by Don Clark