Defining Parsings for RA JMS Agent Sender Jobs

You define parsings for headers, properties, and JMS messages from the Parsing page to extract values from the response. You define parsings in tables. When the Set Task Variables for all Headers & Properties checkbox is checked, task variables are created and set for all headers and properties.

You can create a response parsing query to extract values from the response. To add a payload parsing to an RA JMS Agent Sender Job, select the Parsing page.

Normally a Parsing page is only available for Receiver Jobs, but if the Wait for Response checkbox is checked for a Sender Job, it will be available for that Job as well. For more information on Sender Jobs and the Wait for Response checkbox, see Creating RA JMS Agent Sender Jobs.

Adding Parsings

To add a parsing:

  1. For Message Parsings: Select a message type to parse from the Message Type field. The message types are:
    • Plain Text
    • XML
    • JSON
    • YAML
    • Map
    • Bytes (no parsing available)
    • Stream

    The message type you select determines the layout of the table in the Message Parsing section.

    No parsing table is displayed if you select Bytes as the message type and screen will display "No Parsing for Bytes". This is because you cannot parse the payload for bytes. Bytes is only included in the list for completeness.

  2. Click the Add Row button in the appropriate table.
  3. Enter the following for the filter.
    • Header for Headers Parsing The options for the header name are limited to:
      • The available headers, which are CorrelationID, ReplyTo, Type, Priority, and Expiration.
      • Any pre-defined properties defined in the selected Connection object.
    • Name for Properties Parsing

      • The drop-down lists for the Name field includes properties defined in the selected Connection object. You can:

      • Select one of these names.
      • Select one of these names and edit it.
      • Type in a custom name. These editable value fields can include object variables in the format &<variable name>. The values of these object variables will be replaced at runtime.
    • Parsing Type for Plain Text, XML, JSON, and YAML Message Parsings

      • Used to add message parsing. By default, the options are:

      Plain Text and YAML:

      • Regular Expressions

      XML:

      • XPath
      • XQuery

      JSON:

      • JSONPath
      • JSON to XML and XQuery: This type takes JSON, converts it to XML, and runs it through an XQuery, then it puts the results back into JSON.

      There is a feature to include Groovy as a parsing type. It allows you to harness the power of Java and Groovy to parse the response. Because it makes all the Java/Groovy methods available, it can be a security concern and is therefore turned off by default. Groovy can only be selected as parsing type when the Allow Groovy for Parsings of Received Messages box on the JMS tab of the Agent is checked. If you need to define Groovy parsings, consult your Automation Engine Administrator.

    • Key for Map Message Parsings

      • A key name.

    • Index for Stream Message Parsings

      • An index number (a sequential integer starting with 1).

    • Output Type for All Parsings

      • Select an output type in the Output Type field. Available options are:

      • Save as Variable: A variable with the name you specify in the Output Name field is saved to the database. An Automation Engine scripting language variable's name is limited to 32 alphanumeric characters, including the special characters "$", "_", "@", "ยง" and "#". German Umlauts are not allowed. The first character must not be a number.
      • Write to Job Report: Writes the resulting value to the Job's report log prefixed by the optional name you specified in the Output Name field.
      • Save as Report: Saves the resulting value to a report in the <Agent>/bin/task_reports directory based on the name you specified in the Output Name field. The file will be registered with the Automation Engine and viewable from the Automic Web Interface. When this option is used, the RA JMS Agent expects a parameter value of a file name. If you enter a file name with fully qualified path, the Job will get an error like the following:

        • java.io.FileNotFoundException: task_reports/u01/users/qa4/v10/RA_JMS_Alpha/test3.txt (No such file or directory)

      • Write to File: Writes the resulting value to a file on the Agent's file system. You can enter either a stand-alone file name to write to the <Agent>/bin/task_reports directory on the Agent's file system or a file name with fully qualified path to a different location on the Agent's file system. The file will not be registered with the Automation Engine and is not viewable from the Automic Web Interface.
      • End Job and Abort Job: For message parsing. They allow you to end or abort a Job. This is most useful when receiving multiple messages. A match value can optionally be entered in the Output Name field. If a match value is entered, the action will be taken if the match value equals the parse result. If no match value is entered the action will be taken if the parse result is non-empty. A special match value of 'NULL' can be used, it will cause the action to be taken if the parse result is empty. For examples, see Examples: End Job and Abort Job Payload Parsing.
    • Output Name for All Parsings

      • The output name you select will be used as the variable, file name, or Job report prefix; depending on your selection in the Output Type field.

      For Properties Parsings: you can use {n} in this field when you have multiple messages and the message numbers will be substituted for {n}. For more an example of this feature,

    • Expression for Map or Stream Message Parsings

      • The expression to parse. You can type in an expression, or click  the cell editor icon to open the Test Expression dialog. For more information on the Test Expression dialog, see Examples: JMS Payload Parsing.

      With XPath, XQuery, and JSON types, you can automatically generate an expression from a value in the Input box by selecting the value and clicking the Create Expression button. The Create Expression button is grayed out when the Line Numbers box is checked.

      Important !

      XQuery types require $input in front of their query. This is not automatically added when you click the Create Expression button. So after clicking the Create Expression button, go to the Expression box and add $input to the beginning of the expression. For example, if your expression is //note[1]/to[1]/text(), you would need to change it to $input//note[1]/to[1]/text() in order for it to work correctly.

    • Use Array for Plain Text, XML, JSON, and YAML Message Parsings

      • When this checkbox is checked, the results are saved to an Automation Engine Array variable, where each value can be referenced numerically. For example: &VAR[1], &VAR[2], etc.  If this box  is not checked, the whole result is returned as one variable.

Setting Task Variables for All Headers and Properties

When the Set Task Variables for all Headers & Properties checkbox is checked, the following task variables are set for all tasks: 

  • CorrelationID
  • DeliveryMode
  • Destination
  • MessageID
  • Priority
  • Timestamp
  • ReplyTo
  • Type
  • All user defined properties

The variable &MESSAGES_RECEIVED# is always set.

All of these variables have a # suffix. For example, in a post processing script you would reference Priority as &Priority#.

All Header variables have a prefix of JMS such as JMSPriority or JMSCorrelationID so as not to conflict with any Automation Engine variables (specifically Priority).