Jun 192008
 

For those of you who would like to know what role links are and how you can use them in everyday life, I have a very simple customer request, and an even simpler prototype to demonstrate how to implement role links.

My situation is that I process EDI (HIPAA) files, and there is a standard map that translates the file to a flat file structure. However, the output needs to go into a client specific folder for the existing process to start.

Looking at the source of all truth and knowledge here:

A role is a collection of port types that either uses a service or implements a service. A role defines how parties interact with orchestrations. For example, an orchestration might use the role of Shipper. The Shipper has one or two parties associated with it. When the orchestration decides which shipping company to use to ship an item, it compares the prices of the parties in the Shipper role.

With my limited knowledge of Role Links, I thought that this might be a way to have one orchestration tied to an variable list of send ports. I figured that if I was a Shipper, I want to decide which shipping company (in my case two different folders) and then send it off to them.

After looking at this site and this site I was still very lost as to how to implement it. So I started playing around, and decided on a very simple prototype:

  • Receive a file
  • Interrogate the contents of the file for who the sender is
  • Set the Role Link
  • Send it out with some type of indicator so I know which sender it was

Pretty easy I thought, and actually implementing it was not too hard.

  1. I created an empty BizTalk project
  2. I constructed a sample file and since I am lazy, I made Data a distinguished field. 
  3. I then created an orchestration that had a Port Type defined from the schema I just created.
  4. I then created a Recieve Port using the FilePortType.
  5. I then created a new Role Link Type and named it SendingRoleLinkType
  6. When you expand the new link type, and right click on Role_1, it asks you to Add Port Type
  7. So of course I do, and I choose the existing port type, in the Port Type Wizard
  8. I also rename the Role_1 to Sender
  9. I then created a role named Destination
  10. I am using an existing Role Link Type already defined
  11. It is the Consumer role.
  12. I created two parties and for the HIPAA accelerator, the format is EDI:\\ISASenderID:Qualifier:GSSenderID
  13. These parties are defined as Party1 (EDI:\\123456789:ZZ:123456789) and Party2 (EDI:\\987654321:ZZ:9876543521) CORRECTION: the parties should have been defined as EDI://123456789:ZZ:123456789 and EDI://987654321:ZZ:9876543521 for them to be correct

  14. I then created an expression after my receive shape to assign the role link, and here is the code:

      Destination(Microsoft.XLANGs.BaseTypes.DestinationParty)=
      new Microsoft.XLANGs.BaseTypes.Party(@”EDI:\\”+FileMsg.Data+””,”EDI”);

      Notice that in the argument 1 of Party, is the Value defined in the Party Definition, and obscurely, the OrganizationName (EDI) is the value it is looking up against. I am pulling the partner information (FileMsg.Data) out of the file (which we will see later).

  15. I then created a send shape and connected it to the Destination Port Link
  16. I deployed the project and bound the input to a default xml pipeline
  17. Now the part that exposes the power of Role Links I created a send port for trading partner 1 called, oddly enough, Party 1 Destination and set the path to E:\Role Link\Party1\%SourceFileName%.%MessageID%.xml, I did the same for trading partner 2, called Party 2 Destination and set the path to E:\Role Link\Party2\%SourceFileName%.%MessageID%.xml

  18. In the Party definition I clicked on the send port and chose the correct send port:

  19. Now we need to ‘bind’ the sending to the correct variable port, how you do that is if you expand the Roles, you will see the Sender Role
  20. Right click this and Enlist the Party, Enlist Party1 Then you come up with a Elist Party Properties dialog where you choose which of the ports defined in step 18 to use:

  21. After that is completed, you can enlist the orchestration and start throwing files, oh, here is a sample input to show you the data it was pulling:

Things to take away from this little tutorial:

Role Links allow you to create a lookup feature within an Orchestration to determine where to send the data, and still have all of the information available to be modified through the administration console.

