Parse XML form - Completing the Mapping tab (Version 5.4 fields)

For Parse XML rules created in versions before PRPC Version 5.4, the Mapping tab defines a list of parse steps that define how the system parses the arriving XML message into a page and values on that page.

These fields are deprecated. Click Upgrade to convert older Parse XML rules to the Version 5.4 format. See Parse XML form — Completing the Mapping tab.

Each row contains:

  • A source path to locate one node of the XML document, using notation that is a subset of XPath (W3C XML Path Language version 1.0).
  • An action to be performed when the node is found.
  • For actions that set a value, a target specification.

The Pega Platform incorporates both the Document Object Model (DOM) parser and the SAX parser. Select which you prefer for the system to apply.

Field Description
Source Path Specify a traversal path to the node that is used at run time as the context node for the action of this parse step. The syntax for the source path specification is similar to the W3C XPath standard, and is described below:
  • For an XML element node, enter the name of the element node. For element nodes that are not immediate children of the root element, enter a fully qualified path to the element node using element names separated by '/' characters. If the element does not matter (meaning that any element node at the specified level is equally valid), replace the element name with a '*' character.
  • For an attribute node, enter the name of the attribute node, prefixed by a '@' character. In a source path with multiple element nodes separated by '/' characters, the attribute node must appear as the final (right-most) node.
  • To handle node depth, enter the starting depth of the source path relative to the preceding parse rule. Prefix one or more '>' characters to the beginning of the source path value, one for each element node of the preceding parse rule. The node depth also indicates that this parse rule belongs to the scope of the action defined for the preceding parse rule. For example, if the action of the preceding parse rule is Find All Nodes and the node depth is the same as the node being repeated, this parse rule repeats for each found node.

For example, if the source path is:

>>>PurchaseOrder/*/Product/@id

the system:

  1. Starts at the third node of the preceding parse step, which may be part of the repeated nodes.
  2. Then looks for a child element named PurchaseOrder.
  3. Then looks for its first child element.
  4. Then looks for a child element named Product.
  5. Then looks for its id attribute.

If found, the system performs the action you specify.
Action Select an action to perform on the node specified in the source path. See Actions below.
Target Enter a target for the action. The value you enter depends on the action being performed:
  • When the action is Embed Page, Append Page to List, Add Page to Group, Set Value, Append Value to List, or Append Value to Group, enter a reference to a property of the Page Class.
  • If you selected Call Parse Structured or Call Parse Delimited, identify a Record Type that is the final key part of a Parse Structured rule or Parse Delimited rule.

If the action is Set Group Key or Set Page Class, enter an expression for the Page Group or Value Group key or a page class, using these syntax elements:

  • Enter $NODE-NAME to indicate that the name of the context node is the value of the group key or page class.
  • Enter $NODE-VALUE to indicate that the value of the context node is the value of the group key or page class.
  • Enter a string surrounded by double quotes as the value.

For example, these are valid expression values:

"Data-Customer"
$NODE-NAME
"item" + $NODE-VALUE
Parser Type  
Parser Type Select DOM for Document Object Model parsing (the default) or SAX for parsing based on the Simple API for XML parser. The default is DOM.

While these produce identical results, SAX is generally recommended for large, complex XML documents and DOM is recommended for short documents.

Note: If this rule is to be executed frequently, consider testing both the DOM and SAX with real inputs to determine which performs better.

Actions

You can use any of these in the Action field.

Action Description
Find Node Traverse the source path to the final (right-most) element node. This action is useful for XML data with a deep hierarchical structure. This action typically precedes the Embed Page action. Leave the Target field blank for this action.
Find All Nodes Traverse the source path to the final (right-most) element node. Iterate over this node and all its sibling nodes. This action typically precedes the Append Page to List, Add Page to Group, Append Value to List, or Append Value to Group actions.

Leave the Target field blank for this action. For example, to iterate over the rowdata node, enter:

PhoneBookData/Contact/rowdata

as the Source Path for this action.
Set Group Key Specify the index (subscript value) of the page or scalar value to be added to the target property (of mode Page Group or Value Group ).

This action must precede an Add Page to Group or Append Value to Group action. Enter an expression for the index in the Target field, composed of constants and the current node name or value.

Set Page Class Specify the class of an embedded target page. This action may precede the Embed Page, Append Page to List, or Add Page to Group actions.

Enter an expression for the page class in Target field, composed of string literals and the current node name or value.
Create Page Create a top-level page. This action may be preceded by the Set Page Class action. If you don't specify a page class, the system uses the page class defined by the target property.
Embed Page Create a page and embed it in the property (of property mode Page ) specified by the Target field. The created page becomes the current page for all actions at or below the current node depth.

This action may be preceded by the Set Page Class action. If you don't specify a page class, the system uses the page class defined by the target property.

Typically this action is preceded by the Find Node action.

Append Page to List Create a page and append it to the property (of mode Page List ) specified by the Target field. The created page becomes the current page for all actions at or below the current node depth.

This action may be preceded by the Set Page Class action. If you don't specify a page class, the system uses the page class defined by the target property.

Typically, this action is preceded by the Find All Nodes action.

Append Page to Group Create a page and append it to the property (of mode Page Group ) specified in the Target field. The newly created page becomes the current page for all actions at or below the current node depth.

This action must be preceded by the Set Group Key action, and may be preceded by the Set Page Class action. If you don't specify a page class, the system uses the page class defined by the target property.

Typically, this action follows the Find All Nodes action.

Set Value Set the value of the Single Value property specified by the Target field to the text value of the current element or attribute node.
CAUTION:
Don't use a Parse XML rule to set the value of a property that is the target property of a Declare Expression rule.
Append Value to List Append the value of the current node to the property (of property mode Value List ) specified by the Target field. This action is typically preceded by the Find All Nodes action.
Add Value to Group Add the value of the current node to the property (of property mode Value Group ) specified by the Target field.

This action must be preceded by the Set Group Key action. This action is typically preceded by the Find All Nodes action.

Call Parse-XML Call another Parse XML rule. The system uses the Applies To key part of this Parse XML rule (or the class of the page resulting from the most recent Add Page to Group action) as the first key part, and the value you enter in the Target as the NameSpace to look up the Parse XML rule. The system uses the value of the source path of the current rule as the third key part of the Parse XML rule.
Call Parse-Structured Call a Parse Structured rule. The system uses the Applies To key part of this Parse XML rule as the first key part, and the value you enter in the Target as the Record Type to look up the Parse Structured rule.
Call Parse-Delimited Call a Parse Delimited rule. The system uses the value in the Target field to obtain the Record Type (third key part) for the Parse Delimited rule.

It uses the current Namespace (second key part of this rule) as the Namespace portion of the Parse Delimited rule key.

You can override this Namespace by entering another Namespace value and a period before the Record Type in the Target field (using the format namespace.recordtype).