Example: Creating an X12 Agreement in BizTalk Services Using the TPM OM API

Article
06/12/2017

Important

Microsoft Azure BizTalk Services (MABS) is being retired, and replaced with Azure Logic Apps. If you currently use MABS, then Move from BizTalk Services to Logic Appsprovides some guidance on moving your integration solutions to Logic Apps.

If you're brand new to Logic Apps, then we suggest getting started here:

What are logic apps
Create your first logic app, or quickly get started using a pre-built template
View all the available connectors you can use in your logic apps

Example: How to create an X12 agreement using the TPM OM API with C#.

To create an X12 agreement using C#

Create a Visual Studio C# project and in your Program.cs file, follow the instructions under The First Steps section. Remember to include the service reference to the WCF Data Services client library that you created by adding a service reference to the TPM OM REST API. For example:
```
using BtsServices.PartnerManagement;
```
Here, BtsServices is the name of your C# project in Visual Studio and PartnerManagement is the name of the service reference to the TPM OM REST endpoint.

Add reference to the following namespaces:

using System.Collections.Specialized;
using System.Data.Services.Client;
using System.Net;
using System.Web;

Declare the variables to hold the values that will be required by the program, such as:

private static string acsAddress = "https://mynamespace.accesscontrol.windows.net/"; //sample ACS URL
private static string baseUrl = "https://mybiztalkservice.biztalk.windows.net/default/$PartnerManagement"; //sample base URL for your TPM OM API
private static TpmContext context = null;
private static string issuerKey = "<issuer_key>";
private static string issuerName = "owner";
private static string token = string.Empty;

Retrieve the WRAP ACS token to authenticate with the service. You can use any WRAP token to authenticate, however the code below demonstrates how to retrieve a password token. For more information on how to retrieve WRAP ACS token, see https://msdn.microsoft.com/library/windowsazure/hh674475.aspx.

private static string GetAcsToken(string acsAddress, string issuerName, string issuerKey, string appliesToAddress)
{
    using (WebClient client = new WebClient())
    {
        client.BaseAddress = acsAddress;
        NameValueCollection values = new NameValueCollection();
        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 token and return it.
        return response
            .Split('&')
            .Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase))
            .Split('=')[1];
    }
}

private static void GetAcsToken(string address)
{
    UriBuilder appliesToUriBuilder = new UriBuilder(address);
    appliesToUriBuilder.Scheme = "http";

    if (appliesToUriBuilder.Port == 443)
    {
        appliesToUriBuilder.Port = -1;
    }
    token = GetAcsToken(acsAddress, issuerName, issuerKey, appliesToUriBuilder.Uri.ToString());
}

Pass the Access Control tokens as a header to the request message. Also pass the other mandatory header (x-ms-version) with the request message:

private static void AppendAuthToContext(object sender, SendingRequestEventArgs e)
{
    var request = (HttpWebRequest)e.Request;
    request.Headers["x-ms-version"] = "1.0"; //For this release, set the value of this header to 1.0
    request.Headers[HttpRequestHeader.Authorization] = "WRAP access_token=\"" +
                                                                 HttpUtility.UrlDecode(token) + "\"";
}

Define a method in which you bind the TpmContext object created earlier with the service URI for the TPM OM API REST endpoint, register the callback method, AppendAuthToContext, and set the default save option on the context to batched save:

private static void Initialize()
{
    context = new TpmContext(new Uri(baseUrl));
    context.SendingRequest += new EventHandler<SendingRequestEventArgs>(AppendAuthToContext);
    context.SaveChangesDefaultOptions = SaveChangesOptions.Batch; //You must always use batched save for TPM OM
}

From the Main() function, invoke the GetAcsToken() and Initialize() functions, and create the first couple of partners:

GetAcsToken(baseUrl);
Initialize();

string index = "_" + new Random().Next(1000); //a random identifier to append to each partner
                                              //name to make it unique

//CREATE FIRST PARTNER
Partner partnerA = new Partner();
partnerA.Name = "PartnerA" + index;
partnerA.Description = "DescriptionA" + index;
context.AddToPartners(partnerA); //add the newly created partner to the context
context.SaveChanges(); //save changes to the context.

