How to Use REST in BizTalk Server 2013 to Send a Message to Windows Azure BizTalk Services (WABS)

How to Use REST in BizTalk Server 2013 to Send a Message to Windows Azure BizTalk Services (WABS)

Using the WCF-WebHttp adapter (REST) in BizTalk Server 2013, you can directly send a message to Windows Azure BizTalk Services (WABS). 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 Windows 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 Windows 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 Windows Azure.

The complete Runtime Address consists of the following:
https://YourBizTalkServiceName.biztalk.windows.net/Namespace/BridgeRelativeAddress

The following URL is an example of the complete Bridge Runtime Address:
https://internalenv.biztalk.windows.net/default/CustomerOrdersBridge

The complete Runtime Address consists of the following properties:

Property

Description

BizTalk Service Name

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

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

biztalk.windows.net

The Windows Azure BizTalk Services URL. On WindowsAzure.com, this property is always biztalk.windows.net. The complete Windows 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 a Windows Azure BizTalk Service.

Create the Send Port

The message is sent to the Bridge hosted in a Windows 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 WABSBridgeSendPort.
  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 Windows 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 Windows 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 Windows 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 Windows Azure Management Portal.

In this example, internalenv is the BizTalk Service Name.

biztalk.windows.net

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

http://BizTalkServiceName.biztalk.windows.net

In this example, the biztalk-icbcs1.windows-int.net value is the Windows Azure test environment used internally by Microsoft employees to test Windows 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 Windows 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 Windows 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 a Windows Azure BizTalk Service.

Create the Send Port

The message is sent to the EDI Agreement hosted in the Windows 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 WABSAgreementSendPort.
  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 Windows 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 WABS Bridge or EDI agreement from BizTalk Server 2013 using REST.

Leave a Comment
  • Please add 8 and 7 and type the answer here:
  • Post
Wiki - Revision Comment List(Revision Comment)
Wikis - Comment List
Sort by: Published Date | Most Recent | Most Useful
Posting comments is temporarily disabled until 10:00am PST on Saturday, December 14th. Thank you for your patience.
Comments
  • Very nice article Mandi! Great work! explained in a perfect way!

Page 1 of 1 (1 items)