Archive for January, 2011

New BizTalk articles on TechNet Wiki

Here are a few TechNet Wiki articles that have become available recently. I have usually found it difficult to find relevant content on the TechNet Wiki so I thought it would be good to highlight a few of these.

Improving performance when executing a BRE rule: http://social.technet.microsoft.com/wiki/contents/articles/high-cpu-when-executing-a-business-rules-engine-bre-policy.aspx

Implement ordered messaging with BizTalk and SSIS: http://social.technet.microsoft.com/wiki/contents/articles/implementing-end-to-end-ordered-delivery-using-microsoft-biztalk-server-and-sql-server-service-broker.aspx

BizTalk load testing in VS 2010: http://social.technet.microsoft.com/wiki/contents/articles/load-testing-biztalk-server-solutions-with-visual-studio-2010.aspx

Load testing for simultaneous BizTalk unit tests: http://social.technet.microsoft.com/wiki/contents/articles/create-a-load-test-to-perform-multiple-unit-tests-simultaneously.aspx

Install and configure BAM in a multi-server environment: http://social.technet.microsoft.com/wiki/contents/articles/install-and-configure-bam-business-activity-monitoring-in-a-multi-computer-environment.aspx

Thanks,

, , ,

Leave a comment

Why would you want a WCF LOB SDK Adapter?

Introduction

In my last post I mentioned the registry content for registering a custom WCF LOB SDK binding as an adapter. I am still working out the details of how this should be done for a custom adapter and will be hoping how to do this in a walkthrough in a later post. 

To give you some preview of the process, the adapter class just needs to inherit from Microsoft.Adapters.Common.BizTalk from the BizTalk adapter pack rather than Microsoft.ServiceModel.Channels.Common.Adapter from the WCF LOB SDK. The abstract classes for Microsoft.Adapters.Common.BizTalk are included with the BizTalk Adapter Pack. The GUID values mentioned in the .reg file are set in the derived adapter classes and when calling the base class constructor for the adapter, WcfBtsAsdkAdapterBinding.

While it looks like it is possible to register a custom WCF LOB SDK binding as an adapter, the question comes up as to why would you ever want to do this when you can just use the custom binding in the WCF-Custom adapter anyway. This is one question I have asked repeatedly in reference to why the BizTalk adapter pack gives the developer the option of using the separate adapter rather than the bindings with the WCF-Custom adapter. At this time I am not sure if some of the scenarios I have come up with explain why the BizTalk adapter pack bindings are also exposed as custom adapters.

I wanted to take this post and describe a few scenarios that would be useful for having the capability of an adapter rather than a WCF-Custom binding.

Discussion

Deciding whether to expose a WCF LOB SDK binding vs. a full adapter is an important question that depends largely on the consumers of your data. If you want the same data and management of the connection to your data to be the same whether it is being called from .NET or BizTalk then use of the standard custom binding makes sense. You will only need to code the logic once as the custom binding. But there are typically many differences between .NET applications and BizTalk applications so it seems like there would be compelling reasons to have other settings or different settings based on whether the binding is being called from a BizTalk system. For example, SSO settings like the SSO Application Name and key should not be exposed unless the binding is being called from BizTalk. These properties will not make sense if you are providing a way to connect to your custom LOB data without going through BizTalk.

The full adapter does have a configuration limitation that prevents it from fully functioning as an equivalent to the WCF-Custom binding. The custom binding configuration exposes the custom behavior config window for all WCF-Custom adapter handler properties. At this point I am not sure if it is possible to have the custom full adapter to provide a customized property page for the adapter handler properties. Interestingly, all of the BizTalk adapter pack custom adapters have the properties button grayed out in the adapter handler window.  So it is not even possible to choose the same adapter handler configuration as found on the WCF-Custom adapter handlers so if you did use a full adapter rather than WCF-Custom you would still need to register the custom WCF behaviors in the machine.config. This could possibly be an overlooked scenario in the current implementation.

So theoretically it is possible to come up with a reasonably good scenario for splitting apart the properties and implementation based on the caller type. But due to the current BizTalk admin console limitation on the adapter handlers configuration, there may unfortunately be some tradeoffs.

Thanks,

, , ,

1 Comment

Sample .reg file for WCF-LOB SDK Adapter registration

