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.

style="font-weight: bold 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:

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

See also: