These release notes are for the following xMatters patch release:
Patch version: PATCH-500-008
Release date: February 15, 2013
To download the patch, see the xMatters 5.0 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, clickFollowing in on the Actions menu to the right of this document, and then select the Inbox check box.
This is a MANDATORY cumulative patch for xMatters version 5.0. This patch addresses an issue introduced in 5.0 patch 007 that prevented users from updating the start date for Coverages.
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.
If you are installing on an xMatters deployment using a SQL Server database, please note the issue identified in this knowledge base article before you attempt to apply this patch.
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 007 Release Notes.
Features Added in this Patch Release
For more information about the features added in this patch, see the 5.0.8 (5.0 Patch 8) New Feature Overview
Simplified and improved Events Report
The Event Activity Report has been replaced with an updated and improved Events Report. The new report includes scroll-and-load viewing, type-ahead search capability, and other features not available under the previous version. For more information, see the xMatters installation and administration guide. (The old version of the Events Activity Report is still available; it will be removed in a future release.)
(xMatters reference: SCO-2883)
Installing xMatters without database administrator credentials
The xMatters installer has been updated to not require database credentials to install the database components. Instead, the xMatters installation and administration guide provides SQL scripts the database administrator can use to create the pre-requisites in advance. The installer can then connect to the database and install the required content using only the name and password of the xMatters database user.
(xMatters reference: XFO-3582)
Using Windows Authentication with xMatters
This release includes support for using Windows Authentication (as opposed to SQL Authentication) to connect to the xMatters database. Configuration steps are described in detail in the knowledge base article at Using Windows Authentication with xMatters and SQL Server.
(xMatters reference: XFO-3597)
Updated "Users I Supervise" and User search features
The Users I Supervise and Find Users page have been updated to use scroll-and-load and, in the case of the Find User page, type-ahead search capability. For more information, see the xMatters user guide.
(xMatters reference: HOTH-726)
New scripting methods to require validated Devices
Two new scripting methods have been added, @notification::setValidatedDeviceNames and @notification::setValidatedDeviceTypes, that allow developers to require that User's Devices have been validated before xMatters will send them notifications for a specific event. The combination of the two methods allow developers to specify certain Device Types, Device Names, or a combination of the two.
(xMatters reference: XFO-3642)
Added support for SUCP Phone Numbers
The SUCP Protocol Provider has been updated to include the option to prepend a plus symbol (+), similar to the GSM and SMPP Protocol Provider settings. This allows administrators to configure xMatters to notify text phone Devices using SUCP.
(xMatters reference: XFO-3637)
Rename "Remove Selected" button on Groups page
A small change to the web user interface for some customers that wanted a better indication that "removing" a Group would delete it from the system. The button is now called "Delete Selected Groups", and the confirmation prompt has been clarified.
(xMatters reference: XFO-3661)
Issues Fixed in This Patch Release
To see details about an issue, click the related link in the Details column:
|XFO-3673||Cannot update the start date for a Coverage||Details|
|APO-6388||[Health Monitor] User Service Provider Exhausted||Details|
|APO-6397||Node usage increasing despite lack of activity||Details|
|APO-6408||Node continuing to process after a "node.sh stop" command||Details|
|ARCH-901||IndexOutOfBoundsException when adding a new member to Rotation Team via the type-ahead feature||Details|
|ARCH-912||Exhaustive report shows incorrect Temporary Replacement||Details|
|XFO-3565||Simple SMS Responses no longer work if short code compliance is not enabled||Details|
|XFO-3607||Stack trace while adding Dynamic Team and Team Template to Group||Details|
|XFO-3608||The timezone field of the UpdateSubscription web service is case sensitive||Details|
|XFO-3630||Stack trace in Group Weekly View when viewing a future schedule||Details|
|XFO-3660||Dialogic not working on 5.0 patch 007||Details|
|XFO-3688||Web user interface version of integration agent states does not match the integration agent project||Details|
|XFO-3692||User cannot authenticate during PSTN call-in on a multi-node system||Details|
|XFO-3695||Country field appears on Text Phone Device Details page in legacy mode||Details|
|XFO-3696||Installer excluding database objects when installing on Oracle RAC||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.8.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.8.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.)
To install this patch:
1. Back up the xMatters installation directory (referred to as <xMHOME>).
- 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.3.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 <version> with i586 or x64, depending on your version of the installer):
java -jar xmatters-installer-<version>-5.1.3.jar
- To run the installer in console mode, run the following command:
java -jar xmatters-installer-<version>-5.1.3.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
Cannot update the start date for a Coverage
An issue was reported where a customer was unable to update the start date for a Coverage; instead of updating as expected, the Start Date field would be populated with the End Date. This was due to a change in the datetime pattern used in the Schedule view; this issue has been addressed.
[Health Monitor] User Service Provider Exhausted
In some cases, a combination of mis-configured Devices and a disconnection line or hang-up could cause a flood of alerts from the Health Monitor indicating an exhausted User Service Provider. To address this issue, xMatters will now automatically deduplicate "User Service Provider Exhausted" Health Monitor Alerts.
Node usage increasing despite lack of activity
An issue was identified internally where two voice Devices belonging to the same User could be targeted by a Quick Message using the "Notify Until Accepted" option. In some cases, this could result in a series of log messages and node issues due to live notifications remaining in the processing list despite being delinked. This issue has been addressed.
Node continuing to process after a "node.sh stop" command
On some Linux deployments, using the "node.sh stop" command would not properly stop the node process, forcing the adminstrator to issue a "kill -9" command to stop the process manually. This was due to a misconfiguration in the method used to stop the node process; this issue has been addressed.
IndexOutOfBoundsException when adding a new member to Rotation Team via the type-ahead feature
The type-ahead function in the web user interface could generate an "IndexOutOfBoundsException" stack trace when attempting to add a new member to a Rotation Team. This issue has been addressed.
Exhaustive report shows incorrect Temporary Replacement
The Exhaustive Report was incorrectly displayed Temporary Replacements; this issue has been addressed.
Simple SMS Responses no longer work if short code compliance is not enabled
If the short code compliance feature was not enabled, service providers that do not support short code compliance would discard simple SMS responses. This was due to the logic contained within a method used for notification response processing; the logic has been updated to address this issue.
Stack trace while adding Dynamic Team and Team Template to Group
Some Users were reporting a stack trace error when attempting to add Dynamic Teams or Team Templates to Groups, or when adding a User to a Rotation Team. This was due to a minor issue in the underlying code; this issue has been addressed.
The timezone field of the UpdateSubscription web service is case sensitive
The UpdateSubscription and AddSubscription web services would return an error if the time zone was not specified in upper-case characters. Both web services have been updated to automatically format the timezone field contents to upper-case, and compare them against a similarly formatted list of time zones.
Stack trace in Group Weekly View when viewing a future schedule
A stack trace could occur when creating a Group with a Schedule starting later than the current date, and then attempting to view the start of the Schedule. This was due to an errant request for Temporary Replacement information from an invalid session; this issue has been addressed.
Dialogic not working on 5.0 patch 007
The 5.0 patch 007 installer updated the mechanism used to populate the registry with data required by the Phone Engine to initialize. This was to allow the installer to use a 64-bit JRE to install the product. Although the information was installed to the correct area in the registry, the Phone Engine was not able to read the configuration information. The change to the installer has been reverted, and the installer updated to not allow installation of the 32-bit version with a 64-bit JRE. For information on how to fix a 5.0 patch 007 deployment, see the knowledge base article here.
Web user interface version of integration agent states does not match the integration agent project
An error was recorded in the node logs when attempting to report that an integration service was in an error state. This was due to the web user interface having a different version of the possible integration agent states when compared to the states stored in the integration agent itself. This issue has been addressed.
User cannot authenticate during PSTN call-in on a multi-node system
An update to the interaction script object added caller information to the audit event report. This caused an issue with PSTN, which does not support providing caller ID. The interaction script object has been updated to determine whether caller ID is available; if it isn't, the caller information is not added to the audit event, which prevents a NullPointerException. (Note that for callin scripts to work with PSTN, the Template Company callin script must be copied into the Company associated with the call-in line. For more information, see here.)
Country field appears on Text Phone Device Details page in legacy mode
As of 4.1 patch 006, the new Text Phone Device Details page requires the country code for each Device to be specified separately from the phone number. Some systems are enabled to run in "legacy" mode, where the phone number and country code are contained in the same field, but were reporting that the Country field was still being displayed on the details page. This issue has been addressed.
Installer excluding database objects when installing on Oracle RAC
Some customers reported an issue when attempting to install xMatters 5.0 on Oracle RAC deployments where the database seed was excluding a required trigger. 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.
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
If you are currently fronting your xMatters 5.0 with IIS, upgrading to 5.0 patch 008 will disable your IIS fronting configuration. This is caused by a change to the default product to disable IIS fronting in Jetty by default. The patching process does not currently support the filtering of jetty files during cleanup, and will rename thejetty-ajp.xml file to jetty-ajp.xml.tmpl. If you are currently fronting your xMatters 5.0 application, backup the \webserver\etc\jetty-ajp.xml file to a location outside of the directory tree before applying the patch. Once the patching process is complete, restore the XML file to its original location.
(xMatters reference: XFO-3686, DTN-3204)
xMatters 5.0 patch 007 includes 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
- Remove trigger AUDIT_EVS_ALL_DATA_TR and AUDIT_EVS_FILL_IDS_TR
- Add LATITUDE and LONGITUDE columns to SITES and SITES_REV table
- Add CALLER_ID column to ORGS table
- Add IS_SEND_REST column to MESSAGE_PANEL
- Alter FORM_PERMS_REV table adding column IS_SCENARIO_ADMIN
- Add table PROT_VOXEO for the new VOXEO Protocol Provider
- Add new columns MESSAGE_PANEL_NAME and APPLICATION_NAME to the EVS and EVS_ARC tables and update the EVS_ARC_TR to archive the new columns
- Add new column DEST_PREPEND_PLUS to the PROT_SUCPS table for the SUCP Prepend + feature and update the triggers to include the new column
- Added new tables SNS_TESTED_DVC_FLTR and SNS_TESTED_DVC_FLTR_ARC to hold device names that must be validated in order to receive a notification for the current source notification.
- Enable by default the new Show Find Users and Show Supervised Users page and Site Location Enabled (these were previously controlled by company constants).
JDN-3828 Originally created by Don Clark