On the forums today someone was asking how to register a custom adapter based on the WCF LOB SDK. The question was not how to get it to show up in the bindings list for the WCF-Custom adapter, it was how to get the custom adapter to show up as an actual adapter. With the BizTalk adapter pack, the custom adapters show up both as custom bindings under the WCF-Custom adapter and as custom adapters under Platform Settings\Adapters. The WCF LOB SDK gives good examples for how to register the custom binding and there are some free tools to help with this like this one: http://regwcflobmsbuildtask.codeplex.com/. But there are not any .reg files in the samples folder for the SDK like there are for the samples found at c:\Program Files (x86)\Microsoft BizTalk Server 2010\SDK\Samples\Adapter Development\…

I developed one custom adapter using the older adapter framework for a major client to interface with the Endeca search index tool (www.endeca.com). Based on my experience working with the adapter framework, I knew there was probably a GUID value I could use to find the registry settings for registering a WCF LOB SDK adapter. So I opened the WCF-SQL adapter assembly in Reflector and found the GUID value. Then I opened the registry and searched it under HKLM\Software\Microsoft to find the registry keys for the WCF-SQL adapter. Although this was not surprising to me, it was interesting to see that many of the registry values are similar to the values given for the adapter framework settings in the .reg files of the SDK samples.

Here is the WCF-SQL adapter registry content – shown below. Here is a link for just downloading the .reg file. This seemed like a missing sample file so I will be working on taking the Contoso and Echo adapters and creating registry files for them. There are a couple logical questions about what to do to your custom WCF LOB SDK code in order to make it work with the .reg file so I will be working on that next. Having the .reg file available makes it a lot easier to accomplish the adapter registration.

Thanks!

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{59b35d03-6a06-4734-a249-ef561254ecf7}]
@="WCF-SQL"

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{59b35d03-6a06-4734-a249-ef561254ecf7}\BizTalk]
@="BizTalk"
"TransportType"="WCF-SQL"
"Constraints"=dword:0000030b
"ReceiveLocation_PageProv"="{86e62ea8-d681-4aac-a62b-f8e7dc0306b4}"
"TransmitLocation_PageProv"="{ea897b1c-08b9-4d21-87fa-223f7fc5acf3}"
"AdapterMgmtCLSID"="{dea558d0-6960-4f96-9bc7-9b3837689fc0}"
"AdapterMgmtTypeName"="Microsoft.Adapters.Sql.BizTalk.WcfBtsSqlManage, Microsoft.Adapters.Sql.BizTalk, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
"InboundEngineCLSID"="{1ad7c0c2-cdd2-4e87-922c-6e89d9f8b0e2}"
"InboundTypeName"="Microsoft.Adapters.Sql.BizTalk.WcfBtsSqlReceiver, Microsoft.Adapters.Sql.BizTalk, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
"OutboundEngineCLSID"="{6a640a11-2f39-42eb-96c7-490aac4f32f6}"
"OutboundTypeName"="Microsoft.Adapters.Sql.BizTalk.WcfBtsSqlTransmitter, Microsoft.Adapters.Sql.BizTalk, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
"PropertyNameSpace"="http://schemas.microsoft.com/BizTalk/2006/01/Adapters/WCF-properties"
"AliasesXML"="<AdapterAliasList />"
"ReceiveHandlerPropertiesXML"="<CustomProps><WcfExtensions vt=\"8\" /></CustomProps>"
"ReceiveLocationPropertiesXML"="<CustomProps><Headers vt=\"8\" /><BindingType vt=\"8\" /><BindingConfiguration vt=\"8\" /><ReferencedBindings vt=\"8\" /><ServiceBehaviorConfiguration vt=\"8\" /><EndpointBehaviorConfiguration vt=\"8\" /><InboundBodyLocation vt=\"8\" /><InboundBodyPathExpression vt=\"8\" /><InboundNodeEncoding vt=\"8\" /><OutboundBodyLocation vt=\"8\" /><OutboundXmlTemplate vt=\"8\" /><DisableLocationOnFailure vt=\"11\" /><SuspendMessageOnFailure vt=\"11\" /><IncludeExceptionDetailInFaults vt=\"11\" /><CredentialType vt=\"8\" /><UserName vt=\"8\" /><Password vt=\"8\">Encrypted</Password><AffiliateApplicationName vt=\"8\" /><OrderedProcessing vt=\"11\" /><Identity vt=\"8\" /></CustomProps>"
"SendHandlerPropertiesXML"="<CustomProps><WcfExtensions vt=\"8\" /></CustomProps>"
"SendLocationPropertiesXML"="<CustomProps><Headers vt=\"8\" /><BindingType vt=\"8\" /><BindingConfiguration vt=\"8\" /><ReferencedBindings vt=\"8\" /><EndpointBehaviorConfiguration vt=\"8\" /><StaticAction vt=\"8\" /><UseSSO vt=\"11\" /><UserName vt=\"8\" /><Password vt=\"8\">Encrypted</Password><AffiliateApplicationName vt=\"8\" /><ProxyAddress vt=\"8\" /><ProxyUserName vt=\"8\" /><ProxyPassword vt=\"8\">Encrypted</ProxyPassword><InboundBodyLocation vt=\"8\" /><InboundBodyPathExpression vt=\"8\" /><InboundNodeEncoding vt=\"8\" /><OutboundBodyLocation vt=\"8\" /><OutboundXmlTemplate vt=\"8\" /><PropagateFaultMessage vt=\"11\" /><EnableTransaction vt=\"11\" /><IsolationLevel vt=\"8\" /><Identity vt=\"8\" /></CustomProps>"

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{59b35d03-6a06-4734-a249-ef561254ecf7}\Implemented Categories]

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{59b35d03-6a06-4734-a249-ef561254ecf7}\Implemented Categories\{7F46FC3E-3C2C-405B-A47F-8D17942BA8F9}]

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{59b35d03-6a06-4734-a249-ef561254ecf7}\Install]
"Assembly"="Microsoft.Adapters.Sql.BizTalk, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
"DateTime"="12/28/2010 00:20:47"

