How to Use REST in BizTalk Server 2013 to Send a Message to Azure BizTalk Services

How to Use REST in BizTalk Server 2013 to Send a Message to Azure BizTalk Services

Using the WCF-WebHttp adapter (REST) in BizTalk Server 2013, you can directly send a message to Azure BizTalk Services. The message can be sent to an EDI Agreement or a Bridge hosted in the BizTalk Services Portal.

This topic lists the steps to configure a BizTalk Server send port using the REST adapter to send a message to a Bridge or an EDI Agreement hosted on Microsoft Azure. This topic does not list the steps to create the Bridge or the EDI Agreement in the BizTalk Services Portal.


Send a message to a Bridge


Step 1: Create a Bridge in Visual Studio

A Bridge is a component of a BizTalk Service project created in Visual Studio. When you create the BizTalk Service project, a Bridge is automatically created. When the Bridge is deployed, it’s deployed to the BizTalk Service hosted on Microsoft Azure. The Bridge provides a Runtime Address URL for the bridge to receive messages. When you “send” messages to the Bridge, you send to this Runtime Address URL. The Runtime Address is generated automatically based on your configured settings in the BizTalk Services project in Visual Studio and the BizTalk Service settings in Microsoft Azure.

The complete Runtime Address consists of the following:

The following URL is an example of the complete Bridge Runtime Address:

The complete Runtime Address consists of the following properties:

Property

Description

BizTalk Service Name

The name of the Azure BizTalk Service created in the Microsoft Azure Management Portal.

In this example, internalenv is the BizTalk Service name created when the BizTalk Service is provisioned in the Microsoft Azure Management Portal.

biztalk.windows.net

The Azure BizTalk Services URL. On WindowsAzure.com, this property is always biztalk.windows.net. The complete Azure BizTalk Service URL is:

http://BizTalkServiceName.biztalk.windows.net

To view the complete Runtime Address of the Bridge in Visual Studio:

  1. Double-click the BridgeConfiguration.bcs file to open the bridge in the design area.
  2. Click the Bridge component in the design area.
  3. In Properties, view the Runtime Address property.

Namespace

This namespace is always set to default.

Bridge Relative Address

The Relative Address property entered when you create a Bridge in the BizTalk Services project in Visual Studio.

In this example, CustomerOrdersBridge is the Relative Address property of the Bridge component in the design area.


To create a Bridge, go to How to Create a BizTalk Service Project.

Step 2: Create the BizTalk Server Send Port

The goal is to send the message from BizTalk Server. So, you need a send port. This section lists the steps to configure a BizTalk Server send port to send the message to a Bridge hosted in an Azure BizTalk Service.

Create the Send Port

The message is sent to the Bridge hosted in an Azure BizTalk Service. To get the message out of BizTalk, create the send port using the WCF-WebHttp adapter, also known as the REST adapter, using the following steps:

  1. In BizTalk Administration, right-click Send Ports, click New, and click Static One-way Send Port.
  2. In the General tab, enter a Name for the send port. For example, enter BSBridgeSendPort.
  3. For Type, click WCF-WebHttp and then click the Configure button. Enter the following properties:

     

    General tab

    Property

    Value

    Address (URI)

    Enter the complete Runtime Address of the Bridge. For the namespace, enter default. For example, enter:

    https://internalenv.biztalk.windows.net/default/CustomerOrdersBridge

    HTTP Method and URL Mapping

    Enter the following text to do a POST to the complete Runtime Address listed in the Address (URI) property:

    <BtsHttpUrlMapping>
        <Operation Method="POST" Url = "/" />
    </BtsHttpUrlMapping>

    The General tab looks similar to the following:

    Security Tab

    Property

    Value

    Security Mode

    Click Transport since we are sending using the HTTPS protocol.

    Access control service

    Click Use ACS service identity:

     

    Click the Edit button and enter the Access Control Service (ACS) Issuer Name and Issuer Key. The ACS Issuer Name and Issuer Key values are listed in the Microsoft Azure Management Portal.

    In this example, the ACS namespace is also internalenv. So, the ACS STS URI is https://internalenv.accesscontrol.windows.net/:

    Messages tab

    Property

    Value

    Outbound HTTP Headers

    Enter Content-Type: text/plain. An EDI message is being sent, which is a text file. As a result, enter the text/plain Content-Type:

     


    If you send files to an XML One-Way Bridge or an XML Two-Way Bridge, enter: Content-Type: application/xml.

  4. Click OK.
  5. In the remaining send port properties, enter the following:

    URI

    Automatically populated with the values you enter when configuring the WCF-WebHttp transport.

    Send handler

    Click the host instance associated with the WCF-WebHttp adapter. In some environments, only one host instance may be listed.

    Send pipeline

    Click PassThruTransmit. Another pipeline can be chosen but PassThruReceive is often the simplest:

     


Send a message to an EDI Agreement


Step 1: In Microsoft Azure BizTalk Services Portal, deploy an EDI agreement

When you create an EDI agreement in the BizTalk Services Portal, you enter General Settings, Receive Settings, and Send Settings. The Receive Settings provide a URL for the agreement to receive messages. When you “send” messages to the EDI agreement, you send to this URL. The URL is generated automatically based on your configured settings in the Microsoft Azure BizTalk Services Portal.

