REST Adapter in PI/PO: Enhanced XML/JSON Conversion
Update on 28.01.2016
Recently SCN document PI REST Adapter – JSON to XML conversion (a part of series describing SAP REST adapter functionality and technical capabilities) has been updated and now contains information on enhanced XML/JSON conversion and a demo example on this topic.
SAP Help documentation (currently only found in help materials for release SAP NetWeaver 7.31) now contains description of enhanced XML/JSON conversion – refer to Converting XML/JSON – Advanced Adapter Engine – SAP Library.
Both references have been added to a section “Links” of this blog.
One of features of SAP standard REST adapter, is XML/JSON conversion – that surely makes sense, considering that internal processing in SAP PI/PO is done in XML format on one hand, and JSON format is de-facto format when dealing with REST architectural style on the other hand. Looking into recent SCN forum threads and questions raised about a REST adapter, it can be concluded that generation of JSON output for a processed XML message payload is not always clear and may be misleading. SAP actively enhances functionality of a REST adapter – customization and feature-enrichment of JSON processing being one of actively contributed areas. Many of such features have been documented in SAP Help materials, but one of quite powerful and flexible functionalities – namely, enhanced XML/JSON conversion – was only briefly mentioned in a SAP Note 2175218. In this blog, I would like to demonstrate usage of this functionality and provide details about valid parameterization.
Internally, a REST adapter makes use of 3rd party Jettison library for JSON processing tasks. In standard configuration, REST adapter relies on default conversion logic implemented in Jettison processor, which does not correlate or take into consideration payload elements properties as defined in a corresponding message type, but has its own optimization and type derivation mechanisms that are based on nature of the value of a processed XML document’s element rather than XSD schema of a processed message. As a result, this conversion may sometimes result in unobvious output – here are just few examples which are commonly faced:
- If an XML element was defined as an array, but only contains one item in converted XML payload, Jettison processor will likely convert it to a non-array type;
- If an XML element was defined as a String, but only contains numeric value in converted XML payload, Jettison processor will likely convert it to an integer type.
In some use cases, this kind of improper type conversion may be unacceptable – and this is where enhanced XML/JSON conversion parameterization helps solving a faced problem.
An idea behind enhanced XML/JSON conversion functionality introduced with the SAP Note 2175218, is explicit instruction of JSON processor on how to treat particular XML elements. Let us examine this functionality based on a practical example.
Below is definition of a message type used for a response message in a synchronous scenario, where we make use of a REST sender communication channel. As seen, it contains elements of various types, including an array:
A sample response message in XML format looks like:
Using standard configuration of a REST sender channel, JSON formatted response message produced from an XML formatted message given above, is:
It can be noticed that some elements’ types were interpreted incorrectly – for example:
- Element “ID” wasn’t recognized as a String, but as a number – Jettison processor treated it as a number, because element value contains only numeric characters;
- Element “Properties” wasn’t recognized as an array – Jettison processor treated it as a non-array object with a nested structure, because an element contains only one child entry of an element “Property” (no other sibling elements “Property”).
Let’s fix this using enhanced XML/JSON conversion. In a REST sender channel, parameterization for enhanced XML/JSON conversion is done in a table “Custom XML/JSON Conversion Rules”. Below is configuration which aims troubleshooting type and conversion mismatches highlighted earlier:
After executing an interface once again and checking JSON formatted response message, it can be observed that now JSON output is produced correctly:
I didn’t find details regarding parameterization in official materials, so let me summarize acceptable and valid values used in enhanced XML/JSON conversion parameters, and explanatory notes regarding their usage, in a table below:
|XML Namespace||XML namespace of an XML element|
|Prefix||XML namespace prefix of an XML element|
|Name||XML element name|
XML element type.
Following types are currently supported: String, Integer, Decimal, Boolean.
It makes no difference which notation for the type value is chosen as long as it is one of those mentioned in a list of valid values.
If no value is specified, no specific XML/JSON conversion instructions are applied and default logic of Jettison processor is applied.
Indicator if an XML element is an array or not.
It makes no difference which notation for the array type indicator value is chosen as long as it is one of those mentioned in a list of valid values.
If no value is specified, array type indicator is set to “false” by default.
If element is array
If element is not array
Value that will be assigned to a JSON element in case XML/JSON conversion for a corresponding XML element fails.
For example, in a provided demo, value of an element “Quantity” will be processed as an integer. If original value cannot be converted to an integer (for example, it contains not only numeric characters, but its content is alpha-numeric), then JSON output will receive a default value for such an element, which is “0” in this case.
It should be noted that default value is not verified against element type specified in a field “Type” – it is treated as a String. In this way, for example, it is possible to specify default value “Invalid value” for an element “Quantity” in a provided demo. An error will not be issued neither during activation of a communication channel, nor at runtime during execution of a message by REST adapter, even though provided default value mismatches with an element type (integer). Having this in mind, attention should be paid to provided default value and its compliance to an element type in sake of consistency.
Following values are treated specially:
(with quotation marks) – interpreted as String value “null”
(without quotation marks) – interpreted as null
(just quotation marks) – interpreted as empty String value
Please also refer to following materials discussing enhanced XML/JSON conversion in SAP REST adapter:
- SCN article PI REST Adapter – JSON to XML conversion,
- SAP Help documentation: Converting XML/JSON – Advanced Adapter Engine – SAP Library.