In the last week I have already helped out with two issues on a BizTalk 2010 to 2013 upgrade project that had the same root cause and I thought it was worth documenting this so as to save others the headache of having to figure this out themselves.

BizTalk 2013 contains a new feature in that you can now nominate which send handler is used for which adapter on a given dynamic send port.  This has resulted in the creation of a new SQL table, bts_dynamic_sendport_handlers in the BizTalkMgmtDb database, and with a fresh BizTalk 2013 installation the necessary SQL roles are given the appropriate permissions on this table.  That said things might (I say might because on in some upgrade scenarios we have seen all the permissions applied correctly and in some we haven’t, thus far we can’t account for the different behavior) go a bit differently when doing an upgrade of BizTalk 2010 to 2013… while the new table is created, none of the existing roles appear to be extended to have permissions on this new table (though as I stated on some upgraded environments this was not an issue at all).  Microsoft have written an article about this problem but unfortunately unless you know exactly what the problem is chances are you will not be able to find it (they mention another table as well but thus far that has not been a problem for us).

This issue can have major effects on multiple aspects of BizTalk such as the ESB portal, the BizTalk Community ODBC adapter, or pretty much any utility that makes use of classes (in our specific case it was the BtsCatalogExplorer class) in the Microsoft.BizTalk.ExplorerOM assembly which allows for the traversal of the BizTalk object model. This in theory would extend to the BizTalk documenter, the Orchestration Profiler, and the BizTalk PowerShell provider though I haven’t proven this yet.  Unfortunately the error messages aren’t always very obvious and understanding the root cause of the problem with the ODBC adapter required us to debug the code and it was only when we stepped into the lowest levels that we realized that the BtsCatalogExplorer was failing to populate itself.

On the ESB Portal front the error message says “Server was unable to process request. —> The source was not found, but some or all event logs could not be searched.  Inaccessible logs: Security.”

ESB Portal Failure

On the community ODBC adapter the problem would present itself with a cryptic error message stating “The type initializer for ‘Microsoft.BizTalk.Adapters.ODBC.RunTime.ODBCTransmitAdapterProperties’ threw an exception”.  Note that this problem was only seen by us on ODBC send ports.  Receive locations (at least one way receive locations) appeared to work just fine .

ODBC error

The permissions that are required against the bts_dynamic_sendport_handlers table are delete, insert, select, and update for the BTS_ADMIN_USERS role, and select only for the BTS_HOST_USERS and BTS_OPERATORS role.

It is also quite possible that post the upgrade none of your existing applications will suffer any impacts to their functionality if there are no dependencies on dynamic send ports or the Microsoft.BizTalk.ExplorerOM assembly and it might be a while before you actually encounter this issue.  The problem might also be hidden on development environments if the user in question (be it your BizTalk host instance user / application pool identity / application credentials) is in the sysadmin SQL server role on the BizTalk SQL server and thus the problem might not be observed till an application is migrated to the next environment.

The moral of the story is that if you are going to upgrade your BizTalk 2010 environment to 2013 do not forget to provide the relevant permissions to the bts_dynamic_sendport_handlers table.