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

JSON
A string that is interpreted as a JSON document
JSONPath
The JSONPath that identifies the element that need updating
Value
The value that should be assigned to the JSON element
Cast (optional)
This parameter controls the conversion from Automic Script to JSON datatypes.
- 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.
  
  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)

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
45336
No value provided
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

Limitations

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.

Important!

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.

Examples:

This example uses the script function 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#,'$.disks',&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":false,"inventoryNumber":null}

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:

: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\"}"}