JSON values in Architect

AI-generated summary

Genesys Cloud's Architect platform provides comprehensive JSON management capabilities through its JSON literal and expression editors, supporting strict formatting requirements and multiple data types. The system implements key JSON functions including ToJson, ToJsonCollection, and JsonParse, while handling various JSON types such as strings, numbers, booleans, null objects, arrays, and nested objects. Users can create and manipulate JSON data through variables in flows and scripts, accessing properties via dot notation and managing NOT_SET values with built-in error handling. The platform maintains strict JSON compliance, requiring double quotes for keys and string values, while supporting runtime operations like counting collection items and adding elements to arrays. JSON validation features provide positional information for syntax errors, and though users can save JSON with validation errors, this prevents flow publication. The system offers both literal and expression modes for JSON creation, with specialized handling for currency and phone number conversions, array management, and nested object parsing. Task sequences can incorporate JSON variables through the Update Data action, allowing direct literal input or expression-based value setting.

In Architect’s JSON literal editor, add JSON so that you can set literal values directly. You can also use the expression editor in Architect to add JSON via expressions.

Notes:

The Architect JSON type adheres strictly to JSON rules, and not JavaScript Object literal rules, which means that you must wrap keys and string values in double quotes.

This article specifically addresses the more commonly used JSON functions: ToJson, ToJsonCollection, and JsonParse. For help with more JSON functions, see the Architect expression help.

JSON values

To set JSON values, use the JsonParse or ToJson function in expression mode or enter JSON data directly into the JSON literal editor. JSON output values must have variable references.

JSON editor

For a JSON type variable, for example, in an Update Data action and after you select to use JSON, click Click to add JSON literal value. The JSON Editor pane opens. Then, add your JSON data directly in the editor.

Valid JSON types

JSON data type variables editor accepts these types:

String: Surrounded by double quotes. Example: “hello there”, “{\”unusualExample\”: \”This example looks like an object, but is actually a string that was not parsed into an object.\”}”.
Numeric: Integer or decimal value. Example: 0.0, 1.0, 25, -100.
Boolean: Lowercase, does not need quotes. Values: True / False.
Null: Objects with no value.
Array: Can contain values of any type on this list (string, numeric, Boolean, Null, Object). Example: [ ], [1,2,3], [true, “hello”, {“a”: true}].
Object: Can contain values of any type on this list (string, numeric, Boolean, Null, Array). Surround keys by double quotes. Example: {“customerName”: “John Doe”}, { }.

Show me an exampleClick to expand

Considerations

A JSON value can be NOT_SET.
When a JSON value contains an object, functionality looks up case-sensitive property names on an object.
You can create JSON data type variables in Architect flows and scripting.
You must surround property keys in double quotes for JSON values containing objects.
You can query data within a JSON variable that contains an object via dot notation. For example, access the value for the property “userName” within the JSON variable “Flow.myJson” in an expression via “Flow.myJson.userName”. If you try to access a property on a JSON variable that contains an object value, and the property does not exist within the object at runtime, Architect returns a NOT_SET JSON value. If you try to access a property on a JSON value that is not an object, runtime engines start error handling.

JSON expression creation

You can use JSON within an expression with ToJson, toJsonCollection, and JsonParse.

ToJson: Creates a JSON value with the specified singleton value. When Architect converts a string value, it returns a JSON value with that string value. If you want to parse a string value, use JsonParse.
ToJsonCollection: Converts a JSON value that contains an array to a JSON value collection, when the items are JSON values that Architect clones from items in the array.
JsonParse: Parses the supplied string value to JSON via JSON parsing semantics. When you parse a JSON string, make sure that you surround the keys with double quotes.

ToJson examplesClick to expand

Input	Output
ToJson(MakeDateTime(2022, 8, 4, 0, 0, 0))	A JSON value that contains the string “2022-08-04T00:00:00.000Z”.
ToJson(“Hello”)	A JSON value that contains the string “Hello”.
ToJson(5)	A JSON value that contains the number 5.
ToJson(“{ \”a\”: true }”)	A JSON value that contains a string of “{ \”a\”: true }”. Remember t0 use JsonParse if you want to create a JSON value with an object instead of a string.
ToJson(MakeCurrency(5.25, “USD”))	A JSON value that contains a JSON object of { “amount”: 5.25, “code”: “USD”}.
ToJson(ToPhoneNumber(“tel:+13178723000”))	A JSON value that contains a string of “tel:+13178723000”.

