These release notes are for the following xMatters patch release:
Patch version: PATCH-500-007
Release date: December 17, 201
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, click Receive email notifications on the Actions menu to the right of this document.
NOTE: This patch introduced an issue that prevents users from updating Coverage start dates. It is strongly recommended that you do not install or use this patch level. Use the next patch instead, which includes all of the features and bug fixes in this release, and also addresses the Coverage start date issue.
For information about the next 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 5.0.7 (5.0 Patch 7) New Feature Overview.
The data migration tool has been upgraded to support database links, and is now available from the download page. For updated instructions and more information about the new functionality, see the xMatters installation and administration guide.
This release upgrades the distributed JRE for the node and web server to Java 7.
Improvements to FindGroups web service
Based on customer feedback, the FindGroups web service now supports the optional use of wildcards, specifically percent (%) and underscores (_), to search for Group names. You can also now limit the returned Groups to only those that are currently active. For details, see the FindGroups.pdf file attached to these release notes, below.
Issues Fixed in This Patch Release
To see details about an issue, click the related link in the Details column:
|XFO-3330||Audit report is not translated properly in XLS file||Details|
|XFO-3334||IA is vulnerable to cross-site scripting attacks (XSS)||Details|
|XFO-3350||Licensing violation when creating Groups from the Scenario Report||Details|
|XFO-3364||Process expired data scheduled job fails with stack trace on SQL Server||Details|
|XFO-3447||Inconsistent foreign key constraint when patching from 5.0 patch 003 to patch 005||Details|
|XFO-3522||The izPack installer cannot create 32-bit registry entries on Windows if run with 64-bit JVM||Details|
|XFO-3530||Device not found: UNKNOWN_APPLICATION_ERROR when accessing Find Device web service||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
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 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 installation and administration guide.
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.
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
Audit report is not translated properly in XLS file
When an audit report, such as Event Activity, was exported to an Excel file, the generated spreadsheet did not contain properly translated content. This issue has been addressed.
IA is vulnerable to cross-site scripting attacks (XSS)
To help guard against cross-site scripting attacks, any scripting code that is reflected back to a user is encoded to prevent it from being executed. This will prevent any malicious code appended onto a URL targeting the integration agent from being executed in a user's environment.
Licensing violation when creating Groups from the Scenario Report
Previously, it was possible to create a Group from within the Scenario Report even if the system already contained the maximum number of Groups allowed by its licensing. This could result in other database and licensing problems.
Process expired data scheduled job fails with stack trace on SQL Server
On SQL Server environments, the "Process Expired Data" scheduled job was failing and resulting in a stack trace. This was determined to be caused by a faulty SQL Server trigger; this issue has been addressed.
Inconsistent foreign key constraint when patching from 5.0 patch 003 to patch 005
On some xMatters version 5.0 patch 003 systems, a foreign key constraint violation was preventing the system from starting after it had been patched to 5.0 patch 005. This issue has been addressed.
The izPack installer cannot create 32-bit registry entries on Windows if run with 64-bit JVM
Because Windows automatically redirects inquires from 64-bit and 32-bit applications, the installer cannot create the registry entries for a 32-bit applications installed from a 64-bit application. This resulted in the voice DLLs being unable to locate the registry keys for the voice registry entries. To resolve this issue, the voice-related registry keys are now created using an included 32-bit JVM, rather than the izPack installer.
Device not found: UNKNOWN_APPLICATION_ERROR when accessing Find Device web service
Some integrations were reporting an issue with synchronizations; this issue was due to a Find Device web service call that did not specify a Company. The internal web service helper has been updated to check the Company; the Find Device web service should now work as intended.
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
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)
xMatters version 4.0 patch 10 and version 4.1 patch 2 introduced an upgrade script that added Oracle function-based indices to improve performance. However, these indices will not become effective and used by the Oracle Cost Based Optimizer (CBO) until the statistics are gathered for the related tables and the indices themselves. For more information, see Why isn't Oracle using available indices?.
(xMatters Reference: PRE-68)
Even when the xMatters Integration Agent submits a message to a Company other than the Default Company, the Integration Agent log indicates that the message was submitted to the Default Company.
(xMatters Reference: APE-13596)
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 Changes in This Release
- Added a new table RESPONSE_CHOICES_TRANSL
- Added columns VOICE_PROMPT_LANGUAGE_CODE, TEXT_RESPONSE_LANGUAGE_CODE and DESCRIPTION_LANGUAGE_CODE to the RESPONSE_CHOICES table. Defaults to 'en'
- Added column REC_PHRASE to the RESPONSE_CHOICES table
- Dropped unused indexes on AUDIT_EVS_ALL and AUDIT_EVS_ALL_ARC
- Created new indexes on AUDIT_EVS_ALL and AUDIT_EVS_ALL_ARC for tracking reports
- Adjusted the precision of PARAM_1, PARAM_2 and PARAM3 in AUDIT_EVS_ALL and AUDIT_EVS_ALL_ARC to 100 bytes to accommodate updated messages
- Added column IS_SCENARIO_ADMIN to the FORMS_PERMS_REV table (and updated the FORM_PERMS_REV_TR to track the new column)
- Renamed SHARED_LIST_SEQ to SHARED_LISTS_SEQ to match the standard naming convention
- Modified the INSERT_ORDER column in AUDIT_EVS_ALL to NOT NULL
- Added table REB_SCENARIO_TRANSLTN
- Added column REC_PHRASE to table REB_SCENARIO_PROPERTY_VALUE
- Added an audit trigger to the REB_SCENARIO table
- Added tables REB_SCENARIO_OPTION_HANDLING, REB_SCENARIO_VOICEMAIL_OPTION and associated audit triggers
- Added tables MESSAGE_PANEL_DEVICE_FILTER and MESSAGE_PANEL_DEVICE
- Added indexes to previously unindexed foreign keys for REB related tables
- Added table REB_SCENARIO_PERMS
- Added column IS_SCENARIO_ADMIN to the FORM_PERMS table
- Added audit trigger and indexes to REB_SCENARIO_PERMS
- Added index on the PHRASE column in the VOICE_MSGS table
- Adjusted SQL Server column sizes for foreign key relationships (SQL Server requirement)
- Set VOICE_MSG_ID to NULL in EVS_ARC and remove VOICE_MSG_ID from the EVS_ARC_TR to stop it being populated
- Set the value of the new column REC_PHRASE to the value of the VOICE_PROMPT column in the RESPONSE_CHOICES table if REC_PHRASE is NULL and VOICE_PROMPT is not NULL
- Remove the tie in restriction on the Developer Menu permission
- Updated sequences in ORG_FUNC, ORG_FUNC_PERMS and ROLE_FUNC for the out of box data where default sequences have been used (to prevent primary key violations)
- Added new permission view.menuitem.TotalLiveNotificationReport to allow a User to see the Notifications menu item in System Reports
- Added new permission view.screen.TotalLiveNotificationReport to allow a User to see the System Notification Report screen
- Added XM_ALLOW_LEGACY_SCENARIOS company constant to orgs that have existing scenarios
JDN-3502 Originally created by Don Clark