Decoding JSON Data Using the BizTalk Server 2013 R2 JSONDecode Pipeline Component

By Nick Hauenstein

This is the fourth in a series of posts exploring What’s New in BizTalk Server 2013 R2. It is also the second in a series of three posts covering the enhancements to BizTalk Server’s support for RESTful services in the 2003 R2 release.

In my last post, I wrote about the support for JSON Schemas in BizTalk Server 2013 R2. I started out with a small project that included a schema generated from the Yahoo Finance API and a unit test to verify the schema model. I was going to put together a follow-up article last week, but spent the week traveling, in the hospital, and then recovering from being sick.

However, I am back and ready to tear apart the next installment that already hit the github repo a few days back.

Pipeline Support for JSON Documents

In BizTalk Server 2013 R2, Microsoft approached the problem of dealing with JSON content in a way fairly similar to the approach that we used in the previous version with custom components – performing the JSON conversion as an operation in the Decode stage of the pipeline, thus requiring the Disassemble stage to include an XMLDisassemble component for property promotion.

The official component Microsoft.BizTalk.Component.JsonDecoder takes in two properties Root Node and Root Node Namespace that help determine how the XML message will be created.

Finally, there isn’t a JSONReceive pipeline included in BizTalk Server 2013 R2 – only the pipeline component was included. In other words, in order to work with JSON, you will need a custom pipeline.


Creating a Pipeline for Receiving JSON Messages

Ultimately, I would like to create a pipeline that is going to be reusable so that I don’t have to create a new pipeline for each and every message that will be received. Since BizTalk message types are all about the target namespace and root node name, it’s not reasonable to set that value to be the same for every message – despite having different message bodies and content. As a result, it might be best to leave the value blank and only set it at design time.

This is also an interesting constraint, because if we are receiving this message not necessarily just as a service response, we might end up needing to create a fairly flexible schema (i.e., with a lot more choice groups) depending on the variety of inputs / responses that may be received – something that will not be explored within this blog post, but would be an excellent discussion to bring up during one of QuickLearn’s BizTalk Server Developer Deep Dive classes.

In order to make the pipeline behave in a way that will be consistent with typical BizTalk Server message processing, I decided to essentially take what we have in the XMLReceive pipeline and simply add a JsonDecoder in the Decode stage, with none of its properties set at design time.


Testing the JSONReceive Pipeline

In the same vein as my last post, I will be creating automated tests for the pipeline to verify its functionality. However, we cannot use the built-in support for testing pipelines in this case – because properties of the pipeline were left blank, and the TestablePipelineBase class does not support per instance configuration. Luckily, the Winterdom PipelineTesting library does support per instance configuration – and it has a nifty NuGet package as of June.

Unfortunately, the per-instance configuration is not really pretty. It requires an XML configuration file that resembles the guts of a bindings file in the section dedicated to the same purpose. In other words, it’s not as easy as setting properties on the class instance in code in any way. To get around that to some degree, and to be able to reuse the configuration file with different property values, I put together a template with tokens in place of the actual property values.


NOTE: If you’re copying this approach for some other pipeline components, the vt attribute is actually very important in ensuring your properties will be read correctly. See KB884981 for details.

From there, the per-instance configuration is a matter of XML manipulation and use of the ReceivePipelineWrapper class’ ApplyInstanceConfig method:

[sourcecode language=”csharp”]
private void configureJSONReceivePipeline(ReceivePipelineWrapper pipeline, string rootNode, string namespaceUri)
string configPath = Path.Combine(TestContext.DeploymentDirectory, "pipelineconfig.xml");

var configDoc = XDocument.Load(configPath);




The final test code includes a validation of the output against the schema from last week’s post. As a result, we’re really dealing with an integration test here rather than a unit test, but it’s a test nonetheless.

[sourcecode language=”csharp”]
public void JSONReceive_JSONMessage_CorrectValidXMLReturned()

string rootNode = "ServiceResponse";
string namespaceUri = "";

string sourceDoc = Path.Combine(TestContext.DeploymentDirectory, "sample.json");
string schemaPath = Path.Combine(TestContext.DeploymentDirectory, "ServiceResponse.xsd");
string outputDoc = Path.Combine(TestContext.DeploymentDirectory, "JSONReceive.out");

var pipeline = PipelineFactory.CreateReceivePipeline(typeof(JSONReceive));

configureJSONReceivePipeline(pipeline, rootNode, namespaceUri);

using (var inputStream = File.OpenRead(sourceDoc))
var result = pipeline.Execute(MessageHelper.CreateFromStream(inputStream));

Assert.IsTrue(result.Count > 0, "No messages returned from pipeline.");

using (var outputFile = File.OpenWrite(outputDoc))


ServiceResponse schema = new ServiceResponse();
Assert.IsTrue(schema.ValidateInstance(outputDoc, Microsoft.BizTalk.TestTools.Schema.OutputInstanceType.XML),
"Output message failed validation against the schema");

Assert.AreEqual(XDocument.Load(outputDoc).Descendants("Bid").First().Value, "44.97", "Incorrect Bid amount in output file");


After giving it a run, it looks like we have a winner.


Coming Up in the Next Installment

In the next installment of this series, I will actually put to use what we have here, and build out a more complete integration that allows us to experience sending JSON messages as well, using the new JsonEncoder component.

Take care until then!

If you would like to access sample code for this blog post, you can find it on github.

5 thoughts on Decoding JSON Data Using the BizTalk Server 2013 R2 JSONDecode Pipeline Component

  1. Pingback: What’s New In BizTalk Server 2013 R2 | QuickLearn Training Blog

  2. I have been reading articles and doing some R&D work for an integration solution using ESB 2.3 (BizTalk 2013 R2). We would also like to be able to provide a RESTful service using JSON. Are you aware of anyone doing anything similar so we can share experiences?

    • Not at the moment, but I did just now see your comment and approved it, so maybe the larger BizTalk world as a whole might chime in at this point.

  3. THanks for the series of articles, Nick. They’ve been very helpful. I do have a question, which you mentioned in part 2/5 on your REST support series and said would be addressed later, but I can’t find the follow up.

    I need to have a REST Receive Location that does both a GET and a POST for a Sales Order. On the GET, the URL will contain QueryString parameters for the Order number and potentially another parameter, and no request body. On the POST, we’ll provide a JSON request body.

    On the other side, I have a 3rd party ERP SOAP service, which I consume to either READ or WRITE a Sales Order, using a SEND port with WCF-BasicHttp. The READ service always does a “search” and returns a collection with 0, 1, or many Sales Orders.

    For now, I am just trying to do a pure messaging solution, mapping inbound and outbound at the receive port. Not sure whether it would be easier to do this via orchestration, but eventually this will need an orchestration, since we will need to coordinate calling other services for sending emails, etc., when an Order is submitted.

    I’ve created a JSON-to-XML Receive Pipeline, and an XML-to-JSON Send Pipeline and have been able to successfully POST json and submit a Sales Order and get the response from SOAP, map it to the JSON schema, and use the send pipeline to return a JSON response back to the client.

    What I can’t seem to get is the GET piece, no pun intended. Because my Receive Location and Port leverage my custom JSON-to-XML pipeline, the client can’t simply call the GET endpoint without a response body. Also, how do I support and parse out the different URL query string params and construct the correct request xml with those params?

    Any help is appreciated. If the reply is too long, you can always turn it into another blog post 😉


Leave a Reply

Your email address will not be published. Required fields are marked *