The following image shows the Receive Settings of an EDI Agreement. The Transport stage lists the URL in the Endpoint property:


In this URL Endpoint example, the Receive Settings Endpoint states:
https://internalenv.biztalk-icbcs1.windows-int.net/test01/Agreements/1044/Receive

This Endpoint URL consists of the following properties:

Property

Description

BizTalk Service Name

The BizTalk Service Name created when you provision a BizTalk Service in the Microsoft Azure Management Portal.

In this example, internalenv is the BizTalk Service Name.

biztalk.windows.net

The Azure BizTalk Services URL. On WindowsAzure.com, this property is always biztalk.windows.net. The complete Azure BizTalk Service URL is:

http://BizTalkServiceName.biztalk.windows.net

In this example, the biztalk-icbcs1.windows-int.net value is the Microsoft Azure test environment used internally by Microsoft employees to test Microsoft Azure solutions.

Namespace

The namespace is always set to default.

Agreements

“Agreements” is automatically added to the URL. It cannot be modified.

1044

In this example, “1044” is the Agreement ID. The Agreement ID is automatically generated when the Agreement properties are entered and the Agreement is deployed. It cannot be modified.

Receive

“Receive” is automatically added to the URL. It cannot be modified.

Note

The Send Settings in the Agreement also has the Endpoint URL property. When sending a message from the EDI Agreement in the BizTalk Services Portal, you use this URL. In other words, when an application “receives” messages from the EDI agreement, you receive from this URL. For example:

https://internalenv2.biztalk.windows.net/test/Agreements/1045/Send

When you send messages from a BizTalk send port, you enter this Receive Settings Endpoint URL in the BizTalk Server send port properties.

To configure the Microsoft Azure BizTalk Services Portal for your BizTalk Service components, go to Configuring Components for B2B Messaging on BizTalk Services Portal

To create an EDI Agreement in the Microsoft Azure BizTalk Services Portal, go to Creating Agreements.

Step 2: Create the BizTalk Server Send Port

The goal is to send the message from BizTalk Server. So, you need a send port. This section lists the steps to configure a BizTalk Server send port to send the message to an EDI Agreement in an Azure BizTalk Service.

Create the Send Port

The message is sent to the EDI Agreement hosted in the Microsoft Azure BizTalk Services Portal. To get the message out of BizTalk Server, create the send port using the WCF-WebHttp adapter, also known as the REST adapter, using the following steps:

  1. In BizTalk Administration, right-click Send Ports, click New, and click Static One-way Send Port.
  2. In the General tab, enter a Name for the send port. For example, enter BSAgreementSendPort.
  3. For Type, click WCF-WebHttp and then click the Configure button. Enter the following information:

     

    General tab

    Property

    Value

    Address (URI)

    Enter the Endpoint URL listed in the Receive Settings tab in the EDI Agreement. For example, enter:


    https://internalenv.biztalk.windows.net/default/Agreements/1044/Receive

    HTTP Method and URL Mapping

    Enter the following text to do a POST to the complete Endpoint URL listed in the Address (URI) property:

    <BtsHttpUrlMapping>
        <Operation Method="POST" Url = "/" />
    </BtsHttpUrlMapping>

    The General tab looks similar to the following:

    Security Tab

    Property

    Value

    Security Mode

     

    Click Transport since we are sending using the HTTPS protocol.

    Access control service

    Click Use ACS service identity:


    Click the Edit button and enter the Access Control Service (ACS) Issuer Name and Issuer Key. The ACS Issuer Name and Issuer Key values are listed in the Microsoft Azure Management Portal.

    In this example, the ACS namespace is also internalenv. So, the ACS STS URI is https://internalenv.accesscontrol.windows.net/:

    Messages tab

    Property

    Value

    Outbound HTTP Headers

    Enter Content-Type: text/plain. An EDI message is being sent, which is a text file. As a result, enter the text/plain Content-Type:

  4. Click OK.
  5. In the remaining send port properties, enter the following:

    URI

    Automatically populated with the values you enter when configuring the WCF-WebHttp transport.

    Send handler

    Click the host instance associated with the WCF-WebHttp adapter. In some environments, only one host instance may be listed.

    Send pipeline

    Click PassThruTransmit. Another pipeline can be chosen but PassThruReceive is often the simplest:

     

Conclusion

With these settings, you should be able to successfully send messages to a BizTalk Service Bridge or EDI agreement from BizTalk Server 2013 using REST.

See Also

Another important place to find a huge amount of Azure BizTalk Services related articles is the TechNet Wiki itself. The best entry point is Azure BizTalk Services resources on the TechNet Wiki.

If you are also looking for BizTalk Server related articles, the best entry point is BizTalk Server Resources on the TechNet Wiki.
Sort by: Published Date | Most Recent | Most Useful
Comments
  • Very nice article Mandi! Great work! explained in a perfect way!

  • Great article Mandi.

    One thing, in case of configuring the send port with WCF-WebHttp adapter for sending the message using POST you can just mention POST in HTTP Method and URL Mapping section instead of

    <BtsHttpUrlMapping>

        <Operation Method="POST" Url = "/" />

    </BtsHttpUrlMapping>

    and it works absolutely fine.

Page 1 of 1 (2 items)