Working with JSON in BizTalk Server 2013 R2

One of the few new features in BizTalk Server 2013 R2 is the introduction of a set of JSON Pipeline Components (encoding/decoding) together with a JSON Schema Wizard for both consuming and sending messages in the JSON format.
JSON is mostly considered a format paired together with the Rest “Adapter” introduced in BizTalk Server 2013 (WCF-WebHttp); however, the Pipeline Components will work with any Adapters that are able to consume and submit JSON, and this blog will look into the very basic of the Components and the Wizard, focusing only on JSON and BizTalk and not REST.

JSON (JavaScript Object Notation) is the new black when talking REST to front end developers. This has increased the demand for a broker like the BizTalk Server to have the ability to both consume and send JSON messages.
With the release of 2013 R2, Microsoft has answered this demand, by introducing a JSON decode Pipeline Component (JSON -> XML) together with a JSON encoder Pipeline Component (XML -> JSON).

When creating a new Pipeline (receive or send), the two new components will appear as follows:


Disassembler vs. non disassembler

When taking a first glance at these Components one might wonder:

Shouldn’t a JSON to XML (and vice versa) component have been an Assembler/Disassembler component just like Flat File and EDI?

I don’t think there is a 100% straight answer to that question, but my personal opinion is that MS did the right thing by considering JSON to XML and XML to JSON a decoding and encoding scenario. The JSON structure is very similar to XML and you can convert both ways without any additional meta data information (for JSON to XML, information about a root element name and namespace might be required).

 Building standard reusable JSON Pipelines

The first thing I did after installing my BizTalk Server 2013 R2 was to look at the typical JSON scenarios one can encounter from a Pipeline perspective. I considered that the 3 main JSON Pipelines needed would be:

  1. A Receive Pipeline with a JSON decoder, XML Disassembler and a Party Resolution Component (JSONXMLReceive)
  2. A Receive Pipeline with only a JSON decoder (JSONPassThruReceive)
  3. A Send Pipeline with only a JSON encoder (JSONPassThruTransmit)

JSONPassThruReceive is mainly for testing purposes.

The JSONXMLReceive Pipeline is shown here:


For the JSONPassThruTransmit Pipeline I have placed the JSON encoder Component in the Encode stage, and the JSONPassThruReceive Pipeline just have a JSON decoder Component in the Decode stage.

I have then deployed these three Pipelines in a common BizTalk Application for reusabiliy.

Receiving JSON

Again the blog post will not focus on REST, so in this example, I will simply use the File Adapter for both receiving and sending.

For simplicity let us assume that we receive Loan Requests in the following JSON format:

{“CustomerID”:”106″, “LoanAmount”:”50000″},
{“CustomerID”:”114″, “LoanAmount”:”10000″},
{“CustomerID”:”226″, “LoanAmount”:”75000″, “Comment”:”I need the money now!”},

Here is what we will need to do to have this JSON converted to XML and send through BizTalk:

  1. Create a BizTalk Application and make a reference to the common Application holding the 3 new JSON Pipelines.
  2. Create a new Receive Port and Receive Location (using the File Adapter and the JSONPassThruReceive Pipeline).
  3. Configure the Adapter to pick up files from a local folder, where your test JSON text file resides.
  4. Configure the JSON Pipeline with a RootNode and a RootNodeNamespace (this is required since it is not needed in JSON messages, but needed in XML).


  1. Configure a File Send Port for receiving all messages from our Receive Port (Filter: BTS.ReceivePort == [ReceivePortName]) and start your Application.
  2. Submit the JSON message, and examine the output. The output should resemble the following screen shot):


 Note: The XML output from the JSON decoder has elementFormDefault set to unqualified, and there are no options for changing this.

As you can see, no Schemas were needed! We will look at the JSON Schema Wizard later, but it is important to understand, that for the JSON decoder component to work, nothing else than a supplied root name and namespace is required.

 Sending JSON

Like when receiving, we will do this task without the use of any Schemas. For this demo I am using the following XML:

<Order xmlns=”″&gt; <– (Replace with >)
<Orderline no=”1″>
<Desc>Please send this item ASAP!</Desc>
<Orderline no=”2″>
<Orderline no=”3″>

  1.  Create a Receive Port and a Receive Location, using the File Adapter and the PassThruReceive Pipeline.
  2. Create a Send Port that receives all messages from the Receive Port, using the File Adapter and the JSONPassThruTransmit Pipeline.

