Creating a Connection in EPiServer Connect for CRM

Introduction

This tech note describes how to use EPiServer Connect for CRM in order to create a connection between the CRM application and a Web site based on EPiServer CMS 6. EPiServer Connect for CRM is designed to provide connections for CRM applications Microsoft CRM and SalesForce Web Services. EPiServer Connect for CRM contains a framework allowing partners to configure and work with any of these CRM applications.

There is an ASP.NET profile provider available which can be used like the standard ASP.NET providers. EPiServer Connect for CRM provides an easy way to include this functionality in the templates. EPiServer Connect for CRM has a special virtual role provider that can use information from CRM for grouping users. This makes it is possible to create user-dependent Web site content for different user interest groups.

Requirements

• A working CRM application (MS CRM) or an active login to Sales Force Web services.
• A web server running EPiServer CMS CMS 6 

Note that the Web server with EPiServer CMS needs to have a proper membership provider such as the SqlMembershipProvider, with possibilities to add and change user parameters.

Configuration

The Web site must be properly configured, please refer to configuration Tech Notes for EPiServer Connect for CRM and EPiServer CMS 6.

CRM Applications in EPiServer Connect for CRM

EPiServer Connect for CRM currently provides connections for Microsoft Dynamics CRM and SalesForce Web Services. These applications are described more in the following.

Microsoft CRM application

Microsoft Dynamics CRM 4.0 is a fully integrated customer relationship management system. Microsoft Dynamics CRM integrates with key Microsoft products and technologies, including the 2007 Microsoft Office system and Microsoft Office SharePoint Server 2007, Windows Vista, and others. All communication with the application goes through the Web interface. There are two main services providing a possibility to manage MS CRM remotely.

Sales Force CRM

SalesForce CRM is designed as a Web application that is published on a special site providing CRM functionality. This system is based on its own internal database and interfaces that can be customized. 

EPiServer Connect for CRM Solution Architecture

The architecture of EPiServer Connect for CRM can be viewed in the CRMConnector.vsd Visio file. The solution contains three layers: a client layer, a business layer, and a database layer. These layers ensures consistency and provides flexibility for changes.

1. Client layer

The client layer contains a Web user control for new user registrations to the CRM application. Any additional user controls or custom controls can be easily added to this layer. Apart from UI controls, the layer contains a profile and virtual role provider implementations. These can be used by Web sites sources.

The profile provider gets information from the CRM application. Should the CRM application be inaccessible for some reason, a special fallback provider mechanism is used. This mechanism will instead retrieve settings from a reserve profile provider in “read-only” mode.

The virtual role provider allows for use of a CRM roles schema. It is possible to create a set of custom settings in the Contact table of the CRM application. These settings can contain roles for a CRM contact. When the user logs in to the Web site, appropriate ID and role settings are retrieved from the Contact table of the CRM application. Depending on the settings of the user roles, it is possible to control the site content and show or hide parts of the information for different user groups.

2. Business layer

This layer contains a set of interfaces for business entities of the CRM applications. In the current implementation the layer contains interfaces for the Contact and Account business entities. The main function of the business layer is that it hides all the differences between the CRM applications - MS CRM and Sales Force. The developer can use the business interfaces in the client layer without having to think about any differences.

The Contact business entities contain information about all contacts stored in the CRM data storage. Every contact has information about name, email and other personal data. The Account business entities contain information about business related organizations and companies. Every account has information about company name, address and other company attributes.

3. Database layer

Depending on the CRM application architecture, the EPiServer Connect for CRM database layer contains special interfaces for working with the Web services provided by the CRM applications. The layer contains Web service proxy classes for each CRM application, as well as classes for cache management. It also has helper classes to simplify the work with proxy wrappers.

Getting Information From the CRM Application

To get information from the CRM application you need to go through the following:

1. Configure an application settings file (web.config or app.config files). It is important that this is done correctly. Since the CRM system is an independent application, the CRM administrator can do security changes affecting the setup, without your notification.
    
2. You always need to verify that the connection exists. Since the CRM application is an independent application, it can be inaccessible at any moment. Every call to the CRM system will affect the application performance so try to use a cache mechanism.
     
3. Create an instance of business entity using the factory class. There is a base factory class named CRMBaseFactory that creates instances of business entities according to your settings in the application settings file. The CRMBaseFactory method calls an appropriate Web service method and returns the instance initialized with CRM values.
    
4. Values of the business entity instance can be accessed by an indexer. The parameter for the indexer should be the field name from the application settings file.

Code example: Getting a user email from Microsoft CRM to EPiServer Connect for CRM

1. Configure the Web.config/App.config file.
   Add this to Web.config/App.config file crmConnector node and configure it according to description in the EPiServer CRM Connector Installation Instruction.
    
   <crmConnector current="MSCRM">
    <crms>
      <add name="MSCRM" webServiceUrl="http://172.16.16.139:5555/mscrmservices/
    2006/crmservice.asmx" metadataServiceUrl="http://172.16.16.139:5555/mscrmservices/
    2006/metadataservice.asmx" interfaceUrl="http://172.16.16.139:5555/EPiServer" userName="administrator" password="" domain="" timeout="30000">
        <entities>
          <add name="Contact" crmName="contact" idAttribute="contactid" linkName="conts">
            <attributes>
              <add name="UserName" crmName="new_username" />
              <add name="Email" crmName="emailaddress1" />
            </attributes>
          </add>
        </entities>
      </add>
    </crms>
  </crmConnector> 
2. Create a special class UserEmail that will provide logic for getting user emails, public class EmailUser.
   public class EmailUser
    {
        private string _userName;
        private string _emailUser;
        public EmailUser(string userName)
        {
            this._userName = userName;
        }
        public string Email
        {
            get
            {
                if(this._emailUser == null)
                {
                    this.InitEmailProperty();
                }
            }
        }
    }
3. Call a factory TestConnection to verify that settings are correct inside the method of UserEmail class:
   private void InitEmailProperty()
{
    if(CRMBaseFactory.Current.TestConnection())
    {
        this._emailUser = this.GetUserEmail();
    }
}
4. Add a new method to UserEmail class that will get an email for User1 user:
   private string GetEmailFromCRM()
{
    List<ICRMContact> contactsbyName = CRMBaseFactory.Current.LoadContactsByName(this._userName);
    if(contactsbyName.Count == 0)
    {
        throw new ArgumentException(string.Format("Incorrect user name {0}", this._userName));
    }
    return contactsbyName[0]["Email"];
}