BizTalk Server 2020 – 20 days, 20 posts – day 16. We are almost finishing migrating all the BizTalk Pipeline Components Extensions UtilityPack project, today is the component: Carry SOAPHeader To WCF-BasicHttp Pipeline Component.
Carry SOAPHeader To WCF-BasicHttp Pipeline Component
The Carry SOAPHeader To WCF-BasicHttp Pipeline Component is a pipeline component for BizTalk Server which can be used in a send pipeline and is intended to carry forward the received custom SOAP Header to the outgoing message, in other words:
This component will read the Custom SOAPHeader from the Message Context Properties
The custom header name will be defined on the component configuration and we can read it from the target http://schemas.microsoft.com/BizTalk/2003/SOAPHeader
and will configure this custom header in the OutboundCustomHeaders property used by the WCF-BasicHTTP Adapter.
The OutboundCustomHeaders property is used if you want to specify the custom SOAP headers for outgoing messages. When this property is used, the property must have the <headers> element as the root element. All of the custom SOAP headers must be placed inside the <headers> element
If the custom SOAP header value is an empty string, you must assign <headers></headers> or <headers/> to this property.
This component is useful if you are implementing CBR operations on legacy service (SOAP – .asmx) using the new WCF-Adapters in BizTalk Server. Notice that the SOAP adapters, still present in BizTalk Server 2020, are obsolete and discontinued.
This component requires one configuration that is the SOAPHeaderName where you should specify the SOAP Header name present in the inbound message to be passed to the OutboundCustomHeaders in the outgoing message.
To use this pipeline component in your projects you just copy the CarrySOAPHeader.dll file into the Pipeline Components folder that exists in the BizTalk Server installation directory:
You do not need to add this custom pipeline component to be used by the BizTalk Runtime to the Global Assembly Cache (GAC).
What is BizTalk Pipeline Components Extensions Utility Pack?
BizTalk Pipeline Components Extensions Utility Pack is a set of custom pipeline components (libraries) with several custom pipeline components that can be used in received and sent pipelines, which will provide an extension of BizTalk out-of-the-box pipeline capabilities.
This is the second post in a multi part series on the features of Azure API Management.
As with the previous post where I demonstrated publishing a SOAP Services with pass-through, this time I am going to demonstrate publishing the same SOAP Service as REST, using the SOAP to REST feature of API Management, I consider this feature very important to APIM, in the past many of my clients have built intermediate services using either BizTalk or .Net.
For this blog post I am going to demonstrate how you publish a BizTalk SOAP service as REST in APIM. With APIM you can publish SOAP services by importing the WSDL (this can be either via the URL or by uploading the WSDL file), In APIM Click the “API” menu item on the left, then Click “WSDL”
In this demonstration I am going to use an uploaded file, this is the WSDL from a BizTalk orchestration exposed as a WCF Request/Response Service, it only has a single operation ‘submit”. I am using an uploaded file because the BizTalk server is hosted in an Azure Virtual Machine and I have changed the URL to reflect the DNS name of the Virtual Machine. I could have also changed the name in APIM after the WSDL was imported. Select “SOAP to REST” and configure as shown and click “Create”
Once the WSDL import is complete, we can now see the API and it’s operations, now let click settings to look at the API settings, this is where we can change the URL to the BizTalk Server hosting our SOAP Service. Click the “submit” operation, then click the “policy editor”
Now look at the policy that does the transformation from REST/JSON to SOAP/XML.
Inbound
Outbound
Now lets click the “Test” menu, this is where we can test our API Operation, before we release them to our consumers
APIM fills in all the details to test the API, notice that the payload for the API is JSON, this is because we chose SOAP to REST, SOAP services are XML based, but the above policy we looked at does the conversion from JSON to XML. Click “try it”
You can now see the results of our call to the BizTalk hosted SOAP Service, the results are in JSON again the policy is doing the conversion, now lets click the “trace” tab, this will give us everything that has taken place in APIM as part of our call to the BizTalk SOAP service. You can notice that the policy has set the SOAPAction and converted the JSON body to XML
The Policy for the SOAP to REST feature is using Liquid Template Language to do the JSON to XML and XML to JSON transforms, these templates can be use to transform from JSON to XML, XML to JSON, XML to XML and JSON to JSON, this allow not only the scenario for SOAP to REST, but the ability to manipulate both inbound and outbound payload for maximum flexibility.
Hopefully this has given you a quick demonstration on how to expose your SOAP Services as REST with APIM.
This is the first post in a multi part series on the features of Azure API Management.
When companies embark on a migration to Azure, they tend to have lots of legacy application, when they start using Azure API Management (APIM), they also want to expose some of these legacy applications, that is where the SOAP pass-through feature of APIM helps out. This feature allow you to publish these SOAP services in APIM.
For this blog post I am going to demonstrate how you publish a BizTalk SOAP service in APIM. With APIM you can publish SOAP services by importing the WSDL (this can be either via the URL or by uploading the WSDL file), In APIM Click the “API” menu item on the left, then Click “WSDL”
In this demonstration I am going to use an uploaded file, this is the WSDL from a BizTalk orchestration exposed as a WCF Request/Response Service, it only has a single operation ‘submit”. I am using an uploaded file because the BizTalk server is hosted in an Azure Virtual Machine and I have changed the URL to reflect the DNS name of the Virtual Machine. I could have also changed the name in APIM after the WSDL was imported. Configure as shown and click “Create”
Once the WSDL import is complete, we can now see the API and it’s operations, now let click “Settings” to look at the API settings, this is where we can change the URL to the BizTalk Server hosting our SOAP Service, instead of inside the WSDL file as I have done.
Now lets click the “Test” tab, this is where we can test our API Operation, before we release them to our consumers
APIM Fills in all the details to test the API, notice that the payload for the API is XML, this is because we chose SOAP pass-through, SOAP services are XML based. Click “Send”
You can now see the results of our call to the BizTalk hosted SOAP Service, the results are in XML, now lets click the “Trace” tab, this will give us everything that has taken place in APIM as part of our call to the BizTalk SOAP service. Scroll down to see the full Trace.
Hopefully this has given you a quick demonstration on how to expose your SOAP Services with APIM.
Currently BizTalk Server 2016 has support for REST, but the support is fairly limited and is missing some feature that most developer expect from REST services.
To overcome these missing feature for companies that are exposing these services to their consumers/partner over the internet, I will show you have to use Azure API Management to publish SOAP services from BizTalk as REST.
For this blog post I took the Hello World example from the BizTalk SDK samples and converted it to a Request/Response orchestration and used the WCF publishing wizard to publish
Publish schema as WCF service (this allows better control over the URL)
Rename the Service and Operation, Select Schemas
Select the location to publish to and I am allowing Anonymous for my example
Note: I ended up using BizTalkWcfService2 as the URL, because an issue I am working with the API Management group
Publish Service
Now you need to setup the App Pool and make sure you can get the WDSL, for this example, We also need to update the WSDL to have the internet name for the server, by default the WSDL is going to be generated with the local server name
I downloaded the WSDL file and changed the server name
Open your Azure API Management Instance and go to the Add a new API blade
Click Upload to upload the WSDL file, if it was not necessary to change the WSDL file you could use the URL instead
Update the highlighted fields with your values, Click “Create”
Wait for the create to complete, Click “Done”
Now before we can use our newly imported SOAP service exposed as REST, we need to add it to a Product to allow users to call it.
I am using a Product Named BizTalk, you can create and use any Product Name you like
Now I go back to the API Definition, Click on our “submit” operation
Then Click on the “Test” Tab
This is the Test blade, notice that API Management has supplied the API Management Subscription Key (necessary to call API Management, this is based on the product we put our API in), the Sample JSON Document and a “Send” button to test with. Click the “Send” button
View the results of the call
You will notice that the send and receive bodies are JSON, but we are calling a SOAP Service, this is what the SOAP call would look like
Lets now examine how API Management published our SOAP Service as REST, on the API tab, Click the “View Code”
The API Management use a policy to do the inbound and outbound transformation, the policy uses the liquid language to do the translation from JSON to XML and them XML to JSON and include error handling
The process of importing our WSDL as REST to SOAP automatically created the policy that does the transformations and also created the inbound and outbound JSON schemas
In a later blog post I will talk about how you can modify the schemas and the transformation.
One of the main features that BizTalk is missing with its REST adapter is the ability to provide the definition of the API for the clients to use to generate the code to call our REST services, in the Developer Portal, API Management provides either Open API (swagger) or WADL for our clients to use.
I hope this blog post helped you understand how you can use Azure API Management to publish your BizTalk SOAP Services as REST
In previous post I described a way to consume a public Rest API using the BizTalk WCF-WebHttp adapter in combination with JSON-decoder, which is a new component with the BizTalk Server 2013 R2 edition. Now I like to mix things up a bit and consume a different API that is public. That is you can use this API from Last.fm. This is an online music discovery service that gives you personalised recommendations based on the music you listen to. To use the API of this service you need to registering yourself first. Because when you call of one of the methods of the API you need to stick in an api_key as one of the parameters of your request. This is not uncommon as various cloud API’s have this kind of mechanism.
Scenario
I have the following scenario, where I have built a client application (still one of those old fashioned guys that use window forms). The client application have the following functionality:
Get information of an artist.
Get the top albums from the artist.
Information and top albums can be obtained through calling the Last.fm API artist methods. The client will via BizTalk call these API methods. Similar as in my previous post calling the Airport Service to retrieve its status. Below you find an overview of the scenario.
The communication with the internal endpoint in this scenario will be SOAP/XML. The endpoint is hosted in a two way receive port (request/response). It exposes schemas for two operations: GetArtistInfo and GetTopAlbums. The request message will subsequently be mapped to a REST call to the service indicating that the expected response format is Json or default xml. BizTalk will decode the response into XML, so that it is published as an XML message in the MessageBox in case the response message is Json (GetArtistInfo) otherwise it will be just received by the adapter (GetTopAlbums). 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 or SOAP/XML –> REST/XML –> SOAP/XML) between internal client and the external Last.fm API.
The solution of the described scenario consists of the following parts that will be discussed in the subsequent paragraphs:
Exposing schema’s for internal service exposing an operation to client application that will consume the service.
Creating a custom receive pipeline to enable decoding of Json message to xml (see previous post).
Configuration of a Send Port with the Web-Http adapter (or binding if you like), send and receive.
Demonstrating the solution.
Exposing schema’s as service
To support both calls from the client to the Last.fm API the request schema’s are as follows:
Both request schemas look the same expect for the root name. These could be consolidated to one schema, nevertheless I choose to keep each method call isolated. Both schema contain promoted properties. The elements need to be promoted to variable mapping later when configuring the send port with WCF-WebHttp adapter to support dynamic URL mapping.
The response for the GetArtistInfo will be Json and therefore I will use the postman application in Google Chrome:
Here you can see that for calling the API you need a method parameter, artist name, api_key and format. However, the format is optional. By default XML will be returned when no format has been specified. The Json response can be used as instance for creating an XSD using the JSON Schema Wizard in Visual Studio BizTalk templates. The schema looks like:
Similar approach will be used to get an instance of the response to the GetTopAlbums call. This schema will be based on XML. Having the schemas enabled me to create an internal service that exposes two methods.
Once I have the internal service up and running the next part is to create a custom pipeline for receiving the Json response from the GetArtistInfo API method call. The Json decoder will be specified to serialize that response into XML. For the GetTopAlbums no specific custom pipeline is necessary. The schemas and custom pipeline will be deployed to BizTalk runtime.
Creating and configuring the Send Port with the Web-Http adapter
To be able to communicate with the Last.fm API and call both methods I will need to have two send ports configured with the WCF-WebHttp adapter. The Last.fm API doesn’t require authentication other than supplying the api_key as a parameter in call tp any of the API methods. In the general tab of the WCF-WebHttp Transport properties the address of the service can be specified (URI). Besides the address I need to specify here the HTTP Method (GET) and perform a URL mapping.
The URL mapping will be interesting as I need to add a few parameters to my REST call.
http://ws.audioscrobbler.com/2.0/?method=artist.getinfo&artist=Metallica&api_key=<your last fm api_key>&format=json
My HTTP Method and URL Mapping will look like:
<BtsHttpUrlMapping><Operation Method=”GET” Url=”/?method={method}&artist={artist}&api_key={api_key}&format=json”/></BtsHttpUrlMapping>
Interesting thing in this URL mapping is that & is and &. If you try to just use the & you will run into an error like depicted below:
Next I click Edit… to do the variable mapping i.e. map the parameters to promoted properties of my incoming request message.
Variable is mapped to the property namespace that defines the API_KEY, ARTIST and METHOD.
The general tab is important for specifying the address, method and URL mapping. The other tabs are:
The Binding tab provides you the ability to configure the time-out and encoding-related properties.
The Security tab provide you the ability to define the security capabilities of the WCF-WebHttp send port.
The Behaviour tab provides you the ability to configure the endpoint behavior for the send port.
The Proxy tab provides you the ability to configure the proxy setting for the WCF-WebHttp send port.
The Messages tab provides you the ability to specify how the message is sent to the REST interface.
Note: In this scenario we only use GET operation of the Last.fm API 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!
For further details on configuration settings for these tabs see MSDN article How to Configure a WCF-WebHttp Send Port.
Test the solution
Now building the client to call the Last.fm API methods indirectly via BizTalk was quite some work. I wanted to render the information nicely in a Windows Form. When I enter an artist name and click GetInfo then a request will be send to BizTalk routed to the send port that communicates with Lastfm API and request info of the band Metallica.
The response of the message is nicely rendered in the above form. When I click TopAlbums another request is sent to a different send port that send to a different Last.fm API method.
If we look at the traffic between BizTalk Server and Last.fm using Netmon I can examine what goes over the wire.
This blog has demonstrate how fairly easy it is to consume a Json message with BizTalk Server 2013 R2 after invoking a Rest API. And how I was able to leverage an API from Last.fm. The cool thing is that BizTalk Server 2013 R2 is capable to communicate with tons of REST API’s out there in the cloud with the WCF-WebHttp adapter. And with JSON support things get less complex. I haven’t tried communicating with an API that requires Basic- or OAuth authentication. I probably will have to do some custom coding using behavious like explained in the blog post from Quicklearn.
This sample shows how to modify a BizTalk Web Service to submit Xml Documents into BizTalk and route them using direct binding. The key to routing the message submitted by the Web Service is to make sure the Receive Port uses the Xml Disassembler pipeline.
This sample will work with BizTalk 2006 and BizTalk 2006 R2.
Get more information from the original blog post on this topic: http://www.biztalkgurus.com/biztalk_server/biztalk_blogs/b/biztalk/archive/2006/03/14/how-to-use-soap-to-submitt-xml-documents-into-biztalk-server.aspx and http://www.biztalkgurus.com/biztalk_server/biztalk_blogs/b/biztalk/archive/2006/03/14/working-with-untyped-web-services-in-biztalk-server.aspx
BizTalk Pipeline Components Extensions Utility Pack
