Posts Tagged BizTalk 2009
I have been working on an effort to add some automation around processing of emails. In the past I have worked with the built-in POP3 adapter and also the N Software mail adapters found here: https://www.nsoftware.com/products/biztalk/adapters/emails.aspx. The built-in BizTalk mail adapters are not secure because POP3 and SMTP send cleartext passwords. In organizations that use mail functionality in BizTalk it is very important to implement this securely. N Software provides secure receive email support over POP3 and IMAP but these options are not always enabled on Exchange servers.
Today I renewed my search for a good MAPI/Exchange adapter solution. In this post I am going to look at the Kayxo (MAPI) Exchange Adapter and attempt to aggregate some information that is just not in a very good form on the web right now. I will also give some details on some so-far undocumented configurations and how well they are working.
Downloading the Trial
I have been down this road before and find it is typically very hard to get good information about the available BizTalk MAPI adapters in the marketplace. One of the vendors, Kayxo has a very bad website (www.kayxo.com). On many occasions I have not been able to get the site to work at all. Most of the time the home page just gives you a few email links to get more information about the company. If you do some more search engine investigation, you find there is more information, just not linked off the home page. A good overview page is here: http://www.kayxo.com/products/keab_biztalk_partners.php. If you click on the free trial it brings us to a page that looks like an old table of contents: http://www.kayxo.com/downloads/downloads.php. Here is the link to the install guide in case their site dies again: http://www.kayxo.com/downloads/keab_docs/KEAB_InstallationGuide.pdf.
If you try these links you notice PHP errors all over the page – like they have not updated their site in a while. This kind of spotty experience does not fare well if you are looking for a custom adapter, but keep reading, the story does get better.
On the download page there is a link to download the BizTalk adapter (it has a black background) but when clicking on it you just get another PHP/MySql error message (http://www.kayxo.com/downloads/kayxo_exchange_adapter_biztalk.php):
Warning: mysql_connect() [function.mysql-connect]: Lost connection to MySQL server during query in /home/content/k/a/y/kayxo/html/kayxo/includes/configuracion.php on line 8
Could not connect: Lost connection to MySQL server during query
Apparently they are not very good at working with PHP. 🙂 So I tried clicking on the other links and noticed a naming convention for the downloads. So I tried a few attempts at figuring out the download path. Here it is: http://www.kayxo.com/downloads/keab.zip. I was able to download the 8 MB file and this was the start of a fairly good trial experience.
After downloading the file you can then open the installer and it loads for a while. Back on the overview page (mentioned above), there is a link to the install guide for the adapter. Be sure to download this – it helps make the install process go smoother. The install guide mentions supporting BizTalk 2006/2009. So far in my experience, I have been able to install it successfully on BizTalk 2009 where CU 1 existed. My other config specs were W2K8 [R1], SQL 2008 SP1 CU 1. On my VM I have Office 2010 installed. The install guide for the Kayxo installer says Only Outlook 2003 and 2007 are supported but I was able to get everything in the trial to install successfully with Office 2010.
[Important!] One of the steps of the configuration is to specify the credentials to login into Exchange with. It seems like this would be easy, just specify the domain\username and password, but the wizard has the domain\username part grayed out and just pulls it from the current thread. You actually have to login with these credentials in order for it to pull the correct credentials. So this means you should only try out this adapter on a computer that is part of the same domain as your email server.
There are a couple steps during the installation that seemed a little odd, so my tip for the install is to be sure to read every word that appears on the screen. Right before the install there is a wizard that has you specify a few setup options. One of the screens asks for the database information. Here is the screenshot from the install guide:
The default value given for server is localhost. So if you do not read the heading (very easy to miss), it looks like you are specifying your IIS server name. The first time through here I missed the heading and what do you know, it cannot find a SQL Server at localhost. This is actually the page you specify the database name. So remove “localhost” and provide the SQL Server instance name here. Then you will get to run the installer. The installer creates the program directory, registers 2 adapters with the BizTalk administration console, and adds some extensibility inside Visual Studio. There is actually quite a bit of functionality provided with the trial but you do have to discover some of it on your own.
If you open the install folder at C:\Program Files (x86)\Kayxo\KEAB you will see the installed files. There is an SDK folder which gives you a good idea of what the BizTalk messages and schemas will look like. For example, if you then open SDK\KEAB_Sdk_KeabSampleMove\Folders\Inbox\MailSample_PutInsideInFolder.xml, you will see a sample file. Here is this same sample file. If you look at the file it is based roughly off of a name/value approach with a little bit more structure. The format basically revolves around the MAPI properties. One tool I have found helpful to understand these is called Outlook spy: http://www.dimastr.com/outspy/. In MAPI there are hundreds of properties for the different objects in Exchange. You need to know quite a bit about the MAPI properties in order to effectively use the Kayxo adapter.
To explain more of this, you can open some files within the Kayxo install folder to get a better handle on some of the details. Open C:\Program Files (x86)\Kayxo\KEAB\MapiProperties.xml to find a listing of all of the different MAPI properties that the adapter knows about. Each has a tag associated with it. I am guessing the parsing engine creates a sort of keyed dictionary for the MAPI properties and then can serialize the properties as part of the message. The tool found in the start menu known as the KEAB Write Message Creator is helpful too for generating a message structure based off the MAPI properties.
After the installer finishes, there is a tricky configuration wizard to work through. Unfortunately the install guide does not really help us that much from a diagnostic perspective. You have to read the install guide word-for-word all the way through to find out enough tips to work through the configuration wizard.
If you have Outlook already loaded on your computer and you can connect to your mail server then you will need to be sure that your profile is not in Cached mode. I am not sure what this means, but it is important to know. Here are some directions for disabling this in Outlook 2010:
- Open Outlook 2010, authenticate
- Click File\Account Settings\Account Settings button
- Find your profile and then click Change…
- Under your Server find the “Use Cached Exchange Mode” checkbox and be sure it is cleared.
- Click Next, and then Finish
You should right-click “Run as administrator” to run the “KEAB Configuration” start menu item to start the configuration wizard. Not doing this will result in you getting some access denied error messages. Then you just have four pages of a wizard to fill out. These pages are documented well in the install guide.
I will be trying to expand this content with some more screenshots and will provide other tips here as well.
I did some more search engine investigation and found some good YouTube videos on the adapter: http://www.youtube.com/results?search_query=keab+biztalk&aq=f. The send and receive port ones show a very rich adapter experience so be sure to check these out.
The latest BizTalk 2009 cumulative update (CU) rollup hotfix pack has been released. This is the first installment for BizTalk 2009. Here is the Microsoft KB article: http://support.microsoft.com/kb/2429050. This includes numerous VS development environment fixes and a wide assortment of adapter support updates. This rollup pack also includes support for the HIPAA 5010 EDI schemas.
Recently I heard from Microsoft that there is now a new release model for hotfix rollups for BizTalk. The new model is similar to the service pack model (like with BizTalk 2006 R2 SP1) but is known as a Cumulative Update (CU). From what I have heard this is to provide greater frequency to the collective hotfix releases and a more predictable iteration for releases. This model is similar to what is being done with SQL Server and SharePoint Server. This new model of releases applies to all currently supported BizTalk versions including BizTalk 2006 R2 SP1, BizTalk 2009 and BizTalk 2010. Cumulative updates should be applied after running the older rollup of SP1 for BizTalk 2006 R2. It may seem like old news since BizTalk 2006 R2 SP1 is already at CU 3 but I had not heard many announcements about this or people mention CU 3 so I think most people do not know that the rollup release model was changed.
The BizTalk Developer Center Support page at http://msdn.microsoft.com/en-us/biztalk/aa937674.aspx mentions a little more about the new CU model, that the expected frequency is every 2 months, and that each subsequent CU will include all previous CU hotfixes. I was wondering what was the best way to find all of the latest CU releases and the way that worked for me was to search at support.microsoft.com for “BizTalk cumulative update”, so here is the link for this: http://support.microsoft.com/search/default.aspx?query=biztalk+cumulative+update&catalog=LCID%3D1033&mode=r. The released CU versions show up at the beginning of the search results, ordered, nice and easy.
At this time the CU releases are not being localized so if you are using a localized version of BizTalk you will need to install the English version of the CU. If you encounter any issues with the English CU release on your non English system you should report this as a bug so that a corrected localized version of the CU may be created.
BizTalk 2006 R2 SP1 CU 3: http://support.microsoft.com/kb/2286501/en-us
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 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=18.104.22.168, 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=22.214.171.124, 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.
- If you are using BizTalk Developer edition or did not make an ISO, go to the PartyMigrationTool folder. Keep this open.
- 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
- [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.
Based on a thread today on the MSDN forums I tried working with BizTalk 2010 RTM and the Commerce Server 2007 adapters. These are the same adapters used for Commerce Server 2009. I had worked with these adapters on a recent project with BizTalk 2009. I just wanted to post that the adapter install went successfully and I was able to add the adapters in the BizTalk 2010 administration console and able to create ports like normal. So this is an excellent compatibility story.
I had already confirmed these adapters worked with W2K8 R2 about a year ago. My test today of BizTalk 2010 RTM was also on W2K8 R2 with SQL 2K8 R1. Be aware that I only tested the BizTalk adapters and did not work with the Commerce Server business applications or any other aspect of Commerce Server.
Last year Cactus eventually certified/verified that these same adapters appeared to work successfully with BizTalk 2009: http://blogs.msdn.com/b/rdonovan/archive/2009/07/22/biztalk-server-2009-now-works-with-commerce-server.aspx, so I would expect a similar announcement eventually.
As part of my work installing the ESB Toolkit 2.0 on BizTalk 2009 I have been encountering some significant traps in the configuration of VS 2008 Team Suite and ESB Toolkit 2.0. I have found that it is very important for you to install Visual C++ as part of the VS 2008 install if you want to build the ESB Toolkit locally. This is not a directly expressed dependency in the documentation so this is something to watch out for. On my VMs to preserve space I will typically avoid installing extra features (such as C++, SQL replication, or Books online) that I usually do not need on the applications I work with but I found out the hard way that you should not take the C++ shortcut with the ESB Toolkit.
Another gotcha I have encountered deals with the Windows SDK 6.1. The current version of the ESB Toolkit 2.0 install documentation will refer you the SDK 6.1 download but I think the install originally referenced Windows SDK 6.0A. For all general purposes, the SDK 6.1 is fine but you are recommended to also install a hotfix, http://support.microsoft.com/kb/974479 if you install the SDK 6.1 after having installed VS 2008 SP1. This hotfix overcomes some of the changes brought with 6.1 that alter the behavior of the SDK 6.0A. VS 2008 itself installs the SDK 6.0A if it is functioning correctly. The problem I experienced was that VS 2008 Team Suite does not work properly after VS 2008 SP1 and this leads to many unresolvable problems.
The issues I experienced were because VS 2008 Team Suite does not correctly keep track of the installed features after VS 2008 SP1 is installed. The Team Suite installer behaves unpredictably and will not adequately keep track of the extracted files found in C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC or C:\Program Files\Microsoft SDKs\Windows\v6.0A. If I leave C++ checked during the Team Suite install I will usually always need to go back and repair the install after VS 2008 SP1 because some of the C++ components will be missing or the Windows SDK 6.0A files will be missing by the time I try to compile the ESB Toolkit.
One of the problems I experienced included the problem of the VS 2008 Team Suite installer giving the message (similar to problem identified in this thread: http://social.msdn.microsoft.com/Forums/en-US/vssetup/thread/2f3d0378-3175-49ae-acb7-012594a1bf3c):
A selected drive is no longer valid.
The install order I took when encountering this issue was:
- BizTalk prerequisites – W2K8 R1 x64, SQL 2008 R1, SQL 2008 R1 SP1
- VS 2008 Team Suite with C++ unchecked (SQL express was also unchecked)
- VS 2008 SP1
- BizTalk 2009 x64
- Other BizTalk 2009 installs such as WCF LOB SDK, Adapter Pack, etc.
- BizTalk 2009 ESB Toolkit Pre-Requisites such as MSChart, VS 2008 SDK
- Windows SDK 6.1
Unfortunately, I was not able to come up with a corrective solution for handling this configuration incompatibility. I tried a couple things but was unsuccessful:
- Install the hotfix 974479 which should resolve most of the problems with the Windows 6.1 and VS 2008 SP1. I was still unable to get the VS 2008 Team Suite installer to work
- Uninstall the hotfix 974479.
- Uninstall Windows SDK 6.1
- Uninstall VS 2008 SP1
These last attempts certainly show some despiration but I found that once the Windows SDK 6.1 is installed the VS 2008 Team Suite installer seemed to me to always fail. VS 2008 SP1 is a requirement for BizTalk 2009 so I could not choose to avoid this. I recommend avoiding the Windows SDK 6.1 if possible on a computer or VM with VS 2008 Team Suite and SP1 otherwise you may not be able to compile the ESB Toolkit.
Lately I have been working on building out some VMs for working with BizTalk 2009/ESBT 2.0 and for BizTalk 2010/ESBT 2.1. I am working on a project that is targeting BizTalk 2010/ESBT 2.1 but there is a feature we would like to use which is currently only compatible with BizTalk 2009/ESBT 2.0. So I am working on managing the feature migration as well as planning for how things will work with BizTalk 2010.
One of the proprietary systems I work with uses a named instance in development for the SQL database and no default SQL instance exists. To keep everything relatively simple I have been installing BizTalk on the same named SQL instance. For most of the BizTalk prerequisites and setup this is straight-forward, but once I start working on the ESB Toolkit there are so many changes to make because the ESB Toolkit samples are all based on a default SQL instance.
It seems that the documentation is quite poor in this regard so I wanted to make a list of the things I have had to change to get a named instance to work properly. I did see Andy Morrison’s article mentioning bits of my content at http://geekswithblogs.net/andym/archive/2010/02/02/137753.aspx but it does not mention all of the relevant items specifically for a named instance. Some of the items listed below are steps done before the ESB Toolkit itself but I am including them here for completeness.
- Install SQL using a named instance
- Configure BizTalk using the named instance. Most of the steps in the wizard will work automatically(if SQL is local) but the BAM Tools lines for BAM Analysis and BAM Star Schema databases will still require you to manually enter the named instance information.
- The UDDI configuration wizard will pick up the named instance automatically (if SQL is local) so no extra work here.
ESB Toolkit Setup
- During the ESB Toolkit Configuration Tool you will need to specify the name of the named instance. If SQL is local you can use “.\<instance name>”.
ESB Toolkit Management Portal Setup
- Edit the web.config in c:\Projects\Microsoft.Practices.ESB\Samples\Management Portal\ESB.Portal
- Edit the App.Config in c:\Projects\Microsoft.Practices.ESB\Samples\Management Portal\ESB.UDDI.PublisherService
- Edit the web.config in c:\Projects\Microsoft.Practices.ESB\Samples\Management Portal\ESB.Exceptions.Service\ESB.Exceptions.Service
- Edit the App.config in c:\Projects\Microsoft.Practices.ESB\Samples\Management Portal\ESB.Exceptions.Service\ESB.Exceptions.Service.Implementation
- Edit the web.config in c:\Projects\Microsoft.Practices.ESB\Samples\Management Portal\ESB.BAM.Service\ESB.BAM.Service
- Edit the App.config in c:\Projects\Microsoft.Practices.ESB\Samples\Management Portal\ESB.BAM.Service\ESB.BAM.Service.Implementation
- Edit the App.config in C:\Projects\Microsoft.Practices.ESB\Source\Samples\Management Portal\ESB.AlertService
- Open the ESB.Portal solution in C:\Projects\Microsoft.Practices.ESB\Source\Samples\Management Portal\ESB.Portal and do a find on “data source=” to find a few other locations where the default SQL instance is used with Entity Data Models and other files
- Open the ESBFunctions.ps1 file in C:\Projects\Microsoft.Practices.ESB\Source\Install\Scripts and search for “sqlcmd” to find places where SQL is being called using the default instance. I did a find/replace on “sqlcmd” and replaced it with “sqlcmd -S .\<instance name>” because my named instance was local. You can enter something different if your named instance is remote.
As you can see, there are so many different places that must be changed in order to use the ESB Toolkit with a named SQL instance. This list holds true for both BizTalk 2009 and BizTalk 2010.
<MSBuild Projects =“$(SolutionName)“ Properties=“Configuration=$(ConfigurationName);“/>
<CallTarget Targets=“ApplyBindings“ />
<BizTalk.BuildGenerator.Tasks.StartApplication MessageBoxConnection=“$(BizTalkManagementDatabaseConnectionString)“ ApplicationName=“$(ProductName)“/>
<CallTarget Targets=“UnitTests“ Condition=“$(IncludeTests)“ />
System.IO.FileNotFoundException: The system cannot find the file specified. (Exception from HRESULT: 0x80070002)
at System.Reflection.Assembly.nLoadFile(String path, Evidence evidence)
at System.Reflection.Assembly.LoadFile(String path)
at BizTalk.BuildGenerator.BizTalkHelper.AddResourceReferences(Resource resource, ApplicationResource applicationResource)
at BizTalk.BuildGenerator.BizTalkHelper.DescribeApplication(String applicationName)
at BizTalk.BuildGenerator.UI.WizardForm.ChooseApplicationPage_BeforeMoveNext(Object sender, CancelEventArgs e)
at Divelements.WizardFramework.WizardPageBase.OnBeforeMoveNext(CancelEventArgs e)
at Divelements.WizardFramework.Wizard.c(Object A_0, EventArgs A_1)
at System.Windows.Forms.Control.OnClick(EventArgs e)
at System.Windows.Forms.Button.OnClick(EventArgs e)
at System.Windows.Forms.Button.WndProc(Message& m)
at System.Windows.Forms.Control.ControlNativeWindow.OnMessage(Message& m)
at System.Windows.Forms.Control.ControlNativeWindow.WndProc(Message& m)
at System.Windows.Forms.NativeWindow.Callback(IntPtr hWnd, Int32 msg, IntPtr wparam, IntPtr lparam)