Introduction

This article demonstrates how to integrate Microsoft Dynamics CRM 4.0 using BizTalk Server 2009/2010 to other business applications. There have been several questions on how to talk to MS Dynamics CRM using BizTalk Server 2009/2010 adapters, this article shall attempt to shed some light on it.

Download and install the Microsoft BizTalk Server Adapter for Microsoft Dynamics CRM 4.0

With this adapter you can integrate Microsoft Dynamics CRM 4.0 with any other business application using the Microsoft BizTalk Server 2006/2009.

Microsoft Dynamics CRM 4.0 download link

Verify adapter installation

Open BizTalk Server Administration console and look for the following

How to generate the required schemas, to map and create entities in MS CRM?

Once you have installed the adapter correctly, open a new project in Visual Studio.

These steps will generate the required schemas for mapping.

Step 1: Select right-click on Project -> Add -> Add Generated Items -> Select Add Adapter Metadata.

Step 2: Choose Microsoft Dynamics CRM 4.0, click Next and specify CRM connectivity details.

Step 3: Choose the entities and operations.

The project will look like the following after the schema generation

NOTE: If you have selected more than one entity, the CRM prefixes the schema name with the entity name (for instance Account_Query.xsd). Note that these are common schemas and are identical for every entity. These common schemas can be removed safely and this will reduce the size of schema DLL.

Steps to invoke CRM adapter using a dynamic send port.

Step 1: Locate the CRM property schema

Locate the property schema in the Dynamics Adapter CRM installation folder (typically located at C:\Program Files\CRMDynamicsBizTalkAdapter4.0\Schemas)

Step 2: Assign the values for the property schema

Set the various properties in the property schema

// NOTE: These are dynamic port assignments. 
// These can changed at runtime without any impact! 
CRMAdapterRequestMsg(PropertySchema.ServerUrl) = CRM_URL;
CRMAdapterRequestMsg(PropertySchema.UserName) = CRM_UserName;
CRMAdapterRequestMsg(PropertySchema.Password) = CRM_Password;
CRMAdapterRequestMsg(PropertySchema.CrmOrganization) = CRM_Organization;
CRMAdapterRequestMsg(PropertySchema.AuthType) = CRM_AuthType;

// NOTE: Specify the CRM full URL endpoint. 
CRMDynamicSendPort(Microsoft.XLANGs.BaseTypes.Address) = CRM_URL;

// NOTE: match this with the adapter name in BizTalk Server Administration Console (Microsoft Dynamics CRM 4.0)
CRMDynamicSendPort(Microsoft.XLANGs.BaseTypes.TransportType) = CRM_TransportType; // "Microsoft Dynamics CRM 4.0"

Step 3: Mapping to various CRM operation schemas

Its required to generate schemas for every entity which needs to be created or updated in the CRM. In this example I have demonstated this only for the fetch request. The screen shots illustrate the mapping required to transport to a fetch request.

The crm_action attribute can take the following values

• create
• update (default)
• fetch
• delete

// Custom Functoid code to send RAW XML
public string GetFetchQuery(string fetchQueryRequest)
{
	return fetchQueryRequest;
}

Downloadable Source code

This source code contains two orchestrations. One orchestration invokes the CRM adapter and another one calls it using a call orchestration shape. I have coded it to be as generic as possible.

Note the following points

• The CRM adapter uses the following namespace for sending a response back to the orchestration. The xxx value must be replaced by the specific CRM value that you connect with.

  http://schemas.microsoft.com/crm/2007/BizTalkAdapter/xxx/Response 

• There are two forms of response from CRM, the error response and the correct response. The error response is shown in the attached screen shot. The correct response is under the /Body/Message tag and the ReturnCode value will be 1. The orchestration code extracts the response from the Message tag and transmits it to the logical sent port.
• Notice the send port and receive port settings. This is not required in Production but it is required to run this code.

Send and Receive port settings

HOW to enable debugging in MS Dynamics CRM 4.0 BizTalk Adapter and receive friendly error messages?

The CRM Adapter typically logs error messages in Application Event log. Most of the error messages are generic and does not give enough descriptive meaning. The following are the steps required to log errors in a log file with descriptive error messages.

Step 1: Open registry editor

Search for the following key '6B8335E2-9664-4ad8-A2F6-ADBFD60FF703'

Step 2: Set the following keys as shown in the screen shot.

Step 3: Re-start the BizTalk send handler associated with the CRM adapter

You are all set for a happy integration.

Typical error messages in CRM adapter logs

Exception :: 0x80040203 :: serializedForm ::    at 
System.Web.Services.Protocols.SoapHttpClientProtocol.ReadResponse(SoapClientMessage message, WebResponse response, Stream responseStream, Boolean asyncCall)
   at System.Web.Services.Protocols.SoapHttpClientProtocol.Invoke(String methodName, Object[] parameters)
   at Microsoft.Crm.BizTalkAdapter.CrmService2007.CrmService.Execute(Request Request)
   at Microsoft.Crm.BizTalkAdapter.Runtime.SendToCrm.UpdateDynamicEntity(EntityAttributesValidationResult attributeValidationResult, String entityName)

Attribute :: xxx_currencyid, Attribute Type :: Lookup, Attribute Value :: USD, Error :: There is an error in the XML document.

       
        <xxx_currencyid name="USD" />

Quick References

I suggest having a look at the following post by Brajendra Singh as a starter and some notes on CRM adapter debugging.

• Post by Brajendra Singh
• Discussions on Debugging