JSON values in Architect
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.
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”}, { }.
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.
| 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”. |
| 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 |
| 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.
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.
