This topic explains how to configure and apply the XML Data Bank tool in SOAtest and Virtualize. This tool that extracts XML values (e.g., from a request or response message) so that they can be used in another place. Data can also be sent to a Writable Data Source and accessed in the Extension Tool, or it can be sent to variables for easy reuse across the test suite (SOAtest) or Responder suite or Action suite (Virtualize).

Understanding XML Data Bank

The XML Data Bank tool enables you to extract certain XML values (e.g., from a request or response message) so that they can be used in another place. The XML Data Bank tool can be chained to any other tool that outputs XML. It can extract any information from the XML and make that information available for later use.

For example, you can extract a value from an incoming request and use it to populate an element of the response to be sent when that request is received. You can configure XML Data Banks automatically when using wizards to create virtual assets from traffic. In addition, you can use the "Use Data Source Wizard" to extract a value and use it as a parameterized value in a response. For Message Responders, you can extract values from the incoming request (body or header); for other tools (e.g., tools used in action suites), you can extract values from another tool in the suite. Another option is to manually add an XML Data Bank tool (as an output to an existing tool) that extracts the desired data, then configure other tools to use the extracted data.

Configuring XML Data Bank Using the Data Source Wizard

Configuring the Extraction

To use the "Use Data Source Wizard" wizard to configure an XML Data Bank:

1. (Not applicable for use with Message Responders) Ensure that you have an action set or test suite with at least two tools.

2. In the configuration panel for the tool that you want use the extracted value, select one of the available Form views.
3. From the Operation drop-down menu, select the operation that you want to use the extracted value.
4. In the element view (for example, the id value), go to the message element that you want to use the extracted value, then select Parameterized and Use Data Source Wizard from the available drop-down menus.
   
   
   
   
5. In the wizard that opens:

1. 1. Select the tool you want to extract a value from(for action suite tools). The drop-down menu at the top of the panel will contain all tools in the test or Responder suite that occur before the current tool you are configuring. For example, if you are configuring Tool 4, tools 1, 2, and 3 will display in this menu along with any data sources that may be available.

   2. For Message Responders, select the incoming request message that you want to extract a value from, then specify whether you want to extract values from the message body or message header.

   3. Using the controls on the left side of the panel, indicate what you want to extract and add it to the right side of the panel. The right panel lists the values you have configured for extraction, and shows the name of the data source column where they will be stored (if you keep the default setting).
   4. (Optional) If you want to specify additional options (e.g., if you want to change the name of the column used to store the value, you want the value saved to a writable data source, or you want the value stored to an existing variable) —or if you want to modify advanced XPath settings—then select the appropriate element in table on the right and click Modify. Next, configure the options as needed, then click OK. Available options are described in Options for Each Extracted Element.

Configuring the XML Data Bank Manually

You can also manually chain the XML Data Bank tool to a tool within the Responder, Action, or test suite. To configure the XML Data Bank as a chained tool, complete the following:

1. (Not applicable for use with Message Responders) Ensure that you have an action set or test suite with at least two tools.

2. Right-click the node for the tool associated with the data you want to extract(e.g., if you want to extract a value from an incoming request or outgoing response, choose the Message Responder that handles those messages), then choose Add Output.

3. In the Add Output wizard, indicate where you want to extract the value from (e.g., SOAP Envelope, Incoming Request, Transport Header, Incoming Attachment, Outgoing Response, etc.) and click the Finish button. An XML Data Bank node displays below the tool.

4. Configure the tool as follows:

   1. Use the available controls to specify the XPaths that indicate what value you want to extract. To add an XPath, select a value from the Expected Message list and click the Extract Element button. The value you added displays in the Selected Element list with a Data Source Column name containing the name of the tool the value came from, as well as the extracted value. 

      By default, XPath fields are case sensitive, but you can change case sensitivity by specifying the applicable system property when starting Virtualize. See Case Sensitivity for details.

      
      

      The left panel displays the expected XML response used to create a template from which you can select elements. If this tool receives a valid XML message (e.g., from traffic or as defined by the client tool it is attached to), this panel will be populated automatically. Alternatively, you can copy a sample message into the Literal or Tree tabs. Note that the expected XML does not get saved by default; if you want to save it, enable the Save Expected XML option.

   2. If you want to further configure the XPath or customize extraction settings for this element, click Modify, then modify it as desired. See Options for Each Extracted Element for details.

   3. Repeat steps a and b as needed to configure any additional extractions you want performed.
   4. In the bottom area of the XML Data Bank configuration panel, customize the options as desired. See Tool-Wide Extraction Options for details.

Using the Extracted Value

After adding and/or modifying the extraction, configure the tool that you want to use the extracted data.

Set the value to Parameterized, and choose the appropriate item from the drop-down. For example, if you saved the value to the "title" data source column, you would select it as follows.

Configuration Options

You can configure the following options when configuring an XML Data Bank:

• Options for Each Extracted Element
• Tool-Wide Extraction Options

Options for Each Extracted Element

The following options can be set by modifying a selection listed in the right panel of the XML Data Bank configuration panel.

XPath Options

