Configuring Episerver 7 Connect for CRM

This tech note describes the EPiServer 7 Connect for CRM settings in the application’s configuration file.

Table of contents

• CRM Connector section
• Configuring user profiles
• Virtual role provider
• Configuring the Synchronization Service
• Configuring for sending e-mails

CRM connector section

The crmConnector configuration section contains connection settings for CRM system and mappings for CRM entity fields. See the following configuration example:

<crmConnector current="MSCRM" cacheTime="10">
  <crms>
    <add name="MSCRM" organizationName="Organization" 
         webServiceUrl="http://internal.example.com:5555/mscrmservices/2007/crmservice.asmx" 
         metadataServiceUrl="http://internal.example.com:5555/mscrmservices/2007/metadataservice.asmx" 
         interfaceUrl="http://internal.example.com:5555" 
         domain="Example" userName="CrmUser" password="UserPassword" timeout="30000">
      <entities>
        <add name="Account" crmName="account" idAttribute="accountid" linkName="accts">
          <attributes>
            <add name="Street" crmName="address1_line1" />
            <add name="State" crmName="address1_line2" />
            <add name="PostalCode" crmName="address1_postalcode" />
            <add name="City" crmName="address1_city" />
            <add name="Country" crmName="address1_country" />
            <add name="Name" crmName="name" />
            <add name="WebSiteUrl" crmName="websiteurl" />
          </attributes>
        </add>
        <add name="Contact" crmName="contact" idAttribute="contactid" linkName="conts">
          <attributes>
            <add name="UserName" crmName="new_username" />
            <add name="Low" crmName="new_roles_low" />
            <add name="Medium" crmName="new_roles_medium" />
            <add name="High" crmName="new_roles_high" />
            <add name="CompanyId" crmName="parentcustomerid" parameters="account" />
            <add name="Email" crmName="emailaddress1" />
            <add name="FirstName" crmName="firstname" />
            <add name="LastName" crmName="lastname" />
            <add name="JobTitle" crmName="jobtitle" />
            <add name="Country" crmName="address1_country" />
            <add name="ModifiedOn" crmName="modifiedon" />
          </attributes>
        </add>
      </entities>
    </add>
  </crms>
</crmConnector>

crmConnector element

Root configuration element.

Attributes:

current (required) defines which CRM connection is in use. The value should be the name of CRM defined under crms section described below.

cacheTime is caching time (in seconds) for data from  the CRM system. Value 0 means that caching is disabled.

crms element

Contains one or more add elements, each of them setting up the connection to the CRM system. The following attributes could appear in each of the add sections.

add element attributes:

name (required) is the name of the CRM system. The “current” attribute of the crmConnector section must be equal to one of the CRM names.

organizationName (required only for Microsoft Dynamics CRM) the organization name in CRM system.

webServiceUrl (required) is the URL of the CRM web service.

metadataServiceUrl (required only for Microsoft Dynamics CRM) is the URL of the Metadata web service.

interfaceUrl (required) is the URL of CRM web interface.

domain is domain name for authentication in CRM system.

userName is user name for authentication in CRM system.

password is user password for authentication in CRM system.

timeout (in milliseconds) is connection timeout for CRM web services.

entites element

Contains the list of mappings for CRM entities that are used in the solution. By default this element contains mappings for "Account" and "Contact" entities. Each entity mapping has to be added under the element add.

add element attributes:

name (required) the name of the entity that will be used in solution.

crmName (required) the name of the entity in the CRM system.

linkName (required only for Microsoft Dynamics CRM) the string that is used to create the direct URL to the entity.

idAttribute (required) the name of the attribute that is used as unique identificator for the entity in CRM system.

attributes element

Contains attribute mappings for the entity. Each mapping has to be added under the element add.

add element attributes:

name (required)  is the friendly attribute name. This name must be used to refer to attribute data in solution.

crmName (required) is the name of the attribute in the CRM system. Please refer to the corresponding CRM documentation.

parameters option should be used to provide additional information in order to handle attribute value properly. Currently this setting is used to specify the type of referenced entity for Lookup and Customer fields of Microsoft Dynamics CRM entities. For example, default configuration for Contact entity contains CompanyId attribute which is mapped to parentcustomerid CRM field and parameters setting is defined as "account". Please see the sample configuration above.

Configuring user profiles

You may need to modify the system.web/profile section of the configuration file to configure CRM profile provider, fallback profile provider and specify profile properties which should be stored in CRM. Please see example profile configuration below:

