Evaluating JSON Objects and Arrays

This page covers the usage of Expression Builder JSON functions:

  • Get Element from JSON

  • Get Array Length

  • Decode JSON String

Nodes Returning JSON Objects

The following nodes return JSON objects.

Node

Description

Cloud STT

The JSON object contains multiple transcriptions from the Google ASR.

For an example JSON object structure and common use case scenarios, see Accessing Multiple Transcriptions.

Datastore

The JSON object contains up to 50 rows of data from the datastore.

Form

The JSON object contains all matches in a confusables array.

For an example JSON object structure and common use case scenarios, see Custom Form Confusables.

Integration

The JSON object contains data from an external web service.

The JSON object structure is according to the response from the REST API.

Start

The JSON object contains chatbot task incoming data.

You supply sample data on the start node so the schema is available to the expression builder. See Start.

Accessing Data from Nodes Returning JSON Objects

In the call flow, follow the node returning the JSON object with a node that can assign a variable to an expression.

In the expression builder, use the Get Element from JSON and Get Array Length functions to extract data from the JSON object.

  1. Open the Expression Builder.

  2. Select the Get Element from JSON or Get Array Length function.

    1. In the JSON field, select the name of the node with the response object.

      The drop-down menu shows all nodes with a response object.

    2. In the Path field, click the pencil icon.

      This opens a new dialog.

      The dialog shows the structure of the JSON object to the left and blank fields to the right.

    3. Specify the data to extract.

      For examples, see Get Element from JSON Scenarios and Get Array Length Scenarios.

Example:

The integration node makes a request to an external web service and receives a JSON object of employee details. Use the Get Element from JSON and Get Array Length functions to extract the names of each employee.

Note:

Response data from the node in JSON format is only available in the same task as the node. It is not available in linked tasks. See Link Task.

Get Element from JSON Scenarios

Note:

If the return value is an array or another JSON object, it is stringified when it is saved to a variable. The Decode JSON String function converts the stringified value back to a JSON object (or array). See Decode JSON String.

Scenario

Path

Return Value

Get the value from a key-value pair at the object's top level.

Click the key-value pair in the structure. The path to the key displays in the blank fields.

The return value is a string.

Get an array.

Click the array name in the structure. The path to the array displays in the blank fields.

The return value is an array.

Here is an example.

[
{
"type": "mobile",
"number": "0123-4567-8888",
"enabled": "yes"
},
{
"type": "work",
"number": "0123-4567-8910",
"enabled": "yes"
}
]

Get array[x].

Click the array name in the structure. Enter the index number in the next blank field.

  • The first element of the array is numbered 0.

  • You can enter an index variable {{index}} instead of the index number.

  • For the last element of the array, enter the number of elements minus one. If the array has four elements, the index for the last element is 3. The return value is null if you enter a number greater than this.

The return value in this example is an array.

[
{
"type": "mobile",
"number": "0123-4567-8888",
"enabled": "yes"
}
]

Get the value(s) from a key-value pair inside an array.

Click the key-value pair in the structure. The path displays in the blank fields. The number 0 in the path represents the array index, in this case the first element of the array.

You can edit the array index to suit your requirements.

  • You can enter an index variable {{index}} instead of the index number.

  • Enter * to extract all. The return value is an array, as in ["mobile","work"]

  • Use filters. For more information, see Filter.

  • For the last element of the array, enter the number of elements minus one. If the array has four elements, the index for the last element is 3. The return value is null if you enter a number greater than this.

Use the above example data.

The return value for type for the first element of the phonenumbers array is a string: mobile.

The return value for type for all elements of the phonenumbers array is an array, as in ["mobile","work"].

Get the data returned by the datastore node.

To extract a row/record, enter the corresponding array index number in the first field of the path. For example, enter 0 to extract the first row. The return value is an array of column values.

To extract a column value, click that column in the structure. The column name displays in the second field. The initial value of the first field is 0 to extract the column value from the first row. You can edit this to suit your requirements.

  • You can enter an index variable {{index}} instead of the index number.

  • Enter * for all rows.

  • Use filters. For more information, see Filter.

  • For the last row/record, enter the number of elements minus one. If four rows are returned, the index for the last row is 3. The return value is null if you enter a number greater than this.

Note:

You can apply this scenario to any case where the JSON object is an array.

The return value depends on the path.

Examples are:

  • An array of the column values from a record.

  • A column value from a record.

  • An array of values for a column over given records.

Get Array Length Scenarios

Scenario

Path

Get the length of an array.

Click the array name in the structure. The path to the array displays in the blank fields.

Note:

If you Get Array Length on a string, the return value is blank. If you Get Array Length on an object, the return value is the number of key-value pairs at the object's top level.

Get the number of rows returned by the datastore node.

Leave the Path field blank. See following screen shot.

Note:

Leave the Path field blank whenever the JSON object is an array to get the length of the array.

Decode JSON String

Use the Decode JSON String function when the Studio variable value is a "stringified" JSON object. A Studio variable value is stringified when it is an array or JSON object. Studio variable values are always of type string.

The Decode JSON String function converts the stringified value back to a JSON object (or array) so you can apply functions Get Element from JSON and Get Array Length.

These are some example scenarios.

  • A chatbot task has incoming JSON. To access the data in the system variable sys.MESSAGE_JSON, you need to decode the JSON string.

  • You extract an array or JSON object while Editing the JSON Path or following Get Element from JSON and assign that value to a variable.

Use Decode JSON String as follows.

  1. Open the Expression Builder.

  2. Select the Decode JSON string function.

    The Decode JSON string function runs the php function json_decode(), accepting a JSON encoded string and returning a JSON object.

    1. In the Stringified JSON field, type two curly brackets {{

      The variables in your Studio account display in a menu.

      To filter the list, start typing the name of the variable.

    2. Select the variable containing the "stringified" JSON object.

  3. Build another expression.

    1. In the Function field, select Get Element from JSON or Get Array Length.

    2. In the JSON field, select the expression from step 2.

    3. In the Path field, click the pencil icon.

      Note:

      Leave the Path field blank when the function is Get Array Length and the JSON is an array. When you do this, Studio returns the number of elements in the outermost array.

    4. In the response field, enter the path.

      For examples, see Get Element from JSON Scenarios and Get Array Length Scenarios.

      Studio cannot help you build the path as Studio does not know the JSON structure. In the display, the path is blank. This is true whenever you use Decode JSON String.

Example:

The integration node receives a large set of records. Use Editing the JSON Path to extract a subset of the records to an array. Save the array to a variable. Use Decode JSON String before Get Element from JSON or Get Array Length.