Integration Server 10.11 | Built-In Services Reference Guide | JSON Folder | Summary of Elements in This Folder | pub.json:documentToJSONString
 
pub.json:documentToJSONString
WmPublic. Converts a document (IData object) to a JSON string.
Input Parameters
document
Document. The document (IData object) to be converted to a JSON string.
encodeDateAs
String. Optional. Specifies how java.util.Date instances in the document are encoded in the returned JSON. Set to one of the following:
*long to encode java.utilData instances as timestamps, specifically the number of milliseconds since Jan 1, 1970 00:00:00. The dates are encoded as JSON numbers.
*ISO8601 to encode java.utilData instances as strings in a standard ISO format of: YYYY-MM-DD'T'HH:mm:ss.sssZ. The dates are encoded JSON Strings.
*Custom format in which dates are encoded as strings in the supplied pattern. The pattern must adhere to the date and time patterns as described in the java.text.SimpleDateFormat class in the Oracle Java API documentation. The dates are encoded as JSON strings.
*null to use the dateEncoding setting already in effect for the HTTP client making the request, as follows:
*If the HTTP client request includes jsonDateEncoding=long in the URL, then java.utilData instances as timestamps, specifically the number of milliseconds since Jan 1, 1970 00:00:00. The dates are JSON numbers.
*If the HTTP client request includes jsonDateEncoding=ISO8601 in the URL, the java.utilData instances are encoded as strings in a standard ISO format of: YYYY-MM-DD'T'HH:mm:ss.sssZ. The dates are JSON Strings.
*If the HTTP client request includes jsonDateEncoding= format in the URL, the java.utilData instances are encoded as strings in the supplied pattern. The pattern must adhere to the date and time patterns as described in the java.text.SimpleDateFormat class in the Oracle Java API documentation.
*If the HTTP client request does not include the jsonDateEncoding query parameter in the URL, the service uses the value of the watt.server.json.encodeDateAs parameter. For more information about watt.server.json.encodeDataAs, see webMethods Integration Server Administrator’s Guide
jsonDocumentTypeName
String. Optional. If specified, the transformation from Document (IData) to JSON string is based on the JSON document type. Any deviations from the provided JSON document might cause transformation errors.
When this parameter is provided, Integration Server ignores the encodeDateAs parameter and the watt.server.json.encodeDateAs server configuration parameter.
This parameter must have the fully qualified name of a JSON document type on Integration Server against which the JSON content is validated. This parameter must be in the format: <Folder Name>:<JSON Document Type Name>
For example: data:employeeData
prettyPrint
String. Optional. Formats the jsonString output parameter for human readability by adding carriage returns and indentation to the JSON content. Set to:
*true to format jsonString output variable for human readability.
*false to leave the jsonString output variable in its unformatted state. The service will not add any additional carriage returns or indentation to the JSON content.
*null to use the prettyPrint setting already in effect for the HTTP client making the request, as follows:
*If the HTTP client request includes jsonPrettyPrint=true in the URI, JSON pretty printing is in effect.
*If the HTTP client request includes jsonPrettyPrint=false in the URI, JSON pretty printing is not in effect.
*If the HTTP client request does not include the jsonPrettyPrint parameter, the service uses the value of the watt.server.json.prettyPrint configuration parameter. For more information about watt.server.json.prettyPrint, see webMethods Integration Server Administrator’s Guide.
strict
String. Optional. Valid values are true and false. The default value is false.
The values of strict and jsonDocumentTypeName parameters together determine how Integration Server parses and converts Document (IData) to JSON string in the following manner:
*When strict is false and jsonDocumentTypeName is not specified, there is no change in the behavior.
*When strict is false and jsonDocumentTypeName is specified, the transformation from Document (IData) to JSON string is loosely based on the JSON document type. For conversion rules, see Table 2: Conversion of IData to JSON String.
*When strict is true and jsonDocumentTypeName is not specified, the service returns an exception.
*When strict is true and jsonDocumentTypeName is specified, the transformation from Document (IData) to JSON string is strictly based on the JSON document type. The validation is performed first before the transformation, and any deviations lead to transformation errors. The encodeDateAs parameter and the watt.server.json.encodeDateAs server configuration parameter, if specified, are ignored.
Output Parameters
jsonString
String. JSON string resulting from the conversion of document.
Usage Notes
To turn a document in a pipeline into a JSON response to send over HTTP, the application's service can:
1. Use pub.json:documentToJSONString to turn a document (IData object) in the pipeline into a string of JSON content.
2. Call pub.client:http to send the JSON string as an HTTP request.
3. Set the Content-Type header field to application/json.
When creating a JSON text with pub.json:documentToJSONString, if the document input parameter contains a $rootArray key with an array as its value, Integration Server discards the $rootArray name and transforms the array value into a JSON array. The resulting JSON text will contain only an unnamed array. $rootArray and key/value pairs cannot both appear in the input document. $rootArray indicates that the generated JSON text should consist only of an unnamed array. Combining this with additional key/value pairs leads to unpredictable results.
The JSON standard requires that field names be enclosed in double quotes. However, you may need the service to produce unquoted field names if the generated JSON text will be processed by an older JavaScript interpreter. The watt.server.json.quoteFieldNames server configuration parameter determines whether the pub.json:documentToJSONString service encloses all generated JSON field names in double quotes. Set this parameter to true instruct the pub.json:documentToJSONString service to enclose field names in quotes in the output JSON text. Set this parameter to false to instruct the service to omit the double quotes around field names in the generated JSON text. The default is true.
Note:
Use caution when setting watt.server.json.quoteFieldNames to false as this causes the pub.json:documentToJSONString service to generate non-standard JSON text. This can cause interoperability issues if the JSON text is sent to other organizations.
When strict=true, the validation of a JSON document against the JSON document type happens before transformation, and the validation exception, if any, contains the first error message, which is the result of the pub.json.schema:validate service execution. The validation errors from the pub.json.schema:validate service, if any, can be one or more in the service output. However, only the first error message is displayed in the pub.json:documentToJSONString service exception.
When you validate a JSON document against the JSON document type, the format property in the JSON document type is ignored during transformation. Therefore, the value passed is retained in the same format even after the successful transformation.