Integration Server 10.15 | Built-In Services Reference Guide | JSON Folder | Summary of Elements in This Folder | pub.json:jsonToDocument
 
pub.json:jsonToDocument
WmPublic. Converts a JSON string or the content from a JSON content stream to a document (an IData object). The service gives an option to select the data type to which you want to convert an integer, a decimal, or a boolean value in the JSON data.
Input Parameters
jsonData
Object. JSON content in a string or an input stream to convert to a document (IData object).
documentTypeName
String. Optional. If specified, the transformation from the JSON data to Document (IData) is based on the document type. Any deviations from the provided document result in errors. documentTypeName accepts all kinds of document types.
When this parameter is provided, Integration Server ignores the following parameters:
*decodeIntegerAs
*decodeDecimalAs
*decodeBooleanAs
This parameter must have the fully qualified name of the document type against which the JSON content is validated.
For example: data:employeeData
decodeIntegerAs
String. Optional. Converts all the integer values in jsonData to either String, Integer, Long, or BigInteger Java wrapper type. Depending on the data type to which you want to convert the integer values in jsonData, set to:
*String to convert all the integer values to String. This is the default.
*Integer to convert all the integer values to Integer.
*Long to convert all the integer values to Long.
*BigInteger to convert all the integer values to BigInteger.
*Auto to check the Java wrapper type range in which the input value fits and convert the value to the appropriate wrapper type.
If there is no user selection and documentTypeName is not specified, then by default, converts the value to String.
Note:
If you select the datatype as Integer and the JSON data contains a value outside the range of Integer, the service fails with an error.
decodeDecimalAs
String. Optional.
Converts all the decimal values in jsonData to either String, Float, Double, or BigDecimal Java wrapper type.
Depending on the data type to which you want to convert the decimal values in jsonData, set to:
*String to convert all the decimal values to String. This is the default.
*Float to convert all the decimal values to Float.
*Double to convert all the decimal values to Double.
*BigDecimalto convert all the decimal values to BigDecimal.
*Auto to check the Java wrapper type range in which the input value fits and convert the value to the appropriate wrapper type.
If there is no user selection and documentTypeName is not specified, then by default, converts the value to String.
Note:
If you select the datatype as Float and the JSON data contains a value outside the range of Float, the service fails with an error.
decodeBooleanAs
String Optional.
Converts all the boolean values in jsonData to String or Boolean.
Depending on the value of the variable in jsonData, set to:
*String to convert all the boolean values to String. This is the default.
*Boolean to convert all the boolean values to Boolean.
If there is no user selection and documentTypeName is not specified, then by default converts the value to String.
decodeNullRootAsEmpty
String. Optional. Converts a null value at the root that Integration Server retrieves from JSON content to IData. Depending on the data type to which you want to convert the null values in jsonData, set to:
*true to convert the null value in the JSON data to an empty IData.
*false to convert the null value in the JSON data to an IData with $rootValue. This is the default.
unescapeSpecialChars
String. Optional. Controls whether Integration Server unescapes the special characters '\n', '\r', '\t', '\b', '\f', '\\', '\"' while parsing JSON documents. Set to:
*true to unescape these special characters (for example, '\n' is replaced with new line; similarly, other characters are also replaced) in the output document. This is the default.
*false to keep these characters as is in the output document.
The behavior applies to both values and keys.
Note:
The unescapeSpecialChars parameter overrides the value specified by the watt.server.json.decode.unescapeSpecialChars server configuration parameter. If no value is supplied for unescapeSpecialChars, Integration Server uses the value specified in the watt.server.json.decode.unescapeSpecialChars parameter. For more information about watt.server.json.decode.unescapeSpecialChars, see webMethods Integration Server Administrator’s Guide.
Output Parameters
document
Document. Document (IData object) resulting from the conversion of jsonData.
Usage Notes
Software AG recommends that you use the pub.json:jsonToDocument service to convert JSON to a document (IData) instead of the pub.json:jsonStringToDocument or pub.json:jsonStreamToDocument services. The pub.json:jsonToDocument service simplifies conversion in favor of strings (by default) or as directed by a document type.
This service ignores the following server configuration parameters set for the JSON data:
*watt.server.json.decodeRealAsDouble
*watt.server.json.decodeRealAsString
*watt.server.json.decodeIntegerAsLong
Consider the following points while using this service:
*If the input includes characters from other languages, set the encoding parameter appropriately before adding it as the JSON data. For example, use pub.string:bytesToString to decode the byte to the correct string format. Then, add the decoded data in the JSON data.
*The transformation from the JSON data to Document (IData) is strictly based on the document type. Hence, deviations result in an error. For example, if documentTypeName has a string variable and the JSON data contains an integer value, the service throws an exception.
*If the JSON data contains an exponential value and documentTypeName is not specified, the service considers the value as a decimal value.
If the JSON data contains an exponential value and documentTypeName is specified, the service maps the value to either Integer, Long, BigInteger, Float, Double, or BigDecimal Java wrapper type based on the user selection.
*If you pass JSON data with an array at the root and documentTypeName is specified, the service throws an exception.
*If you assign a bigger number with more than 10 digits to a BigDecimal value in the document, the service automatically converts the number to the exponential form.
*Following are the supported date format examples:
*2010-10-10T10:00:00
*2002-10-09T04:00:00Z
*2018-01-01T00:00:00.000000Z
*PT13H20M0S
*2021-02-16T01:47:44.000-05:00
*2020-07-01T00:00:00-06:00
*2014-08-14T05:41:49.1686804+00:00
*If documentTypeName is specified, and it has multiple variables with same name, the service selects the first suitable match in the document. If there are no matches, the service ignores the duplicate variables. See the following table for examples:
Input
DocumentTypeName
Output
{"age" : “12345”}
*age: Integer
*age: Long
*age: BigInteger
Empty document (As there are no matches, the service ignores the input variable and generates an empty document.)
{"updatedDate" : “22/01/01” }
*updatedDate: String
*updatedDate: Date
String (Selects the first suitable match.)
{"number": [12 , 22 ,23 ]}
*number: Integer array
*number: String array
*number: Object array
Integer array
*If the JSON data contains duplicate variables and documentTypeName is specified, the service throws an exception.
*If the document type contains the following variables, the service ignores the values for such variables:
*byte []
*com.wm.util.XOPObject
*java.lang.Byte
*If the JSON data contains a multi-dimensional array with a data type other than String, then the service converts the input into an object array. You can create a Java service to decode the object array.
If the JSON data contains a multi-dimensional array with the data type as String, the service converts the input into String table.
*For a document variable, if you set the "Allow unspecified fields" property to true, the service considers the unspecified keys in the JSON data and transforms the input value based on decodeIntegerAs, decodeDecimalAs, or decodeBooleanAs. If set to false, the service ignores the unspecified key in the JSON data.
*Following are the minimum and maximum values for different data types:
*Short: -32768 to 32767
*Integer: -2147483648 to 2147483647
*Long: -9223372036854775808 to 9223372036854775807
*Float: -3.402823466 E + 38 to 3.402823466 E + 38
*Double: -1.7976931348623158 E + 308 to 1.7976931348623158 E + 308