Parsing XML Response Bodies Using XPath

Guide Overview

Summary:
Use XPath to drill into XML response bodies so you can identify acceptance/rejection outcomes and extract rejection reasons.

Learning Objectives:

• Understand how XPath traverses an XML document using / between parent and child nodes.
• Configure mappings that identify a lead as accepted based on an XML response body.
• Extract a rejection reason from an XML response body (including why "/text()" is used in the Reason Path).
• Handle repeating nodes (arrays), node attributes, and namespaced (SOAP-style) XML.
• Override response parsing when the response Content-Type header is incorrect.

Quick Start Workflow

1. Get a sample XML response body (accepted and rejected examples are below).
2. Determine the XPath to the outcome node (where the response indicates accepted/rejected).
3. Configure your outcome mapping using the appropriate Outcome Search Term and Outcome Search Path.
4. Configure the rejection reason mapping using a Reason Path (typically with "/text()").
5. Handle advanced cases (repeating nodes, attributes, namespaces) and use Response Content Type Override if parsing fails.

Step‑by‑Step Instructions

Step 1. Understand XML and XPath paths

• Goal: Know how to express “where the data is” in the XML as a single XPath string.
• Context: XML is hierarchically structured and human-readable. XPath drills into the XML from the outermost (root) node down to the node you want to extract. To learn more about XML, see: https://www.tutorialspoint.com/xml/

Instructions:

1. Start at the outermost (root) level of the XML document.
2. Drill down by specifying deeper node names separated by / between parent and child nodes.
3. Continue until you reach the node you need to extract.

Expected Result: You can write an XPath that targets a specific node in your XML response.

Step 2. Identify an accepted response

• Goal: Recognize an accepted lead using an XML response body.
• Context: If the response body for an accepted lead looks like the example below, your mapping can identify the lead as accepted.

Instructions:

1. Use this example accepted response body:

   <result>accepted</result>
   <errors />
   

2. Configure your mapping so the value accepted in the result node is used to identify acceptance.

Expected Result: Responses containing the accepted value at the mapped path are identified as accepted.

Step 3. Extract a rejection reason

• Goal: Extract the rejection reason text from a rejected response body.
• Context: A rejected response can contain an error node with a human-readable rejection reason.

Instructions:

1. Use this example rejection response body:

   <response>
       <result>rejected</result>
       <errors>
           <error>Quota filled for red cars</error>
       </errors>
   </response>
   

2. Configure the mapping to extract the error text as the rejection reason.
3. In the Reason Path, use "/text()" as a capture group so the mapping extracts the tag’s value (rather than only searching for a match).

Expected Result: The mapping extracts Quota filled for red cars as the rejection reason.

Step 4. Handle repeating nodes (arrays)

• Goal: Handle XML where multiple identically-named nodes appear under a parent node.
• Context: LeadConduit automatically attempts to parse repeating child nodes as arrays.

Instructions:

1. Use this example response with repeating <error> nodes:

   <response>
       <result>rejected</result>
       <errors>
           <error>Quota filled for red cars</error>
           <error>Must be older than 18 years</error>
       </errors>
   </response>
   

2. With the same mappings used above, capture both errors.
3. Note that repeating nodes are captured as an array of fields, indexed by integer values starting at 0 (0 = first, 1 = second, etc.).
4. If you want to ignore the first error node and capture the second, add a (1-based) position index to the node name in your reason path.

Expected Result: Both errors are captured as an array, and you can select a specific error by position index when needed.

Step 5. Match or capture node attributes

• Goal: Extract values stored in node attributes (key=value pairs in an opening tag).
• Context: Some responses store the outcome (or other data) as an attribute—for example, an outcome attribute on the result node.

Instructions:

1. Identify whether the value you need is stored as an attribute rather than a child node.
2. Use @ to indicate that an XPath term is an attribute (not a child node) of the node just preceding it.

Expected Result: Your mapping can read values stored in XML attributes.

Step 6. Parse namespaced (SOAP-style) XML

• Goal: Make XPath work on namespaced XML where node names include prefixes (e.g., soap:).
• Context: Most XPath parsers (including LeadConduit’s) don’t deal gracefully with namespacing. Namespaced XML often includes attributes that attach namespace names to node names using a colon (e.g., soap:Envelope). The example in the source is a SOAP variant.

Instructions:

1. To ignore namespaces in your mapping, use this pattern:

   /*[name()='nodename'] instead of /nodename
   

2. Example: to match the StatusCode tag as a success response, use:

   *[name()='soap:Envelope']/*[name()='soap:Body']/*[name()='CreateResponse']/*[name()='Results']/*[name()='StatusCode']
   

Expected Result: Your XPath mapping can traverse namespaced tags and correctly match/extract the node values you need.

Step 7. Override the response Content-Type when parsing fails

• Goal: Fix parsing issues caused by an incorrect response Content-Type header.
• Context: If properly-configured parsing is not working, the response Content-Type header may not have been set correctly by the recipient system.

Instructions:

1. If parsing fails despite correct mappings, check the response Content-Type header.
2. Set the desired Content-Type in the Response Content Type Override mapping.
3. Common XML Content-Types include:
   • application/soap+xml; charset=utf-8
   • text/html
   • application/xml

Expected Result: The response body is parsed using the override type, enabling your XPath mappings to work.

Validate Your Setup

1. Use the online XPath expression tester to confirm your XPath expressions match the nodes you intend to target: http://codebeautify.org/Xpath-Tester
2. Validate an accepted response using the sample:

   <result>accepted</result>
   <errors />
   

3. Validate a rejected response and confirm the reason extraction (including "/text()") using the sample:

   <response>
       <result>rejected</result>
       <errors>
           <error>Quota filled for red cars</error>
       </errors>
   </response>
   

4. If your XML includes repeating nodes, confirm you receive an array (indexed starting at 0) and that a (1-based) position index selects the specific node you want.
5. If parsing still fails, set Response Content Type Override to one of the common XML Content-Types listed above.

Troubleshooting

Frequently Asked Questions (FAQ)

Why do Reason Path mappings use "/text()"?

Because Reason Path mappings extract the XML tag’s value and incorporate it into the flow as appended data; outcome mappings typically only search for a match in the response.

How does LeadConduit handle repeating nodes?

It automatically attempts to parse repeating, identically-named child nodes as arrays, indexed by integer values starting at 0.

How do I ignore namespaces in XPath mappings?

Use /*[name()='nodename'] instead of /nodename, and apply that pattern throughout the path (see the example path ending in StatusCode).

Where can I learn more about XPath?

Tutorial: https://www.tutorialspoint.com/xpath/index.htm

Glossary

• xpath-namespace.jpg100 KB
• xpath-accepted.png300 KB
• xpath-rejection.png100 KB
• xpath-attribute.png600 KB
• xpath-position.png200 KB
• xpath-contenttype.png200 KB