//CREATE SECOND PARTNER
Partner partnerB = new Partner();
partnerB.Name = "PartnerB" + index;
partnerB.Description = "DescriptionB" + index;
context.AddToPartners(partnerB);
context.SaveChanges();

Create a couple of business profiles and link them to the partners created earlier. To create links between the entities, we typically use the AddLink and SetLink methods available on the DataServiceContext.

// CREATE FIRST BUSINESS PROFILE

BusinessProfile profileA = new BusinessProfile();
profileA.Name = "ProfileA" + index;
profileA.Description = "DescriptionA" + index;
context.AddToBusinessProfiles(profileA);

//// The BusinessProfile entity has a property 'Partner', which is a type in TpmContext. 
//// These are navigation properties/links. Some navigation properties/links need 
//// to be set before we can create this entity. Setting the 'Partner' property is must for
//// creating BusinessProfile entity.
context.SetLink(profileA, "Partner", partnerA); //for 1.* or 1.1 links, you must use SetLink
profileA.Partner = partnerA;

//// Similarly, for creating a link from a Partner to Business Profile, you must set
//// the 'BusinessProfiles' navigation property
context.AddLink(partnerA, "BusinessProfiles", profileA); //for *.* links, you need to use AddLink
partnerA.BusinessProfiles.Add(profileA);
context.SaveChanges();

// CREATE SECOND BUSINESS PROFILE
BusinessProfile profileB = new BusinessProfile();
profileB.Name = "ProfileB" + index;
profileB.Description = "DescriptionB" + index;
context.AddToBusinessProfiles(profileB);
context.SetLink(profileB, "Partner", partnerB);
profileB.Partner = partnerB;
context.AddLink(partnerB, "BusinessProfiles", profileB);
partnerB.BusinessProfiles.Add(profileB);
context.SaveChanges();

Create a couple of business identities and attach them with each business profile. Because BusinessIdentity is an abstract entity, we create a QualifierIdentity that derives from the BusinessIdentity entity.

// CREATE THE FIRST QUALIFIER IDENTITY
QualifierIdentity identityA = new QualifierIdentity();
identityA.Name = "IdentityA" + index;
identityA.Qualifier = "ZZ";
identityA.Value = "THEM" + index;
context.AddToBusinessIdentities(identityA);
context.SetLink(identityA, "BusinessProfile", profileA);
identityA.BusinessProfile = profileA;
context.AddLink(profileA, "BusinessIdentities", identityA);
profileA.BusinessIdentities.Add(identityA);

//CREATE THE SECOND QUALIFIER IDENTITY
QualifierIdentity identityB = new QualifierIdentity();
identityB.Name = "IdentityB" + index;
identityB.Qualifier = "ZZ";
identityB.Value = "US" + index;
context.AddToBusinessIdentities(identityB);
context.SetLink(identityB, "BusinessProfile", profileB);
identityB.BusinessProfile = profileB;
context.AddLink(profileB, "BusinessIdentities", identityB);
profileB.BusinessIdentities.Add(identityB);
context.SaveChanges();

You now create a partnership between the two partners. To create a partnership, you first create a Partnership entity and then link it with the two partners you created earlier:

// CREATE A PARTNERSHIP
Partnership partnership = new Partnership();
context.AddToPartnerships(partnership);

partnership.PartnerA = partnerA;
context.SetLink(partnership, "PartnerA", partnerA);
partnerA.PartnershipsAsA.Add(partnership);
context.AddLink(partnerA, "PartnershipsAsA", partnership);

partnership.PartnerB = partnerB;
context.SetLink(partnership, "PartnerB", partnerB);
partnerB.PartnershipsAsA.Add(partnership);
context.AddLink(partnerB, "PartnershipsAsB", partnership);

context.SaveChanges();

You must now create an agreement between the two partners. As part of the agreement creation process, you must also link it to the business profiles for the two partners, the partnership entity for the two partners, and the one-way agreements (send-side and receive-side). We haven’t created the one-way agreements yet, so in this step we create the agreement and link it to the existing entities, Partnership and BusinessProfile. Because we can’t save changes to the context without linking the agreement to the one-way agreement, we will not save the changes in this step using the context.SaveChanges() method.