• XPath: Displays the XPath indicating the value to extract. If you are looking for a more general XPath, you can easily type in a different number into the list indices. For example [1] can be changed to [2] if you are interested in the 2nd occurrence only. After editing the XPath text, click the Validate button to validate the XPath format,  click OK.
• Extract: Allows you to specify exactly what is extracted.
  • Entire Element: Selecting Entire Element will output the entire XPath. For example, XPath/Parent will output <parent>VALUE</parent>. You can configure Index to extract, which controls which element is extracted if the element occurs more than once.
  • Content Only: Selecting Content Only will output only the value. For example, XPath/Parent will output VALUE. You can configure Text Content, which extracts the text content of the element selected, or All Child Nodes, which extracts all child nodes of the element selected.
• XPath Evaluation: Clicking the Evaluate XPath button displays the result of applying the XPath expression against the expected XML.

Data Source Column Options

• Custom column name: Specifies the name of the data source column in which to store the value. Values are stored in an internal data source unless you specify otherwise (e.g., if you select Writable data source column or Variable). This is the name you will use to reference the value in other places. For example, if it is stored in a data source column named My Value, you would choose My Value as the parameterized value. You could also reference it as ${My Value} in literal or multiple response views.

  
  
  
  

• Writable data source column: Enables storing the value in a writable data source column . This allows you to store an array of values. Other tools can then iterate over the stored values.

• Write to all columns that match: Enables storing the value in all columns whose name contains the specified string. When extracting multiple values from a message, each value will be written across all the columns that match. In contrast, if you pick a single writable data source column (the above option), then the values will be written down the column across multiple rows.

• Variable: Enables saving the value in the specified variable so that it can be reused across the current Responder, Action, or test suite. The variable must already be added to the current suite as described in Defining Variables in Virtualize. Any values set in this manner will override any local variable values specified in the Responder, Action, or test suite properties panel.

For headers, you can configure the header name, as well as the data source column options listed above.

Tool-Wide Extraction Options

The following options can be configured in the lower portion of the XML Data Bank tool configuration panel.

• Save expected XML: Specifies whether or not to save the expected XML.
• Canonicalize XML output: Specifies whether or not an extracted element is canonicalized. If this option is selected, and if an entire element is extracted, any necessary namespace declarations are added to the extracted element if the element contains prefixes referencing namespaces that are not declared in the same element.
• Allow alteration: Specifies whether to allow the alteration of an XPath. When this option is selected, an Extract tab and an Alter tab display beneath the Selected Element list. To alter an XPath, select the Allow alteration check box, select the Alter tab, add an XPath by clicking the Extract Element button, and then modify the XPath by clicking the Modify button. The Modify dialog displays and contains the following options:
  • XPath: Displays the selected XPath. To edit and validate a selected XPath, edit the XPath text, click the Evaluate XPath button to validate the XPath format, then click OK.
  • Alteration Type: Allows you to select how the Value you enter alters the extraction. Selecting Append will add the altered value to the end of the extraction. Selecting Prepend will add the altered value to the beginning of the extraction. Selecting Replace With will replace the entire extraction with the altered value you specify.
  • Alteration Value: Allows you to specify either a fixed or parameterized value using a data source.
• Extract empty elements as: Specifies whether or not empty XML elements will be extracted. When this option is enabled, you can use the adjacent text field to specify a text string that indicates what "placeholder" value should be added for every empty extracted element.
  • This option applies when XPath locates a node, but that node has no text content. For example, if you had <parent><child/></parent>, the XPath //*[local-name()="child"]/text() finds the child element, but it has no text content.
  • Note that additional configuration is required if you use this option; see Handling Empty/Missing Elements to Maintain the Integrity of the XML Response.
• Extract missing elements as: Specifies whether or not missing XML elements will be extracted. When this option is enabled, you can use the adjacent text field to specify a text string that indicates what "placeholder" value should be added for every empty extracted element.
  • This option applies when XPath fails to locate any matching nodes. For example if given a simple xml document such as: <parent><child>name</child></parent>, the XPath //*[local-name()="sibling"] would find 0 nodes.
  • Note that additional configuration is required if you use this option; see Handling Empty/Missing Elements to Maintain the Integrity of the XML Response.

Parameterizing XPaths

You can parameterize XPaths to reference Responder suite or test variables, environment variables, and data source values. The syntax to reference variables  is ${myVariableName}. The syntax to reference XML Data Bank values and Data Source values is: ${myColumnName}.

For example, if ${XPath Key} is a data source column name, you could use

/*[local-name(.)="bookstore" and namespace-uri(.)=""]/*[local-name(.)="book"

and

namespace-uri(.)=""][child::node()[local-name(.)="title" and text()="${XPath Key}"]]

Handling Empty/Missing Elements to Maintain the Integrity of the XML Response

By default, empty and missing elements will not be extracted.  This could impact the integrity of the XML response for use in a Writable Data Source.

For instance, assume you have the following XML:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<e>5</e>
	<e/>
	<e>6</e>
</root>

Also assume that you want to create an extraction for all 'e' elements.  To do this, select the first element, then click Extract Element.



Next, select the new extraction, then click Modify.  

In the Modify dialog, change the XPath to extract from /root/e[1]/text() to /root/e/text().



This will extract all three text nodes.

Next, click Data source column and select a writable data source column. When the Data Bank is executed, the writable data source will only contain two rows because the second element is missing text:

ROW 1 = 5
ROW 2 = 6

If you want to write the empty value, change the XPath from /root/e/text() to /root/e and ensure that Content Only is enabled. 



This way, all three elements are extracted, including their content. You can optionally enable the Extract empty element as option to change the value extracted for the empty value. The Data Bank will now append the empty value to the writable data source:

ROW 1 = 5
ROW 2 =
ROW 3 = 6