BizTalk 2010 Party Migration Tool Issues & Workarounds

Introduction

Back during the BizTalk 2010 beta I was testing out the Party Migration tool. This tool enables a smoother migration path from BizTalk 2006 R2 and BizTalk 2009 to BizTalk 2010. It is very useful once you get it to run successfully. Back during the beta I experienced quite a few issues and apparently these issues remain in the final version (RTM) of the tool. This post will describe these issues and give the full steps for a workaround. I am using very similar steps I used during the beta here.

Issues

The party migration tool can be found on the install media at <install media path>\core\BT Server\PartyMigrationTool\PartyMigrationTool.exe. The help description found at http://technet.microsoft.com/en-us/library/aa578307(BTS.70).aspx mentions this should be run from a CD.  It would be nice to know this when trying to run the tool but this is not mentioned in the error messages.

Back during the beta the files were distributed just as they are now with the BizTalk 2010 Developer edition – as an extractable exe that does not come as an ISO. This is problematic because the intention for running this tool is that it will be loaded on an ISO or removable media. So you will need to either burn an ISO or use a workaround.

This tool does require you to right-click Run as Administrator or to execute it from an elevated prompt. Otherwise you will get odd CAS errors:

Request for the permission of type ‘System.Security.Permissions.UIPermission, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089′ failed.. For more details please see the event log.

Initially, if you are using the BizTalk 2010 Developer edition or have not burned an ISO, and try to open the PartyMigrationTool.exe you will receive assembly not found errors like this:

System.IO.FileNotFoundException was unhandled
Message: Could not load file or assembly ‘Microsoft.BizTalk.Migration.PartnerManagement, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35′ or one of its dependencies. The system cannot find the file specified.

If you run off the ISO or removable media everything works but there is another way for this to work.

Workaround

1. If you are using BizTalk Developer edition or did not make an ISO, go to the PartyMigrationTool folder. Keep this open.
2. You will need to add 3 assemblies to the GAC next. I found it easiest to copy these three assemblies to the PartyMigrationTool folder to keep everything together. All of these assemblies are found on the BizTalk 2010 install media. The assemblies you will need are:
   a. Microsoft.BizTalk.B2B.PartnerManagement.dll in \core\BT Server\MSI\Program Files\Developer Tools
   b. Microsoft.BizTalk.Migration.PartnerManagement.dll in \core\BT Server\MSI\Program Files
   c. Microosft.BizTalk.Migration.PartnerManagement.XmlSerializers.dll in \core\BT Server\MSI\Program Files
3. [Note]: I had previously recommended modifying the PartyMigrationTool.exe.config to redirect the assemblies but upon retrying with the RTM bits I thought it was just easier to GAC everything necessary. 2.a. fails anyway because there is not an entry for it in the config.

I did want to mention one other note. When you finally get the tool running, you will need to connect to SQL Server using Windows authentication, SQL authentication is not supported.

Thanks,

BizTalk 2010 Beta Notes and Details

 
Initial Thoughts / Experience
 
I have been testing the BizTalk 2010 beta for about a week now and have been actually having pretty good success with it. I have configured all of the features successfully in the base install, setup the WCF LOB SDK beta, setup the BizTalk adapter pack, setup the ESB toolkit 2.1, and setup both the RFID server components and RFID mobile. The UDDI install on the BizTalk 2010 beta has also gone successfully. So the good news is that this beta is pretty stable in my experience. My environment includes Windows Server 2008 R1 (W2K8 R1), SQL 2008 R1, and VS 2010 RTM Premium. I wanted to mention a couple items for those people who are trying the 2010 beta bits based on the installs:
 