<profile enabled="true" defaultProvider="SqlProfile" automaticSaveEnabled="true">
  <properties>
    <add name="Address" type="System.String" />
    <add name="ZipCode" type="System.String" />
    <add name="Locality" type="System.String" />
    <add name="Email" type="System.String" customProviderData="Email" provider="CrmProvider"  />
    <add name="FirstName" type="System.String" customProviderData="FirstName" provider="CrmProvider"  />
    <add name="LastName" type="System.String" customProviderData="LastName" provider="CrmProvider"  />
    <add name="Language" type="System.String" />
    <add name="Country" type="System.String" customProviderData="Country" provider="CrmProvider"  />
    <add name="Company" type="System.String" customProviderData="CompanyId" provider="CrmProvider"  />
    <add name="Title" type="System.String" customProviderData="JobTitle" provider="CrmProvider" />
    <add name="SubscriptionInfo" type="EPiServer.Personalization.SubscriptionInfo, EPiServer" />
    <add name="CustomExplorerTreePanel" type="System.String" />
    <add name="FileManagerFavourites" type="System.Collections.Generic.List`1[System.String]" />
    <add name="EditTreeSettings" type="EPiServer.Personalization.GuiSettings, EPiServer" />
    <add name="ClientToolsActivationKey" type="System.String" />
    <add name="FrameworkName" type="System.String" />
    <add name="Low" customProviderData="Low" type="bool" provider="CrmProvider" />
    <add name="Medium" customProviderData="Medium" type="bool" provider="CrmProvider" />
    <add name="High" customProviderData="High" type="bool" provider="CrmProvider" />
  </properties>
  <providers>
    <clear />
    <add name="SqlProfile" type="System.Web.Profile.SqlProfileProvider, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" connectionStringName="EPiServerDB" applicationName="EPiServerSample" />
    <add name="FallBackSqlProfile" type="System.Web.Profile.SqlProfileProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" connectionStringName="EPiServerDB" applicationName="EPiServerSampleFallBack" />
    <add name="CrmProvider" type="EPiServer.CRMConnector.Provider.CRMProfileProvider, EPiServer.CRMConnector.Provider" applicationName="EPiServerSample" fallbackProvider="FallBackSqlProfile" />
  </providers>
</profile>

Profile providers

CRM and Fallback profile providers are added in system.web/profile/providers section after Connect for CRM module installation.

CRM profile provider

Stores profile data in CRM system. This provider has following specific settings:

fallbackProvider the name of fallback profile provider which is used to load and store data when CRM system is not available.

applicationName should be the same as for other profile providers of this application.

Fallback profile provider

Fallback provider is any provider that should be used to load and store data when CRM system is not available.

applicationName - should be different from the application name specified for CRM profile provider

User profile properties

Edit profile properties settings to configure which user profile properties should be loaded and stored in CRM system. You may need to update settings for properties like FirstName, LastName, Email, Title, Company and Country to store these data in CRM system. Please see example above.

Define CRM profile provider name in provider attribute of the property element to indicate that this property should be stored in CRM system. Specify the name of corresponding CRM entity attribute in customProviderData element attribute if the names are different.

You should restart IIS to clear the cached properties metadata.

See the MDSN article Implementing a Profile Provider for more detailed information on this subject.

Virtual role provider

Connect for CRM module includes virtual role provider implementation. This provider uses profile data stored in CRM system to verify whether user is in specific virtual role. By default following virtual roles are defined during Connect for CRM installation:

<episerver.framework>
  <virtualRoles replacePrincipal="true">
    <providers>
      <add propertyName="Low" name="Low" type="EPiServer.CRMConnector.Provider.CRMVirtualRoleProvider, EPiServer.CRMConnector.Provider" />
      <add propertyName="Medium" name="Medium" type="EPiServer.CRMConnector.Provider.CRMVirtualRoleProvider, EPiServer.CRMConnector.Provider" />
      <add propertyName="High" name="High" type="EPiServer.CRMConnector.Provider.CRMVirtualRoleProvider, EPiServer.CRMConnector.Provider" />
    </providers>
  </virtualRoles>
</episerver.framework>

Configuring the Synchronization Service

Configuring authentication for the Synchronization Service

Synchronization service is used to get notifications when contact data is changed in external CRM system. Default location of synchronization service is [siteRoot]/modules/ConnectForCrm/SynchronizeService.svc. Consider restricting access to the service by adding location configuration for virtual path where service is deployed, enabling basic authentication for this location and defining users and groups that should have access to the service. Please see Configuring Web Services Authentication article in EPiServer CMS SDK for more details.

Consider adding following settings in in configuration/system.serviceModel section in web.config to enable authorization configuration for Synchronization service location:

<configuration>
  ...  
  <system.serviceModel>
    ...
    <serviceHostingEnvironment aspNetCompatibilityEnabled="true" />    
  </system.serviceModel>
  ...
</configuration>

Credentials must be defined when installing synchronization plug-in for Microsoft Dynamics CRM if authentication is required to access synchronization service. Credentials are stored as plug-in custom configuration and can be updated using plug-in registration tool.

Configuring for sending e-mails

System.Net.Mail API is used to send verification emails and notifications in Connect for CRM Templates. Please check that settings in system.net/mailSettings section are correct in application configuration.

Last updated: November 11, 2013