The example here is for one business process, in my immediate need, for eligibility files, but later we are going to need to have a different location for claim files, while the party definition cannot change, I need to create new send ports, and then add them to the list of send ports in the party definition, and then when enlisting the role, I choose the newly created port! All VERY useful.

  • cal

    thanks Eric.

  • Dan

    Nice example. Quick question…what adapter was used for the send ports in step 17? EDI? FILE?

  • I used the file adapter, but lets just say that for the second one “E:\Role Link\Party2\%SourceFileName%.%MessageID%.xml” all I would need to do is change the adapter type from file to EDI and that port that is defined in the Send Port in the Party definition, would automatically be changed. This being said, when a file was processed by the orchestration, it would negotiate the party and then send it to Party2, that would then mean that it would be sent to the port that is now defined as EDI, and the first party is still sending it as a standard file.

  • JC

    Nice example…I’m trying to do similar things, but I’m having problems with the uri definition for the parties beiing comunicated…is there a way of especifying this uri? Do I need to specify the uri in the EDI file I have to trasnmit?

  • I am not sure what you are asking, please explain further.

  • mettlus

    What if I dont want to use Orchestration? We have a current solution in Bts2k2 (in which we drop the file after interrogation to party specific channel/port) using Bts API SubmitSync!
    How can we achieve similar stuff in bts2k6?

    Thanks

  • You should not have a problem as long as the Party is resolved in the recieve port. This example shows how to resolve the party just before it is transmitted and the party is not defined when it comes in. Let me know if this is not the case, or you have problems.

  • JJ

    Hi…

    I followed your directions exactly and when I run this, I get the following message in the event log:

    The published message could not be routed because no subscribers were found. This error occurs if the subscribing…

    So basically BTS is complaining that there is no subscriber. So in troubleshooting this, I added a filter to the send port based on the receive locaiton name and everything worked. The problem was, of course, that both send ports sent the message since they were essentially subscribed to the receive porets. This is clearly not the behavior that is intended.

    What am I missing?

  • Can you validate the input against the schema that you created in step 2? If you look at the Assembly Viewer, you should see the schema that represents your input.

  • JJ

    “Can you validate the input against the schema that…”

    Hi…that was my first step – in fact, I had BizTalk generate the instance document…all I did was add a value to the data element.

    This is a subscription problem since BTS does not seem to have a subscriber for the message.

    As I said, if I add a filter to the send port (BTS.ReceivePortName == TheNameOfMyReceivePort) all the suspended messages get picked up.

    This is great exept that the Role Link is supposed to pick the send port. So it appears that the role link is not working.

    Been looking at this for many hours and I know it should not be this difficult.

    If you have this as a download-able sample, maybe that could shed some light on this.

  • Oh, I thought that the orchestration was not picking up the messages, in that case, do you have parties listed if you were to expand step 19?
    I would be happy to send you the solution if you would supply a way to send it to you.

  • JJ

    Nailed it 🙂

    Of course it was something really simple – I swithced over to using the XML Transmit pipeline and it worked right away (was using the pass thru pipeline before … I should have known better).

  • Great, hopefully you now understand the potiential in using role links. For me it was the realization that the IT Pro can add/remove ‘trading partners’ destinations without the developer having to do any behind the scenes work. There was not a seperate database that contained connection information that needed updating, everything can be managed through the BizTalk adiministration console.

  • JJ

    Yes…I agree…this approach is very useful. I have used this before, but it has been a while and I was trying to set this up again in a new solution for another customer, so I was rusty.

    The tough part is getting others that don’t know how this stuff works to understand the positive implications this has.

  • mettlus

    Can u explain a little more, how can a party be resolved in the reecive port? and once its resolved how do I route it to its sepcific destination… not using Orchestration!

    TIA

  • You can resolve the party in the recieve pipeline, as discussed via an example in the Custom Party Resolution Example
    As far as not using an orchestration, you can easily use a filter in a send port to not have to invoke an orchestration.

  • Tony

    This was a very useful article, thanks.
    I am using BT2004 and implemented this ok. However I cannot seem to get the exported bindings installing correctly. If I deploy the assembles manually and then import the binding.xml using the Deployment Wizard then all is well. If I include the binding.xml in my installer then the installer completes successfully but no ports are installed. Any ideas?

  • What normally happens is that when you are installing it into a different enviornment, and the new enviornment does not have the same permissions as the prior enviornment or if you look and you will see that the password is *’d out you will need to update the binding file with correct password.

  • Sravan Kasyap K

    This was a very useful article. I have a biztalk interfacing architecture scenario which I have posted in the msdn biztalk forum. I am looking at different ways to implement the same. The link to the article is as below.
    http://social.technet.microsoft.com/Forums/en/biztalkgeneral/thread/7ac98280-6a71-47e8-96b9-72ed3768fb1c?prof=required

    Do you think i can implement the scenario using Role Links? Any help will be greatly appreciated.

  • Priyadarshini

    can u give an example and show how to create role links without orchestration. as in my scenario we have a send port and a party attached to it we need to create a role link send port resolution through any dummy party created.