These release notes are for the following xMatters patch release:
Patch version: PATCH-500-010
Release date: August 31, 2013
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.
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 009 Release Notes.
Features Added in this Patch Release
For more information about the features added in this patch, see the (5.0 Patch 10) New Feature Overview.
Move the Users I Supervise and Groups I Supervise settings
The scroll-and-load technology introduced in 5.0 patch 009 moved the Users I Supervise and Groups I Supervise toggles to inside the Filters drop-down menu. This proved to be an unpopular decision as customers found modifying the setting unwieldy, and difficult to tell whether they were viewing the correct list of Users or Groups. The option has been moved to within the title bar of the scroll-and-load list, and changed into a pair of buttons to make it more obvious which of the filters is being applied.
(xMatters reference: XFO-4418, COR-859)
Retaining search settings for scroll-and-load pages
This patch introduces a system of remembering the search settings you had applied to the Events Report, Performance Reports, and Users and Groups pages. Previously, the system would automatically refresh the pages each time you loaded them, meaning that you would have to reapply your search criteria each time. Now, when you navigate away from one of the above pages, and then return to it, the system will load the page with your previous search criteria automatically applied.
(xMatters reference: XFO-4410, COR-858)
Revised time ranges for Performance Reports
Previously, the list of options for date ranges on the Performance Reports were the same as those available on the Events Reports: 15 minutes (the default), 1 hour, 6 hours, and 12 hours. While these ranges made sense for administrators viewing trends and information about recent events, it was determined that most supervisors tended to need longer time frames to see trends in User and Group responsiveness. The quick pick options for the Performance Reports data range drop-down have been updated to Past 24 Hours, Past Week, Past 4 Weeks, and Past Year.
(xMatters reference: XFO-4403, COR-842)
User Upload Report updates
The Upload Jobs page has been refined and updated. Among other improvements, the page now displays the name of the User who initiated the job, and will also display all upload jobs within the Company.
(xMatters reference: XFO-4396, COR-825)
Updated SUCP Protocol Provider settings
The SUCP Protocol Provider Details page has been updated to fulfill customer requests for the ability to define country exit codes, also known as international access codes, or International Direct Dialing codes. This uses similar functionality to that already present on SMPP providers, and allows administrators to specify whether to prepend phone numbers with a plus symbol ( + ), or with specific digits (the required country exit code).
(xMatters reference: XFO-4340, COR-733)
Adding Team Escalation Type to web services
The xMatters web services have been updated to allow web service users to specify the Escalation Type for members within a Team. The affected web services are AddTeam, QueryGroup, and FindWhoIsOnDuty. (Note that the updated methods are available via the xmatters-5.0.10 endpoint.)
(xMatters reference: XFO-4341, COR-712)
Accessing attachments from Reports
You can now access any attachments associated with an active event from within the event's Reports. A new "Attachments" tab has been added for any event with a related attachments that allows you to download or view the attachments for an active event from within the xMatters web user interface. For archived events, the download links are disabled, but you can still view a list of the attachments that were included with the event.
(xMatters reference: XFO-4338, COR-178)
Removing plain text passwords from logs and scripts
Within some configurations and for select use cases, some integration log files could include the log in credentials of the responder to a notification, displayed in plain text. The xMatters scripting engine, integration agent, and mobile access component have all been updated to include encryption logic to avoid displaying plain text passwords within log files.
(xMatters reference: COR-511, COR-443, COR-577)
Issues Fixed in This Patch Release
To see details about an issue, click the related link in the Details column:
|APO-7281||Data synchronization stack trace should show up in DEBUG logs only||Details|
|ARCH-1580||Simple SMS responses not working properly in legacy mode||Details|
|ARCH-1581||SMTP Invalid Recipient Delivery Errors should not result in retries||Details|
|ARCH-1582||Subscription predicate values do not ignore leading or trailing whitespace when matching||Details|
|ARCH-1656||HTTP Client Device Engine and SMS logging issues||Details|
|ARCH-1664||Stack trace occurs when adding a Team on the Schedule Details page||Details|
|ARCH-1666||Override LocaleAction to validate Accept-Language||Details|
|XFO-4275||Unconsumed messages on the message bus||Details|
|XFO-4367||Duplicate definition in web services endpoint||Details|
|XFO-4373||Recordings: Resource items not associated with correct resource item detail||Details|
|XFO-4376||Recordings: resource broker does not scan the English (UK) directory||Details|
|XFO-4378||Recordings: resource broker creates a duplicate file for a recording while it is being created||Details|
|XFO-4380||Recordings: domain-specific recordings are not associated with the correct resource item detail||Details|
|XFO-4381||Database returns duplicate User ID, preventing User from logging in||Details|
|XFO-4382||Fronting errors with Apache reverse proxy configuration||Details|
|XFO-4385||Installer ignores the Database Name when installing on a SQL Server environment||Details|
|XFO-4438||Add New Group not available due to changes to Permissions||Details|
|XFO-4440||Some settings appear to be discarded when saving a Scheduled Job||Details|
|XFO-4442||SMPP Providers should disable split message configuration fields when using Message Payload||Details|
|XFO-4447||FindWhoIsOnDuty web service operation needs error handling for a Coverage with no associated Team||Details|
|XFO-4523||Unknown Application Error when using a pipe character in the name of a Dynamic Team||Details|
|XFO-4524||Email Device name cannot be locked for externally-owned Device||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:
For use on:
Note that this installer file also requires a 32-bit JRE.
|xmatters-installer-x64-5.0.10||For use only on Microsoft Windows 2008 R2 systems that are using a 64-bit JRE, and which will not require PSTN/Dialog support.|
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.10.jar file to .
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.10.jar
- To run the installer in console mode, run the following command:
java -jar xmatters-installer-<version>-5.0.10.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
A verbose stack trace error related to data synchronization was being included in the main logs. While the error itself was a legitimate issue related to the attempt to process a deleted Group, the placement and length of the stack trace was making the logs unwieldy and confusing. The error message was reduced to a single message, and the stack trace will now be included only when the logging level is set to DEBUG.
When using SMS simple responses in "legacy mode", the responses were not matching properly with the Devices configured in xMatters. This was due to the system automatically appending the Device's country code, when legacy mode text phones include the country code in the Device's PIN. The handling mechanism for SMS simple responses has been updated to determine whether the system is in legacy mode before appending the country code.
When attempting to deliver an SMTP notification to an invalid email address, and despite receiving a 503 error code, the system would reattempt the delivery according to the retry configuration. This behavior has been changed, and the system will no longer retry delivery of an SMTP notification to an invalid email address.
Some Subscriptions were not matching against predicates that had leading or trailing whitespace (extra spaces) in the definitions supplied on the Event Domain. The page has been updated to remove any extra whitespace when saving Event Domain predicates. Note that this will not affect existing Event Domains or Subscriptions.
A number of minor logging issues were identified with the HTTP Client Device Engine; these issues were addressed.
When creating a new Team using the Schedule Details page, the system would return a stack trace instead of adding the new Team. This was due to the system retaining the incorrect session version for the default Coverage; this issue has been addressed.
A potential HTML Tag injection vulnerability was identified in the Accept-Language parameter of LocaleAction. To address this issue, validation was added to the LocaleAction component.
An issue was identified with the external service requests where unconsumed messages would stay in the message bus table because no consumer existed that was capable of removing them. These messages were created by responses generated by the external service message when no response was expected. The behavior of the external service message has been modified to no longer send Request ID tokens within its messages.
The existing web services endpoint contained a duplicate definition for DeviceParameters, which could potentially cause problems when adding a new web service method. This issue has been addressed by removing the extraneous definition, and taking steps to ensure that existing implementations would not be affected by the change.
An issue was identified with the recording-creation process for single-Company deployments where resource items were not being associated with the correct resource item detail. This issue has been addressed.
An issue was identified with the resource broker for recordings on single-Company deployments where new recordings (.vox files) placed in the recordings\english uk folder were not being properly added to the resource list. This issue has been addressed.
An issue was identified on some single-Company deployments where the resource broker would register a new recording file while the recording was being created. This would result in a duplicate .vox file. This issue has been addressed.
When making a new recording, the resource items were not being associated with the correct resource item detail. This could result in a new recording being assigned a new resource item detail, rather than the one intended; this issue has been addressed.
An issue was identified with User web login IDs and target names where certain processes (such as User Upload or Data Synchronization) could inadvertently create duplicate User IDs in the database. As a result, the User would be unable to log into the web user interface even when supplying the correct password. This issue has been addressed.
Some customers fronting their web server with Apache in reverse proxy configuration reported being unable to access some of the pages in the web user interface, specifically those pages built using Google Web Tools (GWT). The issue was traced to a problem with the URL used in the environment to point to the GWT directory; this issue has been addressed.
The installer for xMatters 5.0 prompts the user to enter a name for the database, but by default the installation uses the database associated with the SQL Server Login. To resolve this issue, the Database Name field has been removed from the installer.
Recent upgrades to the Groups page inadvertently changed the Permission used to control whether the logged-in User could access the Add New Group feature. This meant that Users that were previously able to add Groups could not use the feature; the original permission used to control access has been restored.
Some customers reported experiencing some confusion with the schedule and occurrence settings for Scheduled Jobs, specifically when selecting which days of the week the job should run after selecting the "Every Day" option. Saving the job appears to discard the selected days, when in effect the settings were irrelevant. To reduce confusion, the logic on the page has been improved to reduce the ability to make irrelevant selections; for example, days of the week check boxes are now not available when the "Every Day" option is selected.
For the SMPP Protocol Provider configuration settings, the "Split Long Message" and "Split Size" fields do not apply when the "Split Method" is set to "Message Payload". These fields should now be disabled unless they actually affect notifications sent to the provider. Note that the "Maximum Message Length" setting will still apply, and truncate any messages that exceed the specified value.
Previously, the FindWhoIsOnDuty web service operation would return a confusing error message if a targeted Group contained a Coverage without an associated Team. The method now returns a Soap Response of INCOMPLETE_GROUP when any part of the Group is missing.
When adding a Dynamic Team using web services, the system would return an "Unknown Application Error" if the name included a pipe character (|). The SOAP API has been updated to include a new status response message of "INVALID_TEAM_NAME" to indicate when the name of a Team includes invalid characters.
An issue was identified where it was possible to edit the name of an externally-owned email Device using the web user interface. This issue has been resolved.
Appendix 2: 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 will 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 3: DDL and DML Changes in This Release
- Change the cascading rule for DVC_NTFN to remove escalation entries when the parent device notification is deleted (Oracle only)
- Add PRESENTATION_ID to EVS and EVS_ARC
- Add IDX_COMM_FLD_NAME_ONLY index to COMM_FLDS table
- Add DEST_PREPEND_DIGITS column to the PROT_SUCPS table for country exit code support
- Add unique index INDEX IDX_WB_CRDS_NM_ORG on (name,org_id) to the WEB_CREDS table
- Add the PERSON_PLACES and PERSON_PLACE_SETTINGS tables for sticky settings
- Rename function "Enable native login for SAML" to "Enable Native Login For SAML Users"
- Populate PERSON_NOTIFICATION_ESCALATED audit events with escalation level values
- Fix data in the WEB_CREDS table to rename duplicate entries to clean up bad data
JDN-4289 Originally created by Don Clark