BizTalk TPM OM API – Part 1

This is a two-part series on using TPM OM API in BizTalk Services. In Part 1, we discuss the TPM model and in Part 2, we use this model in a sample walkthrough.

B2B customers define trading relationships between partners using technical agreements. BizTalk Services provides B2B capabilities to manage this relationship using the BizTalk Services portal or through API. Trading partner management API is used to manage the lifecycle of an agreement programmatically. The true power of the API is realized when one can dynamically change the behaviour of an agreement at runtime.

Think of a scenario where B2B partners need to comply with a new mandate, say by switching from “:” to “;”separator in X12 messages. Or consider the scenario when you are sending test messages to agreements in the stage environment and you would like to move the agreements to the production environment. In either scenario, BizTalk Services portal is useful if you there are less than 5 agreements to be updated. However if the change is across 100 or even 1000 agreements, it would be helpful to automate the updates.

Before we go further, let’s look at the object model in its basic form. From the diagram below, there are Partners who trade with each other, their businesses (profiles) which exchange data on a pre-negotiated agreement and data adheres to some protocol (settings) like EDIFACT or X12 depending on the region.

The TPM model is exposed for consumption through WCF Data Services, a .NET framework that enables the model to be accessed over Open Data Protocol (OData). Let’s also briefly look at how WCF Data Services are used. WCF Data Services are stateless but the state of the client is maintained in DataServiceContext. In our case, TpmContext inherits DataServiceContext. All CRUD operations to the OM will be carried out using the TpmContext object which exposes a set of object collections of the TPM OM. TpmContext also exposes two important methods setLink and AddLink for managing relationships between objects. The methods accept the source and destination object and the navigation property name between the objects. When the relationship between objects is 1-N, then use AddLink else when the relationship is N-1 or 1-1 use the SetLink method. For example, one Partnership can contain one specific Partner (use SetLink) while one Partner can be part of multiple Partnerships (use AddLink). Both are shown in the code snippet below:

var partnership = newPartnership();
context.AddToPartnerships(partnership);
partnership.PartnerA = partnerA;
context.SetLink(partnership, "PartnerA", partnerA); // navigation property PartnerA
partnerA.PartnershipsAsA.Add(partnership);
context.AddLink(partnerA, "PartnershipsAsA", partnership); // navigation property PartnershipAsA
partnership.PartnerB = partnerB;
context.SetLink(partnership, "PartnerB", partnerB); // navigation property PartnerB
partnerB.PartnershipsAsB.Add(partnership);
context.AddLink(partnerB, "PartnershipsAsB", partnership); // navigation property PartnershipAsB
context.SaveChanges();

Now once we know the complete model, we can tie the objects and their navigation properties and use it to update the model. let’s look at the complete model:

The objects in the model are explained in the table below:

Note all X12, EDIFACT, AS2 specific objects are shown in the table. The objects have to be created or updated, added to the TpmContext and the corresponding navigation property must also be updated using setLink or addLink in code for CRUD operations with OM API. Now that we have the background, in Part 2 let’s put things in action and write a sample application using the API.

-Karthik Bharathy

You can also follow me on Twitter @kb_chirps for quicker updates on BizTalk or read my book on "Getting Started with BizTalk Services" (pre-order from here)