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:

#	TPM Object	Description
1	TpmContext	WCF DataServiceContext object on client to make OM API calls to service
2	Partner	Company participating in a trading partner relationship
3	BusinessProfile	Business within the company
4	Partnership	One or more agreements between two partners constitute a partnership
5	BusinessIdentity	Identifier and it value of either the sender or receiver (abstract)
6	QualifierIdentity	Realization of BusinessIdentity for X12, EDIFACT, AS2
7	Agreement	Technical agreement settings between two business profiles
8	OnewayAgreement	Either send or receive direction of the agreement
9	ProtocolSettings	Settings specific to a one way agreement
10	X12ProtocolSettings	Realization of Protocol settings for X12
11	X12EnvelopeOverrides	Send side X12 envelope override settings
12	X12SchemaReferences	Schemas referred to in the One-way agreement for X12
13	X12ValidationOverrides	Validation override settings for one way X12 agreement
14	BatchDescription	Batch configuration for the one way agreement (X12 Send or EDIFACT send)
15	EDIFACTProtocolSettings	Realization of Protocol settings for EDIFACT
16	EDIFACTEnvelopeOverrides	Send side EDIFACT envelope override settings
17	EDIFACTSchemaReferences	Schemas referred to in the One-way agreement for EDIFACT
18	EDIFACTValidationOverrides	Validation override settings for one way EDIFACT agreement
19	AS2ProtocolSettings	Realization of Protocol settings for AS2
20	Contact	Contact information of person, tied to Profile and Agreement
21	CustomSettings	Custom name-value pairs that can stored for an agreement or profile

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)