Hybrid integration with BizTalk Server and Azure (Part 2)

Hybrid integration with BizTalk Server and Azure (Part 2)

The previous blog securely connected our BizTalk server to our Azure environment through the use of Service Bus Queues. We now need a way that we can control who can send messages to the Queue without too much overhead on our part.

In this second part of the series, we will be setting up the API Management service and take a first look at policies and how we can leverage them for us.

Azure API Management

For now, we will deploy an Azure API Management service, add a new blank API that will point to our queue’s namespace while injecting the headers through policies.

Azure provides a publisher portal where you can completely manage your API Management Service. This will be slowly phased out and every functionality will be integrated in the blades. We will be only working in the blades for now.

From the portal, add a new API Management Service. You will need to enter a name, resource group, location, organization name and administrator email before deploying. Be sure to use the Developer pricing tier if you are testing as otherwise your credits will run out fast. Deploying your API Management service will take some time, so this is the perfect time to (re)fill your coffee.

Now that the API Management Service has been deployed, there are several things that need to be done. We will need to add a new API in which we point to our Bus Service namespace. There we will add a new endpoint that points to the created queue. Furthermore, we will need to update the policies so that calls get the right headers and add the API to a product of choosing.

We will start with adding a new API. From the API Management Service blade, go to APIs ( – Preview).
Add a new Blank API.

In the popup, provide the following information:

  • Web Service URL
    The endpoint to which this API will point. My preference here is to add the Service Bus Namespace and inject the complete URL via policies.
  • Name
    The name of this API. This will allow you to segregate API calls based on subscription and provides a logical container for your calls.
  • Description
    Can be seen in the developer portal.
  • API URL suffix
    Provides a unique suffix for this API.
  • The URL scheme
    By default, HTTPS is selected. HTTP can be used as well but as we connect to the service bus queue by HTTPS, I will continue this.

The greyed out Base URL box below will preview the URL that will be needed to publicly access the API.

The APIs (- PREVIEW) blade will now have been updated with the new API. Click on it to see the API operations and add a new one.

After adding an operation, you will be prompted to configure the Frontend. This will allow you to define query parameters, (required) headers, requests and responses. We will not be doing any of that as all we want is the body of our request to be accessed by BizTalk.

In Frontend screen, use POST in the URL and pick a suitable path and display name. The URL you choose here is the one that will be publicly accessed.

Azure will also be looking in your backend for this URL. The URL you would need to use would be (in this example) “/biztalkbroker/messages”.  The old developer portal had a textbox near it that would create a policy and redirect your message to the correct endpoint. We will be creating this ourselves.

Now that the operation has been created, it’s time to point it right to our queue and pass along the necessary headers to be able to post to the queue.

Be careful here. Depending on what API or operation you are in, you can change the inbound processing for every incoming request on every API or just on one operation.

For now, just change the headers for the incoming request on this operation by going to the operation you created and editing the inbound processing.

A base policy has already been applied. This means that this operation will inherit the policies from the levels above it. The sequence goes as follows: Operation

We can choose here to edit the policies in a form based editor or a code based editor. Form view allows you to easily set some query parameters, headers or body. Mocking allows your API to return a static response instead of calling the backend.

I prefer the Code based editor as it allows more flexibility.

To insert headers into the inbound section, place your cursor in the inbound section and click “Set HTTP Header” under the Transformation policies on the right. Change the name and value to the corresponding ones as in the test POST and change the action to “override”.

Be sure to escape every “&” character in a string with “&”. You will get errors otherwise and not be able to save.

The final policy is Rewrite URL. Insert this policy in the inbound as well and set the template variable to the URL needed. If your backend service is your Service Bus namespace, you will need “/BusName/messages”.

Now that our public endpoint is visible, pointing to our queue and BizTalk is connected to the queue, we are almost finished with this part. Now the management part of the service kicks in. Exit the APIs (- PREVIEW- blade and go to the Products (- PREVIEW) blade.

You will see the default Starter and Unlimited products. Add a new one and provide a Display name (the name field will automatically be generated as you type the display name) and a description.

Set the state to Published so that it can be accessed immediately and deselect Requires subscription. This will allow anyone to access the endpoints of this product.

If you want to regulate and manually approve who can sign up for your API, toggle Require approval.

Go to the detail blade of the new Product and pick APIs. Add the API you previously created.

Your product now has your API and is ready to be accessed. The only thing left to do is pick up your keys which you will need to pass on to the Azure API Management Service when making a call.

For the purpose of this tutorial, we will copy and paste our own primary keys from the Azure Portal. Users can go to the developer portal and subscribe to the product.

Go to the Users (- PREVIEW) blade and select Administrator. You will see subscription for the three products. Click on  and press toggle secrets. Copy your secret and use your favorite API tester to send a POST to the API with the header “Ocp-Apim-Subscription-Key” set to your key.

Your message should be dropped by BizTalk.


  • Named values! This guide shows the authorization header field injected as a string. It would be better for managing the API and for security if the Authorization string was stored in a Named Value.


We opened up our BizTalk receive location by setting up an endpoint in the API Management that connects to the Service Bus Queue and adds the Authorization header. Our endpoint is not completely public and only accessible by signing into the portal and receiving a subscription key.

We have only scratched the surface of the possibilities with policies and API Management. For more information on the different policies available, this article has an up-to-date list of all the policies.

In the next part, we will be setting up Blob storage and a Function to prepare for the Logic App that will save the message and send a pointer to it.

Happy POST’ing!