Callouts

Callouts, also referred to as Business Logic Extensions in the SDK, provide a synchronous mechanism to run custom logic or spawn custom processes both before and after Microsoft CRM executes a request against the platform layer. Figure 9-8 shows the callout integration approach.

Figure 9-8: Callout architecture

Microsoft CRM 3.0 supports both pre-callouts (events that fire before an action is taken against the platform) and post-callouts. Further, the Microsoft CRM 3.0 callout architecture is fully .NET-compliant, which means it uses a simple configuration file registration to solve the COM+ installation woes.

Tip 

When developing integration to and from other applications, you will typically make heavy use of the Microsoft CRM pre- and post-callout model.

Available Events

As users work within the application, their actions cause Microsoft CRM to trigger callout assemblies. Table 9-4 lists the events available for both pre- and post-calls.

Table 9-4: Pre- and Post-Callout Events

Event	Event names	Description
Create	PreCreate PostCreate	Fired when a new record is created
Update	PreUpdate PostUpdate	Fired when an existing record is modified
Delete	PreDelete PostDelete	Fired when a record is deleted
Assign	PreAssign PostAssign	Fired when a record is assigned to a new owner
Set state	PreSetState PostSetState	Fired when a record's state value is changed
Merge	PreMerge PostMerge	Fired when the merge command is executed against two records

Configuration File

The callout configuration file defines the callout events and registers custom assemblies against those events. The configuration file must be named Callout.config.xml and deployed to the assembly directory located on the Web server <crm install drive>\Program Files\Microsoft CRM\server\bin\assembly by default. An example configuration file does not exist on the Web server, but examples do exist with the sample code of the SDK.

Tip 

Add the configuration file to your project to keep it under version control so that multiple developers can easily access it.

We will now discuss the key elements that the configuration file contains. The main node is the <callout> node, which takes an entity and an event as attributes. The entity will be the entity schema name, and the event will be one of the twelve events listed in Table 9-4. The following is an example of registering a post-callout routine to fire when a user modifies an Account record.

 <callout entity="account" event="PostUpdate"> 

The <callout> node has a child node called <subscription>. Subscriptions define the assembly, class, and parameters of your event. The assembly and class attributes do just as you would expect. A sample callout subscription is shown here.

 <callout.config version="2.0">  <callout entity="account" event="PostUpdate">  <subscription assembly="CalloutAssembly.dll"  >   <prevalue>name</prevalue>   <postvalue>name</postvalue>  </subscription>  </callout> </callout.config> 

The <prevalue> and <postvalue> child nodes denote which entity schema attribute values Microsoft CRM should pass in to the callout assembly. In the preceding sample, the PostUpdate event will send the Account's original name value (prevalue) as well as the submitted value (postvalue). These prevalue and postvalue nodes are optional, but if you do not include them, Microsoft CRM will not pass any values to your callout method. Again, Microsoft CRM will pass only non-null values into your callout code, so make sure that your code won't error if it doesn't receive a data value that it expects.

Note 

Microsoft CRM will ignore the <prevalue> and <postvalue> nodes depending on the event. For instance, the <postvalue> node is ignored for the pre-callout events.

Lastly, do not include nodes that you do not need in your assemblies. You will just hinder performance by sending a larger XML stream than required, and you will also put more processing on your methods, as you will have to filter through the extraneous elements.

Tip 

If necessary, you can pass all the fields using the keyword @all, as in <prevalue>@all </prevalue> or <postvalue>@all</postvalue>. Remember that Microsoft CRM returns only non-null values to the callout, even if you use the @all setting.

The SDK contains additional examples of the callout assemblies and configuration files.

Development

When you develop a callout assembly, you must add a reference to Microsoft.Crm.Platform.Callout.Base.dll in your project file. This file is located on the Microsoft CRM server CD (Disk 1) at <server CD>\GAC\Microsoft.Crm.Platform.Callout.Base.dll. Copy this file to a directory on your development client, and add a reference to it in Visual Studio .NET. As always, update the Url parameter with your Microsoft CRM server. Also update the default record GUIDs per the comments in the code.

After you reference the Callout.Base.dll file in your project, you can build a custom callout assembly. Simply create a standard class library and add a class file. Your class file must inherit from CrmCalloutBase, as the following snippet shows.

 using Microsoft.Crm.Callout; namespace MyCompany.Callout {  public class CalloutExample : CrmCalloutBase  {  } } 

Important 

You should not reference any of the Microsoft CRM .dll files other than Microsoft.Crm.Platform.Callout.Base.dll in your projects.

Deployment

Because of its .NET architecture, deploying your custom Microsoft CRM 3.0 callout requires minimal effort. You simply copy your assemblies and the callout configuration file to the Microsoft CRM Web server in the following directory: <crm install drive>\Program Files\Microsoft CRM\server\bin\assembly.

After you put the files in this folder, you must restart Internet Information Services (IIS), which you can do with an iisreset of the Microsoft CRM Web server. If you already have a callout installed and you try to update the folder, you might get the error shown in Figure 9-9, because IIS already has an instance of the .dll file in memory.

Figure 9-9: Error deploying a callout

To avoid this problem, perform an iisreset before copying the assembly files. Remember that you should try to deploy only when users are not accessing Microsoft CRM, because running the iisreset command restarts the Web server.

Note 

You do not have to deploy Microsoft.Crm.Platform.Callout.Base.dll. Microsoft CRM automatically installs this file to the global assembly cache (GAC) of the Web server during the installation process, which makes it available to your assemblies.

We will demonstrate coding examples of the callout at the end of the chapter.