, , ,

2 Comments

Recent Licensing Changes to BizTalk-Related Technologies

Introduction

I got some pretty good traffic for my recent post on the changing BizTalk landscape regarding 3rd party BizTalk adapter companies that no longer sell adapters so I thought it would be good to also try to aggregate some recent licensing changes. Due to new products being out now for both of the license changes, the old terms are no longer available and the old products can no longer be purchased (AFAIK). Both of these licensing changes seemed shocking and a little annoying to me because the previous version was a great deal, especially when paired with a BizTalk standard license.

Forms Services (InfoPath on the web)

  • In SharePoint 2007 it was possible to run Forms Server under a Standard CAL.
  • In SharePoint Server 2010, Forms Services requires Enterprise edition.

From a BizTalk perspective not being able to work with InfoPath on the web without purchasing a full, enterprise edition of SharePoint is a significant barrier to entry. InfoPath has often been used with BizTalk for providing a rich client application for error routing & resubmit scenarios. There are actually many samples of using InfoPath with BizTalk that are included with the BizTalk SDK.  BizTalk standard is a very  good deal for smaller businesses when compared to Enterprise edition. Fortunately it is still possible to use InfoPath with BizTalk 2010 as long as the InfoPath client has been installed.

A really interesting and likely cost-competitive workaround would be to use SharePoint Online which will eventually support Forms Services. I was unable to determine if this capability is already available but there are several Microsoft people mentioning this is an upcoming reality. Here is one example: http://social.technet.microsoft.com/Forums/en-US/onlineservicessharepoint/thread/03581d46-64bc-4c8e-953b-211ac55fc70c/.

BizTalk Adapter Pack when used outside of BizTalk

  • With BizTalk 2009 it was possible to purchase a separate license for using the BizTalk adapter pack WCF custom bindings without a BizTalk license.
  • With BizTalk 2010 a BizTalk license (Standard or Enterprise) must be purchased

At the very bottom of the page at http://www.microsoft.com/biztalk/en/us/editions.aspx, this change to the BizTalk Adapter Pack is listed. I am not sure if this change might have been a trade-off with the developer edition now being free. It seems like a relatively good trade. In my experience I have not seen many people pay for the BizTalk Adapter Pack separately from BizTalk. I was actually surprised when anyone mentioned even knowing about this separate SKU for just the BizTalk adapter pack.

Since BizTalk is not licensed on a CAL model it seems like just a matter of time before the BizTalk Adapter Pack could be remotely hosted (perhaps even in the cloud) and could be provisioned for costs in this way. This is just a guess – I have no knowledge of this being an upcoming trend or possibility. But considering the requirement of needing to upgrade to a BizTalk server edition for anyone currently using the pack in their .NET applications, there seems to be a compelling reason to have a cost-restricted upgrade model.

Conclusion

