A callout is custom business logic that you can add to modify or augment the standard behavior of the Microsoft CRM system. Another way to think about callouts is that they are extension points made available by the Microsoft CRM system. You can subscribe to a published set of events to have your code run when the event occurs. As part of the subscription, you must specify an event handler. The event handler is a segment of code that runs in response to the system event that is fired. Your event handler must comply with the callout interface. The callout model supports both pre-callouts and post-callouts. Pre-callout code is run before an operation occurs; post-callout code is run after an operation has been completed. There can be any number of pre-callouts or post-callouts associated with a given entity and event.
Callouts run under the security account which is specified on the Identity tab of the CRMAppPool Properties dialog. The dialog can be accessed by right clicking the CRMAppPool Application Pool in Internet Information Services (IIS) Manager and then clicking Properties in the context menu. By default, CRMAppPool uses the "Network Service" account identity. Knowing the CRMAppPool identity is useful when it is desirable to add that account identity to the PrivUserGroup for the purpose of impersonation. For more information on impersonation, refer to the Security and Impersonation section of the SDK documentation.
The following diagram illustrates high-level callout architecture.
The V1.x callout model is being deprecated in Microsoft CRM 3.0 but is supported for backward compatibility. Existing V1.x post-callouts will upgrade and continue to work as long as they do not use classes that are no longer supported, such as activities. For more information, see Mapping from Version 1.2.
In Microsoft CRM 3.0, the callout components can be written in any Microsoft .NET CLR-compliant language such as Microsoft Visual C# and Microsoft Visual Basic .NET. These components are not registered in COM+ as they were in V1.x of the SDK. An XML configuration file is used to configure the callout components. This makes it easier to set up and deploy callouts.
Note Microsoft CRM 3.0 callouts must be created with the .NET Framework version 1.1. Visual Studio 2003 supports this version of the .NET Framework.
The following table lists the logical events that are exposed.
|PreCreate||Generated before an entity instance is created.|
|PostCreate||Generated after an entity instance is created.|
|PreUpdate||Generated before an entity instance is updated.|
|PostUpdate||Generated after an entity instance is updated.|
|PreDelete||Generated before an entity instance is deleted.|
|PostDelete||Generated after an entity instance is deleted.|
|PreAssign||Generated before an entity instance is assigned to a new owner.|
|PostAssign||Generated after an entity instance is assigned to a new owner.|
|PreSetState||Generated before the state is changed for entity instance.|
|PostSetState||Generated after the state is changed for an entity instance.|
|PreMerge||Generated before merging two entity instances.|
|PostMerge||Generated after merging two entity instances.|
|PreSend||Generated before sending an e-mail.|
|PostDeliver||Generated after delivering an e-mail|
A typical SDK message, such as Create, generates a pre-event and a post-event. You can subscribe to these events by registering a custom callout component. Compared to the V1.X callout model, the new callout model limits the entities for which callouts can be registered. A complete list of entities and user actions that generate these events is described in the Reference section of this document.
After a callout component is registered for a given entity and an event, the system can call the component to execute custom logic when the event occurs. As part of the invocation of the callout component, entity and user context information, in addition to event specific information, is passed to the callout component.
Callout components can pass information back to the system. The information that is passed back depends on the type of callout. For more information, see the documentation of each callout method in the Reference section.
A pre-callout is invoked by the system in response to an event, but before the event is processed by the system. Pre-callout code runs synchronously within the method call. This means that the system initiates the pre-callout and then waits for it to complete before continuing the execution of any other pre-callouts subscribed to that same entity and event. There can be any number of pre-callouts associated with each entity and event.
When the pre-callout component is invoked, the system passes the full set of entity attributes to the callout component. The pre-callout component can modify the attributes and pass them back to the system. The pre-callout can return an instruction back to the system that indicates whether to stop, continue, or abort execution of subscribed pre-callouts and processing of the event. The pre-callout can also return a custom error message. This error message is passed back to the system from the pre-callout and displayed to the user only if the pre-callout returns an abort instruction. The system ignores the custom error message if the returned instruction from the pre-callout is to stop or continue. For more details, refer to the pre-callout methods in the source code sample and the PreCalloutReturnValue enumeration.
The following illustration shows the pre-callout model.
If there are multiple pre-callout components registered for an entity and an event, the system invokes all the components serially. The entity and user context remain the same with each invocation. However, the values for the attributes may be different because each pre-callout component can modify the attribute values. For example, if there are three callouts registered for the Account PreCreate event, the second callout component receives attribute values that may have been modified by the first callout component. Similarly, the third callout component receives attribute values that may have been modified by both the first and second callout components.
The post-callouts are invoked by the system in response to the post-events, which occur after an event has been processed by the system. Any number of post-callouts components can be associated with each entity and event.
You can specify a set of entity attributes to be passed to the post-callout component. The system captures the attribute values (pre values) for the specified attributes before the event is processed by the system. These attributes are called the pre-image attribute set. The post-image of the attributes is also passed to the callout component. You define the set of attributes to be passed in the configuration file.
When post-callouts are fired, the system has already committed the data changes. If the core system operation fails, the system does not invoke any post-callouts.
Post-callouts execute synchronously within the system method call. This means that the system initiates the post-callout and then waits for it to complete before continuing the execution of the system method call.
For more information and a list of the callout events, see CrmCalloutBase Class.
© 2007 Microsoft Corporation. All rights reserved.