Microsoft BizTalk CRM 4.0 Adapter

posted at: 9:46 AM by Chris Scott

Microsoft recently released the BizTalk adapter for Microsoft Dynamics CRM 4.0. I have been working with the new adapter on a recent project and have found a few key items that are good to be aware of:

 

Number and size of new Schemas - The new adapter uses the 2007 endpoint which is much richer in functionality and includes some of the core features needed to support full integrations including the many-to-many relationships. At the price of this functionality though is many new schemas for a total of 8 per entity (the previous adapter had 3)

• [EntityName]_CoreTypes.xsd – defines various security related data types and methods. Includes references to [EntityName]_types.xsd.
• [EntityName]_CoreTypes_1.xsd – defines various platform level methods. Includes references to [EntityName]_types.xsd and [EntityName]_webservices.xsd.
• [EntityName]_Query.xsd – defines many of the items needed for query expressions and fetch statements.
• [EntityName]_Scheduling.xsd – defines various appointment requests. Includes references to [EntityName]_types.xsd and [EntityName]_webservices.xsd.
• [EntityName]_Types.xsd – defines the GUID data type.
• [EntityName]_WebServices.xsd – defines the business entity and several of the CRM data types. Includes references to [EntityName]_types.xsd.
• [EntityName]_WebServices_1.xsd – essentially is the WSDL output. Includes references to all schemas above.
• [EntityName]_Entities.xsd – defines the attributes on the entity and used to map all messages to CRM. Includes references to all schemas above.

The schemas range in size from 1 kilobyte to over a megabyte (depending on the size of the entity). For integrations dealing with more than a couple of entities, the size and number of schemas will likely be a problem.

Our solution includes over 30 entities. During the compiling of our BTS solution with the new schemas, the following error was thrown by Visual Studio:

Unexpected error writing metadata to file 'c:\Documents and Settings\Administrator\My Documents\Visual Studio 2005\Projects\BizTalk Server Project1\obj\Development\~BizTalk Server Project1.dll' -- ''

The result of our testing showed that the new schemas caused the DLL size to be too large as Visual Studio tried to compile the project (documented in MSDN). We tried breaking the solution into multiple projects, but we still ran into this problem. Our solution was to create a “common” set of schemas from the 7 generated and update the [EntityName]_Entities.xsd to reference the common schemas rather than the entity specific schemas. This is a fairly simple solution and we have not found any issues in testing, but it does require updating the CRM schemas each time you download or update a CRM entity.

CRM Response Namespace - A core feature of the new adapter and of CRM 4.0 is supporting multiple organizations. While this is a really cool feature, we have found an issue with the new adapter that make truly supporting multiple organizations in BizTalk very challenging. The CRM response XSD, a generic XSD containing the success or failure message sent from CRM on each call, has an organization specific namespace. For example, in Ascentium’s development environment (organization is AscentiumCrmDev) has a CRM response XSD namespace of http://schemas.microsoft.com/crm/2007/BizTalkAdapter/AscentiumCRMDev/Response. The problem with this is that if the organization name changes from what the BizTalk solution was developed on, the response message will fail because of the differences in expected namespace.

Here are a couple of possible solutions that we considered:

• Creating a custom receive pipeline to change the namespace.
• Create multiple inbound schema and maps for known organizations and map your ports to the appropriate maps.
• Ignore the response message from CRM.

There are many more possible solutions including keeping the organization names the same between all environments, but this defeats the purpose of supporting multiple organizations. For our solution, we implemented a custom receive pipeline to update the namespace as the message comes back from CRM. This is not a simple solution and requires a decent amount of coding, but it serves the long term need for our project.

Empy DateTime Data Types – Messages bound to a CRM schema with data type of CrmDateTime containing an empty string receive this error:

CrmSoapExtension detected CrmException: System.Web.Services.Protocols.SoapException: Server was unable to process request. ---> Microsoft.Crm.CrmArgumentNullException: serializedForm ---> System.ArgumentNullException: Value cannot be null. Parameter name: serializedForm

To get around this, we updated our maps to include a logical string functoid on date time data types. This removed the node from the message sent to CRM if the value passed in is empty.

 

Overall, I have been pleased with the updated CRM adapter for BizTalk. It offers a lot of rich functionality and is a welcome tool for CRM 4.0 integrations. Just be aware of the above issues when you start working with the new adapter.

 

Chris

This posting is provided "AS IS" with no warranties, and confers no rights.