BizTalk Server 2013 R2 Consuming JSON Messages

BizTalk Server 2013 introduced a couple of new adapters. One of them was the WCF-WebHttp adapter that offers REST Support. The WCF-WebHttp adapter gives you the ability to send messages to Restful services and receive messages through an exposed endpoint. One of the limitations with the adapter (binding) was the lack of Json support. You had to write your own custom pipeline components to serialize the Json format to XML (you can read about it in this blogpost: BizTalk Server support for restful services). In the new BizTalk Server 2013 R2 there is out-of the box support for sending and receiving JSON messages with the following features:
You do not have to write your own custom components anymore. By creating a custom pipeline and dragging either a JsonEncoder or JsonDecoder you can serialize Json into xml or vice versa. With an instance of a Json message you can use the wizard to create a Json XSD schema.

Scenario

There are many web services present that have a REST interface and talk JSON over the wire. The WCF-WebHttp adapter in BizTalk Server 2013 R2 provides means to communicate with these services. There are various scenario’s you can think of to how to demonstrate the functionality of the WCF- WebHttp. In this blog I will demonstrate how to consume a relatively simple Restful Endpoint that you can choose from the Restful Service endpoints of the US Federal Aviation Administration. In this case I will use the Airport Service as an example. The Airport service provides the airport status and delay information from the Air Traffic Control System Command Center (ATCSCC) for every US Airport. It has one endpoint that only supports the GET operation.
The GET request is the fundamental, widely used operation in the REST world. You can simply visit a URL in a browser (or programmatically) and for instance in the case of the Airport Service type the following URL:

http://services.faa.gov/airport/status/SEA?format=xml

The browser will return a machine understandable structured data like below:

clip_image002

In this blog we will not specify the xml format, but the Json format i.e. format=json. There will be scenarios in the real world that services do not support xml format and only communicate through the REST protocol and json format. Let’s assume the airport service only supports json. The URL would look like:

http://services.faa.gov/airport/status/SEA?format=json


The following more advanced scenario describes how the airport service is consumed through BizTalk Server 2013 R2 that receives a request from a client application:

From a client application a request for the status of an airport will be send as a soap/xml message. BizTalk will map this request to a GET operation to the Restful service endpoint. That’s is the incoming message contains the airport code that is marked as property for its schema (xsd). That property will mapped to outgoing request URL to call the Restful endpoint. The endpoint on its turn will process the request and hopefully will provide the status of a given airport based upon the airport code provided within the request URL. The result will be mapped to response message that will be routed back to the client application, where it will be rendered in a Windows Form.

image


The communication with the internal endpoint in this scenario will be SOAP/XML as explained. The endpoint is hosted in a two way receive port (request/response). The message will subsequently be mapped to a REST call to the service indicating that the expected response format is json. BizTalk will decode the response into XML, so that it is published as an XML message in the MessageBox. The receive port will subscribe on that message so it will be routed back as response to the client that on his turn renders it in the UI (Form). This scenario shows that BizTalk acts as a broker and protocol mediator (SOAP/XML à REST/JSON à SOAP/XML) between internal client and the external airport service.

Building the solution

The solution of the described scenario consists of the following parts that will be discussed in the subsequent paragraphs:

Exposing schema’s as service

The first step in this scenario is creating the internal service endpoint based on the following schemas
 
clip_image006

Request schema containing one element, AirportCode, which is promoted as property. Later I will explain, the reason why the AirportCode is promoted. The other schema is based on the Json response of the Airport Service. By calling the service in the browser (Chrome with Postman application) using the following http://services.faa.gov/airport/status/SEA?format=json you can obtain the Json.

clip_image008

Save this file as json. Subsequently you follow the following steps:
clip_image010
clip_image011
clip_image012
clip_image014

First schema will be request of the service endpoint and the second the response the generated schema based on json. Both schema are with the same BizTalk project. You must compile this BizTalk project as you will need the assembly later.

The following steps will lead to creation of a WCF Service based on the early two created schemas:
Launch the BizTalk Web Services Publishing Wizard and follow the steps described in MSDN page How to Use the BizTalk Web Services Publishing Wizard to Publish Schemas as a Web Service. Basically you launch the wizard, pass the welcome screen. Specify adapter (WCF binding) to communicate with the service, whether or not you want the service expose Meta data, in which application (receive location) you like tie the service to.

clip_image016
clip_image018
clip_image020
clip_image022
clip_image024
clip_image026
clip_image028
clip_image030
clip_image032

Create a custom receive pipeline

BizTalk Server 2013 R2 provides pipeline components that can be used to process JSON messages within a BizTalk Server application, i.e. JSON decoder and JSON encoder. For the custom receive pipeline we will use the JSON decoder pipeline component. To create the custom receive pipeline you can follow the steps below:

In Visual Studio within your Solution Explorer of your project, you right-click and point to Add > New Item > Receive Pipeline. Specify a name for the pipeline name like JsonReceive.btp, and then click Add. Within the Decode stage you can add the new JSON decoder. In the other stages and other pipeline components as shown in the screenshot, and save changes.

clip_image034

In the properties of the JSON decoder you specify the Root Node and Root Node Namespace.

clip_image036

You can do this at design time like above or in run-time.

clip_image037

Next you add the XML Disassembler pipeline component in the Dissemble stage. Save and your custom receive pipeline for serializing JSON to XML is ready.

Creating and configuring the Send Port with the Web-Http adapter

To be able to consume the Airport Service with BizTalk you will need to have a send port configured with the WCF-WebHttp adapter. This can be done by configuring the WCF-WebHttp adapter or binding if you like in case you choose WCF-Custom. The configuration is pretty straight forward. The Airport Service is a public service that requires no authentication for its usage. In the general tab of the WCF-WebHttp Transport properties the address of the service can be specified (URI). Besides the address you specify here the HTTP Method (GET) and perform a URL mapping.

clip_image038

In HTTP Method and URL Mapping section you specify the method (operations) you are going to perform. In the case of the Airport Service this is going to be only the GET. In case you use an orchestration that the Name has to be specified, which is the name of the operation of the logical port. The URL mapping you define what is going to added after the specified URI. To make it more dynamic instead of hard-coding in general or like in this scenario the airport code you make use of variable mapping configuration feature. So what's between the brackets is a variable that can be mapped to promoted property. The HTTP Method and URL Mapping looks in this case like:

<BtsHttpUrlMapping>
<Operation Method="GET" Url=”status/{airportcode}?”/format=json">
</BtsHttpUrlMapping>

Variable mapping is powerful technique to define any custom variable (or place holder) in your URL, in this scenario case {airportcode} and map that variable to any context property with property name and namespace. The Variable mapping is specified by click the Edit… button.

clip_image040

Variable is mapped to the property namespace that defines the AirportCode.
The general tab is important for specifying the address, method and URL mapping. The other tabs are:
Note: In this scenario we only use GET operation of the Airport service. Based on the verb you have to specify in the Suppress Body for Verbs the GET, because a payload is not required for this operation. Since BizTalk sends out messages with a payload this needs to suppress!

clip_image042

For further details on configuration settings for these tabs see MSDN article How to Configure a WCF-WebHttp Send Port.

Test the solution.

Last part is the client. The client in this scenario is a Windows Forms application. This application has a simple UI and a reference to the created WCF-Service host in a BizTalk receive location. The client will send the chosen airport code to the service.

clip_image043

The client has a combo box with airport names and corresponding codes of all the US Airports. When you select SEA the code for Seattle/Tacoma Airport then the airport code SEA will be sent as a request message to the WCF-Service. Eventually the response will be rendered in the client.

clip_image044

If you want to monitor the network traffic between BizTalk and the Restful service you could for instance use Netmonitor 3.4.

clip_image046

And examine the out- and inbound traffic from BizTalk to Restful endpoint and back.

clip_image048

In case you enable tracking for the WCF-WebHttp configured send port you can examine the tracked messages in BizTalk.

clip_image050

Above you see the response from the Restful endpoint that arrives at BizTalk.

clip_image052

And how it is send to the client as XML.

This blog has demonstrate how fairly easy it is to consume a json message with BizTalk Server 2013 R2 after invoking a Restful service. Now custom coding is required to serialize a Json format into XML the internal format of the BizTalk messaging engine. Currently REST/Json has taken over the XML/Soap world, at least in the cloud that is. Numerous services available in the cloud support REST let alone only support REST. Therefore, BizTalk Server has adapted to that shift in cloud and supports REST through the WCF-WebHttp adapter and support for JSON.

Cheers,

Steef-Jan

Labels: , , , , , ,