These release notes are for the following xMatters patch release:
Patch version: PATCH-500-009
Release date: May 17, 201
To download the patch, see the xMatters 5.x Product Suite page.
NOTE: This document is subject to change after the initial release of this patch. 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 patch should be applied to all xMatters Application Nodes, Notification Nodes and Web Servers (and to the DataSync Server, if applicable).
Note that this version of the xMatters installer is capable of installing a new xMatters deployment, including all of the updates released in this patch, or of patching an existing installation. (I.e., you do not need install xMatters using the original 5.0 installer and then apply this patch afterwards.)
It is strongly recommended that you review the Patch Release Notes for all patch levels between your current patch level and this latest release before applying the upgrade. Some patches may require specific configuration changes not included in these release notes.
Because this is a cumulative patch, you should install the patch with the highest version number. For an overview of features and fixes included in the previous patch release, see xMatters 5.0 patch 008 Release Notes.
Features Added in this Patch Release
For more information about the features added in this patch, see the 5.0.9 (5.0 Patch 9) New Feature Overview
Scroll-and-load pages added for Users and Groups
The new scroll-and-load technology first introduced for the Events Report has been added to the Users and Groups pages in the web user interface. The new pages also replace the Find Users and Find Groups pages and allow administrators and supervisors to quickly locate and manage Users or Groups in a single list, without the need for pagination. At the same time, the new Search bar allows you to create simple or complex searches or filters, and change them on the fly as the results list updates automatically.
(xMatters reference: XFO-3714, XFO-3956, XFO-3973, XFO-3982, XFO-4009, XFO-4061)
Export Users and Upload Users features updated
The new Users page now allows you to export a list of Users into a CSV file that is compatible with the Upload Users feature, which has also been updated to allow the assigning of Roles, Time Zones, and Languages. (For more information about these changes, and how to update your existing Upload Users template to the latest version, consult the xMatters Web Help.)
(xMatters reference: XFO-3724, XFO-4060)
Improved Events Report filtering and export
The filtering and search capabilities on the Events Report have been improved to include the ability to always display an event's timestamp (instead of the default relative time), and to allow administrators to search for specific property values. You can also now export the entire contents of your currently displayed Events Report to an external spreadsheet file.
(xMatters reference: COR-544, COR-504, COR-498)
Performance Reporting usability and annotation updates
Both the Group Performance Report and the User Performance Report have been updated to use the scroll-and-load functionality introduced for the Users and Groups pages. In addition, the performance reports are now able to handle integration responses that include annotations. If a contribution is defined for a given response, and the response string starts with a matching string followed by a space, the contribution will be correctly attributed.
(xMatters reference: XFO-4019, XFO-3991, XFO-4050)
Updated REST API to extract notification data
A new REST API operation (GET notifications) allows you to extract notification data from xMatters to a simple CSV file. This allows database administrators to import xMatters data into an external data warehouse.
(xMatters reference: COR-593)
Issues Fixed in This Patch Release
To see details about an issue, click the related link in the Details column:
|APO-6894||Name space for SOAP responses changed; integrations no longer working||Details|
|ARCH-1047||HELP / STOP SMS recognition is case-sensitive||Details|
|ARCH-1086||Stack trace when SMTP POP response is longer than 256 chars||Details|
|ARCH-1194||Node marked as "inactive" still processes events, and the user interface displays the wrong status||Details|
|ARCH-1195||Deleted Protocol Provider still included as an option for a User Service Provider.||Details|
|ARCH-1196||Incomplete permission set for Notification Report||Details|
|XFO-3528||Calling extension over ISDN results in unexpected exceptions||Details|
|XFO-3686||Web server fronting stops working after applying 5.0 patch 007||Details|
|XFO-3745||waitForSilence scripting method fails silently||Details|
|XFO-4029||Integration file import fails with no error message||Details|
|XFO-4032||Updating xMatters 5.0 (patch 6 or earlier) fails on SQL Server deployments||Details|
|XFO-4039||Library performing update checks on startup||Details|
|XFO-4040||Breadcrumbs not shown in correct sequence on User Details page||Details|
|XFO-4042||Coverage bar not displaying correct hover text for Users with special characters||Details|
|XFO-4044||Home Page/My Devices page displaying incorrect breadcrumbs||Details|
|XFO-4045||Installer silently skips files with newer timestamps||Details|
|XFO-4048||Installer cannot install stand-alone web server||Details|
|XFO-4049||Installer does not consistently identify Linux OS name||Details|
|XFO-4283||Unable to add customized Company logo to web user interface||Details|
Installing This Patch
Apply this patch to all xMatters Application Nodes, Notification Nodes and Web Servers (and any DataSync installations, if applicable).
Files Included With This Patch
- xmatters-installer-i586-5.0.9.jar: for use on 32-bit or 64-bit operating systems using a 32-bit JRE (required for PSTN/Dialogic support).
- xmatters-installer-x64-5.0.9.jar: for use on Microsoft Windows 2008 R2 only, using a 64-bit JRE.
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 patch 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.)
The following instructions describe how to use the installer to patch an existing xMatters 5.0 deployment. For information about installing a new xMatters deployment, see the xMatters 5.x Documentation.
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.0.9.jar file to <xMHOME>.
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.0.9.jar
- To run the installer in console mode, run the following command:
java -jar xmatters-installer-<version>-5.0.9.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
Name space for SOAP responses changed; integrations no longer working
A change to the xMatters WSDL could result in SOAP response name spaces changing, which caused existing integrations to stop functioning. This was due to the way a component generated the schema and automatically incremented the name space. The issue has been addressed.
HELP / STOP SMS recognition is case-sensitive
An issue was identified where xMatters was unable to properly resolve a HELP or STOP response to an SMS message unless the response was entirely upper-case. The logic has been changed to be case-insensitive.
Stack trace when SMTP POP response is longer than 256 chars
A stack trace could occur when attempting to process an invalid response (longer than 256 characters) through SMTP POP. This resulted in audit events not being properly persisted in the database, and was due to a missing validation process for event string fields. This issue has been addressed.
Node marked as "inactive" still processes events, and the user interface displays the wrong status
An issue was identified where a deactivated node could still process events, and was shown as "Active" in the web user interface. This was due to an error where the node would not correctly process its status when starting up. This issue has been addressed.
Deleted Protocol Provider still included as an option for a User Service Provider.
An issue was identified where it was possible to select a deleted Protocol Provider to use for a User Service Provider. This was due to an error that enabled administrators to remove Protocol Providers that were actively in use. This issue has been addressed.
Incomplete permission set for Notification Report
The addition of the new Notification Report also included a new permission that identified the Roles allowed to view it. This permission was incomplete and resulted in the ability to circumvent the permission system and view the report (and only the report) by pasting the URL into a new browser. This issue has been addressed by adding more permissions to account for the ability to act on the report.
Calling extension over ISDN results in unexpected exceptions
On some customer deployments, phone calls using the same trunk line would report the same call result for different numbers. Users reported hearing no answer, or silence followed by a hang up. This issue has been addressed.
Web server fronting stops working after applying 5.0 patch 007
An issue was identified where web server fronting would stop working after applying xMatters 5.0 patch 007 to an existing deployment. This was caused by logic in the patch installer that would incorrectly rename a required Jetty file.
waitForSilence scripting method fails silently
An issue was identified with the @phone::waitForSilence script method where an end user could be on the line for an extended period before being dropped. Afterward, the phone line would be left in an unstable state and then reset. After ten resets, the line would be removed from the pool of available lines. This was due to a conflict between CTADE and the Windows API function. This issue has been addressed.
Integration file import fails with no error message
On some deployments, integrations could not be imported into Event Domains due to a regex error in a related library file, and would fail without displaying an error message. This issue has been addressed.
Updating xMatters 5.0 (patch 6 or earlier) fails on SQL Server deployments
Some SQL Server deployments were unable to apply the latest xMatters patch due to a missing unique constraint in a database table. This issue has been addressed.
Library performing update checks on startup
An issue was identified where one of the included libraries was checking for updates during startup. This issue has been addressed.
Breadcrumbs not shown in correct sequence on User Details page
An issue was identified where the breadcrumbs displayed on a User's Details page were not in the correct sequence. This could cause errors for a User attempting to backtrack in the web user interface. This issue has been addressed.
Coverage bar not displaying correct hover text for Users with special characters
The hover-text displayed over the shift bars on the Group details page would not display correctly if the Users included in the Coverage had special characters in their names. This issue has been addressed.
Home Page/My Devices page displaying incorrect breadcrumbs
An issue was identified where the breadcrumbs on a User's home page and Devices page would not display correctly. This issue has been addressed.
Installer silently skips files with newer timestamps
Previous versions of the xMatters 5.0 installer would not overwrite some required files if the target file had a newer timestamp than the expected previous patch release date. This could result in the installation not functioning if new features or changes depended on an update to a configuration file, particularly in the JRE. To address this issue, the installer will now overwrite all necessary files, except for .properties configuration files and fronting configuration (jetty.xml).
Installer cannot install stand-alone web server
An issue was identified when attempting to install only the web server using the xMatters 5.0 installer. The problem was traced to a missing classpath in the licensing settings, and has been addressed.
Installer does not consistently identify Linux OS name
An issue was identified with the xMatters 5.0 installer where certain versions of Linux were being incorrectly flagged as not supported by the installer. This issue has been addressed.
Unable to add customized Company logo to web user interface
The ability to add customized Company logos to page headers in the web user interface was not working correctly on some deployments of xMatters 5.0 and xMatters On Demand. This issue has been addressed.
Appendix 2: Notice of Name Change
AlarmPoint Systems, Inc. is now xMatters, inc. This change extends to how we name our products: the AlarmPoint Integration Agent is now the xMatters integration agent; AlarmPoint Enterprise is now xMatters enterprise; and so on.
You can learn more about why we changed our name here
During the ongoing transition to the new naming conventions, legacy corporate and product names will still appear in some parts of our products, such as directory paths, logs, and messages. This document reflects the new names whenever possible, while respecting the need for clarity when referring to older products, legacy issues, existing knowledge base articles, etc.
Appendix 3: 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 with 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 4: DDL and DML Changes in This Release
- Add ROLE_SEQ sequence to ROLE_ID on ROLE table
- Add SAML_IDENTIFIER_TYPE, SAML_IDENTIFIER_LOCATION, SAML_ATTRIBUTE_NAME columns to ORGS and ORGS_REV tables
- Alter ORGS_IA_TR and ORGS_REV_TR to take the new SAML columns into account
- Create PROPERTY_VALUE_ITEM table
- Add missing t_string_agg function (needed for epic server data transformation)
- Drop the LABEL column from the PROPERTY table
- Alter the PHONE_NUMBER column of AUDIT_EVS_ALL and AUDIT_EVS_ALL_ARC from varchar(20) to varchar(30)
- Add the IS_LATEST column to the RECIP_RESP_STATS table
- Modify the IDX_RRS_RECIP_ID_DATE index to include the IS_LATEST column
- Drop the "phone" parameter from Voxeo Protocol Providers, and reset the order of the other two parameters
- Rename the view and menu item permissions for the Users page to match the page's new title
- Add permissions for viewing the notification report and system notification report
- (REB) Update presentation message contents with UUID
- (REB) Merge value from LABEL column to NAME column on PROPERTY table
- Ensure PERMS_SEQ next value is greater than the maximum PERM_ID from the PERMS table
- (REB) Add permissions to add scendarios and activity updates in the REB
- Delete permissions to view the Find Users page and menu item, since this page no longer exists
- (ARCH-1274) Add permission to view the Legacy Activity Reports menu item to all users with permission to view the Activity Reports menu item
- Rename permission to view B2C Notification Reports and and B2C System Notification Reports
- Delete permissions to view the Find Groups menu item and page as the page no longer exists
- Set value of new IS_LATEST column in RECIP_RESP_STATS table to 'N' for responses which have been superseded
JDN-4186 Originally created by Don Clark