Like most projects it’s always a good idea to build a proof of concept that helps you better understand what you are trying to achieve and highlight possible challenges that you may encounter. Since I’m in the early stages of a project which will integrate Sitecore with Microsoft Dynamics CRM, I needed to build a proof of concept since I knew nothing about this type of integration.
My goals for the proof of concept were as follows:
- Install the Microsoft Dynamics CRM Security Provider module provided by Sitecore.
- Ensure that the Read-only and Read-Write modes both work as described in the documentation.
- Read-only mode – Used to connect to the Microsoft CRM system to read the data only (except for some special cases that will be described later in this chapter). This means that the module does not allow you to update the data in the CRM system from Sitecore.
- Read-Write mode – When the module is configured to use read-write mode, you can also update data in the Microsoft CRM system directly from Sitecore.
- Ensure that marketing lists from MS Dynamics properly map to Sitecore roles.
- Figure out which data fields are mapped out-of-the-box from MS Dynamics to Sitecore and visa-versa. I expected to have to do some custom work to map unsupported field types.
Microsoft Dynamics can be run as a server installation or via the cloud using MS Dynamics Online. For this proof of concept I decided to use MS Dynamics Online since it allows you to get up and running with very little effort thanks to their 30 day trial offer.
Installing and configuring the Dynamics CRM Security Provider module
After setting up a fresh install of Sitecore (in record time thanks to Sitecore Instance Manager) the first step was to install the Dynamics CRM Security Provider module. This module contains the functionality that connects user data between Sitecore and Dynamics. The configuration instructions for this module are outlined in the Dynamics CRM Security Provider Module Guide available on the developer network.
Aside from some significant modifications to the Web.config file, the most challenging part was getting the Dynamics connection string correct in the ConnectionStrings.config file. Getting the connection string correct took way too long! There is documentation regarding the connection string but it is very difficult to determine what values to plug in for certain parameters.
After a lot of trial and error here is an example of the connection string you will need to use in order to connect to Microsoft Dynamics Online (Note that the connection string will differ between Dynamics Online and the server installation of Dynamics).
<add name="CRMConnString" connectionString="CRM:url=https://[SOMETHING].crm.dynamics.com/XRMServices/2011/Organization.svc; user id=[EMAIL]; password=[PASSWORD]; organization=[ORGANIZATION_NAME]; authentication type=1; partner=crm.dynamics.com; environment=Production;" />
URL – You will be able to determine the proper URL parameter to use in the connection string by logging in to your MS Dynamics trial account. The first segment of your custom URL should be used and has the format of something.crm.dynamics.com. This segment should be added to the URL parameter so it looks something like this: https://something.crm.dynamics.com/XRMServices/2011/Organization.svc.
User Id – The user id parameter is actually the email you were given during sign up which you will use to sign into your trial account.
After properly installing and configuring the Dynamics CRM Security Provider module you should be able to see a set of default CRM users (the Dynamics Online trial account includes a set of example users) populated in the Sitecore User Manager! If you do not see a set of CRM users in the Sitecore User Manager then make sure to double check the Sitecore log files. There were some useful connection errors logged there that helped me trouble shoot some issues.
At this point you will have successfully connected Sitecore and Dynamics so that user data can be shared between the two platforms. If you have followed the configuration documentation then you will have added the following set of profile fields to the Web.config file:
<add type="System.String" name="Country" customProviderData="crm|address1_country"/> <add type="System.String" name="City" customProviderData="crm|address1_city"/> <add type="System.String" name="BirthDate" customProviderData="crm|birthdate"/> <add type="System.String" name="DoNotEmail" customProviderData="crm|donotemail"/>
This section of the Web.config determines which fields are mapped between the two platforms in order to share data. By default these four fields are mapped from Sitecore CRM users to contacts in Dynamics. For example, if we look at the first field we can see that a field named “Country” is mapped from Sitecore to a field named “address1_country” in Dynamics. At first glance it is hard to determine exactly where the “address1_country” field is located in the CRM because the fields real names are usually hidden by more user friendly display name labels used in the CRM. So the “Country“ field is mapped the “Country/Region” field in the CRM.
The default configuration for the CRM module also enables the two-way Read-Write mode so data updated on either platform should be reflected on the other.
A Handful of Issues
Overall the module works fairly well but I did see some issues that I wanted to highlight. The first thing that I noticed is that there seems to be a problem mapping the Date and DateTime from Sitecore to Dynamics. This seems to be a bug which has been reported to Sitecore support.
After seeing the issue with the Date field I decided to double check each field type that is said to be supported out-of-the-box by the Dynamics CRM Security Provider module. The table below shows my findings:
|DateTime||Date & Time||No (Bug in module)|
|string||money||No (Bug in module)|
|string||option set||No (Bug in module)|
Update: Sitecore support has provided a patch in order to fix the field mapping bugs listed above. Thank you as always!
CRM Updates not Reflected in the Sitecore User Manager
There was another issue I came across that was very concerning since it could potentially lead to data being overwritten in the CRM when Read-Write mode was enabled.
Here is the issue. After updating a contact’s profile data in the CRM, I would then open the corresponding user in Sitecore using the User Manager tool. Obviously I would expect that the Sitecore user would have the updated info from Dynamics but that was not the case. Instead the Sitecore user would contain older data which was very confusing. If I were to open up, make no changes, and then save the custom profile fields for a user then the older data from Sitecore would be sent to Dynamics and the up-to-date info in Dynamics would be overwritten. Admittedly I don’t expect Sitecore users to be using the User Manager tool all that much but I did not feel comfortable moving forward with this issue.
Sitecore support was able to diagnose the cause of the issue (which was helpful) but were unable to provide a fix. Sitecore says that this issue is expected behaviour for the current version of the module and it has been added to a wish list for future updates. The issue revolves around caching (specifically the UserProfileCache). The CRM module does not contain a mechanism for making sure up-to-date data is pulled from the CRM since the User Manager tool relies heavily on caching when displaying users.
Luckily, the information provided by Sitecore support sent me down the right path and I was able to find an acceptable solution to this problem that ensures that data will not be overwritten in the CRM when Read-Write mode is enabled. Find the solution here: https://sitecorecontextitem.wordpress.com/2014/06/25/sitecore-fixing-a-potential-problem-with-the-dynamics-crm-module/
I also want to note that the user caching issue is only a problem when using the Sitecore User Manger GUI to view and update user information. If you were to programmatically update a user’s information then the module functions properly and there is no risk of accidentally overwriting newer data in the CRM.
Here are the results that I wanted to determine based on my goals listed above.
- Install the Microsoft Dynamics CRM Security Provider module provided by Sitecore. (Yes)
- Ensure that the Read-only and Read-Write modes both work as described in the documentation (Yes, although I highlighted and fixed a potential issue that could cause loss of data in Read-Write mode)
- Ensure that marketing lists from MS Dynamics properly map to Sitecore roles. (Yes, works as advertised)
- Figure out which data fields are mapped out-of-the-box from MS Dynamics to Sitecore and visa-versa. I expected to have to do some custom work to map unsupported field types. (Yes. I have reported possible field mapping bugs to Sitecore and determined that custom work will need to be done in order to map certain types of fields. For example, I would like to map the “Droplink” field from Sitecore to the “Option Set” field in Dynamics)
As far as proof of concepts go this one was rather eventful.