JPath and JSON Text Functions

After installation of the Module for JSON format, 2 new functions appear in the list of WAPT internal functions: JPath and JSON Text.

JPath

JPath is an internal function of WAPT. It is designed for server responses containing JSON and works on the same principle as XPath function.

$XPath function in WAPT supports all features of XML Path Language. In particular, you can use it to select nodes or node-sets in the XML document by specifying some path expression. The node is selected by following the specified path through the document.

XPath can understand only XML (tree-structured XML document), so first of all we should convert JSON to XML. In XML document any node has a name, but in JSON some nodes do not have names. In particular, such structure as array does not have any name. However, we use arrays in the XPath function. That is why we introduce the own internal name for arrays - Element - to be able to work with them. For example, when we pass through the document hierarchy /node1/node2/ and find some array, we give the name "Element" to it and the resulted path will look like this:

/node1/node2/Element[number] - this way we choose an element of array with the specified number.
The sequence of embedded tags can be continued further - inside the specified element of array.

When we convert JSON to XML, we also make some changes in another structure of JSON - in an object. Each object in JSON looks as follows: {property-name1 : value1, property-name2 : value2, …}

There are no attributes for values in JSON, however they may be required in the XPath function. You will need this attribute when organizing a search, for example: find all nodes where the attribute type is equal to int. That is why we add an attribute type to values of properties.

Attribute type is a single attribute of values which is added during the conversion of JSON to XML. It can be equal to array, object, bool, string, double, int, uint, null depending on a value.

The Syntax of JPath Function

$JPath function has the following syntax:

$JPath({path}, YES/NO, {var-name})

Here path is the sequence of opening tags standing before a desired node,
YES/NO indicates whether quotation marks " " must be deleted (YES) or not (NO) in the received value of this function.
var-name is the name of variable which contains the extracted JSON (this parameter is optional).

A dialog for defining JPath function looks as follows:

XPath: Here you should enter the sequence of opening tags that stand before a desired node. This sequence can contain variables. Use $Var(var-name) function to insert the necessary variables in the path expression. Enter the $ sign in the XPath field and you will see a prompt with the list of available variables (defined on the previous pages). Select a desired variable in the list to insert it in the path expression.

It is recommended to write all names within the XPath string with the quotation marks " ", because $JPath accepts some symbols which are illegal for XML. If the XPath string does not contain illegal characters, it will be processed without quotation marks. However, if it contains some symbol illegal for XML, then the function will not work without quotation marks.

You can read JSON message either from

The server response to this (to the previous) request, or
Variable.

If you choose the option "Variable", you should click the Select... button and select the necessary variable in the list.

Strip quotation marks: Removes quotation marks " " in the received value of this function.

Examples of Usage

Example 1.

This example demonstrates the usage of the first JSON structure - an object. Here we extract the value of "id" from the JSON message of server response.



We define a variable param1 which uses the JPath function to extract the value from the message by its path:



Let's click the "Test" button to test the execution of this function. It successfully extracts the value of "id":

The following examples demonstrate the usage of the second JSON structure - array.

Example 2.

Here we want to receive the value of "state" property:



We define the following variable for this purpose:



Let's click the "Test" button to test the execution of this function:

Example 3.

In this example you can also see the usage of arrays in JSON code.



Here is the full listing of response code:



So, there is an array of 4 objects (separated by a comma). To work with arrays in JSON, we should name each of them as Element. In this example we define the following function to work with the third element of array:

$JPath(/Element[3]/attr/id)

As a result, we receive the value of "id" property:

Example 4.

The previous two examples demonstrate how to select nodes in the XML document by specifying some path expression. Besides, you can organize a search to find all objects with the values equal to the certain string/number or having the certain type or something else. Suppose, you receive the following response from the server:



Here is the listing of response code:


...............................................................................................................................
and so on.

Let's organize the following search: find all elements of array with the "N" property equal to "Thursday" and return their values of "C" property. We should define the following function:

$JPath(//Element[N='Thursday']/C)



As a result, we will receive the list of values:

Example 5.

JPath and JSON Text functions can process only JSON. However, when you receive a server response containing JSON, in many cases that response consists not only of JSON, but also HTML, JavaScript and other code. There can be several parts of JSON inserted in HTML or JavaScript. To work with such response, you should first of all extract the necessary part(s) of pure JSON to some variable. Usually it is done with the help of Search or Hidden functions. Only after that you can apply JPath function to the extracted JSON - in this function you should specify the name of variable containing JSON. Note that variable must contain a valid JSON to use it in JPath function.

In the following example you can see the JSON array of objects inside the JavaScript code:



Let's extract the second element of array and apply JPath function to it. To get the second element of array, we define a variable which is calculated using the Search parameter function:



Here we specify left and right boundaries and the index equal to 1 - to take the first of found values. Index equal to 0 is used to get values randomly. If we test this function, we will receive the following result:



It is a JSON object, so JPath function can be applied to it. Now we define the second variable which is calculated using the JPath function applied to the previous variable var1:



We select the option Variable, then click the Select... button and select var1 variable in the list:



This function will find the value of "d" property in the second element of array:



So, the result will be the following:

JSON Text

JSON Text function is similar to WAPT function Static text. Both of them return the specified string of text. JSON Text function additionally supports the JSON formatting. When you define this function, you should enter any valid JSON in the Text field. You can insert variables $Var(var-name) inside the entered text. After execution of this function, the text will contain the calculated values of these variables.

Example 1.



Here is the result of execution of this function:

Example 2.

In this example we will show the usage of variables.
Suppose that earlier we created a variable var2 which is calculated using JPath function. Now we can use this variable in the body of JSON Text function:



After execution of this function, the actual value of var2 variable will be substituted in JSON text: