Experimenting with BizTalk's XML to JSON conversion

Latest version of BizTalk Server comes with features for communicating with JSON based systems. Simply add pipelines for decoding and encoding you JSON messages, but pay attention when defining your schemas. I will show you why.

Let’s imagine…

…that you have a source data containing information about sticks and and bricks in XML format and you need to send to the “Stick and Brick Management” system in JSON format:

Simply two lists of objects, no magic here. To convert this XML to corresponding JSON in BizTalk, you need schema defining the message structure and pipeline for encoding the message. Here is the schema I use in this example:

Note that I have only defined the min and max occurs setting for one of the arrays. As BizTalk normally isn’t too picky about validating messages, it is rather common to see schemas without any definitions for those values. The pipeline I use is just a generic pipeline where I have added JSON encoding component. No settings at all.

Setup and test

To test my schema and pipeline against my example data, I created one receive port with standard XML-pipeline and one send port with my JSON-pipeline using file adapter. Send port is subscribing all messages coming through the receive port and therefore I have a setup that should pick XML-files from one folder and write corresponding JSON-files to another. Exited to see what happens? I won’t keep you waiting any longer:

Looks pretty much what I expected. In XML-world I probably would have added one layer between the the array (Sticks, Bricks) to envelope one child record (Stick, Brick), but when converted to JSON it doen’t look so bad. Seems like BizTalk once again doesn’t really care if the max occurs is not defined in for Sticks (defaults to 1) and the source has more than one record. Sticks are handled just the same as the Bricks.

So where’s the catch?

If everyting works as expected, why bother writing about it at all? Well, it gets interesting when we change the source data a bit. Nothing else changes, just the source data:

Now the source data follows the schema definition as there is only one Sticks record. And here is the result:

Do you see the difference? Sticks is no longer array in the JSON. The structure of the produced JSON depends on the amount of the records in the source data. What if the receiving system expects to always get array of sticks? Smells like problems.

So what can we do to fix this? You simply have to tell BizTalk that you always have array of sticks. And this is done by adding the same min and max occurs definitions also to the Sticks in the schema. Running the second example data again through Biztalk after this change produces following result:

And now Sticks is array again, even though there is only one record!

Lesson learned

Event though BizTalk’s behaviour is normally not affected by mistakes in the min and max occurs definitions in the schemas when using XML, they play important role when you use the default XML to JSON conversion functionality in Biztalk Server 2013. Obviously it is good practice to make sure that your data matches the schemas, but in this case it is vital.