ToJsonCollection examplesClick to expand

Input	Output
ToJsonCollection(JsonParse(“[ true, 100 ]”))	A JSON collection value with two JSON value items in it. The first JSON value contains the Boolean value true and the second JSON value contains the number 100.
ToJsonCollection(MakeEmptyJsonArray())	An empty JSON collection value.
Count(ToJsonCollection(JsonParse(“[ true, 100 ]”)))	2
Count(AddItem(ToJsonCollection(JsonParse(“[ true, 100 ]”)),MakeEmptyJsonObject()))	3

JsonParse examplesClick to expand

Input	Output
JsonParse(“\”Hello\””)	A JSON value that contains the string “Hello”.
JsonParse(“[ 0, 1, 2 ]”)	A JSON value that contains the array [ 0, 1, 2 ].
JsonParse(“{ \”a\”: true, \”b\”: 100, \”c\”: [ true, false ], \”d\”: null }”)	A JSON value that contains a JSON object of { “a”: true, “b”: 100, “c”: [ true, false], “c”: null }
JsonParse(ToString(NOT_SET))	A NOT_SET JSON value.
JsonParse(“true”)	A JSON value that contains the Boolean value true.

Validation

When the JSON literal editor determines that the text is invalid, a validation error opens. Sometimes, the error contains positional information, which indicates at what character the validation fails. If your error contains a position number, click the message to move your cursor to the error. You can save while your JSON literal value is in error, however doing so adds validation errors to the flow and prevents you from publishing it.

Show me an example of an error with positional informationClick to expand

Add a JSON variable to a task sequence

The following example describes how to add a JSON variable to an Update Data action.

From the Toolbox, expand the Data menu and drag an Update Data action to the wanted location in the task.
In the Name field, add a meaningful name to describe the item.
Click Add update statement and select JSON.
In the Enter variable name field, type the label to identify the variable on tasks.
In the Value To Assign field, select from the following options.
- To set the value from literal mode, click Click to add a JSON literal value. The JSON literal editor opens, and you can create and edit formatted JSON.
- To set the value using an expression, click Expression Modes next to Click to add a JSON literal value and do one of the following steps.
  - Add the expression inline.
  - Click Expression and add the expression inline.
(Optional) To add another variable, click Add update statement.

[NEXT] Was this article helpful?

Get user feedback about articles.

JSON values in Architect

AI-generated summary

In Architect’s JSON literal editor, add JSON so that you can set literal values directly. You can also use the expression editor in Architect to add JSON via expressions.

Notes:

The Architect JSON type adheres strictly to JSON rules, and not JavaScript Object literal rules, which means that you must wrap keys and string values in double quotes.

This article specifically addresses the more commonly used JSON functions: ToJson, ToJsonCollection, and JsonParse. For help with more JSON functions, see the Architect expression help.

JSON values

To set JSON values, use the JsonParse or ToJson function in expression mode or enter JSON data directly into the JSON literal editor. JSON output values must have variable references.

JSON editor

Valid JSON types

JSON data type variables editor accepts these types:

String: Surrounded by double quotes. Example: “hello there”, “{\”unusualExample\”: \”This example looks like an object, but is actually a string that was not parsed into an object.\”}”.
Numeric: Integer or decimal value. Example: 0.0, 1.0, 25, -100.
Boolean: Lowercase, does not need quotes. Values: True / False.
Null: Objects with no value.
Array: Can contain values of any type on this list (string, numeric, Boolean, Null, Object). Example: [ ], [1,2,3], [true, “hello”, {“a”: true}].
Object: Can contain values of any type on this list (string, numeric, Boolean, Null, Array). Surround keys by double quotes. Example: {“customerName”: “John Doe”}, { }.

Show me an exampleClick to expand

Considerations

