One of the challenging things about being CTO for a small company is that you have no choice but to wear many different hats and solve a smattering of problems that you wouldn't normally deal with as CTO of a larger organization. The benefits that this brings—besides giving you more control—is the opportunity to learn about tools and technologies in greater depth than you normally would. Recently, this has been the case for me with Microsoft's CRM software.
(For those of you not using Microsoft's CRM software, you can find out all about it here.)
Our Process
At Knowledge Relay, we have been using Microsoft CRM for quite a while now (since its first release). Among other things, we use it to keep track of potential contacts (CRM Leads) that have registered with us on our Web site to download the software products we sell. Once we have a lead in the system, a sales person can make the decision when to convert the lead into a CRM Contact or CRM Customer based on other criteria (such as the lead downloading or purchasing our software). Despite achieving this customer-to-Web site tracking, we were not achieving the kind of efficiency and automation goals to make the product really simple and effective for our small sales staff to use. Sales persons were having to manually copy information out of e-mails generated by our Web site and paste that information into forms within the CRM system. Obviously, this is not a model of efficiency. So, we decided to look into the possibility of having our Web site automatically generate both leads and activities associated with those leads. Then, any sales person logging into CRM would see the items appear in their activity list.
Knowing that Microsoft CRM is an ASP.NET Web application powered by XML Web Services at the back-end, I had a hunch that either I'd need to call the appropriate Web Services from my code, or use the CRM API which, in turn, would call the appropriate Web Services. Because the latter is the approach I found used in the CRM SDK, I went with that. Now that I knew how to programmatically access the CRM, I set out to accomplish the following:
| Web Site Action(s) |
CRM Action(s) |
| 1. User Registration |
1. CRM Lead Creation
2. CRM Activity referencing new Lead |
| 2. User confirms e-mail/registration |
1. CRM Activity referencing new Lead |
| 3. User downloads a product |
1. CRM Activity referencing new Lead |
| 4. User requests a product demo |
1. CRM Activity referencing new Lead |
Developing the Solution
With my developer hat on, I went to the Class Library section of the CRM SDK Reference. The first page reads:
"This class library is a library of classes, interfaces, and enumerations that are included in the Microsoft CRM SDK. These are found in the Microsoft.Crm.Platform.Proxy.dll assembly. This library provides access to system functionality and is designed to be the foundation on which custom Microsoft CRM applications are built.
The Microsoft.Crm.Platform.Types.dll assembly contains the value types used to build XML strings for the APIs found in the proxy assembly."
Eureka! Okay, so I found the names of the two assemblies I need to reference to have access to the CRM system functionality. Now, all I need to do is go find these two assemblies. My first thought was to go look in the bin directory beneath the root of the CRM virtual directory where the CRM was installed on our server. I found many assemblies there, but neither of the two I was looking for. Strangely enough, it turns out that these two assemblies are not copied from the CRM disc as part of the installation process. To get them, you'll have to locate the wwwroot\bin directory on your installation CD. This wasn't mentioned anywhere that I could find in the CRM SDK Documentation, but the Microsoft.public.crm.developer newsgroup produced the answer without much trouble. Now that I had these two assemblies, I created a new ASP.NET project in Visual Studio.NET 2003 and referenced them from the /bin subdirectory of my project virtual directory.
In the small corner of the CRM I worked in (Leads and Activities), creating CRM objects generally followed the same pattern:
- Construct a string that points to the CRM platform server's virtual directory. For example, http://myservername/mscrmservices/. This directory should contain the .srf files that will be referenced in the URL property of various CRM objects. You'll see more about this in the code samples listed later.
- Create a Microsoft.Crm.Platform.Proxy.BizUser object and assign it the necessary credentials using a System.Net.CredentialCache object. Add credentials using the URI of the .srf files that the CRM Objects need access to.
- Use the BizUser.WhoAmI() method to return a Microsoft.Crm.Platform.Proxy.CUserAuth object that will contain the GUID representing the System User Id for the BizUser object. You'll need this GUID value to inject into the <owner> node of the XML text you submit to the CRMLead.Create() method.
- Construct an XML string that describes the CRM Object you want to create. The CRM SDK Documentation conveniently provides links to .xsd files that describe the XML schemas for the various CRM Objects.
- Optionally, you can capture the GUID value for the created CRMLead or CRMActivity object returned by their respective Create() methods. You may or may not need to store this GUID somewhere for later use.
The Code
The following code demonstrates the concept of creating CRMLead and CRMActivity objects. I've removed some of the code related to the custom requirements for our Web pages so the code can apply generally to any implementation.
Listing 1: Generate a CRMLead and CRMActivity upon user registration
public class ConfirmRegistration : System.Web.UI.Page
{
private string FirstName;
private string LastName;
private string ServerName;
private string VirtualDirectory;
private string Dir;
private string CRMLeadGUID;
private Microsoft.Crm.Platform.Proxy.CRMLead Lead;
private Microsoft.Crm.Platform.Proxy.CRMActivity Activity;
private Microsoft.Crm.Platform.Proxy.CUserAuth UserAuth;
private Microsoft.Crm.Platform.Proxy.BizUser bizUser;
private void Page_Load(object sender, System.EventArgs e)
{
if(Request.QueryString["firstname"] != null)
{
FirstName = Request.QueryString["firstname"];
}
if(Request.QueryString["lastname"] != null)
{
LastName = Request.QueryString["lastname"];
}
ServerName = "MyServer";
VirtualDirectory = "mscrmservices";
Dir = http:// + ServerName + @"/" + VirtualDirectory + @"/";
System.Net.CredentialCache MyCredentials =
new System.Net.CredentialCache();
System.Net.NetworkCredential MyNetCred =
new System.Net.NetworkCredential(
@"johndoe",
@"somepassword",
@"ourdomain.com");
MyCredentials.Add
(new Uri(Dir + "BizUser.srf"), "NTLM", MyNetCred);
MyCredentials.Add
(new Uri(Dir + "CRMLead.srf"), "NTLM", MyNetCred);
MyCredentials.Add
(new Uri(Dir + "CRMActivity.srf"), "NTLM", MyNetCred);
//BizUser object
bizUser = new Microsoft.Crm.Platform.Proxy.BizUser();
bizUser.Credentials = MyCredentials;
bizUser.Url = Dir + "BizUser.srf";
//CRMLead object
Lead = new Microsoft.Crm.Platform.Proxy.CRMLead();
Lead.Credentials = MyCredentials;
Lead.Url = Dir + "CRMLead.srf";
try
{
UserAuth = bizUser.WhoAmI();
String LeadXml = @"<lead>";
LeadXml += @"<lastname>";
LeadXml += LastName;
LeadXml += @"</lastname>";
LeadXml += @"<firstname>";
LeadXml += FirstName;
LeadXml += @"</lastname>";
LeadXml += @"<ownerid type=""" +
Microsoft.Crm.Platform.Types.ObjectType.otSystemUser.
ToString();
LeadXml += @""">";
LeadXml += UserAuth.UserId ;
LeadXml += @"</ownerid>";
LeadXml += @"</lead>";
CRMLeadGUID = Lead.Create(UserAuth, LeadXml);
}
catch(System.Web.Services.Protocols.SoapException)
{
//error handling logic here
throw;
}
catch(Exception)
{
//error handling logic here
throw;
}
//Create the CRM Activity
try
{
Activity = new CRMActivity();
Activity.Credentials = MyCredentials;
Activity.Url = Dir + "CRMActivity.srf";
string ActivityXML = "<activity>";
ActivityXML += @"<subject>Registration for";
ActivityXML += FirstName + " " + LastName;
ActivityXML += @"</subject>";
ActivityXML += @"<description>";
ActivityXML += "Here is the description";
ActivityXML += @"</description>";
ActivityXML += @"<activitytypecode>134";
ActivityXML += @"</activitytypecode>";
ActivityXML += @"<objecttypecode>4"; //4 = CRMLead
ActivityXML += @"</objecttypecode>";
ActivityXML += @"<objectid>" + CRMLeadGUID;
ActivityXML += @"</objectid>";
ActivityXML += @"<prioritycode>1";
ActivityXML += @"</prioritycode>";
ActivityXML += @"<scheduledstart>";
ActivityXML += DateTime.Now.ToString("s",
DateTimeFormatInfo.InvariantInfo);
ActivityXML += @"<ownerid type=""" +
Microsoft.Crm.Platform.Types.ObjectType.otSystemUser.
ToString();
ActivityXML += @""">";
ActivityXML += UserAuth.UserId + @"</ownerid>";
ActivityXML += @"</activity>";
//Create the "Activity Party" XML
String ActPartyXml = @"<activityparties>";
ActPartyXml += @"<activityparty><partyid>";
ActPartyXml += CRMLeadGUID + @"</partyid>";
ActPartyXml += @"<partyobjecttypecode>" +
Microsoft.Crm.Platform.Types.ObjectType.otLead.ToString();
ActPartyXml += @"</partyobjecttypecode>";
ActPartyXml += @"<participationtypemask>" +
Microsoft.Crm.Platform.Types.ACTIVITY_PARTY_TYPE.
ACTIVITY_PARTY_REGARDING.ToString();
ActPartyXml += @"</participationtypemask>";
ActPartyXml += @"</activityparty>";
ActPartyXml += @"</activityparties>";
//Create the Activity
string CRMActivityGUID =
Activity.Create(UserAuth, ActivityXML, ActPartyXML);
}
catch(System.Web.Services.Protocols.SoapException)
{
//error handling logic
throw;
}
catch(Exception)
{
//error handling logic
throw;
}
}
}
As you can very easily tell, the CRM API involves creating a lot of XML text to pass to the CRM Web Service end point.
IE 7
Firefox 2.0
