Home » Capitalizing on Microsoft Dynamics CRM 3.0 Callouts: Introduction to Callouts

Capitalizing on Microsoft Dynamics CRM 3.0 Callouts: Introduction to Callouts

ustomer Relationship Management (CRM) plays a major role in today’s competitive business industry. Imagine how frustrated you would feel if you were to get a call from customer support at a bank where you already hold a credit card asking you…if you’re interested in applying for a credit card! Microsoft’s Dynamics CRM (MSCRM) is a software package that helps avoid such problems by uniquely identifying your customers and tracking your organization’s interactions with them. This article presents an overview of MSCRM Callout and how you can implement it in your applications.

Callouts are also called “Business Logic Extensions.” They help developers using MSCRM execute business logic, either before or after a published event has occurred. Callouts are useful when you want to integrate MSCRM with other systems, such as SharePoint, or other ERP systems. There are two types of callouts: pre- and post-callouts. A pre-callout fires just prior to the occurrence of an event, while a post-callout fired just after the event occurs.

Callouts consist of two parts:

A callout configuration file
A callout assembly

The callout configuration file contains callout definitions.

Author’s Note: You must save all your callouts in a file named callout.config.xml.

Another requirement for callouts is that they must be able to validate against an XML schema file. Listing 1 shows the callout schema.

Fortunately, a typical callout config file is considerably simpler than the schema; here’s an example:

                        @all           @all

In the preceding code, the node defines the entity name (lead) and the event (PostUpdate) for this callout, meaning that this callout will fire after a Lead record gets updated in MSCRM.

The child node defines an assembly and a class name from a DLL containing custom business logic that you want to run when the callout fires.

The

and child nodes define values passed to the callout method.

Creating or Updating Callout Configuration files
You have to be very careful when creating or updating the callout configuration file. More often than not, the configuration file ends up being the root cause for many common callout errors. Here are few points to remember when you’re creating or modifying the configuration file:

When you first install MSCRM, no callout configuration file exists; you have to create the file manually.
Because there is only one callout configuration file (callout.config.xml) for all the callouts, it quickly becomes important to keep the callout configuration file under some sort of version control, such as VSS, TFS, Subversion, and so on.
Prevalue and postvalue nodes in the callout config file are used only by Post callouts.
MSCRM passes only non-null values to the callout even if you specify that it should to pass all values (using @all as in the preceding example).
In the prevalue and postvalue nodes, specify only those columns that you need in callout code. Specifying unnecessary columns will send large amounts of XML data as input to the callout methods and hence will hinder performance.
MSCRM lets you to associate any number of callouts with an event. However, it’s not possible to write more than one callout method for an event in one class.
Changes you make to the configuration file do not effect until you restart IIS.

Implementing a Callout
As an example, here’s a sample callout that appends sales leads to a text file whenever the lead status changes from “new” to a different status. Here, you’d use the PostUpdate event of the lead entity to trigger the callout. To begin, you need to create a callout configuration file (if you don’t have one already). To do that:

Restart IIS
Navigate to C: Program FilesMicrosoft CRMserverinassembly

Author’s Note: All paths assume MSCRM is installed on your C: drive.

In that folder, create a new XML file named callout.config.xml.
Open this file in notepad and paste the contents of the sample file callout.config.xml (available in the downloadable code that accompanies this article).
Restart IIS again.

Now, you need to create the callout assembly. To do so, follow these ten steps.

Open Visual Studio and create a new class library named LeadIntegrationCRMCallout.
Copy the Microsoft.Crm.Platform.Callout.Base.dll located in the Microsoft CRM server CD (Disk 1) at GAC to your local bin folder.
Add a reference to that DLL.
Add a web service reference to the CRM service and name it CrmSdk.
Rename the default class1.cs to LeadCallout.cs.
Paste (or download) the code shown below into LeadCallout.cs

      public override void PostUpdate(      CalloutUserContext userContext,       CalloutEntityContext entityContext,       string preImageEntityXml,       string postImageEntityXml)   {         XmlDocument entityDoc;      try      {         entityDoc = new XmlDocument();         entityDoc.LoadXml(postImageEntityXml);            string nameSpaceValue = entityDoc.ChildNodes[0].Attributes            ["xmlns"].Value;         XmlNamespaceManager xsn = new            XmlNamespaceManager(entityDoc.NameTable);         xsn.AddNamespace("z," nameSpaceValue);            string entityXpath = "//z:BusinessEntity";         XmlNode businessEntityNode =             entityDoc.SelectSingleNode(entityXpath, xsn);                            string businessEntityName =             ((XmlElement)businessEntityNode).            GetAttribute("Name").ToString();            switch (businessEntityName.Trim().ToLower().ToString())         {            case MSCRMLEAD:               ProcessLeads(preImageEntityXml, postImageEntityXml);               break;            default:               break;         }      }      catch (Exception ex)      {         //TODO :Log exceptions to Event log      }      finally      {         entityDoc = null;      }   }

To finish the procedure:

Build the assembly.
Restart IIS.
Copy the newly created assembly into the C:Program FilesMicrosoft CRMserverinassembly folder.
Restart IIS.

How the Callout Works
Here is what the PostUpdate callout method does. Whenever a lead record’s status is changed, it fires the PostUpdate method, which serializes the postImageEntityXml to a dynamic entity and calls the ProcessLeads method if the name of the entity is lead. The ProcessLeads method writes the postImageEntityXml to a text file. To run the application, follow these steps.

Launch the CRM browser and navigate to the Sales tab.
Click on Leads, and then click on New.
Enter the first name, last name, and country, and then click on Save, and finally, Close.
Double-click on the newly created record to open it in edit mode.
Change the status from “New” to something else.
Open the text file whose name begins with “Crmcallout” on the C: drive.
Compare the values in the text file with the newly updated record in the CRM (see Figure 1).


Figure 1. Updated Record: Your newly updated record should look similar to this one.

Some important points that you should note while developing a callout are:

You should not access System.Console or use Pinvoke in the callout code.
Make sure that you don’t update the entity itself in its post-callout; doing so will cause a deadlock. If you must do that, put the required code in place to avoid deadlocks.
MSCRM callouts do not call Dispose methods; therefore, you should write your code so it explicitly releases resources.

Deploying Callout Assemblies
When you finished developing the assembly, place it in the C:Program FilesMicrosoft CRMserverinassembly folder. Note that you don’t need to deploy the Microsoft.Crm.Platform.Callout.Base.dll because it’s already installed in the GAC. Finally, restart IIS to force the changes to take effect. If you get an error similar to the one in Figure 2, cycle IIS again.


Figure 2. Typical IIS Error: IIS can’t copy files when they’re in use.

Using MSCRM callouts, you can validate CRUD operations and integrate your CRM application with other applications, such as ERPs, SharePoint Portals, etc. In a nutshell, you’ve seen how to build a callout assembly that exposes methods triggered when specific corresponding MSCRM events fire. Building the callout assembly is straightforward, but when you finish creating and deploying the assembly, remember to reset IIS before executing the application. The second article in this series delves into some more advanced issues.

About Our Editorial Process

At DevX, we’re dedicated to tech entrepreneurship. Our team closely follows industry shifts, new products, AI breakthroughs, technology trends, and funding announcements. Articles undergo thorough editing to ensure accuracy and clarity, reflecting DevX’s style and supporting entrepreneurs in the tech sphere.

See our full editorial policy.