CRM WCF LOB Adapter

Background

Most BizTalk developers integrating with Microsoft CRM know that mapping between your business processes and the CRM Web Service can be very challenging. Knowledge of XSLT is beneficial for creating the key/value pairs in order to use the operations provided by the CRM Web Service.

With this in mind, I wanted to find way to make the integration experience between BizTalk and CRM simpler and easier. My first few prototypes were able to provide the functionality I needed for integrating with CRM but involved using orchestrations. This brought about a lot of coding overhead like automatic retries etc. Thinking long and hard about this I knew the right approach was to build either a custom BizTalk Adapter or a WCF LOB Adapter.

Introducing the CRM WCF LOB Adapter

The following is a screenshot of the Consume Adapter Service:

Specifying the URI of the CRM Web Service and clicking on the “Connect” (assuming you have rights to CRM) presents the following:

Next, add the CRM entities you want to operate on:

As can be seen in the above screenshot:

• There is an entity “Account” added which allows for CRUD operations. (Create, Retrieve, Update and Delete operations.)
• An insert only operation on the “Contact” entity.
• The FetchXml operation which is used for the more complicated queries in which the select is not suitable or capable of performing.

Clicking on the “OK” then generates the schemas and binding file for BizTalk:

Opening the “Account” schema you will see the following:

Delete and Insert expanded:

Each operation on an entity is handled similarly:

• Delete
• The request operation only allows the "Primary Key" of the entity. (“AccountId” in the case above.) 
• The response returns the "Primary Key" (AccountId”) that was deleted or the index and any error(s) that may have arisen while deleting the account.
• Insert
• The request operation allows you to specify the fields that you want inserted into CRM.
• Note: There is no "Primary Key"(AccountId) available in the insert as the reason for this is that CRM prefers the Primary Key to be generated server side using a sequential GUID. 
• The response returns the Primary Key of the Account inserted or the index and any error(s) that may have arisen while inserting the account.
• Update
• The request operation allows you to specify all the fields you wish to update. The “AccountId” is a mandatory field as it is the primary key used by CRM to update the matching record.
• The response returns the “AccountId” of the Account inserted or the index and any error(s) that may have arisen while inserting the account.
• Select
• The request operation only provides a “Column” and “Where” parameter for specifying the columns and the conditions for the query.
• The response returns all fields available to the Account entity.

Complex Types 

The schemas generated will produce the complex types required by each entity (E.g. OptionSets and EntityReferences). The complex types are the lookups and picklists available within CRM.

OptionSets

EntityReferences

Select request and response

The select request has the same feel as the Select from a SQL query. You specify the columns that you want retrieved from CRM as well as the "Where" clause.

Conditions:

• The AndOr allows you to specify the logic gates "AND" or "OR".
• Column specifies the CRM field you want the where condition to be performed on.
• The operator specifies the operations to be performed on the conditions.
• The Operator can have the following operations:

• Value provides the values that the condition need to be filtered on
• Where can be expanded to form more complicated queries. The Condition element contains a "Where" record which can have sub where conditions.

The following is a sample Select request and it's respective response:

FetchXml

For situations that require complex queries, the FetchXml is the answer. The idea I was approaching here was to allow complex queries to be created using the FetchXml builder, then wrap the FetchXml message around the output from the FetchXml builder.
The FetchXml looks like the following:

A sample of the FetchXml looks like the following:

In the request message there are attributes that can be specified. E.g. page = 1 and count = 10

This allows paging to occur on the CRM server side where you can specify that you only want the first 10 responses belonging to the “Account” entity.

There is a context property which contains this information as can be seen below:

The context property above allows an orchestration to retrieve more records as necessary and not overload the BizTalk Server, especially when selecting a large set of data.

The FetchXml Response looks as follows with the ten account records:

The response returns all the attributes as specified using the “<all-attributes>” element:

Conclusion

In conclusion, the WCF LOB Adapter provides powerful capabilities that not only allow BizTalk Server to integrate with other systems but also to generate the contracts/ schemas BizTalk developers can easily consume.