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:
Next, add the CRM entities you want to operate on:
Clicking on the “OK” then generates the schemas and binding file for BizTalk:
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.
- 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.
- 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.
- 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.
- 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 TypesThe 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.
Select request and response
- 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:
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:
The FetchXml looks like the following:
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 FetchXml Response looks as follows with the ten account records:
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.