• Start with a fresh VM if possible
• Make sure you have uninstalled all pre-release .NET 4 bits such as the client profile and extended profile otherwise your VS 2010 application will not work properly. Ensure you have all of the .NET 4 RTM versions installed.
• Make sure you are using VS 2010 RTM.
• It is a good idea to uninstall the WCF LOB SDK from BizTalk 2009 before installing the WCF LOB SDK for BizTalk 2010. I had a failed install of the SDK for BizTalk 2010 when I did not uninstall the previous version of the WCF LOB SDK
• I was able to get the Notification Services hotfixes from BizTalk 2009 to install correctly on BizTalk 2010. As always, with new versions of BizTalk, some of the hotfixes no longer work but fortunately these are working fine. Here is the URL for getting these: http://support.microsoft.com/hotfix/KBHotfix.aspx?kbnum=953752
• Some of the features of the new BizTalk 2010 are meant to run from a CD. So you want to burn an ISO of the extracted files to see this. Make sure your ISO burner supports a format like ISO+JOILET because there are some very long file names in the extracted files.
• (Cheesy tip #1): If you actually have to burn a CD in your ISO maker, you can remove the x64 folders from the extract for x86 target systems or vice versa to make all the files fit on a CD.
• Once you create an ISO, check out the PartyMigrationTool folder in the root folder of the install media. It has an exe with the same name for migrating the BizTalk 2006 R2 or BizTalk 2009 parties to the new trading partner agreement and business profile format, new for 2010.
• Do not try copying the PartyMigrationTool files from the CD to your VM or server – the config file pulls these using assembly redirects and it takes a lot more work to copy the file and all of its dependencies to get it to run correctly. You could alternately update the config for the tool to point to the corrected path to the MSI folder…

There are many new features to describe in BizTalk 2010. First of all, all of the improvements made with BizTalk 2006 R2 SP1 should be available in BizTalk 2010. I found the WCF extension behavior pop-up in the send/receive handlers for WCF-Custom to work and the certificate overrides for AS2 functionality is also working. I know some of these have been long awaited features that were not in BizTalk 2009. Here is a list of the features from R2 SP1 if you want to check on them: http://msdn.microsoft.com/en-us/library/ee532481(BTS.20).aspx.

Changes in BizTalk 2010

 

There is quite a bit of improved functionality as well as some new features as well. I will list out many of these features and then spend more time on some of them. Much of the documentation is now available in the beta. Please see http://www.microsoft.com/downloads/en/results.aspx?freetext=biztalk+2010&displaylang=en&stype=s_basic for a listing of downloads and documentation pieces. During BizTalk 2009 beta much of this was not available so a big kudos to the BizTalk documentation team for having this available with the beta!

 

Improvements

 

• Platform realignment, now officially supported for W2K8 R2, compatible with SQL 2008 R2, VS 2010, SharePoint 2010
• Updated BizTalk map VS extension – many new features such as copy/paste, easier to use interface for connecting lines, suggested mapping column hints, etc.
• BizTalk admin console changes in the organization of parties through business profiles and agreements
• Simplified console experience for host settings including new fields for many registry keys and config settings.
• Support for using .NET 4 although not complete at this point
• Many ESB Toolkit improvements.

One of the changes I am excited about is the way parties are handled within BizTalk 2010. One of the pain points for doing AS2 and EDI work in BizTalk has been the complexity of so many forms and screens for all of the many settings for the parties. The product group (PG) has been working on making all of this work more intuitive and has restructured both the party display in the BizTalk admin console and the layout of settings in the property pages.

Below you can see the new structure added to the admin console so you can classify more than one business profile (which represents the identifiers and settings for communications) for each organization:

 

 

For each business profile you can communication tabs based on message format (X12 or EDIFACT) or communication type (AS2). This is nice – you no longer are required to right-click on a party to get the AS2 or EDI settings . The use of a tool strip in the UI is a good modernization of the party manager. Perhaps we will also see icons or other wizard links here in the future. The AS2 profile selection is shown below:

 

 

The EDI selection is shown below:

 

 

Agreements form the basis for describing message exchanges and the layout for managing these has become more intuitive. In BizTalk 2006 R2 or 2009 it easy to get mixed up about “Party as Sender” vs. “Party as Receiver” when you have many transactions that can go either way. The following shot shows some visual cues to help with this:

 

 

In general, the party configuration has been organized and I think you will appreciate the ease of use compared to previous versions of the party settings pages.

There are lots more improvements, be sure to download a copy of the beta and test it out! I will be sure to post more on gotchas and workarounds as I find them so check back here! Thanks!

BizTalk EDI Routing Workarounds

I have been in the final stages of a large BizTalk EDI project and I have been struggling with the appropriate infrastructure for managing a single AS2 HTTP endpoint that interacts with a VAN over which multiple trading partners’ data is sent. The main challenge has been that if a single endpoint to BTSHTTPReceive.dll is exposed, it will provide data for many trading partners yet these partners may be used across one or more BizTalk applications. Since the endpoint usually exists as a 2-way receive port with As2EdiReceive/As2Send as the pipelines, I have been using send ports with filters to catch the messages after they are pushed to the MsgBox from the exposed endpoint. When just a single BizTalk application exists that includes the endpoint, all messages can be routed easily. But when more than one BizTalk application exists, it becomes much more complicated.

 

For example, if you have the exposed endpoint in Application 1 and two send ports in Application 2, these send ports will be able to pick up messages received on the exposed endpoint but you will see errors being logged from Application 1 that the messages could not be routed successfully. For this reason, I have found that it is important to have send ports that are used for picking up messages received through BTSHTTPReceive.dll in the same BizTalk application as the receive port for the endpoint. So I have written to disk the messages received from the endpoint that are used in other BizTalk applications as a way of offloading the messages to processes and orchestrations in the other BizTalk applications.

 

One problem with this approach is that sometimes the messages received in Application 2 do not have the correct ISA/GS headers or may have been altered through the application of the Global EDI properties. These properties can make understanding BizTalk routing very painful because they frequently cloud or disguise the intended recipient of messages. In my project, messages that are received in Application 2 have been placed in the correct folder so I know that the routing infrastructure was able to match the ISA and GS headers to the party properties, yet at some point during the routing the Global EDI properties were applied anyway. Today I identified a workaround for a situation in which a message has been routed with incorrect headers.

 

For send ports that have filters that write messages out to offload to other BizTalk applications, you can use a PassThruTransmit pipeline on the send port filter to write the body of an EDI message out to disk. You are probably thinking that this is crazy because this will represent the XML of the EDI message body. For me this worked great because the EDI message body stayed intact even when the EDI global properties got applied. Then on a receive port you can use the XmlReceive pipeline to pull in the message text written out via PassThruTransmit, which is an XML version of the EDI message body. This identifies the root of the message and identifies that it is the XML version of the message. In essence this functions a lot like an EDI receive without needing to worry about the resolution of the ISA/GS headers to determine the namespace because the namespace is included on the root of the EDI-XML message. So to summarize the process of getting an EDI message body from an exposed AS2 endpoint when the EDI global properties get messed up, use the following pipeline pattern in your ports:

 

BTSHTTPReceive.dll –> (R) AS2EdiReceive / AS2Send –> (S with Filter) PassThruTransmit –> (R) XmlReceive

 

Good luck to everybody working with EDI in BizTalk. Its easy once you get the hang of it, but until then its usually bumps and bruises.

 

Thanks,

Role Link Deployment Issue and Workaround

On my most recent project I am employing send port role links as a way to route messages within BizTalk for test and production EDI trading partners. This is one way to use a single orchestration for handling multiple trading partners (BizTalk parties). So in my orchestration instead of simply having a send port, I have a role link that contains a send port. Since the project’s deployment simply consists of a single server I am deploying directly from Visual Studio. During a recent round of changes I encountered an error that was consistently blocking deployment from Visual Studio. This error is given below:

 

Failed to update binding information.
Could not validate TransportTypeData, Address or Public Address properties for Receive Location <Receive Location Name>. Retrieving the COM class factory for component with CLSID {CFF09884-6582-49C2-A74F-0FD85849281E} failed due to the following error: 8007045a.

 

Another variation of this error is:

Failed to add resource(s). Change requests failed for some resources. BizTalkAssemblyResourceManager failed to complete end type change request. Failed to update binding information. Could not validate TransportTypeData, Address or Public Address properties for Receive Location <Receive Location Name>. Retrieving the COM class factory for component with CLSID {CFF09884-6582-49C2-A74F-0FD85849281E} failed due to the following error: 8007045a. 

These errors occur when trying to redeploy over BizTalk applications that use role links with send or receive ports. These deployments from Visual Studio have been attempted with the deployed BizTalk applications in both the enlisted/started and unenlisted/stopped states. I have found that these errors occur for me on more than one BizTalk development system, on both Windows XP and Windows Server 2003 systems, both running BizTalk Server 2006 R2. I was able to determine a modified deployment process to enable deployment to be successful in these scenarios. Here are the steps I came up with in order to successfully deploy a project with role links which is my workaround for the errors above:

 

1. Build/rebuild in Visual Studio in the build configuration you want to deploy under.
2. Stop the BizTalk application you want to deploy to.
3. Export the latest bindings for the BizTalk application. This will include information about all of the send and receive ports and role links. You may want to check to include the global party information in a separate file for an exhaustive binding backup.
4. Unconfigure the receive ports by right-clicking on the BizTalk application and clicking “Configure…”. I would specify <None> for the receive port bindings. Leave the role links completely configured and do not worry about removing the send ports from the BizTalk parties.
5. Delete the receive ports from the BizTalk application.
6. Deploy from Visual Studio
7. Reimport the bindings that you exported in step 3.
8. Make sure everything looks correct in the Configure window. The bindings should be rebound successfully.
9. Start the BizTalk application again.

This is a mysterious problem that was not solved by rebuilding or cleaning my BizTalk solution. At this point it may be a BizTalk deployment bug. The benefit of the workaround is that you do not need to unconfigure the role links themselves or modify the send ports specified for each party. With one role link you could have many configured parties so this workaround could save you a significant amount of time during deployment.

 

Thanks,

Another Way to Explain BizTalk Role Links

I am working on a project where I am extending a BizTalk application so that I can route messages from a single FILE port to different BizTalk applications and various orchestrations through the use of role links. Role links are one of the less frequently used and discussed tools of an experienced BizTalk developer. Getting my mind around role links was difficult because of the number of configuration details required to setup a role link. I am indebted to Eric Stott’s blog post at http://blog.biztalk-info.com/archive/2006/10/25/BizTalk_Role_Links_explained.aspx, but I think it would seem easier to describe role links as a precursor to the WCF binding architecture. I will describe some architecture notes on role links next but to see my thoughts on how role links are like WCF, skip on down a few paragraphs.  

 

Role links are essentially the opposite of dynamic ports. A dynamic port consists of one port that then has multiple variations of configurations based on the dynamic expressions applied to this port for one adapter. A role link is a static configuration but is essentially a collection of ports of different adapters. For a dynamic port there is not always an explicit party concept; in a dynamic port a message is being sent from one organization to some other variable organization. And in a role link a message is either being sent or received and is then one of a collection of organizations for each endpoint. Role links are based on ports that are designated as being associated with some BizTalk party. The party can have one or more aliases which act as destination tokens when used with role link based routing.

 

So here are a few examples of how role links could be used:

- When you need to have dev, test, and production parties all hosted in a single BizTalk application and merely need to differentiate logic for these parties based on ports

- When you need to expose a single business process to multiple parties without creating more than one orchestration to handle all of them.

- When you need more than 1 backup port in a BizTalk application

- When you are struggling to manage so many BizTalk artifacts and are looking for a way to reduce the number of orchestrations

- When you want a lightweight built-in BizTalk routing mechanism that has a simple but flexible mechanism for specifying a routing destination.

- When you want to expose more than one adapter for some organization as connectivity options

 

This last example of a role link use helped me think about a more contemporary example of a role link. In WCF when you expose a service, it is possible to expose more than a single endpoint for a service so that the organization that connects to the service can use either HTTP or TCP or some other protocol or set of binding options to connect to the service. This is frequently used to expose a WSI basic profile service for interoperability and a WS-* or SOAP 1.2 service for newer clients as in the following example: http://keithelder.net/blog/archive/2008/01/17/Exposing-a-WCF-Service-With-Multiple-Bindings-and-Endpoints.aspx. WCF provides the binding infrastructure so that it is possible for a client to have various options for connectivity. In the same way, role links provide a way to provide to a client multiple integration options that all get consumed into the same business process.

 

So role links are very similar to the binding infrastructure in WCF due to the trasnport-level flexibility both enable. If you are a BizTalk developer, you should take role links for a spin because they provide some very valuable extensibility options. It does take a while to get used to role link abstractions so I recommend taking WCF as a good example of what role links seek to accomplish and then throw adapters and parties in the mix and it makes much more sense. Have fun with role links!

Tips for “The Signing Certificate has not been configured for the AS2 party”

Recently I have been working on an AS2/EDI project at a client and have been struggling for a few weeks with a certificate issue. The situation I was having trouble with is that I needed to send an AS2/EDI message through BizTalk and have it digitially signed as well as encrypted. I had already distributed a public key to my trading partner, it was just that when trying to send the message out via BizTalk I would receive the error:

A BTS MIME error was encountered when attempting to encode a message. Error: The Signing Certificate has not been configured for AS2 party. AS2-From: <From Value> AS2-To: <To Value>
Event ID: 8132

Overall, the MSDN documentation on this issue (http://msdn.microsoft.com/en-us/library/bb967848.aspx) is pretty limited, and in the documentation at the link it mentions that this error occurs with the “BizTalk Server 2006 EDI”, when in fact it also occurs with BizTalk Server 2006 R2 EDI. This is just one of the many misleading details that make this a difficult issue to overcome.

 

So the documentation mentions that you need to provide a certificate for the BizTalk group through the group properties under the Certificate tab. A big gotcha to know about this is that the certificate must have the private key included. The following image shows what you should expect to see when a certificate includes the private key – a grey key symbol and note at the bottom of the view certificate window:

 

 

Depending on what adapters you are using with the certificate, you will also need to import this certificate to other certificate stores for other user accounts. The BizTalk environment I have been working with is a multi-machine install on a machine in a domain controlled by Active Directory. All of the BizTalk service accounts are domain accounts. What I had been doing for importing the certificates was that I created a custom MMC and then added all of the snap-ins for the different service accounts – one for the current user, one for the machine account, and then one each for the BizTalk AppHost and IsolatedHost accounts. One very important detail I did not understand about until today was that a service account’s certificate store was different when accessed from one user than another. So for example, I would login into the BizTalk Administrator account and add the Certificates snap-in for the BizTalk AppHost user (service account for the BizTalk Windows service and drop the certificates into the Personal store but I would still get the error.

 

Today I was looking at the following article – http://msdn.microsoft.com/en-us/library/aa559902.aspx#step5. This is the certificates setup step for the B2B solution. About halfway down the page you find a note that mentions you must login to the service account (interactively) in order to manage the certificates for this user. Usually service accounts do not have the right to logon interactively so this was something I kept overlooking. Once I enabled the BizTalk AppHost and IsolatedHost accounts the ability to login, and then I added the certificate to their personal certificates store I was able to get past the above message. The MMC snap-in framework perhaps disguises the fact that a certificate is not placed in the correct location for Personal certificates when logged in under a different user. The Certificates MMC makes it seem like you are adding a certificate to a shared storage location when in fact Personal certificates are more like an isolated, individual storage.

 

Another very important tip to know about is that you need to avoid enabling private key protection in the certificate with the private key or you will get additional error messages. Here are the messages I received when I did not disable private key protection:

A BTS MIME error was encountered when attempting to encode a message. Error: Exception of type ‘Microsoft.BizTalk.Component.MIMEException’ was thrown. HResult – 1061152225

The next error I saw in the logs was a little more helpful:

There was a failure executing the send pipeline: “Microsoft.BizTalk.EdiInt.DefaultPipelines.AS2EdiSend, Microsoft.BizTalk.Edi.EdiIntPipelines, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856as364e25″ Source: “AS2 encoder” Send Port: <Send Port> URI: <HTTP Address> Reason: The MIME encoder failed to sign the message because the certificate has private key protection turned on or the private key does not exist.

Please disable private key protection to allow BizTalk to use a certificate for signing.

This message means that the certificate that was loaded in a couple of certificate stores is protecting the private key and is not allowing it to be used by BizTalk. When exporting, be sure that you do not check the box for “Enable strong protection (requires IE 5.0, NT 4.0 SP4 or above) as seen below:

 

 

Also, when importing, do not check the box for “Enable strong private key protection. You will be prompted every time the private key is used by an application if you enable this option” as seen below in the following shot:

 

 

So as you can see, there are many pitfalls along the way to configuring a certificate for use with BizTalk. These tips should help clear up some of the gaps in the documentation.

 

Thanks,