Creating EDI Bridges in MABS (post August 2014 Update)

In my last post, I talked about the new EDI features in the August 2014 release of Microsoft Azure BizTalk Services (MABS), particularly in regards to the separation of agreements and bridges. In this article, I’m going to discuss how you actually create & invoke these new bridges – especially since the experience wasn’t quite as intuitive as I would have expected and the documentation is still a bit light.

Prior to the August update, you used to create an agreement and this would automatically generate the send & receive bridges that hosted the agreement. Now that you create these artefacts independently, you can enjoy greater flexibility and reusability – but it also entails a few extra steps and requirements in order to establish it. Let’s walkthrough the process.

1. Create the Partner Profiles

You can’t really do anything without creating these. Nothing terribly significant has changed about this process in the latest update – except that you no longer have the option of creating an agreement template within a profile.


For this example, I’ve created two partner profiles with their respective “ZZ” identifiers:

Partner Name Partner ID
PartnerA 12345
PartnerB 23456

2. Create the EDI Bridge

Unlike EAI bridges (which must be created using the SDK within Visual Studio 2012), you create a new EDI bridge within the BizTalk Services Management Console using the familiar “Add” button at the bottom of the screen.

The first task is to choose from the drop-down whether to create an EDI or an AS2 bridge; we’ll choose EDI bridge for now. Note that you can also set some delimiter configuration if you’re intending to use EDIFACT (we’ll skip that for now as we’re going to create X12 agreements only):


Click the “Continue” button and you can configure all the same screens you did within the Agreement view before the August update – with the exception of the “Protocol” and “Batching” pages (which now live in the agreement itself). In both of the “Transport” pages (Send & Receive), you’ll see that the inbound URL is automatically set to use a GUID. However, you can change this to a custom token if you like (e.g. “SendPO”, etc.):


Once you’ve finished specifying the transport, routing, & any transformations, you can deploy the bridge. Note that at no point do you specify the agreement(s) that will use this bridge.

Now the “Bridges” view will display all your deployed bridges, including two bridges for the EDI bridge you just created (one for Send and one for Receive):


Each bridge is a hyperlink, so you simply click the EDI bridge link to view/edit the settings.

3. Create the Agreement

The experience of creating the agreement is pretty much the same as before – except that you are only presented with the “Protocol”  and (for Send) “Batching” pages within the relevant sections, as all the other pages you used to fill out are now handled in the bridge configuration.

Once you’ve completed the agreement configuration and saved it, you will discover the automatically  assigned “Agreement ID” in the leftmost column. This is an important piece of information:


4. Link the Agreement with the Bridge

Now of course the next step is to link the agreement with the bridge.  But wait… how do you do that??

After scratching my head for awhile and consulting Dr. Google, I finally found the answer on this page on MSDN. Essentially, linking happens automatically by evaluating the agreement and/or partner identifiers in the message and thereby loading the agreement with the matching specification.

Here’s where the true flexibility of the design comes to the surface. You can have multiple bridges deployed (with different routings, transformations, etc.) and invoke the same agreement from either, depending on which URL you send the request to.

What isn’t so obvious is – how do you specify the identifiers in the request message?

5. Send the Identifiers in the Message Header

According to the documentation, if you are sending a message to an EDI Send bridge (not an AS2 bridge – that’s handled differently), at least one of the following needs to be included in the message header:

  1. Agreement ID
  2. Combination of agreement name and partners
  3. The identities in the agreement

The documentation is a bit sketchy here (but is likely to be updated soon). For one thing, what does “message header” mean? Since the bridge endpoint is essentially a REST endpoint, it means by default it must be the HTTP header.  The next question is – what are the header names that must be used?

Fortunately, Harish Kumar Agarwal from the product team was extremely helpful with a prompt answer to my query. Here are the appropriate header names to use:

Option Header Name Example Value
1 AgreementID 1
2 AgreementName SendPO-PartnerB
HostPartner PartnerA
GuestPartner PartnerB
3 SenderIdentifier 12345
SenderQualifier ZZ
ReceiverIdentifier 23456
ReceiverQualifier ZZ

As an example, I got it to work by including an HTTP header named “AgreementID” set with the identifier displayed in the management portal (e.g. “1”). If you don’t have the headers specified correctly, it will result in sending the message to the configured suspension location with a “No agreement found for the given details” error.

To test this, I started by downloading Sandro Pereira‘s excellent EAI Bridge Message Sender tool, which is a handy GUI application that wraps the familiar command line MessageSender and MessageReceiver tools. But I needed to make some small modifications to allow the insertion of custom HTTP headers; the main changes are shown below:



The result is that by specifying the appropriate headers, I was able to successfully send an 850 Purchase Order to my EDI bridge, viewing the output by routing the EDI result to a Service Bus queue:


As for using the AS2 bridges, that will need to be the topic of another future blog post. But for now, be aware that the  AS2-To and AS2-From headers must be specified in the request, similar to the above headers.

About Dan Toomey
Enterprise integration geek, Microsoft Azure MVP, Pluralsight author, public speaker, MCSE, MCT, MCTS & former professional musician.

9 Responses to Creating EDI Bridges in MABS (post August 2014 Update)

  1. Pingback: Using AS2 Bridges in MABS (post August 2014 Update) | Mind Over Messaging

  2. Peter Chen says:

    Hi Dan,

    The article is very useful.
    Can you send modify program to me,please ?


  3. Arthur says:

    Hi! Can you please send the program to me?


  4. Selwyn Mart says:

    Hi Dan,
    Thank you for this article I found this helpful.
    But I still have trouble in connecting Bridge to Agreements without using any program. Could you please help me.

  5. pn2017 says:

    Hi Dan,

    This article helps me a lot. But still I have trouble connecting Bridges to Agreements without using any test tool (just Biztalk portal). Could you please help me?

    • Dan Toomey says:

      Hi pn2017,
      I’m afraid I can’t help much without more detail(?) Have you specified the appropriate headers as mentioned in the post?
      What I can suggest is that you try abandoning MABS and using the new Enterprise Integration Pack instead. This will be the way forward for doing EDI in Azure.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

John Glisson - Geek of the Cloth

Thoughts on integration, technology and what-not...

Prashant BizTalk And Azure Integration Blogs

My Integration Experiences - BizTalk And Azure Integration


THINK: It's not illegal....yet.....

Abdul Rafay's BizTalk Blog

My experiences with BizTalk related to architecture, development and performance in my enterprise.

BizTalk musings

Issues, patterns and useful tips for BizTalk development


Enterprise Applicaiton Integration and SOA 2.0

Connected Pawns

Mainly BizTalk & Little Chess

Adventures inside the Message Box

BizTalk, Azure, and other tools in the Microsoft stack - Johann Cooper


Talk, talk and more talk about BizTalk

Richard Seroter's Architecture Musings

Blog Featuring Code, Thoughts, and Experiences with Software and Services

Sandro Pereira BizTalk Blog

My notes about BizTalk Server 2004, 2006, 2006 R2, 2009, 2010, 2013 and now also Windows Azure BizTalk Services.

BizTalk Events

Calendar of BizTalk events all over the world!

Mind Over Messaging

Musings on BizTalk, Azure, and Enterprise Integration News

The latest news on and the WordPress community.

%d bloggers like this: