User Guide > Process Steps and Components > Iterator Step > XPath Iterator
Was this helpful?
XPath Iterator
The XPath Iterator is a non-XML language used to iterate through and identify specific sections in an XML document. Use XPath Iterator to extract content from an XML document and iterate over the extracted result set.
XPath Iterator 1.1.1, 1.3.0, and 1.4.0 are supported.
Note:  Version 1.1.1 supports older version 1.1.0 and version 1.3.0 supports older version 1.2.1.
The XPath Iterator does the following:
• Enables extracting data from complex XML documents
• Facilitates iteration over the extracted result set
• Accepts sources, and queries at design time or run time
The following skill set is recommended:
• Scripting
• XML
• XML Path Language (XPath)
XPath Iterator 1.4.0 Feature Breakdown
The XPath Iterator 1.4.0 component introduces the following enhancements:
• PutMessage with XML document only - Supports loading, parsing, and retaining an in-memory representation of an XML document, enabling multiple subsequent XPath expressions to be evaluated against the same document.
• PutMessage with XPath expression only - Allows an XPath expression to be provided either through a step property or as a DJMessage argument to the PutMessage action. If a new PutMessage action is invoked before all results from a previous invocation have been consumed via GetMessage, any remaining results are discarded and replaced with the results of the new expression.
• Match count retrieval via GetMessage - Enhances the GetMessage action to support retrieval of the total number of available matches, in addition to returning the next available match from the most recent XPath evaluation.
XPath Iterator Properties
There are no component properties for XPath Iterator version 1.3.0 and 1.4.0.
The following component properties are displayed for XPath Iterator 1.1.1.
Property
Description
Dynamic XPath or XML Source Document
Dynamic XPath or Dynamic XML source.
Source XML Document
Path to XML document.
In the step property, you can provide the following:
• Step option value (design time) - XML file or XPath expression
• Source DJMessage object (run time) - XML file or XPath expression
If the input is a source XML file, then the file content can be passed in the source message.
Source Message is the value supplied within the source DJMessage.
Supported Actions
Action
Description
IsConnected
Indicates whether the component currently has an active and valid connection. This option is available only in version 1.4.0.
Disconnect
Closes an existing connection and performs clean up as needed. This option is available only in version 1.4.0.
PutMessage
Extracts data from an XML source document (based on the XPath expression provided) and prepares the result set.
PutMessage lists an optional source message parameter containing either an XPath expression or an XML source (URL).
The PutMessage action contains two step properties: XML source and XPath expression. You can pass the XML source or XPath expression at design time or through Source Message at run time.
GetMessage
Iterates through the result set. This action should be called after the PutMessage action. The GetMessage action requires a target DJMessage object. The size limit for DJMessage is 25 GB or more, though actual support may vary depending on system resources and available memory.
Note:  The process returns error code 4 if you call GetMessage before PutMessage.
Supported Action Parameters
The following action parameters are supported for XPath Iterator version 1.1.1, 1.3.0, and 1.4.0.
Action
Parameter
Description
PutMessage
Message
The DJMessage parameter for the PutMessage action can be used to load or input a message into the XPath Iterator component.
GetMessage
Message
The DJMessage parameter for the GetMessage action retrieves a message from the XPath Iterator component and loads it into the body of the specified DJMessage.
Supported Action Properties
There are no action properties for XPath Iterator version 1.1.1.
The following action properties are applicable for XPath Iterator 1.3.0 and 1.4.0.
Action
Property
Description
PutMessage
Source Message Input
Describes what the message argument contains. Potential values are:
• XML Source - (Default) Message contains an XML body or is empty.
• XPath Expression - Message contains an XPath expression or is empty.
• Content Ignored - The source message is ignored by the PutMessage action. This option is available only in version 1.4.0.
PutMessage
XPath Expression
XPath expression that will be evaluated against the loaded XML document. Displayed if Source Message Input
is set to XML Source or Content Ignore.
PutMessage
XML Source
Path to XML source file. Displayed if Source Message Input is set to XPath Expression or Content Ignore.
GetMessage
Message Output Type
Selects the content that will be returned in the provided message. Potential values are:
• Next Matching Value - Output message contains the next match from the latest XPath expression evaluation or empty if no previous.
• Match Count - Output message contains the remaining match count.
In earlier versions, the PutMessage action does not process its options independently; both an XML source and an XPath expression must be provided each time the action is executed.
Starting with version 1.4.0, the PutMessage action processes these options independently, enabling greater flexibility. The following scenarios are supported:
• XML source provided (either in the message or via a path specified in the “XML Source” property)
– Any previously loaded XML document will be replaced.
– Any unprocessed matches from previous XPath evaluations are cleared.
– The XML document is loaded and retained in memory, allowing any number of subsequent XPath expressions to be evaluated against it.
• XPath expression provided (either in the message or via the “XPath Expression” property)
– If no XML document has been previously loaded, the PutMessage action ends with an error.
– Any unprocessed results from previous XPath evaluations are cleared.
– The XPath expression is evaluated against the currently loaded XML document, and the resulting matches are retained for retrieval via the GetMessage action.
• Both XML source and XPath expression provided (using any combination of the methods described above)
– The behaviors of the two scenarios above are combined. A new XML document is loaded, and the XPath expression is immediately evaluated against it. The resulting matches are retained for future retrieval via the GetMessage action.
 
This table outlines the various possible step property combinations supported by XPath.
XML Source
XPath Expression
Description
Example
Combination of Design and Run Time
Source Message (Content)
Expression
Provide XML content at run time
srcMsg.body=fileread("C:\people.xml")
Provide XPath expression at design time
//Person[@title="doctor"]
Source Message (URL)
Expression
Provide URL to the XML file at run time
srcMsg.Body = "C:\people.xml"
Provide XPath expression at design time
//Person[@title="doctor"]
URL
Source Message (Expression)
Provide XML content at design time
C:\people.xml
Provide XPath expression at run time
srcMsg.Body="//Person[@title="doctor"]"
Design Time
URL
Expression
Provide URL to the XML file at design time
C:\people.xml
 
 
Provide XPath expression at design time
//Person[@title="doctor"]
*Content: msg.Body = fileread("C:\myspace\people.xml")
**URL: msg.Body = "C:\myspace\people.xml"
Errors
Code
Name
Description
Reason
1
ERR_EOF
End of file reached
No more items to return
4
ERR_READERR
Component not initialized
XPath is not initialized. ERR_READERR occurs when GetMessage is called before PutMessage.
34
ERR_INVALID
Invalid XPath expression or XML source file
Error occurred while processing XPath expression or loading XML source
Possible reasons:
• Invalid XPath expression or XML source
• Empty field value
50
ERR_UNSPECIFIED
Unknown error
Unknown error identified by the component
Last modified date: 01/08/2026