JSON_SET_VALUE

Use the JSON_SET_VALUE script function to set the value of an existing element in a JSON document.

Syntax

JSON_SET_VALUE (JSON,JSONPath,Value[,Cast])

Parameters

Parameter Description Format Allowed Values
JSON A string that is interpreted as a JSON document. String n.a.
JSONPath The JSONPath that identifies the element that need updating. String n.a.
Value The value that should be assigned to the JSON element. n.a. n.a.
Cast

(Optional) This parameter controls the conversion from Automic Script to JSON datatypes.

 String
  • auto: Automatic determination of datatype. AUTO tries to cast the given value to the following datatypes (in that order), the value will be converted to the first matching datatype: JSON String, Number or String.
  • boolean: Converts the following values to JSON true or false (true: 1,'Y' | false: 0,'N').
  • number: Force the conversion to a JSON number, even if Automic Script Datatype is not a number.
  • String: Force the casting to a string (NEW_VALUE might be another datatype).
  • JSON: Interpret the string as a valid JSON document, for converting quoted JSON strings into JSON sub-documents.

Casting Examples

The following section explains casting using practical examples. Consider the following script:

:SET &JSON_DOC# = '{"val":""}'

:SET &RET# = JSON_SET_VALUE(&JSON_DOC#, '$.val',&VALUE#,&CAST#)

The following table summarizes the changes in &JSON_DOC# after the ADD_ITEM call given different &ITEM# and &CAST# values:

&VALUE# &CAST# &JSON_DOC# after ADD_ITEM
'[1,2,3]' AUTO {"val":[1,2,3]}
'[1,2,3]' STRING {"val":"[1,2,3]"}
'1' AUTO {"val":1}
'1' STRING {"val":"1"}
'1' NUMBER {"val":1}
'1' BOOLEAN {"val":true}
'twelve' AUTO {"val":"twelve"}
'twelve' NUMBER {"val":""} (remark: invalid casting - JSON document is not modified and a casting error is returned)

Important Considerations

Keep the following rules, limitations, and tips in mind when using this script function:

  • Always test JSONPath expressions in an Automation Engine script before you put them into production. JSONPath expressions developed in other tools may not work as there is no common JSONPath standard.
  • JSON_SET_VALUE does not allow you to add new items to objects or arrays. Use JSON_ADD_ITEM for this purpose.
  • PATH_TO_ELEMENT can only target one JSON element that should be set. The path must exist in the document.
  • JSON documents larger than 1MB are not supported.

Tip: Sometimes you need to quote (escape) parts of your JSON documents because they are processed by a separate entity. You can achieve escaped parts by using the cast type string for the quoted JSON sub-document.

Return Value

None / Error Code in case of error.

Runtime Errors

JSON_SET_VALUE will fail with a runtime error on the following conditions:

  • 45334: If your JSON document is invalid.
  • 45342: Syntax Error in JSONPath expression.
  • 45337: Invalid Cast-Parameter: AUTO, STRING, NUMBER, BOOLEAN, or JSON expected.
  • 45338: Cannot cast value into chosen data type.
  • 45340: JSONPath does not match any element.

Examples

This example uses the script function to enrich a JSON object with new values:

:SET &JSON_DOC#='{"OS": "Linux","disks": null, "isAvailable": false, "inventoryNumber":123}'

:SET &IS_AVAIL#=1

:SET &RET# = JSON_SET_VALUE(&JSON_DOC#,'$.disks','[{"GB":2000, "type":"HDD"},{"GB":512, "type":"SSD"}]','JSON')

:SET &RET# = JSON_SET_VALUE(&JSON_DOC#,'$.isAvailable',&IS_AVAIL#,'BOOLEAN')

:SET &RET# = JSON_SET_VALUE(&JSON_DOC#,'$.inventoryNumber','null')

:P &JSON_DOC#

Activation report result:

U00020408 {"OS":"Linux","disks":[{"GB":2000,"type":"HDD"},{"GB":512,"type":"SSD"}],"isAvailable":true,"inventoryNumber":null}

The following example escapes quoted JSON sub-documents:

:SET &DOC# = '{"deploymentName": "hugeServer", "ansibleConf":""}'

:SET &QUOTED_SUBDOC# = '{"awsZone":"srvaws02"}'

:SET &RESULT# = JSON_SET_VALUE(&DOC#, '$.ansibleConf', &QUOTED_SUBDOC#, 'STRING')

:P &DOC#

!outputs {"deploymentName":"hugeServer","ansibleConf":"{\"awsZone\":\"srvaws02\"}"}

See also:

seealso

JSON Processing