//CREATE AN AGREEMENT
Agreement agreement = new Agreement();
agreement.Name = "Agreement" + index;
agreement.ProtocolName = "X12";
context.AddToAgreements(agreement);

//LINK AGREEMENT TO A PARTNERSHIP
agreement.Partnership = partnership;
context.SetLink(agreement, "Partnership", partnership);
partnership.Agreements.Add(agreement);
context.AddLink(partnership, "Agreements", agreement);

//LINK AGREEMENT TO PROFILEA
agreement.BusinessProfileA = profileA;
context.SetLink(agreement, "BusinessProfileA", profileA);
profileA.AgreementsAsA.Add(agreement);
context.AddLink(profileA, "AgreementsAsA", agreement);

//LINK AGREEMENT TO PROFILEB
agreement.BusinessProfileB = profileB;
context.SetLink(agreement, "BusinessProfileB", profileB);
profileB.AgreementsAsB.Add(agreement);
context.AddLink(profileB, "AgreementsAsB", agreement);

The next step is to create one-way agreements from PartnerA to PartnerB and from PartnerB to PartnerA. As part of creating a one-way agreement, you should also link it to the entities Agreement, BusinessIdentity, and ProtocolSettings. We have already created the Agreement and BusinessIdentity entities but we haven’t yet created the ProtocolSettings entity. So, in this step, we only create the one-way agreement entities and link them to the Agreement and BusinessIdentity entities. In the next step, we create the ProtocolSettings entity and link it to the one-way agreement entities.

Note

You should not commit the changes to the context before linking the one-way agreement to the ProtocolSettings entity otherwise you would get an exception. Hence, in this step, we do not use the context.SaveChanges() method to commit the changes to the context.

//CREATE ONE-WAY AGREEMENT FROM PARTNER A TO PARTNER B
OnewayAgreement onewayAgreementAtoB = new OnewayAgreement();
context.AddToOnewayAgreements(onewayAgreementAtoB);

//LINK THE ONE-WAY AGREEMENT TO THE AGREEMENT ENTITY
onewayAgreementAtoB.AgreementAsAToB = agreement;
context.SetLink(onewayAgreementAtoB, "AgreementAsAToB", agreement);
agreement.OnewayAgreementAToB = onewayAgreementAtoB;
context.SetLink(agreement, "OnewayAgreementAToB", onewayAgreementAtoB);

//LINK THE ONE-WAY AGREEMENT TO BUSINESS IDENTITIES
onewayAgreementAtoB.SenderBusinessIdentity = identityA;
context.SetLink(onewayAgreementAtoB, "SenderBusinessIdentity", identityA);
identityA.OnewayAgreementSender.Add(onewayAgreementAtoB);
context.AddLink(identityA, "OnewayAgreementSender", onewayAgreementAtoB);
onewayAgreementAtoB.ReceiverBusinessIdentity = identityB;
context.SetLink(onewayAgreementAtoB, "ReceiverBusinessIdentity", identityB);
identityB.OnewayAgreementReceiver.Add(onewayAgreementAtoB);
context.AddLink(identityB, "OnewayAgreementReceiver", onewayAgreementAtoB);

//CREATE THE ONE-WAY AGREEMENT FROM PARTNER B TO PARTNER A
OnewayAgreement onewayAgreementBtoA = new OnewayAgreement();
context.AddToOnewayAgreements(onewayAgreementBtoA);

//LINK THE ONE-WAY AGREEMENT TO THE AGREEMENT ENTITY
onewayAgreementBtoA.AgreementAsBToA = agreement;
context.SetLink(onewayAgreementBtoA, "AgreementAsBToA", agreement);
agreement.OnewayAgreementBToA = onewayAgreementBtoA;
context.SetLink(agreement, "OnewayAgreementBToA", onewayAgreementBtoA);

