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.