Defining message formats and rules

This topic describes custom message formatting, including how to create scripts and format rules.

What is custom message formatting?

Custom message formatting is a way to display message data in a more user-friendly, readable way without actually modifying the data of the message in any permanent way. This is done by creating a javascript template script following an established API which will transform the data for display in a special tab in the message editor. Once the script is created, it can be uploaded from a navigation option in the Admin Console. Once uploaded, the script can be selected from a drop-down menu located in the Formatted tab in the message editor; upon selection the script is executed and the output is displayed in the message editor. This data can be copied to the clipboard and saved in another application or text editor.

One common use case for some WMQ messages is to transform EBCDIC characters to ASCII characters. This script is provided as an example in the product’s API package.

Creating a script

Examples are given in the product. The script must contain the special boiler plate for loading and provide the “inTransform” method as part of the script API. The message data and a message context object is provided for this method. The output of the method is expected to be a string.

To create a message format script

1. Select Message Formats from the Navigation Panel. 
2. In the Message Format Scripts section in the displayed workspace, click the '+' icon. The following window is displayed:
   
3. Enter a Script Name, and Description (optional), and click Upload Script to browse to the relevant script file.
4. Once the file is uploaded, click Create.
5. If no errors are displayed, the script was successfully uploaded and a confirmation message displayed in the Status Panel. The script is also displayed in the Message Format Scripts section, and is available for use by the message editor.

To modify a message format script

1. In the Message Format Scripts section, select Edit from the operations drop-down menu alongside the relevant script.
2. Modify the description and upload an updated script, as required.

3. Click Update.

   Note

   To change the name of a script, a new script must be created.

To view a message format script

1. In the Message Format Scripts section, select View Script from the operations drop-down menu alongside the relevant script.
2. The script is displayed in a read-only format.

To delete a message format script

1. In the Message Format Scripts section, select Delete from the operations drop-down menu alongside the relevant script.
2. In the displayed confirmation message, click OK.

What is a message format rule?

A message format rule is a convenient way to apply a certain Message Format Script to a message automatically, if specific conditions are met. The rule provides for checking the condition of matching a specified message format in the message context (“Format” field in MQMD header).

As an example, a message can have a value of “MQSTR” or something custom like “MQMFT”. You can create a rule which will apply script “ABC” to any message with Format = “MQMFT”. With the rule in place, selecting the Formatted tab in the message editor will display the message formatted by “ABC” without having to select the script from the drop-down menu. A second option for applying a rule is to check the first number of characters in the message; this is referred to in the rule as an “Eye Catcher”. For example, if we create a rule with an Eye Catcher value of “XYZ”, any message opened in the editor in which the first 3 characters match “XYZ”, the assigned script will be chosen automatically for the Formatted tab.

To create a message format rule

1. Select Message Formats from the Navigation Panel. 
2. In the Message Format Rules section in the displayed workspace, click the '+' icon. The following window is displayed:
   
3. Enter a Rule Name, Description (optional), the Message Format, and an Eye Catcher (one of Message Format or Eye Catcher must be filled in order for the rule to be saved).
4. Select the relevant Message Format Script from the drop-down list.
5. Click Create.
6. If no errors are displayed, the rule was successfully uploaded and a confirmation message displayed in the Status Panel. The rule is also displayed in the Message Format Rules section.

To modify a message format rule

1. In the Message Format Rules section, select Edit from the operations drop-down menu alongside the relevant rule.
2. Modify the relevant fields, as required.

3. Click Update.

   Note

   To change the name of a rule, a new rule must be created.

To delete a message format rule

1. In the Message Format Rules section, select Delete from the operations drop-down menu alongside the relevant rule.
2. In the displayed confirmation message, click OK.