//LINK THE ONE-WAY AGREEMENT TO the BUSINESS IDENTITIES
onewayAgreementBtoA.SenderBusinessIdentity = identityB;
context.SetLink(onewayAgreementBtoA, "SenderBusinessIdentity", identityB);
identityB.OnewayAgreementSender.Add(onewayAgreementBtoA);
context.AddLink(identityB, "OnewayAgreementSender", onewayAgreementBtoA);
onewayAgreementBtoA.ReceiverBusinessIdentity = identityA;
context.SetLink(onewayAgreementBtoA, "ReceiverBusinessIdentity", identityA);
identityA.OnewayAgreementReceiver.Add(onewayAgreementBtoA);
context.AddLink(identityA, "OnewayAgreementReceiver", onewayAgreementBtoA);

Finally, you must create the X12ProtocolSettings entity (for both send and receive-side agreements) and link it to the respective one-way agreement entities. In this step, we’ll finally commit the changes to the context because all the required links are created.

//CREATE PROTOCOL SETTINGS FOR onewayAgreementAtoB
X12ProtocolSettings protSettingsAtoB = new X12ProtocolSettings();
protSettingsAtoB.Name = "ProtocolSettingsAtoB" + index;
protSettingsAtoB.ProtocolName = "X12";
context.AddToProtocolSettings(protSettingsAtoB);

//LINK PROTOCOL SETTING TO onewayAgreementAtoB
protSettingsAtoB.OnewayAgreement = onewayAgreementAtoB;
context.SetLink(protSettingsAtoB, "OnewayAgreement", onewayAgreementAtoB);
onewayAgreementAtoB.ProtocolSettings = protSettingsAtoB;
context.SetLink(onewayAgreementAtoB, "ProtocolSettings", protSettingsAtoB);

//CREATE PROTOCOL SETTINGS FOR onewayAgreementBtoA
X12ProtocolSettings protSettingsBtoA = new X12ProtocolSettings();
protSettingsBtoA.Name = "ProtocolSettingsBtoA" + index;
protSettingsBtoA.ProtocolName = "X12";
context.AddToProtocolSettings(protSettingsBtoA);

//LINK PROTOCOL SETTING TO onewayAgreementBtoA
protSettingsBtoA.OnewayAgreement = onewayAgreementBtoA;
context.SetLink(protSettingsBtoA, "OnewayAgreement", onewayAgreementBtoA);
onewayAgreementBtoA.ProtocolSettings = protSettingsBtoA;
context.SetLink(onewayAgreementBtoA, "ProtocolSettings", protSettingsBtoA);

context.SaveChanges();

As an additional step, you can enter the schema of the message that this agreement will process. You can do this for both the send and receive-side agreements. The following step demonstrates how to do this only for the receive-side agreement.

//CREATE SCHEMA REFERENCE ENTITY
X12SchemaReference schemaReference = new X12SchemaReference();
schemaReference.MessageId = "810";
schemaReference.X12ProtocolSettings = protSettingsBtoA;
schemaReference.SchemaPath = "/X12_00401_810.XSD";
schemaReference.SchemaVersion = "00401";
context.AddToX12SchemaReferences(schemaReference);

//LINK SCHEMA REFERENCE TO X12 PROTOCOL SETTINGS ENTITY
context.SetLink(schemaReference, "X12ProtocolSettings", protSettingsBtoA);
protSettingsBtoA.SchemaReferences.Add(schemaReference);
context.AddLink(protSettingsBtoA, "SchemaReferences", schemaReference);
schemaReference.X12ProtocolSettings = protSettingsBtoA;
context.SaveChanges();

Compile and run the program. After the program exits successfully, log on to the BizTalk Services Portal to verify that the agreement is created. Note that there are still some tasks left before you can use the agreement to process messages. You must now:
- Upload any schemas and transforms required for the agreement.
- Specify the route settings to route the message to the destination endpoints, once the message is processed by the agreement.
- If required, specify the batch settings for the send-side agreement.
- Deploy the agreement. When you run the program, the agreement is created in the BizTalk Services Portal and its status is set to “Draft”. You must deploy the agreement from the BizTalk Services Portal before the agreement can start processing messages.
For more information on these steps, see Create an X12 Agreement in Azure BizTalk Services.

Share via

Example: Creating an X12 Agreement in BizTalk Services Using the TPM OM API

To create an X12 agreement using C#

See Also

Additional resources