These release notes are for the following xMatters patch release:
Patch version: PATCH-500-001
NOTE: This document is subject to change after the initial release of this patch.
This is a cumulative patch for version 5.0 features and issues, and 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. You do not need to install xMatters using the original 5.0 installer, and then apply this patch.
Support Policy Reminder
The xMatters Support Policy was updated in February 2009.
Features Added In This Patch Release
For more detail about the features below, see the xMatters 5.0 New Feature Overview.
xMatters 5.0 now supported on Windows 2008
xMatters version 5.0 patch 001 is now available for Windows 2008. Along with Java-based graphical and console installation options, this update includes support for SAPI, Dialogic cards, and MAPI. For more information, see the xMatters installation and administration guide.
Deleted User, Team, and Device data is purged relative to Process Expired Data settings
Whenever you delete data from xMatters, the database marks it as deleted, but continues to store the data until the system has removed all other data that may be related to it. To determine when it is safe to completely remove the data, xMatters uses the settings specified on the Schedule Job Details for Process Expired Data page in the web user interface. For more information, see the xMatters installation and administration guide.
Note that this change may result in expired data being deleted from your database once the patch is applied. You may want to review your data retention settings prior to applying this patch.
(xMatters Reference: XFO-1830, XFO-1953)
Removed historical data from Group Details
Previously, the web user interface did not store information for previous shifts, but instead displayed details for historical shifts (those that occured prior to the current date) based on the Group's and Coverage's current settings. This led to some confusion as the details for previous shifts were not accurate. To reduce any potential confusion or issues, all historical data for shifts has been removed from the web user interface, and days prior to the current date are left blank. This applies to both Weekly and Monthly views.
(xMatters Reference: XFO-1833, XFO-1970)
Time and date formatting consistent across all Reports
The date, time, and time zone information has been made consistent across all Reports in the web user interface. This includes identifying the name of the time zone on which the Report is based, instead of representing it as a number of hours plus or minus GMT. The time and date information included with the Who's on Duty Report has also been updated.
(xMatters Reference: XFO-1834, XFO-1976)
Increased duration for BlackBerry messages
The length of time that BlackBerry messages will remain available on a recipient's Device has been increased to 36 hours.
(xMatters Reference: XFO-1835)
Script updates now applied to Template Company scripts
As of this patch, any script updates, fixes, or changes included in a patch release are automatically applied to the Template scripts. This allows xMatters to propagate required script changes to existing deployments, and allows customers to receive script updates and fixes automatically. Note that if you have made modifications to your Template Company scripts, patching your deployment will overwrite those changes. For more information, see "Warning: Database changes", below.
(xMatters Reference: XFO-2476)
Issues Fixed in This Patch Release
To see details about an issue, See Appendix 1: Issues Fixed In This Release:
|xMatters Reference||Issue Fixed|
Installation not validated on CentOS
|XFO-1852||Who's on Duty Report inconsistent with Group Weekly View|
|XFO-1854||Who's on Duty Report showing incorrect One Time Coverage replacements|
|XFO-1856||Teams not being added correctly from the Team Details page|
|XFO-1864||Data Synchronization cannot update the Supervisor for a Group with two or more existing Supervisors|
|XFO-1994||Incorrect Event Summary status for messages left in recipient's voice mail|
|XFO-2012||Installer unable to accept license file with spaces in the file name|
|XFO-2020||MAPI Device Engine does not work with non-English characters|
|XFO-2028||Data synchronization unable to export Groups that have the same external keys|
|XFO-2045||Inaccurate description of Service Provider Access Role|
|XFO-2060||FindGroups web service treating underscore as wild card|
|XFO-2135||Incorrect escalation count calculated for Group Performance Report|
|XFO-2224||Sample Messaging Panels returning stack trace when displayed|
|XFO-2371||Deleting Subscription Domain predicates reassigns predicate rankings on the Event Domain|
|XFO-2455||Device validation messages on BlackBerry Devices not formatted correctly|
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: Database Changes
Note that this patch changes the way Template scripts are used by xMatters:
You should no longer make changes to the scripts in the Template Company. As of this patch, these scripts are now subject to automatic changes and updating. If you have already modified the Template scripts, export them (using the Developer IDE) from the Template Company and import them into the Default Company before installing this patch. Once the patch is applied, you can then change the associated Event Domains (in the web user interface) to use the Default Company scripts instead of the Template scripts.
Be aware that this patch also includes database changes that may impact your replication mechanism (consult with your database administrator for further details). 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
xMatters 5.0 installer not validated on CentOS
The original xMatters 5.0 installer was validated only on Red Hat Linux. The latest xMatters installer has been validated on CentOS 5.3.
(xMatters Reference: XFO-1814)
Who's on Duty Report inconsistent with Group Weekly View
The Who's On Duty Report, when displaying a weekly Group schedule, contained details that were inconsistent with the hover-over information displayed in the Weekly View on the Group Details page. This issue has been addressed.
(xMatters Reference: XFO-1852)
Who's on Duty Report showing incorrect One Time Coverage replacements
When adding a One Time Coverage to replace an existing shift, the Who's On Duty Report would often display both the replaced shift and the original shift, even though the original shift would never occur. The Report now shows only the replacement One Time Coverage.
(xMatters Reference: XFO-1854)
Teams not being added correctly from the Team Details page
When creating a nested Team (i.e., adding a Team to an existing Team using the Team Details page), xMatters would occasionally omit one of the added Teams. This was due to an issue in the way Teams were ordered, and has been addressed.
(xMatters Reference: XFO-1854)
Data Synchronization cannot update the Supervisor for a Group with two or more existing Supervisors
When attempting to add or update the Group Supervisor for a Group using the Data Synchronization feature, the update would not be correctly applied if the Group already had two or more Group Supervisors. This issue issue has been addressed; Data Sync should now update the Group Supervisors correctly.
(xMatters Reference: XFO-1864)
Incorrect Event Summary status for messages left in recipient's voice mail
When a notification is delivered to a User's voice mail, the Event Summary status would display as "Not yet notified" instead of "Delivered to Device". This has been addressed by bringing the handling of notifications delivered to voice mail more in line with the handling of other notifications, and displaying the status as delivered to a Device.
(xMatters Reference: XFO-1994)
Installer unable to accept license file with spaces in the file name
The initial release of the xMatters 5.0 installer would return an error message ("License Failure: unable to find license file") when attempting to upload a license file that contained spaces in the file name. This issue has been addressed by changing the way the installer handles the license file name.
(xMatters Reference: XFO-2012)
MAPI Device Engine does not work with non-English characters
In previous versions, the MAPI Device Engine could not properly process non-English characters, and would display incorrect characters. This was due to the way extended ASCII characters were escaped in the HTML. This has been addressed by pushing the data to the MAPI engine as explicitly Unicode.
(xMatters Reference: XFO-2020)
Data synchronization unable to export Groups that have the same external keys
The Data Synchronization tool was unable to export Groups that had the same external keys. This issue has been addressed by changing and simplifying the way external keys are generated during an export: all external keys generated and assigned during an export now use a universal unique identifier (UUID) rather than the method detailed in the documentation for previous versions.
(xMatters Reference: XFO-2028)
Inaccurate description of Service Provider Access Role
The Service Provider Access Role was inaccurately described in the Role Details page in the web user interface, and in the related topic in the online help. Both descriptions have been updated to better describe the Role and its intended purpose.
(xMatters Reference: XFO-2045)
FindGroups web service treating underscore as wild card
The FindGroups web service (and the Find Groups page in the web user interface) would treat an underscore entered in the Search field as a wild card. This led to unexpected results in the returned Groups; for example, some Groups that did not have underscores in their names would be included, and Groups that did have underscores would be excluded. This issue has been addressed by changing the way the web services and Group search queries handle underscores in Group names.
(xMatters Reference: XFO-2060)
Incorrect escalation count calculated for Group Performance Report
An issue was identified with the Group Performance Report where an escalation occurred, but the related event was completed before the escalated User accepted the notification. This resulted in the escalation being excluded incorrectly; this issue has been addressed.
(xMatters Reference: XFO-2135)
Sample Messaging Panels returning stack trace when displayed
Incomplete or outdated code in the Sample Message Panels (located in the jsp/messaging/samples folder) was resulting in a stack trace when attempting to use the panels in the web user interface. The sample panels have been updated and retested.
(xMatters Reference: XFO-2224)
Deleting Subscription Domain predicates reassigns predicate rankings on the Event Domain
When removing predicates from a Subscription Domain, the ranking of those predicates on the associated Event Domain could be incorrectly adjusted. The code related to predicate removal has been updated to no longer update predicate rankings on the Event Domain.
(xMatters Reference: XFO-2224)
Device validation messages on BlackBerry Devices not formatted correctly
Device validation notifications sent to BlackBerry Devices should be formatted in HTML to display properly in the Device's browser. The validation messages have been updated to display correctly.
(xMatters Reference: XFO-2455)
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.
For more information (including instructions on how to switch between the AlarmPoint and xMatters interfaces), see Common questions about rebranding from AlarmPoint to xMatters.
Appendix 3: Known Issues
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)
Appendix 4: Database Changes in This Release
The following changes have been made for this patch release:
- Adds column REPLY_TO to table PROT_SMPP_ROUTE_OV
- Adds table PROT_HTTPXMSMS_ROUTE_OV and associated trigger PROT_HTTPXMSMS_ROUTE_OV_IA_TR
- Adds column TOKEN_MSG to tables AUDIT_EVS_ALL and AUDIT_EVS_ALL_ARC, and updates the archival trigger TRIGGER AUDIT_EVS_ALL_ARC_TR
- Adds column SHORT_CODE_COMP to tables PROT_HTTPXMSMS and PROT_HTTPXMSMS_REV, and updates the revision trigger PROT_HTTPXMSMS_REV_TR and the ownership trigger PROT_HTTPXMSMS_REV_TR
- Adds table PERSON_PROFILE
- Adds table PERSON_PROFILE_SECTION
- Adds table PERSON_PROFILE_SEC_ITEM
- Adds column IS_JOIN_CONFERENCE to table RESPONSE_CHOICES
- Adds column MESSAGE_PANEL_ID to tables EVS and EVS_ARC
- Adds table PROPERTY_VALUE
- Adds table PERSON_PROPERTY_VALUE
- Adds table PROPERTY_LIST_VALUE
- Adds table PERSON_PROFILE
- Adds table FORM_PERMS, associated revision table FORM_PERMS_REV, ownership trigger FORM_PERMS_IA_TR, and revision trigger FORM_PERMS_REV_TR
- Adds indices IDX_AUDIT_EVS_ALL_ORGID and IDX_AUDIT_EVS_ALL_COMPANYNAME to table AUDIT_EVS_ALL
- Adds indices IDX_AUDIT_EVS_ALL_ARC_ORGID and IDX_AUDIT_EVS_ALL_ARC_COMPANY to table AUDIT_EVS_ALL_ARC
- Updates trigger TRIGGER AUDIT_EVS_ALL_ARC_TR
- Creates trigger EVS_ARC_TR
- Creates function SPLIT_CSV
- Creates function GET_NEXT_SIMP_RESP_CHOICE
- Creates procedure SIMP_SMS_RESP_QUERY
- Creates index IDX_EVS_MESSAGEPANELID on table EVS
- Creates object T_STRING_AGG and function STRING_AGG, to remove usages of the unsupported WM_CONCAT function
- Adds permissions 'view.menuitem.ProfileManager' and 'view.screen.ProfileManager' to access the My Person Profile page, granting it to SuperAdmin, CompanyAdmin, and Default roles
- Replaces the previous 'ability.act.LoginAsAgent' permission with a more appropriate one with the same name
- Removes invalid, default entries for Apple Push and Fax protocol provides from the APPLE_PUSH_DVC_DTL and FAX_DVC_DTL tables (unsupported in premises installations)
- Added missing entries in the META_ARC_TABLES
- Changed the script packages that are active by default from the ones in the Default Company to the ones in the Template Company
- Updated all default script packages in the Template company to improve the Blackberry/BES content
JDN-3110 Originally created by Don Clark