Extracting an XML Collection from an XML String

Use the Extract XML Collection action to extract a row or a collection of rows from an XML string or from a section of an XML string. Each row in the collection must have the same predefined set of properties.

A collection extracted in this way is equivalent in operation to one resulting from a Load Collection event action. This means that:

  • It can be manipulated by a subsequent Update Collection action.
  • On any subsequent relevant action, it can be converted back to an XML string using  the XML() function.
  • On any subsequent relevant action, its rows can be repeated using the ROWS() function, and each row's properties can be referenced using the P() or FP() functions.

This event action provides a convenient way to work with XML data without having to parse through the tags.

To set up the action and its parameters:

  1. Create an event action with the action type Extract XML Collection.

    See Creating Event Actions.

  2. When you click Edit Parameters, the Event Action Extract XML Collection form is displayed.

    This form has these buttons, each with an accompanying field:

    Button/Field Notes/Comments
    XML Template The button opens the Event Action Select XML Template form, which allows you to select and load the XML template to use with the XML data being extracted. You can also type the XML template in this field manually, or paste it from another source.

    An XML template is an XML fragment that has the same structure as a single row of data in the XML from which the data is to be extracted. This XML fragment can thus serve as a template for that row of data.

    The field displays the XML template as a single string.

    XML The button opens an instance of the Event Action Expression Editor.

    The XML referred to here is the XML string from which data is to be extracted.

    When this type of event action is part of an event handler:

    • With a BodOnReceive event, a commonly used function is BODXML(), which extracts data from the inbound Business Object Document (BOD).
    • You can also:
      • Use the FILECONTENTS() function to read in the contents of a fixed XML file.
      • Use the XML() function to construct an XML string from another collection.
      • Reference a variable or parameter.
      • Manually type a fixed XML string into the field.
    Path The button opens an instance of the Event Action Set Extract XML Collection form that allows you to set the extraction path for the XML.

    This path is to one or more nodes in the XML string under which the data resides for the rows to be extracted. This is expressed in XML Path Language (XPath) syntax.

    See Setting an extraction path for XML data.

    Property Map The button opens an instance of the Event Action Set Extract XML Collection form that allows you to create one or more sets of property name/value pairs that map values to be extracted from the XML string to properties in each row of the resulting collection.

    The property map consists of a list of comma-separated pairs. Each pair, in turn, consists of a property name and a path separated by an equals sign.

    • The property name governs how the extracted value can be referenced later in each row of the extracted collection.
    • The path describes the location of the data to be extracted for the named property, relative to each location in the XML string identified by the Path field.
      Note:  This path is expressed in XML Path Language (XPath) syntax.
    Result Set Assignment The button opens the Event Action Set Result Set ID form, which allows you to provide a name for the set of records that result from the processing of this event action.
  3. Set these parameters and click OK to close the form.