Updating custom subscription panels for xMatters 5.x

This article applies to the xMatters On-Premise solution only; it has not been verified with xMatters On-Demand.

Some previous integrations for xMatters included a custom subscription panel that was pre-configured to retrieve values for some properties from the host system and automatically populate the fields on the subscription form with the appropriate options. Unfortunately, many of these custom panels were designed for outdated version of xMatters and do not always work properly when integrations are migrated to our newer products.

This article lists the various components of the custom subscription panels, and explains how to update them to work with xMatters 5.0 and xMatters 5.1. Note that your panel may not experience all of these issues, depending on the date of release and the specific integration you are updating. You may not need to apply all of these changes to your subscription panel (if it ain't broke, don't fix it).


After migrating an integration to xMatters 5.x, you might experience any or all of the following symptoms:

  • Subscription settings do not persist when you change from one tab to another on the panel.
  • Layout is incorrect (e.g., text is overwritten by other text).
  • Controls don't work (e.g., "Save" button doesn't actually save the settings).

Most of these problems are due to changes in the xMatters web server code, some of which are incompatible with legacy Java Server Pages (JSP) content.

The following instructions will allow you to resolve a variety of known incompatibilities between xMatters 5.x web server code and custom subscription panels.

Back up the subscription panel

Before making any of the following changes, make sure you create a backup version of the custom subscription panel. 

To back up your panel:

  1. Log on to your xMatters server as an administrator and, on the Developer tab, click Subscription Domains.
  2. Click your subscription domain in the list and, on the Subscription Domain Details page, find the value of the Custom Page URL field.
    • It should be something like: jsp/subscription/hpsmim-3-0/SMIMSubscriptionForm.jsp
  3. In the xMatters installation folder on your server's file system, at the indicated subfolder within one of the following locations (depending on your version of xMatters):
  1. Make a copy of the JSP file.
  2. Open the custom subscription panel in a text editor, and you're ready to make changes.

Fix javascript errors

To fix the outdated Javascript, search for any instances of


and replace them with


Fix layout problems

To fix layout errors such as text being overwritten by labels, find any divs with a "width" value that is less than the "margin-left" value and modify these values so that the width is greater than the left margin. A good first step is to swap the values; for example:


  div.form-row label.summary {
  	font-weight: bold;
  	width: 0px;
  	margin-left: 85px;


  div.form-row label.summary {
  	font-weight: bold;
  	width: 85px;
  	margin-left: 0px;

You can also improve the layout of tab contents by adding a grey background and an optional label; for example:

Add the following tag to the tab's code:

<group label="">

For example, replace:

    <tab-content id="summary_tab" label="Summary">


    <tab-content id="summary_tab" label="Summary">
      <group label="Summary">


Fix data persistence issues

To address the data persistence issues, first replace all instances of "document.<formName>" with "document.forms['<formName>']"

For example, if the form name is "OMUSubscriptionForm", replace instances of

var lastTab = document.OMUSubscriptionForm.currentTab.value;)


var lastTab = document.forms['OMUSubscriptionForm'].currentTab.value; )

Persist selected values when switching tabs

Next, find the line where onsubmit is assigned, and note the functions that are invoked. Copy the names of any that are similar to "select<something>TargetOptions".

For example, from

onsubmit="selectNodeTargetOptions(this); selectLayoutGroupTargetOptions(this); return validateForm(this);"

You would copy "selectNodeTargetOptions(this)" and "selectLayoutGroupTargetOptions(this)"

Now search for the definition of the onLoad() function; e.g., search for code similar to "function onLoad()", and then paste the "select<somthing>TargetOptions" function invocations that you copied previously to replace any instances of "this" with "document.forms['<form-name>']", as you did earlier.

For example, replace




The onLoad function definition should now look something like this:

  function onLoad()
   <previously-existing content not shown>

Eliminate deprecated code

The "subscription-device-filter" tag is not supported in xMatters 5. Search for any instances of this tag and delete them from the subscription JSP file. For example, delete tags similar to:

<subscription-device-filter group-label="Devices"/>


xMatters internal reference: SUP-10020, DTN-4215

Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk