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

We saw the TPM model in the earlier post. Let’s now look at creating a Partner and querying the result using OM API.
TPM OM OData source is hosted at https://<deploymentName>$partnermanagement where <deploymentName> is the name of your BizTalk Services deployment. The metadata of the datasource represents the EDM data model for OData in XML. This can be obtained by adding the $metadata to the query.

For example, type the URL in the browser https://<deploymentName>$partnermanagement/$metadata to see the TPM objects, navigation properties and associations as below.

 TPM OM Odata metadata

Let’s connect to this OData source from C# to build a simple application. For the complete source code, please refer to the MSDN Code Gallery link below.

1. Install WCF Data Services 5.3.0 on your client machine

2. From Visual Studio, create an empty C# project. Right click on Service References in Solution Explorer and choose Add Service Reference…


3.       3. Type the $metadata URL in the Address field and hit Go. You will see the TpmContext in the Services. Rename the Namespace to TpmServiceReference


4.     4. Add the directive using <yournamespace>.TpmServiceReference;

 Now in order to query the service we need three things –

Query ACS to get the authorization token for the endpoint

Initialize the TpmContext with the OData source URL

Add an event handler that passes this token as part of the header for every GET/POST call

Add the logic to query the OData service

5      5. Get the ACS details of your deployment – Go the Windows Azure Management Portal, BizTalk Services node and click on Connection Information and note down the details.

 Azure Management portal command bar

           6. Query ACS for a token – use variables for ACS address, issuer name, issuer secret and the deployment address to which the token is queried for.

privatestaticstring GetAcsToken(string acsAddress, string issuerName, string issuerKey, string appliesToAddress)


using (WebClient client = newWebClient())


   client.BaseAddress = acsAddress;

   NameValueCollection values = newNameValueCollection();

   values.Add("wrap_name", issuerName);

   values.Add("wrap_password", issuerKey);

   values.Add("wrap_scope", appliesToAddress);


   byte[] responseBytes = client.UploadValues("WRAPv0.9/", "POST", values);


   string response = Encoding.UTF8.GetString(responseBytes);


   // Extract the SWT token and return it.

   return response


      .Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase))





7.        7. Initialize the TpmContext with the base URL of the OData source (this will not contain the /$metadata). Also add the event handler to stamp the ACS token to the header

TpmContext context = newTpmContext(newUri(baseUrl));

context.SendingRequest += newEventHandler<SendingRequestEventArgs>(context_SendingRequest);

            context.SaveChangesDefaultOptions = SaveChangesOptions.Batch;

context.IgnoreMissingProperties = true;


8.        8. Add an event handler

privatestaticvoid context_SendingRequest(object sender, SendingRequestEventArgs e)        {

// add timestamp expiration to fetch token only when necessary

string token = GetAcsToken(BaseUrl);


var request = (HttpWebRequest)e.Request;

request.Headers[HttpRequestHeader.Authorization] = "WRAP access_token=\"" +

HttpUtility.UrlDecode(token) + "\"";


request.Headers["x-ms-version"] = "1.2";



Note: x-ms-version is a mandatory header and indicates the version of the TPM OM API OData service. 1.2 here is the version for the BizTalk Services February update

 9.   You can now use CRUD operations. Here is a sample to create a Partner and Profile. Note the use of SetLink using navigation properties.

//Create partner A

var partnerA = newPartner() { Name = "PartnerA", Description = "DescriptionA" };



//Create new BusinessProfile for partnerA

var profileA = newBusinessProfile() { Name = "ProfileA", Description = "DescriptionA" };


context.SetLink(profileA, "Partner", partnerA);



10.    10. You can also use Linq to query the data

// Query the list of all partners

var allPartners = from p in context.Partners

orderby p.Description

select p;


Compile and run the application to create the partner and also see the list of existing partners. Note the MSDN Code Gallery sample contains code to add X12, EDIFACT and AS2 agreements as well. After creation of agreements from TPM OM API, the agreements are in Draft state. You need to go to the BizTalk Services portal to edit the agreement, add Transform and Route settings and then deployment the agreement.


-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)