A JSON value can be NOT_SET.
When a JSON value contains an object, functionality looks up case-sensitive property names on an object.
You can create JSON data type variables in Architect flows and scripting.
You must surround property keys in double quotes for JSON values containing objects.
You can query data within a JSON variable that contains an object via dot notation. For example, access the value for the property “userName” within the JSON variable “Flow.myJson” in an expression via “Flow.myJson.userName”. If you try to access a property on a JSON variable that contains an object value, and the property does not exist within the object at runtime, Architect returns a NOT_SET JSON value. If you try to access a property on a JSON value that is not an object, runtime engines start error handling.

JSON expression creation

You can use JSON within an expression with ToJson, toJsonCollection, and JsonParse.

ToJson: Creates a JSON value with the specified singleton value. When Architect converts a string value, it returns a JSON value with that string value. If you want to parse a string value, use JsonParse.
ToJsonCollection: Converts a JSON value that contains an array to a JSON value collection, when the items are JSON values that Architect clones from items in the array.
JsonParse: Parses the supplied string value to JSON via JSON parsing semantics. When you parse a JSON string, make sure that you surround the keys with double quotes.

ToJson examplesClick to expand

Input	Output
ToJson(MakeDateTime(2022, 8, 4, 0, 0, 0))	A JSON value that contains the string “2022-08-04T00:00:00.000Z”.
ToJson(“Hello”)	A JSON value that contains the string “Hello”.
ToJson(5)	A JSON value that contains the number 5.
ToJson(“{ \”a\”: true }”)	A JSON value that contains a string of “{ \”a\”: true }”. Remember t0 use JsonParse if you want to create a JSON value with an object instead of a string.
ToJson(MakeCurrency(5.25, “USD”))	A JSON value that contains a JSON object of { “amount”: 5.25, “code”: “USD”}.
ToJson(ToPhoneNumber(“tel:+13178723000”))	A JSON value that contains a string of “tel:+13178723000”.

ToJsonCollection examplesClick to expand

Input	Output
ToJsonCollection(JsonParse(“[ true, 100 ]”))	A JSON collection value with two JSON value items in it. The first JSON value contains the Boolean value true and the second JSON value contains the number 100.
ToJsonCollection(MakeEmptyJsonArray())	An empty JSON collection value.
Count(ToJsonCollection(JsonParse(“[ true, 100 ]”)))	2
Count(AddItem(ToJsonCollection(JsonParse(“[ true, 100 ]”)),MakeEmptyJsonObject()))	3

JsonParse examplesClick to expand

Input	Output
JsonParse(“\”Hello\””)	A JSON value that contains the string “Hello”.
JsonParse(“[ 0, 1, 2 ]”)	A JSON value that contains the array [ 0, 1, 2 ].
JsonParse(“{ \”a\”: true, \”b\”: 100, \”c\”: [ true, false ], \”d\”: null }”)	A JSON value that contains a JSON object of { “a”: true, “b”: 100, “c”: [ true, false], “c”: null }
JsonParse(ToString(NOT_SET))	A NOT_SET JSON value.
JsonParse(“true”)	A JSON value that contains the Boolean value true.

Validation

Show me an example of an error with positional informationClick to expand

Add a JSON variable to a task sequence

The following example describes how to add a JSON variable to an Update Data action.

From the Toolbox, expand the Data menu and drag an Update Data action to the wanted location in the task.
In the Name field, add a meaningful name to describe the item.
Click Add update statement and select JSON.
In the Enter variable name field, type the label to identify the variable on tasks.
In the Value To Assign field, select from the following options.
- To set the value from literal mode, click Click to add a JSON literal value. The JSON literal editor opens, and you can create and edit formatted JSON.
- To set the value using an expression, click Expression Modes next to Click to add a JSON literal value and do one of the following steps.
  - Add the expression inline.
  - Click Expression and add the expression inline.
(Optional) To add another variable, click Add update statement.

[NEXT] Was this article helpful?

Get user feedback about articles.

JSON values in Architect

JSON values

JSON editor

Valid JSON types

Considerations

JSON expression creation

Validation

Add a JSON variable to a task sequence

[NEXT] Was this article helpful?

Loading...

JSON values in Architect

JSON values

JSON editor

Valid JSON types

Considerations

JSON expression creation

Validation

Add a JSON variable to a task sequence

[NEXT] Was this article helpful?