JSONPath and XPath

In most cases, you'll use a Business Value to request and parse responses from REST Web services. In Process Director, the Business Value provides the easiest and most effective method for making REST requests and using the data that is included in the REST response.

Just like a Business Value that returns SQL data, a REST Business value will receive a response containing data field values. You must configure a Business Value property for each data field you wish to access from the REST Response.

For each property, the Property Name column is where you'll provide a name for each property, which will be used in the Process Director UI. For each field in the REST Response, the Property Type must be set to REST Data in order to extract the data from a single data field in the REST Response.

An additional setting, Entire REST Response will, as the name implies, simply use the entire XML or JSON file content as the property value. This setting may be useful if you need to see the REST Response contents to understand how to parse them to extract individual fields.

Parsing the REST Response is very important to ensure you extract the correct data. The Property Value column is where you provide Process Director with the instructions on which REST Response field you wish to extract for each property.

Unlike a SQL Business Value, where you simply write the name of a valid database field in this column, a Rest Business Value requires that you provide detailed instructions for parsing the REST Response, to extract the data you want.

The parsing syntax you'll need to use will vary, based on whether the REST Response contains data in XML or JSON Format. Parsing an XML REST response requires you to use a parsing format called XPath, while parsing a JSON response requires the use of JSONPath.

Time and space do not allow us to provide detailed training on these two parsing formats here. There are many freely available resources on the Internet for learning the basics of both XPath and JSONPath. Here are two resources you might find useful, but there are many others:

XPath: W3Schools.Com
JSONPath: SmartBear.com

Note BP Logix does not endorse these resources. They are merely shown here for your convenience.

Let's look at some simple XML and JSON REST Responses to see how we'd parse them using each format. For this example, we'll use some sample weather data for San Diego, CA. These REST documents are available on the BP Logix Documentation portal. Those these are static documents, you can use their URL as the REST URL of a Business Value, for testing on your Process Director installation.

You can use the URL for either of these documents

XML and XPath #

The XML REST Response looks like this:

XPath uses the forward slash character (/) to navigate from the highest node to the lowest one. The current node is the top node of the XML REST response, and it contains the city, clouds, and temperature nodes.

Part of XML's structured nature is to name each node in the XML structure. At the very top of the response, the first node is named <current>. Since we have to start our XPath expression at the highest node, and we need to add a slash between each node, our XPath expression will begin with:

current/

If we want to find the XML node that tells us whether it's clear or cloudy, we'd need to add the <clouds> node, which is located in the second level of the XML hierarchy:

current/clouds/

The <clouds> node contains two attributes: value and name. We need to get the data in the name attribute. Attributes are identified using the "At sign" (@), which means that this value is an attribute of the previous node. So, we need to add this value to our expression as:

current/clouds/@name

This gives us the full XPath expression to access our data, which should return the value broken clouds.

We can use different XPath expressions to return other data from this response, as shown in the table below.

Data	XPath Expression
City	`current/city/@name`
Country	`current/city/country`
Current Temp	`current/temperature/@value`
Low Temp	`current/temperature/@min`
High Temp	`current/temperature/@max`

JSON and JSONPath #

The JSON REST Response looks like this (Though the formatting makes it look like the JSON Response contains more information, it is the same length, 859 characters, as the XML response shown above):

{
   "coord": {
      "lon": -117.2028,
      "lat": 32.7635
   },
   "weather": [
      {
         "id": 803,
         "main": "Clouds",
         "description": "broken clouds",
         "icon": "04d"
      }
   ],
   "base": "stations",
   "main": {
      "temp": 66.65,
      "feels_like": 65.55,
      "temp_min": 59.76,
      "temp_max": 74.79,
      "pressure": 1017,
      "humidity": 54
   },
   "visibility": 10000,
   "wind": {
      "speed": 12.66,
      "deg": 270
   },
   "clouds": {
      "all": 75
   },
   "dt": 1680903688,
   "sys": {
      "type": 2,
      "id": 2017332,
      "country": "US",
      "sunrise": 1680874144,
      "sunset": 1680919947
   },
   "timezone": -25200,
   "id": 0,
   "name": "San Diego",
   "cod": 200
}

JSON path uses a dollar sign character ($) to denote the top or global level of the JSON response. Each level below that is separated by a period (.)character.

In JSON, each data node in the hierarchy is marked by the use of either curly brackets ({})or square brackets ([]). In general, when counting from the top of the Response, each time we reach a bracket character, we need to use a period (.) to specify a different node.

The global JSON Response is always specified by using the dollar sign ($) character. So, that's always the first character of a JSONPath parsing phrase. At the very top of the response is the opening curly bracket that contains the full response. This curly bracket starts the first node of the response, and we have to add a period to the JSONPath expression to indicate we are moving to the next lower node in the hierarchy:

$.

At this level of the response, there are two nodes, coord and weather. If we once again want to extract the data that indicates whether it's clear or cloudy, the data we need is in the weather node, so we need to add it to the JSONPath expresson:

$.weather

The weather portion of the JSON response contains several lower-level nodes. The actual data for current conditions is contained in the main node of the weather portion. But note that, immediately after weather, there is a square bracket, followed by a curly bracket in the JSON response. Each of these brackets requires that we add a period character as a node marker for each of them, in order to properly count the nodes between weather and main. Thus, we end up with our completely parsed path of:

$.weather..main

This gives us the full JSONPath expression to access our data, which should return the value Clouds.

We can use different JSON Path expressions to return other data from this response, as shown in the table below.

Data	JSONPath Expression
City	`$.name`
Country	`$.sys.country`
Current Temp	`$.main.temp`
Low Temp	`$.main.temp_min`
High Temp	`$.main.temp_max`

More Information about Rest Services

REST Services: An overview of using REST Web Services.

JSON and XML for REST: How sample XML or JSON REST responses might compare.

Documentation Feedback and Questions

If you notice some way that this document can be improved, we're happy to hear your suggestions. Similarly, if you can't find an answer you're looking for, ask it via feedback. Simply click on the button below to provide us with your feedback or ask a question. Please remember, though, that not every issue can be addressed through documentation. So, if you have a specific technical issue with Process Director, please open a support ticket.

Send Feedback to BP Logix

Related Topics

JSONPath and XPath

XML and XPath #

JSON and JSONPath #

More Information about Rest Services

Documentation Feedback and Questions