How to handle JSON inside Diaplan in WMS

Starting from WMS Beta 5.04, res_json is integrated into the system. It is a wrapper module around a JSON library that allows you to handle JSON documents inside Wildix Dialplan and send requests to external software (e.g. CRM systems).

List of supported apps and functions

Parameters:

• doc: the name of the variable that contains the JSON document

• path: path to the element you are looking for (like /path/to/element, or /path/to/element/3 to identify the element with index 3 in an array)

• elemtype: element type, one of bool, null, number, string, node or array

• name: the name of the element to be added (may be missing if adding elements to an array)

• value: value to be set for the element we added

• newvalue: value to be set

JSONRESULT values

If any of the functions or apps fails, a call would not be terminated. In case an app/ function would need to return an abnormal result, they would do so by setting the value of a Dialplan variable called JSONRESULT. The values are:  

• ASTJSON_OK (0) - the operation was successful

• ASTJSON_UNDECIDED (1) - the operation was aborted mid-way and the results are not guaranteed

• ASTJSON_ARG_NEEDED (2) - missing or invalid argument type

• ASTJSON_PARSE_ERROR (3) - the string that was supposed to be a JSON document could not be parsed

• ASTJSON_NOTFOUND (4) - the expected element could not be found at the given path

• ASTJSON_INVALID_TYPE (5) - invalid element type for a jsonadd or jsonset operation

• ASTJSON_ADD_FAILED (6) - the jsonadd operation failed

• ASTJSON_SET_FAILED (7) - the jsonset operation failed

• ASTJSON_DELETE_FAILED (8) - the jsondelete operation failed

Detailed information about apps and functions  

JSONELEMENT(doc,path) 

Returns the value of an element at the given path.

The element type is set in the Dialplan variable JSONTYPE. Depending on the type of the JSON variable, the values are:

• True, False => returned values are 1 or 0 respectively; JSONTYPE is bool

• NULL => returned value is an empty string; JSONTYPE is null

• Number => returned value is a number; JSONTYPE is number

• String => returned value is a number; JSONTYPE is string

• Array => returned value is a JSON representation of an array; JSONTYPE is array

• Object => returned value is a JSON representation of the underlying object; JSONTYPE is node.

jsonvariables(doc)

Reads a single level JSON document into Dialplan variables with the same names. The JSON document is considered to be the representation of a dictionary, or key-value pairs, containing scalar values. For example, {"one":1,"two":"deuce","three":"III"} will set the values of the Dialplan variables one, two and three to the values 1, deuce, and III respectively. Depending on the type of each variable, their possible values are:

• True, False => 1, 0

• NULL => the resulting variable will contain an empty string

• number, string => the number or the string

• array => the string !array! (array values cannot be returned into a single variable)

• object => string, the JSON representation of the underlying object parameters

jsonadd(doc,path,elemtype,[name][,value])

Adds an element to the JSON document at the given path. The value of the variable that contains the JSON document is updated to reflect the change. The element to be added has a type (elemtype), a name, and a value. 

• elemtype can be one of bool, null, number, string, node or array.
  A bool "false" value is represented as either an empty string, 0, n, no, f or false (case insensitive); any other value for a bool elemtype is interpreted as true. For a null elemtype, the value paramenter is ignored. 

• The value parameter is also ignored for an array elemtype: in this case, an empty array is created. Further on, you may append elements to this array using repeated calls to the jsonadd app, for example:
  exten => s,n,jsonadd(json,path/there,array,vec)
  exten => s,n,jsonadd(json,path/there/vec,string,,abcd)
  exten => s,n,jsonadd(json,path/there/vec,number,,1234)
  exten => s,n,noop(${JSONELEMENT(json,path/there/vec/0)} & ${JSONELEMENT(json,path/there/vec/1)})
  The last line will display abcd & 1234 to the console.