The JSON encoder Pipeline Component has one property: RemoveOuterEnvelope, which is set to False as default. We will leave it for now and later test what impact changing it will have.

  1. Enable the Receive Location and start the Send Port.
  2. Submit the XML sample though the newly created Receive Location, and examine the output.

The output should resemble something like this:

JSON_output_remove_falseNote: the root element (Order) is kept in the JSON message. This is because we left RemoveOuterEnvelope as False.

Try changing it to True and run the test again. Your output should now be identical, only with the Order root missing.

Again notice that all this can be done without the use of Schemas.

Using the JSON Schema Wizard

When adding a new item in a BizTalk Project in BizTalk Server 2013 R2, you will notice that a new item type has appeared:


This Wizard is used for creating an XML Schema based on JSON input.

Let us try with the Loan Requests JSON we used for the receiving demo earlier:

  1. Give your new Schema an appropriate name, and click Add.
  2. Click Next>
  3. Point to the sample JSON file and supply the same Root node name and Target namespace as we did on the JSON Receive Pipeline earlier.


  1. Click Finish.

Your project should now include the newly created Schema, and the Schema should resemble the XML we generated when testing receiving JSON earlier.

Schema_GeneratedYou can also try to validate the Schema against an XML output file from the receive demo.

The types created by the Wizard will not always be correct, and might need manual correction.

The Wizard can be used both for creating a Schema when we receive JSON, but also for creating the correct Schema for representing the XML we need to send to the JSON encoder, when we need to send a specific JSON format to a target system.


The JSON encoder and decoder Pipeline Components don’t use any Schemas for converting to/from JSON. They are easy to get up an running without any Disassemblers or Schemas..

The JSON Pipelines created can be reused, and should be placed in a common BizTalk Application.

Since there are no Schema awareness on the decoding and encoding Components, no date conversion can take place. Many JSON receivers will not expect the XML date format “2014-01-01” but rather a JSON specific format like this:


This will then need to be formatted in the XML before the JSON encoder, which I think is a bad design (a Map should NEVER be aware of JSON, Flat file etc.).

Having said that, more and more JSON consumers are changing to the XML way of formatting dates and datetimes.


Kategorier: Biztalk, Integration

Tagged as: ,


  1. Nice Article Morten.
    I am trying to send some JSON data to another system where object name is to be removed.
    Example shown below

    “orderId”: “ID_0”,
    “orderName”: “Name_0”
    “orderId”: “ID_1”,
    “orderName”: “Name_1”

    Another requirement is that the data should be in single line.
    Can you think of some other approach other than creating a custom pipeline for this.

    Thanks in Advance

  2. Much of this is dependent upon the kind of foods on your table, once you are eating them and also the amount and type of exercise you happen to be doing.
    Everyone fantasizes that shedding pounds will transform his / her entire life.
    Obesity may be the upshot of busy style of living and bad food habits.

  3. It preserves essential oils of the scalp, so your
    hair stay perfectly moisturized for long. It’s all about body
    with my lightweight formula that has a fusion of passion flower sunrise and pearl.
    Washing your hair daily, strips it of all the necessary oils to keep
    it healthy.

  4. Se trata de un modelo confeccionado íntegramente en lana acrílica, que proporciona mayor comodidad y abrigo durante el uso.

  5. We stumbled over here from a different website and thought I might as well check
    things out. I like what I see so now i am following you. Look forward
    to looking over your web page again.

  6. Hello there, I do believe your website could possibly be having browser
    compatibility issues. Whenever I look at your blog in Safari, it looks fine however, if opening in IE, it’s got some overlapping issues.

    I simply wanted to provide you with a quick heads up! Apart
    from that, fantastic blog!

  7. Woah! I’m really enjoying the template/theme of this website.
    It’s simple, yet effective. A lot of times it’s difficult to get that “perfect balance” between user friendliness and visual
    appearance. I must say that you’ve done a awesome job with this.
    Additionally, the blog loads extremely quick for
    me on Firefox. Superb Blog!

  8. I am not sure where you’re getting your information, but good topic.

    I needs to spend some time learning more or understanding more.
    Thanks for magnificent info I was looking for this info for my mission.

Skriv et svar

Udfyld dine oplysninger nedenfor eller klik på et ikon for at logge ind: Logo

Du kommenterer med din konto. Log Out /  Skift )

Google photo

Du kommenterer med din Google konto. Log Out /  Skift )

Twitter picture

Du kommenterer med din Twitter konto. Log Out /  Skift )

Facebook photo

Du kommenterer med din Facebook konto. Log Out /  Skift )

Connecting to %s