User Guide > Process Steps and Components > Iterator Step > JSONPath Iterator
Was this helpful?
JSONPath Iterator
The World Wide Web Consortium (W3C) formalized an official specification for an XML path language (XPath) in 1999. XPath has served as a central mechanism for directly addressing parts of XML documents since that time. It is integral to XSLT, XPointer and countless software which consumes or uses XML.
Unfortunately, there is no "formal" JSON path language specification backed by an organization like the W3C. However, there is a convention, which was defined by Stefan Goessner in 2007. The convention defines a path language for JSON that is similar to XPath. He coined the name JSONPath for the notation. Since that time, multiple JSONPath implementations in various programming languages have been developed. JSONPath is the de facto "XPath for JSON".
Given the proliferation JSON-formatted content, the need exists to be able to extract specific properties or objects from JSON documents without having to write a map. The JSONPath Iterator provides a means to accomplish this task.
In a nutshell, the JSONPath Iterator supports the following features:
• Specification of a source JSON document
• Evaluation of a JSONPath expression against the source document
• Iteratively retrieve matching objects or properties from the document
JSONPath Iterator 1.0.0 version is supported.
JSONPath Iterator Properties
When you create an instance of JSONPath Iterator component in the Configuration tab > Message Components section, properties will not be defined in the Edit Message Component window.
Supported Actions
Action
Description
PutMessage
Consumes the provided JSON document and JSONPath expression. Loads the document and evaluates the expression against it.
GetMessage
Can be called repeatedly to retrieve the values which were matched by the expression that was evaluated by PutMessage. Returns EOF if no additional values remain.
Supported Action Parameters
Action
Parameter
Description
PutMessage
Message
The source DJMessage for PutMessage. It can optionally contain the following information:
• Source JSON document (if both the JSON File action property and JSONPath.sourcefile message property are not set)
• JSONPath.expression message property. See DJMessage Option Override Properties
GetMessage
Message
When GetMessage is called, the body of the DJMessage referenced by the Message property will be populated with the next value from the set of results, which were produced by the evaluation of the JSONPath expression against the source document.
 
Supported Action Properties
Action
Property
Description
PutMessage Action
JSONPath Expression
The expression that will be evaluated against the loaded JSON document. This value can be overridden by the DJMessage property, JSONPath.expression. It is an error condition if both are missing.
JSON File
The name of a local file from which (if provided) the component will read the source JSON document. The value of this option (whether it is blank or populated) will be overridden by the DJMessage property, JSONPath.sourcefile. If neither is provided, then the source JSON document is expected to be in the body of the DJMessage argument to PutMessage. It is an error condition if the source JSON document cannot be loaded using any of the options.
GetMessage Action
Not applicable
Not applicable
DJMessage Option Override Properties
The values provided in the PutMessage action properties (JSONPath Expression and JSON File) can be overridden with DJMessage properties. Following are the override properties:
• JSONPath.expression: Can be set in the DJMessage referenced by the argument to the PutMessage action. If provided, it overrides the value set in the JSONPath Expression option.
Note:  It is considered an error if both JSONPath Expression action property and JSONPath.expression DJMessage property are missing.
• JSONPath.sourcefile: Can be set in the DJMessage referenced by the argument to the PutMessage action. If provided, it will override any value that is set in the JSON File option.
Note:  If both are missing, then the source JSON document is read from the DJMessage body.
Errors
The following table describes error codes generated for the JSONPath Iterator component.
Action
Code
Description
PUTMESSAGE
ERR_BADOPTIONVALUE
Generated if the JSONPath expression is not set.
 
ERR_INVALID
Multiple errors can result in ERR_INVALID. These include the following:
• Unable to read the source JSON document
• Unable to parse the source JSON document
• JSONPath expression is badly formatted
GETMESSAGE
ERR_READERR
Generated if GetMessage is called without initializing the component instance with PutMessage. In other words, the component is not "connected."
ERR_EOF
Generated if GetMessage is called after the last result from the expression evaluation has been retrieved.
Last modified date: 10/22/2024