JSON Variables
(Available from version 7.1 onwards.)
JSON variables allow you to work with JSON objects and arrays.
JSON Array
Create a JSON Array variable to store and work with JSON arrays.
Properties
JSON arrays do not have any properties.
Information on Examples for Methods
Example JSON Arrays
Show
An individual example is provided for each JSON Array method described in this topic. Each example performs an operation on one of the JSON arrays below.
Array_Add_Set
This array is used in the examples for all methods named Add <Type> and Set <Type> by Index.
["A","B","C"]
Array_Contains_Get
This array is used in the examples for all methods named Contains <Type> and Get <Type> by Index.
["John",37,true,[6,80,"Brown","Blue"],{"Street": "Long Road","Number":54,"City":"Meadowville"}]
Example Workflows
Show
The sample project includes one workflow for each method described below.
The project also contains the following two workflows:
_Populate Arrays
The workflow _Populate Arrays populates the two arrays described above with their elements. This workflow is invoked at the start of all other workflows.
_Convert_Arrays_To_Text
The workflow _Convert_Arrays_To_Text writes the two arrays described above to the two text variables:
-
Array_Contains_Get_Text
-
Array_Add_Set_Text
This workflow is invoked at the end of all other workflows, where required. It also resets all arrays and objects so that you can run the workflows multiple times without having to exit Debug mode each time.
Project Download
Download the project here and unzip to the folder %AppData%/Nice_Systems/AutomationStudio/Projects\.
The downloadable project can only be loaded if using Real-Time Client 7.2 or higher.
Methods
Add Boolean
Adds a Boolean element to the end of the JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
Boolean |
Boolean |
The Boolean value to add to the end of the JSON array. |
Returns
Nothing
Example
This example adds the Boolean value true to the end of the JSON array Array_Add_Set.
The initial contents of Array_Add_Set are:
["A","B","C"]
After running the workflow, the array is written to the text variable Array_Add_Set_Text.
Show JSON Array
[ "A", "B", "C", true ]
Add JSON Array
Adds a JSON array as a new element at the end of the JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
JSON array |
JSON array |
The JSON array to add to the end of the JSON array. |
Returns
Nothing
Example
This example adds the JSON array Array_Contains_Get to the end of the JSON array Array_Add_Set.
The initial contents of Array_Add_Set are:
["A","B","C"]
After running the workflow, the array is written to the text variable Array_Add_Set_Text.
Show JSON Array
[
"A",
"B",
"C",
[
"John",
37,
true,
[
6,
80,
"Brown",
"Blue"
],
{
"Street": "Long Road",
"Number": 54,
"City": "Meadowville"
}
]
]
Add JSON Object
Adds a JSON object as a new element at the end of the JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
JSON object |
JSON object |
The JSON object to add to the end of the JSON array. |
Returns
Nothing
Example
This example adds the JSON object Object_Address to the end of the JSON array Array_Add_Set.
Show the Object_Address Object
{
"Street": "Long Road",
"Number": 54,
"City": "Meadowville"
}
The workflow is shown below.
The initial contents of Array_Add_Set are:
["A","B","C"]
After running the workflow, the array is written to the text variable Array_Add_Set_Text.
Show JSON Array
[
"A",
"B",
"C",
{
"Street": "Long Road",
"Number": 54,
"City": "Meadowville"
}
]
Add Number
Adds a number element to the end of the JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
number |
number |
The number to add to the end of the JSON array. |
Returns
Nothing
Example
This example adds the number 7 to the end of the JSON array Array_Add_Set.
The workflow is shown below.
The initial contents of Array_Add_Set are:
["A","B","C"]
After running the workflow, the array is written to the text variable Array_Add_Set_Text.
Show JSON Array
[ "A", "B", "C", 7 ]
Add Text
Adds a text element to the end of the JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
text |
text |
The text to add to the end of the JSON array. |
Returns
Nothing
Example
This example adds the text NICE to the end of the JSON array Array_Add_Set.
The workflow is shown below.
The initial contents of Array_Add_Set are:
["A","B","C"]
After running the workflow, the object is written to the text variable Array_Add_Set_Text.
Show JSON Array
[ "A", "B", "C", "NICE" ]
Contains JSON Array
Checks if the element at the specified index of the JSON array is a JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
index |
number |
The index of the JSON array to inspect. Index values are counted from 1. |
Returns
Returns a Boolean value of true if the element at the specified index of the JSON array is a JSON array.
Example
This example checks whether the 4th element in the JSON array Array_Contains_Get is an array. The array is shown below. The 4th element is indeed an array.
["John",37,true,[6,80,"Brown","Blue"],{"Street": "Long Road","Number":54,"City":"Meadowville"}]
The workflow is shown below.
After running the workflow, the Boolean variable Contains indicates whether the 4th element in the array is a JSON array.
In debug mode, Contains is set to true, as expected.
Contains JSON Object
Checks if the element at the specified index of the JSON array is a JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
index |
number |
The index of the JSON array to inspect. Index values are counted from 1. |
Returns
Returns a Boolean value of true if the element at the specified index of the JSON array is a JSON object.
Example
This example checks whether the 5th element in the JSON array Array_Contains_Get is a JSON object. The array is shown below. The 5th element is indeed a JSON object.
["John",37,true,[6,80,"Brown","Blue"],{"Street": "Long Road","Number":54,"City":"Meadowville"}]
The workflow is shown below.
After running the workflow, the Boolean variable Contains indicates whether the 5th element in the array is a JSON object.
It is set to true, as expected.
Contains Value
Checks if the element at the specified index of the JSON array is a primitive value (Boolean, number, decimal, text, or DateTime).
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
index |
number |
The index of the JSON array to inspect. Index values are counted from 1. |
Returns
Returns a Boolean value of true if the element at the specified index of the JSON array is a primitive value.
Example
This example checks whether the 2nd element in the JSON array Array_Contains_Get is a primitive value. The array is shown below. The 2nd element is indeed a primitive value.
["John",37,true,[6,80,"Brown","Blue"],{"Street": "Long Road","Number":54,"City":"Meadowville"}]
The workflow is shown below.
After running the workflow, the Boolean variable Contains indicates whether the 2nd element in the array is a primitive value.
It is set to true, as expected.
Count Elements
Returns the number of elements in the JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
None |
|
|
Returns
Returns a number.
Example
This example counts the number of elements in the array Array_Add_Set. The array is shown below.
["A","B","C"]
The workflow is shown below.
After running the workflow, the number of elements is written to the variable Number.
It is set to 3 as expected.
Get JSON Array by Index
Returns the JSON array at the specified index of the JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
index |
number |
The index of the JSON array to return. Index values are counted from 1. |
Returns
Returns a JSON array. If the element at the specified index is not a JSON array, an empty JSON array is returned.
Example
This example returns the array at the 4th element in the JSON array Array_Contains_Get. The array is shown below.
["John",37,true,[6,80,"Brown","Blue"],{"Street": "Long Road","Number":54,"City":"Meadowville"}]
The workflow is shown below.
After running the workflow, the array is written to the JSON array Array_Returned which in turn is written to the text variable Array_Returned_Text.
Show JSON Array
[ 6, 80, "Brown", "Blue" ]
Get JSON Object by Index
Returns the JSON object at the specified index of the JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
index |
number |
The index of the JSON array to return. Index values are counted from 1. |
Returns
Returns a JSON object. If the element at the specified index is not a JSON object, an empty JSON object is returned.
Example
This example returns the JSON object at the 5th element in the JSON array Array_Contains_Get. The array is shown below.
["John",37,true,[6,80,"Brown","Blue"],{"Street": "Long Road","Number":54,"City":"Meadowville"}]
The workflow is shown below.
After running the workflow, the object is written to the JSON object Object_Returned which in turn is written to the text variable Object_Returned_Text.
Show JSON Object
{
"Street": "Long Road",
"Number": 54,
"City": "Meadowville"
}
Get Value by Index
Returns the value at the specified index of the JSON arrray.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
index |
number |
The index of the JSON array to return. Index values are counted from 1. |
Returns
If the element at the specified index is a primitive value (Boolean, number, decimal, text, or DateTime), it is returned as a text value. If the element is not of one of these types, an empty text value is returned.
If the element is a Boolean, returns text values of True or False with initial letters capitalized.
Example
This example returns the value at the 2nd element in the JSON array Array_Contains_Get. The array is shown below.
["John",37,true,[6,80,"Brown","Blue"],{"Street": "Long Road","Number":54,"City":"Meadowville"}]
The workflow is shown below.
After running the workflow, the value is written to the variable Text.
Is Empty
Checks if the JSON array is empty.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
None |
|
|
Returns
Returns a Boolean value of true if the JSON array is empty.
Example
This example checks whether the JSON array Array_Contains_Get is empty.
The workflow is shown below.
After running the workflow, the Boolean variable Contains indicates whether the array is empty or not.
It is set to false, as expected.
Load from Text
Loads a text string to the JSON array. The text string must be a legal JSON array and the array must be an array of JSON objects.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
text |
text |
The text of the JSON array to upload. Must be a legal JSON array. |
Returns
Nothing
Example
The workflow below populates the JSON array variable JSON_Array with the following text that represents a JSON array of two JSON objects:
[{"Name":"Spot","Type":"Dog","Breed":"Dalmatian","Age":3.5},{"Name":"Cleopatra","Type":"Cat","Breed":"Siamese","Age":8.0}]
The result of the Load from Text method is written to the Boolean variable Success.
When executed, the JSON array is populated and the variable Success is set to True.
If the text loaded was not a valid JSON array, Success would have been set to False.
Remove by Index
Removes the element at the specified index of the JSON array. Elements at later indexes are shifted one index to the left.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
index |
number |
The index of the JSON array to remove. Index values are counted from 1. |
Returns
Returns a Boolean value of true if the element at the specified index was removed.
Example
This example removes the 2nd element in the JSON array Array_Add_Set.
The initial contents of Array_Add_Set are:
["A","B","C"]
After running the workflow, the array is written to the text variable Array_Add_Set_Text.
Show JSON Array
[ "A", "C" ]
Set Boolean by Index
Sets the element at the specified index of the JSON array to a specified Boolean value.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
Boolean |
Boolean |
The Boolean value to assign to the specified index. |
|
index |
number |
The index of the JSON array to set. Index values are counted from 1. |
Returns
Returns a Boolean value of true if the element was set successfully.
Example
This example sets the 2nd element in the JSON array Array_Add_Set to true.
The initial contents of Array_Add_Set are:
["A","B","C"]
After running the workflow, the array is written to the text variable Array_Add_Set_Text.
Show JSON Array
[ "A", true, "C" ]
The variable Contains indicates whether the operation was successful.
The variable Contains is set to true.
Set JSON Array by Index
Sets the element at the specified index of the JSON array to a specified JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
JSON array |
JSON array |
The JSON array to assign to the specified index. |
|
index |
number |
The index of the JSON array to set. Index values are counted from 1. |
Returns
Returns a Boolean value of true if the element was set successfully.
Example
This example sets the 2nd element in the JSON array Array_Contains_Get to the array Array_Add_Set.
The initial contents of Array_Contains_Get are:
["John",37,true,[6,80,"Brown","Blue"],{"Street": "Long Road","Number":54,"City":"Meadowville"}]
The initial contents of Array_Add_Set are:
["A","B","C"]
After running the workflow, the array is written to the text variable Array_Contains_Get_Text.
Show JSON Array
[
"John",
[
"A",
"B",
"C"
],
true,
[
6,
80,
"Brown",
"Blue"
],
{
"Street": "Long Road",
"Number": 54,
"City": "Meadowville"
}
]
The variable Contains indicates whether the operation was successful.
The variable Contains is set to true.
Set JSON Object by Index
Sets the element at the specified index of the JSON array to a specified JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
JSON object |
JSON object |
The JSON object to assign to the specified index. |
|
index |
number |
The index of the JSON array to set. Index values are counted from 1. |
Returns
Returns a Boolean value of true if the element was set successfully.
Example
This example sets the 2nd element in the JSON array Array_Add_Set to the JSON object Object Address.
The initial contents of Array_Add_Set are:
["A","B","C"]
The object Object Address is shown below.
{
"Street": "Long Road",
"Number": 54,
"City": "Meadowville"
}
The workflow is shown below.
After running the workflow, the array is written to the text variable Array_Add_Set_Text.
Show JSON Array
[
"A",
{
"Street": "Long Road",
"Number": 54,
"City": "Meadowville"
},
"C"
]
The variable Contains indicates whether the operation was successful.
The variable Contains is set to true.
Set Number by Index
Sets the element at the specified index of the JSON array to a specified number.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
number |
number |
The number to assign to the specified index. |
|
index |
number |
The index of the JSON array to set. Index values are counted from 1. |
Returns
Returns a Boolean value of true if the element was set successfully.
Example
This example sets the 2nd element in the JSON array Array_Add_Set to the number 7.
The workflow is shown below.
The initial contents of Array_Add_Set are:
["A","B","C"]
After running the workflow, the array is written to the text variable Array_Add_Set_Text.
Show JSON Array
[ "A", 7, "C" ]
The variable Contains indicates whether the operation was successful.
The variable Contains is set to true.
Set Text by Index
Sets the element at the specified index of the JSON array to a specified text.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
text |
text |
The text to assign to the specified index. |
|
index |
number |
The index of the JSON array to set. Index values are counted from 1. |
Returns
Returns a Boolean value of true if the element was set successfully.
Example
This example sets the 2nd element in the JSON array Array_Add_Set to the text NICE.
The workflow is shown below.
The initial contents of Array_Add_Set are:
["A","B","C"]
After running the workflow, the array is written to the text variable Array_Add_Set_Text.
Show JSON Array
[ "A", "NICE", "C" ]
The variable Contains indicates whether the operation was successful.
The variable Contains is set to true.
JSON Object
Create a JSON Object variable to store and work with JSON objects.
Properties
JSON objects do not have any properties.
Information on Examples for Methods
Example JSON Object
Show
All examples presented here are based on the JSON object shown below. This JSON object stores all information relevant to a branch of a chain of auto garages. It includes details about the garage itself, its customers, and the customers' cars.
{
"Garage_Name": "ACME Car Repairs",
"Garage_Code": 3141403,
"Garage_License_No": 3334001510,
"Garage_Address": {
"Street Number": 195,
"Street": "Kelvin Drive",
"City": "Forest Hills",
"Code": 2052
},
"License_Valid": true,
"Agent_For": [
"Toyota",
"Fiat",
"BMW",
"Chrysler"
],
"Customers": [
{
"First_Name": "John",
"Last_Name": "Smith",
"Address": {
"Street Number": 10,
"Street": "Hunter Street",
"City": "Sunnyvale",
"Code": 3232
},
"Cars": [
{
"Registration": "3300265",
"Manufacturer": "Toyota",
"Model": "Corolla",
"Year": 1985,
"Under_Warranty": false,
"Extras": [
"DVD Player",
"Alarm",
"Sunroof"
]
},
{
"Registration": "852314",
"Manufacturer": "Fiat",
"Model": "Panda",
"Year": 2020,
"Under_Warranty": true,
"Extras": []
}
]
},
{
"First_Name": "Mary",
"Last_Name": "Johnson",
"Address": {
"Street Number": 33,
"Street": "Linksfield Street",
"City": "Rainville",
"Code": 9913
},
"Cars": []
}
]
}
Download the JSON file here.
Example Workflows
Show
The sample project includes one workflow per method. For example, the workflow that demonstrates the method CountEntities is shown below.
Each workflow starts with a step Load Main JSON Object which invokes the workflow LoadFromStart, shown below. This workflow:
-
Resets all variables in the project so that you can debug the other workflows with consistent outcomes.
-
Populates the JSON object Main_JSON_Object that holds the example JSON shown above.
-
Writes the contents of Main_JSON_Object to a text variable Main_JSON_Object_Text.
Project Download
Download the project here and unzip to the folder %AppData%/Nice_Systems/AutomationStudio/Projects\.
The downloadable project can only be loaded if using Real-Time Client 7.2 or higher.
Methods
Contains JSON Array
Checks if the JSON object includes an array specified by name along the root of the JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
array name |
text |
The name of the array. |
Returns
Returns a Boolean value of true if the array exists on the root of the JSON object, or false if it does not.
Example
This example tests whether there is an array called Agent_For in the example JSON object. The expected response is true.
Show JSON
{
"Garage_Name": "ACME Car Repairs",
"Garage_Code": 3141403,
"Garage_Address": {
"Street Number": 195,
"Street": "Kelvin Drive",
"City": "Forest Hills",
"Code": 2052,
"License_Valid":true
},
"Agent_For":["Toyota", "Fiat", "BMW", "Chrysler"],
The workflow below writes the response to the Boolean variable Contains.
The response is true, as expected.
Contains JSON Object
Checks if the JSON object includes a nested JSON object specified by name along the root of the JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
object name |
text |
The name of the object. |
Returns
Returns a Boolean value of true if the object exists, or false if it does not.
Example
This example tests whether there is an object called Garage_Address in the example JSON object. The expected response is true.
Show JSON
{
"Garage_Name": "ACME Car Repairs",
"Garage_Code": 3141403,
"Garage_Address": {
"Street Number": 195,
"Street": "Kelvin Drive",
"City": "Forest Hills",
"Code": 2052,
"License_Valid":true
},
"Agent_For":["Toyota", "Fiat", "BMW", "Chrysler"],
In the workflow below, the response is stored in the Boolean variable Contains.
The response is true, as expected.
Contains Key
Checks if the JSON object includes a primitive key-value pair specified by name along the root of the JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
key |
text |
The name of the key-value pair. |
Returns
Returns a Boolean value of true only if the key-value pair exists and is set to a primitive value of type Text, Number, Decimal, DateTime, List or Boolean.
Example 1
This example tests whether there is a key-value pair named Garage_Code in the example JSON object that has a value of a primitive type. The expected response is true.
Show JSON
{
"Garage_Name": "ACME Car Repairs",
"Garage_Code": 3141403,
"Garage_Address": {
"Street Number": 195,
"Street": "Kelvin Drive",
"City": "Forest Hills",
"Code": 2052,
"License_Valid":true
},
"Agent_For":["Toyota", "Fiat", "BMW", "Chrysler"],
In the workflow below, the response is stored in the Boolean variable Contains.
The response is true, as expected.
Example 2
This example tests whether there is a key-value pair named Garage_Address in the example JSON object that has a value of a primitive type. The expected response is false because the Garage_Address is not set to a primitive value, but to a JSON object.
In the workflow below, the response is stored in the Boolean variable Contains.
A false response is returned
Convert to Text
Returns the JSON object as text.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
None |
|
|
Returns
Returns the JSON object as text.
Example
In this example, the text of the example JSON object Main_JSON_Object is written to the text variable Main_JSON_Object_Text.
The text variable contains the full JSON object.
Count Entries
Counts the number of entries (key-value pairs, objects, and arrays) on the root path of the JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
none |
Returns
Returns a number.
Example
In the workflow below, the number of entries is stored in the number variable Count.
The response is returned as 7.
This is as expected as there are 7 entries on the root of the JSON object (shown below collapsed to the root).
Get JSON Array by Name
Returns a JSON array specified by name from the JSON object. The JSON array must exist on the root of the JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
array name |
text |
The name of the array. |
Returns
Returns the JSON array if it exists on the root path of the JSON object.
Example
This example retrieves the JSON array Agent_For.
The array is shown below.
Show JSON
"Agent_For": [
"Toyota",
"Fiat",
"BMW",
"Chrysler"
],
In the workflow below:
-
The array Agent_For is retrieved from the example JSON object Main_JSON_Object and is stored in the array JSON_Array.
-
For debugging purposes, so that we can see the contents of JSON_Array:
-
The array JSON_Array is added to the JSON object JSON_Object_Temp.
-
The JSON object JSON_Object_Temp is converted to text which is stored in the text variable JSON_Array_Text.
-
The array contents are returned as expected.
Get JSON Array by Path
Returns a JSON array specified by path from the JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
array name |
text |
The path to the array to return. Use format: $.(key). Where the path includes an array, use format: $.(array name)[array index no.].(key). Array index numbers are zero-based. |
Returns
Returns the JSON array if it exists at the path specified.
Example
This example retrieves the Cars array for the 1st customer.
The array is shown below.
Show JSON
"Customers": [
{
"First_Name": "John",
"Last_Name": "Smith",
"Address": {
"Street Number": 10,
"Street": "Hunter Street",
"City": "Sunnyvale",
"Code": 3232
},
"Cars": [
{
"Registration": "3300265",
"Manufacturer": "Toyota",
"Model": "Corolla",
"Year": 1985,
"Under_Warranty": false,
"Extras": [
"DVD Player",
"Alarm",
"Sunroof"
]
},
{
"Registration": "852314",
"Manufacturer": "Fiat",
"Model": "Panda",
"Year": 2020,
"Under_Warranty": true,
"Extras": []
}]
In the workflow below:
-
The array Cars for the 1st customer in the example JSON object Main_JSON_Object is retrieved and stored in the array JSON_Array. The path is specified as $.Customers[0].Cars.
-
For debugging purposes, so that we can see the contents of JSON_Array:
-
The array JSON_Array is added to the JSON object JSON_Object_Temp.
-
The JSON object JSON_Object_Temp is converted to text which is stored in the text variable JSON_Array_Text.
-
The array contents are returned as expected.
Get JSON Object by Name
Returns a nested JSON object specified by name from the JSON object. The nested JSON object must exist on the root of the JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
object name |
text |
The name of the nested JSON object. |
Returns
Returns the nested JSON object if it exists on the root path of the JSON object.
Example
In this example, the JSON object Garage_Address is retrieved.
The object is shown below.
Show JSON
{
"Garage_Name": "ACME Car Repairs",
"Garage_Code": 3141403,
"Garage_License_No": 3334001510,
"Garage_Address": {
"Street Number": 195,
"Street": "Kelvin Drive",
"City": "Forest Hills",
"Code": 2052
},
In the workflow below:
-
The nested object Garage_Address is retrieved from the example JSON object Main_JSON_Object and is stored in the JSON object JSON_Object.
-
For debugging purposes, so that we can see the contents of JSON_Object:
-
The JSON object JSON_Object is converted to text which is stored in the text variable JSON_Object_Text.
-
The object contents are returned as expected.
Get JSON Object by Path
Returns a nested JSON object specified by path from the JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
object path |
text |
The path to the nested JSON object to return. Use format: $.(key). Where the path includes an array, use format: $.key.(array name)[array index no.].(key). Array index numbers are zero-based. |
Returns
Returns the nested JSON object if it exists at the specified path of the JSON object.
Example
This example retrieves the JSON object for a customer's address.
The object is shown below.
Show JSON
"Customers": [
{
},
{
"First_Name": "Mary",
"Last_Name": "Johnson",
"Address": {
"Street Number": 33,
"Street": "Linksfield Street",
"City": "Rainville",
"Code": 9913
},
"Cars": []
}
]
}
In the workflow below:
-
The JSON object Address for the 2nd customer is retrieved from the example JSON object Main_JSON_Object and is stored in the JSON object JSON_Object. The path is specified as $.Customers[1].Address.
-
For debugging purposes, so that we can see the contents of JSON_Object:
-
The JSON object JSON_Object is converted to text which is stored in the text variable JSON_Object_Text.
-
The object contents are returned as expected.
Get Value by Name
Retrieves the value of a key specified by its name from the JSON object. The key must exist on the root of the JSON object. A value is only returned if its data type is Text, Number, Decimal, DateTime, List, or Boolean. If the key is a JSON array or JSON object, no response will be returned.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
key |
text |
The name of the key for which to return the value. |
Returns
Returns the value as a text string.
If the element is a Boolean, returns text values of True or False with initial letters capitalized.
Example
In this example, the variable Value_by_Name is set to the value of the key Garage_Name.
The relevant section of the example JSON object is shown below:
Show JSON
{
"Garage_Name": "ACME Car Repairs",
"Garage_Code": 3141403,
"Garage_License_No": 3334001510,
In the workflow below, the value of Garage_Name is stored in the variable Value_by_Name.
The variable Value_by_Name is set to ACME Car Repairs, as expected.
Get Value by Path
Retrieves the value of a key specified by its path from the JSON object. A value is only returned if its data type is Text, Number, Decimal, DateTime, List, or Boolean. If the value is a JSON array or JSON object, no response will be returned.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
key path |
text |
The path to the key for which to return a value. Use the format $.(key).(key). Where the path includes an array, use format: $.(array name)[array index no.].(key). Array index numbers are zero-based. |
Returns
Returns the value as a text string.
If the element is a Boolean, returns text values of True or False with initial letters capitalized.
Examples
Example 1
In this example, the value of the garage's Street name within its Garage_Address object is returned from the example JSON object. The expected response is Kelvin Drive.
Show JSON
{
"Garage_Name": "ACME Car Repairs",
"Garage_Code": 3141403,
"Garage_Address": {
"Street Number": 195,
"Street": "Kelvin Drive",
"City": "Forest Hills",
"Code": 2052,
"License_Valid":true
},
In the workflow below, the value of the key-value pair is written to the variable Text_Value. The path is specified as $.Garage_Address.Street.
As expected, the value Kelvin Drive is returned.
Example 2
This example retrieves the manufacturer of the 2nd car of the 1st customer listed in the example JSON object. The expected response is Fiat. Because arrays are zero-based, the customer element number is set to 0 and the car element number is set to 1.
Show JSON
"Customers": [
{
"First_Name": "John",
"Last_Name": "Smith",
"Address": {
"Street Number": 10,
"Street": "Hunter Street",
"City": "Sunnyvale",
"Code": 3232
},
"Cars": [
{
"Registration": "3300265",
"Manufacturer": "Toyota",
"Model": "Corolla",
"Year": 1985,
"Under_Warranty": false
},
{
"Registration": "852314",
"Manufacturer": "Fiat",
"Model": "Panda",
"Year": 2020,
"Under_Warranty": true
}
]
In the workflow below, the value of the key-value pair is written to the variable Text_Value. The path is specified as $.Customers[0].Cars[1].Manufacturer.
As expected, the value Fiat is returned.
Is Empty
Checks if the JSON object is empty. Returns true if is.
|
Parameter |
Input Type |
Description |
|---|---|---|
|
None |
Returns
Returns a Boolean of value of true if the JSON object is empty.
Example
This example checks whether the example JSON object is empty or not. The result is written to the Boolean variable IsEmpty.
The response is returned as false because the JSON object is not empty.
Load from Text
Loads a text string to the JSON object. The text string must be a legal JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
text |
text |
The text of the JSON object to upload. Must be a legal JSON object. |
Returns
Returns a Boolean value of true if successful. Failure likely indicates that the specified text is not a legal JSON object.
Example
In this workflow:
-
All variables used in the project are reset so that you can debug the other workflows with consistent outcomes.
-
The text of the example JSON object is loaded to the JSON object Main_JSON_Object.
-
For debugging purposes:
-
The result of the Load From Text method is stored in the Boolean LoadSuccess to indicate whether the method succeeded or failed.
-
So that we can see the contents of Main_JSON_Object in debug mode, its contents are converted to text and stored in the text variable Main_JSON_Object_Text.
-
The Boolean LoadSuccess is set to true, indicating that the JSON object was loaded successfully.
The variable Main_JSON_Text stores the JSON object in text format.
Load from Variable
Populates the JSON object with the contents of a specified complex variable. A key-value pair is added to the JSON object for every property of the complex variable.
Any data included in the JSON object is cleared before it is populated with the contents of the variable.
Use the Write to Variable method to populate a complex variable using data stored in the JSON object.
The use of this method is demonstrated in the example below, and in more detail in the scenario Transfer Complex Variable Data Between Solutions.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
variable |
variable |
The complex variable to use to populate the JSON object. |
Returns
Nothing
Example
This workflow populates the JSON object variable JSON_Obj with the properties of the variable Smith Industries, which is of the user-defined type Account. To help us view the value of JSON_Obj, the workflow stores its contents in the text variable JSON_Obj_Text.
Before running the workflow, the values of the parameters of Smith Industries are as shown below:
After the workflow is run, the text variable JSON_Obj_Text is populated as below.
Remove by Name
Removes an entry (key-value pair, array, or nested object) with a specified name from the JSON object if the entry is on the root of the JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
entry name |
text |
The name of the entry to remove. |
Returns
Returns a Boolean value of true if the entry was found and removed.
Example
In this example, the Garage_Code entry is removed from the example JSON object Main_JSON_Object.
Before removal, the Garage_Code entry is the second entry in the JSON object:
In the workflow below:
-
The entry Garage_Code is removed from the example JSON object Main_JSON_Object.
-
For debugging purposes:
-
The result of the method Remove by Name is stored in the Boolean Removed to indicate whether the method succeeded or failed.
-
So that we can see the contents of Main_JSON_Object, the JSON object Main_JSON_Object is converted to text which is stored in the text variable Main_JSON_Object_Text.
-
The Garage_Code entry is now missing from the JSON object.
The Boolean variable Removed is set to true, indicating that the entry was removed from the JSON object.
Set Boolean by Name
Replaces the value of an existing key-value pair (specified by name) on the root of the JSON object with the specified Boolean value. If no key-value pair with the specified name exists on the root, a new key-value pair is added at the bottom of the root with the specified name and the specified Boolean value as the value.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
value |
Boolean |
The value to set for the Boolean key-value pair. |
|
key |
text |
The name of the key-value pair. |
Returns
Nothing
Example
In this example, a new key-value pair is added to the JSON object Main_JSON_Object and the value of an existing key-value pair is modified.
In the workflow below:
-
A new key-value pair is set in the example JSON object Main_JSON_Object: Extended_Hours is set to true.
-
The value of the existing key-value pair, License_Valid, is changed from true to false.
-
For debugging purposes:
-
So that we can see the contents of Main_JSON_Object, the JSON object Main_JSON_Object is converted to text which is stored in the text variable Main_JSON_Object_Text.
-
The value of License_Valid is now shown as false and the key Extended Hours has been added to the bottom of the JSON object and is set to true.
Set JSON Array by Name
Replaces the value of an existing key-value pair (specified by name) on the root of the JSON object with the specified JSON array. If no key-value pair with the specified name exists on the root, a new key-value pair is added at the bottom of the root with the specified name and the specified JSON array as the value.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
array name |
text |
The name of the key-value pair. |
|
JSON array |
JSON array |
The JSON array to insert. |
Returns
Nothing
Example
In this example, the array called Agent_For is replaced with a new array in the example JSON object.
The original array is shown below.
Show JSON
"Agent_For": [
"Toyota",
"Fiat",
"BMW",
"Chrysler"
],
In the workflow below:
-
The JSON array JSON_Array is populated with the values Nissan, Honda, and Mazda.
-
The JSON array named Agent_For in the example JSON object Main_JSON_Object is then set to JSON_Array.
-
For debugging purposes:
-
So that we can see the contents of Main_JSON_Object, the JSON object Main_JSON_Object is converted to text which is stored in the text variable Main_JSON_Object_Text.
-
The array Agent_For now reflects the new values set.
Set JSON Array by Path
Replaces the value of an existing key-value pair (specified by its path) in the JSON object with the specified JSON array.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
path |
text |
The path to the key-value pair. Use format: $.(key). Where the path includes an array, use format: $.(key).(array name)[array index no.].(key). Array index numbers are zero-based. |
|
JSON array |
JSON array |
The JSON array to insert. |
Returns
Returns a Boolean value of true if successful.
Example
This example replaces the empty Extras array under the 1st customer's 2nd car in the example JSON object.
The relevant section of the original JSON object is shown below.
Show JSON
{
"Registration": "852314",
"Manufacturer": "Fiat",
"Model": "Panda",
"Year": 2020,
"Under_Warranty": true,
"Extras": []
}
In the workflow below:
-
The JSON array JSON_Array is populated with the values Alloy Wheels and Tinted Glass.
-
The JSON array named Extras under the 2nd Car under the 1st Customer in the example JSON object Main_JSON_Object is then set to JSON_Array.
-
For debugging purposes:
-
So that we can see the contents of Main_JSON_Object, the JSON object Main_JSON_Object is converted to text which is stored in the text variable Main_JSON_Object_Text.
-
The object with the updated array is shown below.
Show JSON
{
"Registration": "852314",
"Manufacturer": "Fiat",
"Model": "Panda",
"Year": 2020,
"Under_Warranty": true,
"Extras": [
"Alloy Wheels",
"Tinted Glass"
]
}
Set JSON Object by Name
Replaces the value of an existing key-value pair (specified by key name) on the root of the JSON object with the specified nested JSON object. If no key-value pair with the specified name exists on the root, a new key-value pair is added at the bottom of the root with the specified name and the specified nested JSON object as the value.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
JSON Object |
JSON object |
The JSON object to assign to the value of the key-value pair. |
|
nested object name |
text |
The name of the key-value pair. |
Returns
Nothing
Example
In this example, the JSON Object Contact_Details shown below is added to the root of the example JSON object.
Show JSON
{"Tel_1": "04-131-4411",
"Tel_2": "04-131-4412",
"Fax": "04-133-0033",
"email": "acmegarage@garages.com"
}
In the workflow below:
-
The JSON object JSON_Object_Temp is populated with the JSON object above.
-
The JSON object JSON_Object_Temp is added to the example JSON object Main_JSON_Object.
-
The Main_JSON_Object is written to the text variable Main_JSON_Object_Text so it can be viewed in the debugger.
The resulting JSON object is shown below. Note the Contact Details added at the bottom.
Show JSON
{
"Garage_Name": "ACME Car Repairs",
"Garage_Code": 3141403,
"Garage_Address": {
"Street Number": 195,
"Street": "Kelvin Drive",
"City": "Forest Hills",
"Code": 2052
},
"Customers": [
{
"First_Name": "John",
"Last_Name": "Smith",
"Address": {
"Street Number": 10,
"Street": "Hunter Street",
"City": "Sunnyvale",
"Code": 3232
},
"Cars": [
{
"Registration": "3300265",
"Manufacturer": "Toyota",
"Model": "Corolla",
"Year": 1985,
"Under_Warranty": false
},
{
"Registration": "852314",
"Manufacturer": "Fiat",
"Model": "Panda",
"Year": 2020,
"Under_Warranty": true
}
]
},
{
"First_Name": "Mary",
"Last_Name": "Johnson",
"Address": {
"Street Number": 33,
"Street": "Linksfield Street",
"City": "Rainville",
"Code": 9913
},
"Cars": []
}
],
"Contact_Details": {
"Tel_1": "04-131-4411",
"Tel_2": "04-131-4412",
"Fax": "04-133-0033",
"email": "acmegarage@garages.com"
}
}
Set JSON Object by Path
Replaces the value of an existing key-value pair (specified by its path) in the JSON object with the specified JSON object.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
JSON object |
JSON object |
The JSON object to insert. |
|
path |
text |
The path to the key-value pair. Use format: $.(key). Where the path includes an array, use format: $.(array name)[array index no.].(key). Array index numbers are zero-based. |
Returns
Returns a Boolean value of true if successful.
Example
This example modifies the address of the 1st customer in the example JSON object. The original address is shown in the customer's object below.
Show JSON
"Customers": [
{
"First_Name": "John",
"Last_Name": "Smith",
"Address": {
"Street Number": 10,
"Street": "Hunter Street",
"City": "Sunnyvale",
"Code": 3232
},
The address will be changed to:
Show JSON
{
"Street Number": 21,
"Street": "Granville Crescent",
"City": "Greenside",
"Code": 4455}
In this workflow:
-
The address above is loaded to the JSON object JSON_Object_Temp.
-
The JSON object JSON_Object_Temp, which now stores the new address, is written to the JSON object Main_JSON_Object to replace the address of the 1st customer. The path is specified as $.Customers[0].Address.
-
For debugging purposes:
-
The result of the Set JSON Object by Path method is stored in the Boolean SetOK to indicate whether the method succeeded or failed.
-
So that we can see the contents of Main_JSON_Object, the JSON object Main_JSON_Object is converted to text which is stored in the text variable Main_JSON_Object_Text.
-
The 1st customer's address is updated.
Set Number by Name
Replaces the value of an existing key-value pair (specified by name) on the root of the JSON object with the specified number. If no key-value pair with the specified name exists on the root, a new key-value pair is added at the bottom of the root with the specified name and the specified number as the value.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
value |
number |
The number to assign to the key-value pair. |
|
key |
text |
The name of the key-value pair. |
Returns
Nothing
Example
This example updates the Garage_License_No value from 3334001510 to 800900 in the example JSON object. The original is shown below.
In the workflow below:
-
The value of Garage_License_No in the example JSON object Main_JSON_Object is set to 800900.
-
For debugging purposes:
-
So that we can see the contents of Main_JSON_Object, the JSON object Main_JSON_Object is converted to text which is stored in the text variable Main_JSON_Object_Text.
-
The updated value is shown below.
Set Text by Name
Replaces the value of an existing key-value pair (specified by name) on the root of the JSON object with the specified text. If no key-value pair with the specified name exists on the root, a new key-value pair is added at the bottom of the root with the specified name and the specified text as the value.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
value |
text |
The text to assign to the value of the key-value pair. |
|
key |
text |
The name of the key-value pair. |
Returns
Nothing
Example
In this example, a new key-value pair is added to the JSON object Main_JSON_Object.
In the workflow below:
-
A key Garage_Owner with value Owen Pitcher is added to the root of the example JSON object Main_JSON_Object.
-
For debugging purposes:
-
So that we can see the contents of Main_JSON_Object, the JSON object Main_JSON_Object is converted to text which is stored in the text variable Main_JSON_Object_Text.
-
The new key-pair added to the bottom of the main JSON object is shown below.
Show JSON
],
"Contact_Details": {
"Tel_1": "04-131-4411",
"Tel_2": "04-131-4412",
"Fax": "04-133-0033",
"email": "acmegarage@garages.com"
},
"Extended_Hours": true,
"Garage_Owner": "Owen Pitcher"
}
Set Text by Path
Replaces the value of an existing key-value pair (specified by its path) in the JSON object with the specified text.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
value |
text |
The text to assign to the key. |
|
path |
text |
The path to the key-value pair. Use format: $.(key). Where the path includes an array, use format: $.(array name)[array index no.].(key). Array index numbers are zero-based. |
Returns
Returns a Boolean value of true if successful.
Example
This example changes the first name of the first customer from John to Jane in the example JSON object.
The relevant section of the original JSON object is shown below.
In the workflow below:
-
The value of First_Name under the 1st Customer is set to Jane. The path is specified as $.Customers[0].First_Name.
-
For debugging purposes:
-
The result of the Set Text by Path method is stored in the Boolean SetOK to indicate whether the method succeeded or failed.
-
So that we can see the contents of Main_JSON_Object, the JSON object Main_JSON_Object is converted to text which is stored in the text variable Main_JSON_Object_Text.
-
The revised JSON object is shown below.
Write to Variable
Populates the properties of a specified complex variable with the values of the key-value pairs in the JSON object.
Only properties with names that match the keys in the JSON object are populated.
The use of this method is demonstrated in the example below, and in more detail in the scenario Transfer Complex Variable Data Between Solutions.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
variable |
variable |
The complex variable to populate with data from the JSON object. |
Returns
Returns a text list of all issues encountered while trying to write to the selected variable, for example, where the variable does not have a property with the same name as a key in the JSON object, or if the property type does not match the value in the JSON object. (See Example 2 below.)
Example 1
This example is a continuation of the example provided for Load from Variable.
This workflow sets the values of the properties of the variable Smith and Sons (which is of the user-defined type Account) using the contents of the JSON object variable JSON_Obj. The variable JSON_Obj was populated with the values of the properties of another variable of type Account - see the example for Load from Variable.
Before this workflow is run, the contents of the JSON Object are as shown below:
After the workflow is run, the properties of Smith and Sons are as shown below.
Example 2
In Example 1, the key-value pairs stored in the JSON object completely matched the properties of the variable that was selected in the Write to Variable function.
The workflow below instead writes its contents to the variable JS Inc which is a variable of the user-defined type Account_Short. The output of the Write to variable function is written to the text list Write_Errors.
After the workflow is run, the properties of JS Inc are as shown below.
Compare the properties of JS Inc. to the contents of the JSON object shown above:
-
Street Name and House Number data are missing from JS Inc. Because JS Inc. does not have properties with those names, that data is not written to the variable.
-
The Monthly Fee value in the JSON object was not written to the Monthly Fee property of JS Inc. because the value of 132.31 cannot be written to a property of type Number.
The text list variable Write_Errors presents all errors encountered while writing the JSON object to the variable. These match the comparison above.