So both of these licensing changes can make a big impact on your architectural estimates for projects unless you look at using a cloud or ASP based workaround.

Thanks,

, ,

1 Comment

Handling Google Web Services Throttles

Introduction

On a recent project I was working on some integration with the Google Web Services static map API (documented here: http://code.google.com/apis/maps/documentation/staticmaps/) as part of an overall BizTalk solution. The integration was being used to record the latitude and longitude of coordinates of stores.

The calls to the Google Web Service were going through a custom .NET method due to some extra business logic being executed before making the call to the web service. When testing the integration on one or two geographic locations, everything worked successfully. But when the integration was tested for hundreds of geographic locations that all needed to be updated in a short period of time, the web service would just return empty data after a period of time. This was a notoriously hard bug to resolve because there was not any additional contextual information about why the web service calls were just returning empty information.

It took some digging but eventually I realized that the Google web service throttles itself to limit usage and prevent a Denial-of-Service (DoS). This limitation is documented here: http://code.google.com/apis/maps/documentation/staticmaps/#Limits. When the web service throttled the results came back as 0 Latitude and 0 Longitude (0,0) so this is confusing and misleading because this is actually a location on the globe, just right in the middle of the Atlantic ocean. A fault with a descriptive error message would have been better.

Workaround

Due to this limitation, I had to add some customized delays and locking to the .NET method so that the calls to the web service would not overwhelm the Google web service’s throttle. This scenario was even more complicated because we did not want more than one BizTalk orchestration instance to overflow the web service throttle either. Because the .NET assembly is running in the BizTalk process custom use of threading  is suspect – you do not know if it will work properly. It was difficult to determine the right interval of polling the Google web service that gave us the maximum thoroughput without causing the service to throttle. But following code worked for us in handling this scenario:

public static object LockObject = new object();

public static string GetLatLonCoordinates(string addressLine)
{
string ret = "";

lock(LockObject) {

// delay for 10 seconds - to avoid the Google request rate limitation.
// For more information on the limits of the Google Static Maps API,
// see: http://code.google.com/apis/maps/documentation/staticmaps/#Limits
Thread.Sleep(10000);

if (addressLine == null) { return "0,0"; }
if (addressLine.Trim().Length == 0) { return "0,0"; }

try
{

GoogleCoordinates coor = GoogleWebServiceWrapper.GetCoordinates(addressLine);
ret = coor.Latitude.ToString() + "," + coor.Longitude.ToString();

}
catch (Exception e)
{
System.Diagnostics.EventLog.WriteEntry("Application", e.Message, EventLogEntryType.Error);
}
}
return ret;
}

Leave a comment

BizTalk 2010 on SQL 2011 CTP 1 (Denali)

Today I kicked off an install test of BizTalk 2010 with SQL Server 2011 CTP 1 (Denali). Here is my install order, all on a single box using local accounts:

This install order did produce one error when setting up VS 2010. The SQL 2008 R2 management objects could not be installed. I was not sure if this was important for BizTalk or not so I just ignore the error. Everything else with VS 2010 installed correctly. BizTalk installed. I am still working on getting Notification services and BAM installed so I will update this post later. The configuration wizard went through quite quickly and I did not have problems. So at this point I think BizTalk 2010 is working successfully on SQL 2011 CTP 1.

Thanks,

,

2 Comments

Some tips for a BizTalk catastrophic event

Introduction

Today I witnessed a BizTalk catastrophic event. One of the SQL drives for a company I work for failed. In scrambling to find some solutions and fixes for the errors we were seeing I realized I could not find a great case study in a catastrophic event for BizTalk. One thing that would be nice would be to have sort of a list of errors you may see and a list of resolutions. In this post I just want to document a few errors I did not know about and mention what was helpful and what you can do to resolve the issues.

One helpful page I found on BizTalk errors is at http://www.codedigest.com/Articles/BizTalk/250_BizTalk_-_Errors_and_Warnings_Causes_and_Solutions.aspx.

Details

Today we have seen quite a few errors. A couple errors were logged indicating the catastrophic errors:

The following stored procedure call failed: ” { call [dbo].[bts_InsertPredicate_BtsWebServices]( ?, ?, ?, ?, ?, ?, ?, ?)}”. SQL Server returned error string: “Warning: Fatal error 823 occurred at <datetime>. Note the error and time, and contact your system administrator.”.

The following stored procedure call failed: ” { call [dbo].[bts_InsertProperty]( ?, ?, ?, ?, ?)}”. SQL Server returned error string: “Connection failure”.

There were lots of other similar ones. Basically if you see { call [dbo].[bts_<anything>](?*) } then it means some BizTalk stored proc is failing.

We started investigating at this point. The fatal error 823 is a disk I/O error and is documented here: http://technet.microsoft.com/en-us/library/aa337267.aspx. A handy tip for SQL errors is to just search “MSSQLSERVER_” + error code to find the TechNet article. So for us it was searching on MSSQLSERVER_823.

Eventually it was determined that we needed to restore the BizTalk databases. The following link was really helpful as far as getting ready for the restore process: http://msdn.microsoft.com/en-us/library/cc296638(v=BTS.10).aspx. Our system did not have log shipping enabled (the article refers to it but it still provides some good details). So I stopped the remaining host instances in the BizTalk admin console. Then I had to switch to the Service Control Manager to stop other services.

But errors keep getting thrown. The BizTalk applications were still running so I stopped them. Then I checked the ports and they should be stopped by this point but a few were not. I had to manually stop the receive locations, which stopped without complaint. Then when trying to stop the send ports I get this error for every one:

Could not stop Send Port ‘<name>’. Unable to acquire the necessary database session for this operation.  (Microsoft.BizTalk.SnapIn.Framework)

Sometimes I am also getting this error:

Could not retrieve transport type data for Receive Location ‘<name>’ from config store. Both SSO Servers (Primary='<servername1>’ and Backup='<servername2>’) failed. Backup server failure: Exception from HRESULT: 0xC0002A0A (Microsoft.BizTalk.SnapIn.Framework)

The BizTalk administration console is unable to resolve this error while the database is in an inconsistent state. I tried a couple things such as restarting MSDTC or the WMI service (some common admin console workarounds) as well as restarting the admin console but it did not work. One weird thing is that the admin console is able to connect to the group database server, but it seems like something about the send port information in the database cannot be retrieved.

— Update —-

The above errors occurred because something about the BizTalk databases was having problems. For lack of a better word the databases were corrupted. After talking to Microsoft Product Support (shout out to Anzio Breeze), they helped us resolve the problem. The problem was that a BizTalk backup had been restored successfully but was not functioning properly. To diagnose the problem, dbcc checkdb was run on BizTalkMsgBoxDb and SSODB.  The resolution was to restore an older backup. The older backup restored and took longer so we are guessing that more data restored than the previous restore attempt.

If you get a SQL fatal error 824 then one possible symptom is that a database is corrupted. Try restoring from a backup.

Thanks,

,

Leave a comment

Tips for your profile.ps1 file when using BizTalk with Powershell

Introduction

I have been meaning for a while to add some PowerShell posts to my blog but had been busy lately. I have been using the BizTalk PowerShell provider (http://psbiztalk.codeplex.com) that my friend Randal van Splunteren helped create. I now use PowerShell  all the time in my BizTalk work and find it to be very helpful for common administrative tasks like deploying pipeline components, exporting backups of binding files, and handling automated deployments. I am definitely not a PowerShell expert but more of an enthusiast at this point. I will post some of the tips and tricks I have found in using PowerShell for BizTalk development. I am not going to introduce PowerShell for beginners but approach this as giving you some interesting, useful scripts.

I have found it typically difficult to find lots of useful examples of BizTalk PowerShell. So I aim to change this by providing some of mine so that other people can take advantage of them.

Today I am going to show most of my profile.ps1 file which is called by PowerShell when starting up the shells.

Details

Working with PowerShell and BizTalk is still a relatively involved task. This is primarily because of BizTalk’s still heavy dependence on x86 architecture. The install guide for the BizTalk PowerShell provider mentions you need to load the 32-bit version of the PowerShell shell to add the snap-in. When I first started working with this provider I kept loading the 64-bit provider and I kept getting this error:

Add-PSSnapin : The Windows PowerShell snap-in ‘BizTalkFactory.Powershell.Extensions’ is not installed on this machine.
At line:1 char:13
+ Add-PSSnapin <<<<  BizTalkFactory.Powershell.Extensions
    + CategoryInfo          : InvalidArgument: (BizTalkFactory.Powershell.Extensions:Stri
   ng) [Add-PSSnapin], PSArgumentException
    + FullyQualifiedErrorId : AddPSSnapInRead,Microsoft.PowerShell.Commands.AddPSSnapinCommand

So be sure to load the 32-bit shell. There are quite a few challenges for the BizTalk PowerShell scripter because the SQL provider is based on 64-bit architecture. In my daily work I often want to kick off a SQL agent job so this requires managing more than one PowerShell instance at a time. For this reason, there is some complexity in loading all of the useful providers. It is handy to do this provider loading in the profile.ps1 file. To simplify my work, I also set a few executable aliases that I frequently call during deployment of BizTalk artifacts. Most of my profile.ps1 file is shown below:

# This script is for a 64-bit system
if(([diagnostics.process]::GetCurrentProcess()).path -match '\\syswow64\\') {

	Write-Host "32-bit Powershell"

	Write-Host "Loading Powershell provider for BizTalk snap-in"
	Add-PSSnapin BizTalkFactory.Powershell.Extensions

	New-PSDrive -Name BTS -PSProvider BizTalk -Root BTS:\ -Instance "." -Database BizTalkMgmtDb
	Set-Location -Path BTS:
}
else {

	Write-Host "64-bit Powershell"

	Write-Host "Loading SQL Provider"           # from http://msdn.microsoft.com/en-us/library/cc281962.aspx
    $ErrorActionPreference = "Stop"
    $sqlpsreg="HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.SqlServer.Management.PowerShell.sqlps"

    if (Get-ChildItem $sqlpsreg -ErrorAction "SilentlyContinue")  {
       throw "SQL Server Provider is not installed."
    }
    else {
        $item = Get-ItemProperty $sqlpsreg
        $sqlpsPath = [System.IO.Path]::GetDirectoryName($item.Path)
    }

    # Set mandatory variables for the SQL Server rovider
    Set-Variable -scope Global -name SqlServerMaximumChildItems -Value 0
    Set-Variable -scope Global -name SqlServerConnectionTimeout -Value 30
    Set-Variable -scope Global -name SqlServerIncludeSystemObjects -Value $false
    Set-Variable -scope Global -name SqlServerMaximumTabCompletion -Value 1000

    # Load the snapins, type data, format data
    Push-Location
    cd $sqlpsPath
    Add-PSSnapin SqlServerCmdletSnapin100
    Add-PSSnapin SqlServerProviderSnapin100
    Update-TypeData -PrependPath SQLProvider.Types.ps1xml
    update-FormatData -prependpath SQLProvider.Format.ps1xml
    Pop-Location

    # More of my code
    New-PSDrive -Name localSql -PSProvider SqlServer -Root SQLSERVER:\SQL\Bencpc
    Set-Location -Path C:

}

# Setup some useful shortcuts for commonly used executables in BizTalk deployment
Set-Alias gac "C:\Program Files\Microsoft SDKs\Windows\v6.0A\Bin\gacutil.exe"
Set-Alias msbuild "C:\Windows\Microsoft.NET\Framework\v3.5\msbuild.exe"
Set-Alias btstask "C:\Program Files (x86)\Microsoft BizTalk Server 2010\btstask.exe"

1 Comment

The Changing BizTalk Landscape

Today has been a bit of whirlwind. In my search for a MAPI adapter I found out that Kayxo went out of business recently and their Exchange BizTalk adapter no longer exists as a buyable product. No wonder I did not get a response from them by email. This also explains their poor website. Perhaps I missed a Business Week or a USA Today article but I can honestly not find very good information on their closing. If you want a copy of the download, just let me know.

Also, I found out that iWay does not sell BizTalk adapters. If you look at their website they look like an adapter provider but I found out today they do not actually sell native adapters. For example, take this page: http://www.iwaysoftware.com/biztalk.html, it all looks like the adapters are BizTalk adapters. In the past I had definitely recommended iWay as a BizTalk adapter provider but I heard today they sell a competing integration platform and do not actually provide BizTalk adapters.

So the MAPI adapter search is definitely dead now, I will have to build one. Please let me know if you know of another MAPI adapter provider.

Thanks,

15 Comments

Kayxo BizTalk Exchange Adapter Tips

Introduction

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.

Installation

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.

Configuration

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:

  1. Open Outlook 2010, authenticate
  2. Click File\Account Settings\Account Settings button
  3. Find your profile and then click Change…
  4. Under your Server find the “Use Cached Exchange Mode” checkbox and be sure it is cleared.
  5. 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.

Additional Documentation

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.

Thanks,

,

Leave a comment