BizTalk 2010 Party Migration Tool Issues & Workarounds


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.


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 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=, 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=, 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.


  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.


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:
  • 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:

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 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!
  • 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!

Another BizTalk/PeopleSoft Integration Option

As I am wrapping up my BizTalk EDI project I also wanted to mention that this project has incorporated a nontraditional integration option between BizTalk and PeopleSoft. Microsoft provides the BizTalk Enterprise Adapter Pack which includes the PeopleSoft adapter. This provides a way to integrate between BizTalk and PeopleSoft and provides a handy way for extracting the message schemas of the different services exposed by PeopleSoft via the Compontent Interfaces. These days PeopleSoft itself has its own EDI integration platform as well as the ability to interact with the Filesystem and so there are various layers of infrastructure within PeopleSoft that you can choose to integrate over.
On my project it was possible to map PeopleSoft flat-file formats to EDI message types and exchange the files over the network and then out to the VAN. So rather than work directly with PeopleSoft, the solution was to work across a file system, receiving PeopleSoft flat files and transforming them to EDI and then on receipt of EDI messages, transforming them into PeopleSoft flat file acknowledgements. In my opinion this was a less difficult implementation option than the use of the PeopleSoft adapter because you did not need to configure a Java environment or install a PeopleSoft component interface. Next I will give some details of the PeopleSoft flat-file format to give you a little more information about how involved the mapping was in this solution.
The PeopleSoft flat file format was based on 3 groups of positional lines, the first group always has one line for each transaction (multiple in a batch), then the second group has n lines below the first group and the third group has m lines below the second group. The first group is tagged with 000A, the second group with 100A and the third with 200A. So for basic EDI messages this nesting of groups corresponded pretty well with the traditional PO1, N1, and SCH loops. Unfortunately the message format in PeopleSoft is configurable in the PeopleSoft administrator website and it is possible to add or remove columns very easily so it is possible that a message format could be changed and result in a disruption of the BizTalk application that uses the messages. 
The benefit of using the PeopleSoft adapter is that you have a sure reference for the generation of the message types. This was by far the largest challenge of the project; knowing the format details for the PeopleSoft adapter is not documented that well and is variable based on the message type configuration. But if you do not have the security option to install a custom component interface for the PeopleSoft adapter or have other difficulties getting the PeopleSoft adapter to work, this post has provided you with yet another option for integration.

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. 🙂

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.

Some Tips on BizTalk AS2 Development

Here are a few tips I encountered when working on an AS2 and EDI project.
You will want to avoid using an EdiSend on the send side of a 2-way port in which the receive is As2EdiReceive because you will encounter EDI assembler errors where the SOAP messages are being run through the EDI assembler. Make sure to use just the As2Send on the send side of the receive port. The AS2 tutorial at mentions creating a 2-way port with As2EdiReceive/As2Send. This is the correct way of doing this.
When developing with EDI and AS2, you will eventually want to create a filter for receiving BizTalk NACKs that you may see with AS2 communications. You can create a send port filter using the filter property EDIInt.IsAs2Http200OKRresponse == true. This way if BizTalk does receive a NACK it will not log it as an error. This is a valuable tip for setting up an BizTalk environment for AS2 communications so that low-level AS2 message errors can be filtered out to a separate folder or location.

BizTalk Best Practice – Use Well-Known Identifiers for EDI Global Properties

When working on a BizTalk EDI project recently, I received some errors that seemed to be doing things that I had not configured BizTalk to do. The error messages were mentioning that a problem was occuring when sending an EDI message from Party A to Party B with a message namespace which was for an 850 response message but I had only configured Party B to send to Party A with an 855. It took me a long time to get my mind around what was happening until I looked at the EDI global properties. This new portion of BizTalk Server 2006 R2 provides a default catch-all party for messages that cannot be resolved for a party based on the ISA/GS headers. Essentially what happens when the BizTalk runtime is unable to resolve the ISA/GS headers on a message to a trading partner party, it will change the context properties and ISA/GS headers and then if these do not resolve to party or other errors are encountered, these will be logged. So if you are looking in the logs for an error message, what you see may not always be true to what you would expect. Here is a link to some more information on the EDI global properties –, and the role of the party in EDI processing –
For this reason, I have started using well-known identifiers in my EDI global properties so that if the BizTalk runtime cannot resolve the ISA/GS headers, at least I will know this after reading the Event Viewer log messages. So for the ISA 06/GS02 value I specify GLOBALSENDER and for ISA08/GS03 I specify GLOBALRECEIVER. Although I appreciate that BizTalk provides a fallback party resolver, this seems misleading or worse. Think for example if you specified a value for one trading partner as the fallback and then when you added another partner, it would be easy to wind up sending unsolicited messages to a different partner. Also, I think that if the party cannot be successfully resolved based on the ISA/GS headers, you need to know this rather than have the runtime substitute a value for you. The default values such as BTSSender are ok but do not convey the sense that they are coming from the global properties. BTW, the BTSGuestParty is another one of the built-in parties that operates on behalf of the BizTalk runtime, so watch out for this party as well. As far as I know, though, the ISA/GS headers for this party cannot be configured.

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 ( 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:
Private Key Image-sm 
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 – 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=, 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:
export cert shot
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:
import 2
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.

BizTalk AS2 and EDI error documentation

Today while working on debugging some AS2 and EDI message tests, I encountered an MSDN area that I realized needs to be more heavily documented. Whenever I encounter an error number or code in the event log I have to go to a search engine and look it up to find out more information on the error. Many times the error codes are documented on 3rd party websites where Administrators can punch in a hex value to determine the error category. Today I was trying to get to the bottom of an EDI error and found the following MSDN listing of AS2 and EDI error details: If you go to this link the article itself will not have any subarticles linked below it. You will need to use the table-of-contents on the left frame to see all of the subarticles, which represent all? of the different errors you might receive when doing AS2 and EDI processing in BizTalk. Each of the articles for the errors also suggests some possible resolution strategies, which is really helpful. I just wanted to pass along this information for anyone doing diagnostics on AS2 and EDI processing in BizTalk because this is helping me enormously.

PeopleSoft EDI Resources

I am currently working at a client who is integrating PeopleSoft EDI files over BizTalk to the GXS Trading Grid. From an investigation of the number of people who have integrated PeopleSoft with BizTalk, this appears to be a pretty big frontier. I wanted to post a few helpful resource links for working with PeopleSoft and EDI. Fortunately, there is some really good documentation produced by PeopleSoft about the EDI capabilities of PeopleSoft and the EDI formats that their products support. The most important resource I have found to date is the PeopleSoft Enterprise EDI 9 Peoplebook –, which includes descriptions on how to setup EDI inbound and outbounds transactions. This PDF book also gives a list of the individual X12 EDI format messages that individual products within the PeopleSoft Financials & Supply Chain suite can export. Its particularly interesting to see that different products within the suite can export different versions of EDI schemas. For example, an 850 message can be generated from the Purchasing application as well as the Sales application.
The PeopleSoft adapter as part of the Enterprise Applications adapter pack is another way to integrate between PeopleSoft and BizTalk. I will be posting more details on how integration with PeopleSoft goes and whether there are any gotchas to watch out for. Here is a tutorial for setting up the PeopleSoft adapter:

Blog at

Up ↑