So you are setting up CRM connection in Sitecore using the latest package and wondering how to proceed or why things are not working out. Then this guide is for you.

Installing Sitecore CRM Connector

The latest version of Sitecore connector for the Dynamics CRM is missing a number of packages and it assumes that you have installed the CRM SDK and Web Forms for Marketers (WFFM) beforehand. However in this guide we will guide you in performing a correct setup of the solution.

1. From the Sitecore Developers portal download the following extensions:
   1. Dynamics CRM Campaign Integration NOT SC PACKAGE
   2. Web Forms for Marketers 8.1 rev. 151217
   3. Dynamics CRM Campaign Integration for WFFM 22 rev 151027
2. Extract the zip file Dynamics CRM Campaign Integration NOT SC PACKAGE
3. 3. Once the extensions have been downloaded; from the Sitecore Control Panel install Microsoft Dynamics CRM Security Provider 2.1 rev. 150403 package. The package is in the folder just extracted.
   Why do we need this package?
   1. It will provide the CRM SDK files
   2. Create the Sitecore items that are required by the CRM connector
4. When the package installs tick the checkbox to restart Sitecore Server (as per the instructions in the package) or Restart IIS
5. Next install Web Forms for Marketers 8.1 rev. 151217
   As requested in the package instructions you will need to:
   1. Run an SQL script manually on the Reporting Database (if using the standard installation it is called Sitecore_Analytics)
   2. Attach the WFFM databases from the /Website/Data folder.
   3. Update the Web.config as shown in the instructions to enable the captcha functionality.
6. Now that we have the two dependency packages installed, install Dynamics CRM Campaign Integration for WFFM 22 rev 151027
7. Now that the packages are installed we need to modify the configurations files.
   Note: You will need to perform all configuration changes before you can see it working in Sitecore.
   1. First let’s add a connection string for the CRM. This needs to be added to the file App_Config/ConnectionStrings.config. The must be named CRMConnString and the connection string format is:

      CRM:url=https://<CRM account>.api.crm.dynamics.com/XRMServices/2011/Organization.svc;user id=<CRM user email address>; password=<Password used by the CRM user>;authentication type=1;organization=<CRM account>

      Note: It is possible to change the connection string name from CRMConnString but it will require a change in the file App_Config/Inclulde/crm.config. The change will need to be done at the bottom of the file where it specifies the value for the Crm.ConnectionStringName to match the connection string name.

   2. b. Next, we need to tell Sitecore that when someone performs a login it must check both in the Sitecore database and as well in the CRM. To do this, update the file App_Config/Sitecore.config, and set the switchingProviders to look as shown below:

      <switchingProviders>
        <membership>
          <provider providerName="sql" storeFullNames="true" wildcard="%" domains="*" />
          <provider providerName="crm" storeFullNames="false" wildcard="%" domains="crm" />
        </membership>
        <roleManager>
          <provider providerName="crm" storeFullNames="false" wildcard="%" domains="crm" />
          <provider providerName="sql" storeFullNames="true" wildcard="%" domains="*" />
        </roleManager>
        <profile>
          <provider providerName="crm" storeFullNames="false" wildcard="%" domains="crm" />
          <provider providerName="sql" storeFullNames="true" wildcard="%" domains="*" />
        </profile>
      </switchingProviders>

      Note: The documentation states that the roleManager CRM entry can be placed after the roleManager.

   3. So in the switching providers we have referenced a domain called ‘crm’. But Sitecore doesn’t know about it as yet. To get Sitecore to recognise the ‘crm’ domain add the following line to App_Config/Security/Domains.config

      <domain name="crm" ensureAnonymousUser="false" defaultProfileItemID="{DDEDA46F-169B-4A70-8732-DBD3F407AF2E}"/>

      Note: the defaultProfileItemID references an item that is created when the package Microsoft Dynamics CRM Security Provider 2.1 rev. 150403 is installed.

   4. Finally we need to instruct Sitecore to use the switchingProvider options for user and role management. To do this, we update the web.config with the following changes.
      1. Find the membership element under the system.web element of the Web.config
         1. Find the child element providers and for the sitecore provider change the realProviderName to ‘switcher‘. The line will look like:

            <add name="sitecore" type="Sitecore.Security.SitecoreMembershipProvider, Sitecore.Kernel" realProviderName="switcher" providerWildcard="%" raiseEvents="true" />

         2. Then add the following element before the provider closing tag

            <add name="crm" type="CRMSecurityProvider.CRMMembershipProvider, CRMSecurityProvider" connectionStringName="CRMConnString" applicationName="sitecore"  minRequiredPasswordLength="1" minRequiredNonalphanumericCharacters="0"
             requiresQuestionAndAnswer="false" requiresUniqueEmail="true" readOnly="false" enablePasswordReset="true" passwordFieldName="new_sitecorepassword" autoCreatePasswordField="false"/>

            Note:The membership provider add element has a reference to the connection string for the CRM. If you have changed it from the standard one, you will need to update the connectionStringName attribute value here.

      2. Now do the same changes for the roleManager child nodes.
         1. Find the child element providers and for the sitecore provider change the realProviderName to ‘switcher‘. The line will look like:

            <add name="sitecore" type="Sitecore.Security.SitecoreRoleProvider, Sitecore.Kernel" realProviderName="switcher" raiseEvents="true" />

         2. Add the following line below the sitecore element

            <add name="crm" type="CRMSecurityProvider.CRMRoleProvider, CRMSecurityProvider" connectionStringName="CRMConnString"/>

      3. Finally set the profile element under system.web to use the switcher as the defaultProvider.

         <profile defaultProvider="switcher" enabled="true" inherits="Sitecore.Security.UserProfile, Sitecore.Kernel">

         1. Add the following line to the profile providers element

            <add name="crm" type="CRMSecurityProvider.CRMProfileProvider, CRMSecurityProvider" connectionStringName="CRMConnString"/>

Troubleshooting

When updating the user password from Sitecore backend the error “The CRM provider is not configured to store password.” is shown

The error is not quite descriptive and it is a generic catch all error that the CRM provider will throw back. Perform the following checks to identify the issue:

• Ensure that the passwordFieldName="new_sitecorepassword"​ and ​autoCreatePasswordField="false" has been configured as part of the system.web > membership > providers CRM entry [Thanks to Scott Mulligan to point it out on Slack]
• Add the entry ensurePasswordReset="true" to system.web > membership > providers CRM entry [Thanks to Martina Welander to point it out on Slack]
• Check that the passwordFieldName value and the CRM Contact field name match. For non CRM users, the Sitecore Users loaded from the CRM are defined as Contacts in CRM. Note that not all Contacts will be loaded but only the ones that are active and have an email.