These release notes are for the following xMatters patch release:
Patch version: PATCH-500-005
Release date: October 18, 2012
NOTE: This document is subject to change after the initial release of this patch.
This patch has been replaced with xMatters 5.0 patch 006 .
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 004 Release Notes.
This patch introduces the first migration patch for xMatters 4.1 users to migrate to xMatters version 5.0. Complete instructions, details, and requirements are included in the latest edition of the xMatters installation and administration guide.
New and Improved Reports
This patch removes the Event Summary, Notification Summary, and Exhaustive Reports, and replaces them with the improved Event Log, Report Card, Tracking, and Notifications Reports.
Issues Fixed in This Patch Release
To see details about an issue, see Appendix 1: Details For Issues Fixed In This Release
|XFO-3162||Stack trace occurs when attempting to log in as a Tenant Company User without a password|
|XFO-3224||License updates do not overwrite temporary keys|
|XFO-3226||Stack trace when opening a Subscription panel popup window on WebSphere|
|XFO-3237||Error when adding Users to a Group with more than 1000 members|
|XFO-3314||Missing JavaDoc in the integration agent directory|
|XFO-3318||Group Monthly View does not display Temporary Replacements|
|XFO-3325||The integration agent release date and version number are not correct for Linux 64-bit version|
|XFO-3326||IIS redirector updated to include a new URL|
|XFO-3354||Developer Tab not displaying on 5.0 installation|
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
Stack trace occurs when attempting to log in as a Tenant Company User without a password
A stack trace may occur when attempting to log in as a mapped Tenant Company User if the User account does not have a password specified. To resolve this issue, the User Account Mapping feature will no longer display accounts that do not have complete web credentials.
License updates do not overwrite temporary keys
Applying a permanent license was incorrectly maintaining the original, temporary keys. If these temporary licenses were close to their expiry date, Users would see a reminder pop-up every time they logged in. This issue has been addressed, and applying a permanent license will now disable the temporary license keys.
Stack trace when opening a Subscription panel popup window on WebSphere
On WebSphere deployments, opening a pop-up window from a Subscription panel may cause a stack trace. This is due to an incorrect mapping in the web.xml file for WebSphere. This issue has been addressed.
Error when adding Users to a Group with more than 1000 members
Adding Users to a Group that already has more than 1000 members could result in an error, preventing Users from adding any more Group members. This issue has been addressed.
Missing JavaDoc in the integration agent directory
The xMatters integration agent guide mentions that the classes and methods comprising the Service API are described in a JavaDoc included in the integration agent installation folder, but this folder was not being created during the installation of the integration agent. The JavaDoc should now be installed properly.
Group Monthly View does not display Temporary Replacements
The Group Monthly View displays a pop-up window with Coverage information for each day of the month. This view was not including Temporary Replacement information; this issue has been addressed.
The integration agent release date and version number are not correct for Linux 64-bit version
The Linux 64-bit installation of the integration agent was displaying an incorrect release date and version number in response to the iadmin get-status command. This could result in a incorrect information being sent as part of a support ticket; this issue has been addressed.
IIS redirector updated to include a new URL
The properties file used by the IIS redirector to forward calls to xMatters has been updated to include the URL /rest/*. This change is required to handle the email domain whitelist functionality on the Email Device Details page added in 4.1 patch 014.
Developer Tab not displaying on 5.0 installation
On xMatters deployments without any active Voice Engines, the Developer tab was not displaying for any Users in the web user interface. This was due to an incorrect permission that tied the display of the Developer tab to the number of Voice Engines in the deployment. 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 http://blog.xmatters.com/2010/05/31/alarmpoint-is-now-xmatters-why-the-change/ .
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
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
- Add TERMINATION_DATE column to the EVS and EVS_ARC tables
- Remove old REB callback status quartz job
- Add SAML_ENABLED, IDP_ENTITY_ID, SP_ENTITY_ID, IDP_CERTIFICATE_LOCATION and IDP_SSO_URL to ORGS and ORGS_REV for SAML support
- Add INSERT_ORDER with auto-increment to AUDIT_EVS_ALL and AUDIT_EVS_ALL_ARC
- Add new table MESSAGE_PANEL_RECIPIENT
- Add NUM_RS_CALLBACK default throttle value (100) if it is currently null
- Update the ARC trigger to archive the INSERT_ORDER column
- Remove SCEN_OBSERVERS and SCEN_OBSERVERS_REV table, related sequence and references in other tables
- Add column ORG_ID to the VOICE_MSGS table
- Add the column IS_SYSTEM to PROPERTY table
- Add the following tables for REB scenario - REB_SCENARIO, REB_SCENARIO_PROPERTY_VALUE, REB_SCENARIO_VALUE_ITEM
- Add is_visible column to PROPERTY_LIST_POSSIBLE table
- Drop unused indexes in AUDIT_EVS_ALL and AUDIT_EVS_ALL_ARC tables
- Add COUNTRY_CODE, DIRECTION and DEVICE_NAME to the BILLING_NTFN table
- Add PREVENT_ARCHIVE column in AUDIT_EVS_ALL and update the archive trigger to include this column
- Update SIMP_SMS_RESPS_QUERY to remove temporary choices
- Update SDAG_ROLE_FK1 in SUBSCR_DMN_ROLES to cascade on delete
- Add DEVICE_NAME to the BILLING_VOICE table
- Add tables REB_SCENARIO_DEVICE_FILTER, REB_SCENARIO_DEVICE, REB_SCENARIO_RECIPIENT and REV_SCENARIO_DEVICE_GROUP and related triggers
- Adjust the precision on the FK field MESSAGE_PANEL_ID in ACTIVITY_UPDATES_REV
- Add unique key index to table BILLING_VOICE
- Add unique key index to table PROPERTY_LIST_POSSIBLE
- Rename sequence SHARED_LIST_SEQ to SHARED_LISTS_SEQ
- Update AUDIT_EVS_ALL_ARC_TR for SQL Server to populate INSERT_ORDER correctly
- Update INSERT_ORDER to column to not allow NULLS
- Add permission view.screen.profile.TemporaryReplacementList to hide temp replacements from profile page
- Add permission view.screen.profile.DeviceList to hide device lists from the profile page
- Set the INSERT_ORDER value on the AUDIT_EVS_ALL and AUDIT_EVS_ALL_ARC tables to the maximum AUDIT_EV_ID where the INSERT_ORDER value is NULL
- Fix legacy devices with mismatched target_name column values
- Update the response, choice, and notification messages for all SMTP device engines
- Update INIT_OR_CONCLUSION column on REB event creation data in EVS and EVS_ARC tables
- Add permission view.menuitem.NotificationReport to enable users to see the Notifications menu item
- Add permission ability.act.ViewRebScenarios to allow users to see the list of Relevance Engine Scenarios
- Add permission ability.act.EditRebScenarios to allow users to modify the Relevance Engine Scenarios
- Add permission ability.act.DeleteRebScenarios to allow users to remove Relevance Engine Scenarios
- Remove permission view.menuitem.CompanyDomainSummaryReport
- Modify SHORT_CODE_COMP default value to be 'N'
- Update SHORT_CODE_COMP values to 'Y' where the value is 'WELCOME', 'CUSTOM' or 'WELCOME_CUSTOM'
- Update SHORT_CODE_COMP values to 'N' where the value is 'NONE'
- Removed permission restriction from view.menu.Developer that ties the Developer tab to the number of Voice Engines in the deployment
- Update primary key values in ORG_FUNC (and related tables) into the reserved range to prevent clashes with customer data when migrating systems
JDN-3332 Originally created by Don Clark