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.


B
2B 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:

 TPM OM model (in detail)



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)