Azure integration with Microsoft Dynamics CRM

You can connect Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online 2015 Update with the Microsoft Azure platform by coupling the CRM event execution pipeline to the Microsoft Azure Service Bus. This connection lets the data that’s been processed as part of the current CRM operation to be posted to the bus. Microsoft Azure Service Bus solutions that are “CRM-aware” can listen for and read the data that’s posted on the service bus by Microsoft Dynamics CRM. The posted data is stored in a RemoteExecutionContext class instance that is an extended version of IExecutionContext passed at run time to Microsoft Dynamics CRM asynchronous plug-ins.

Key elements of the connection

The key elements that implement the connection between Microsoft Dynamics CRM and the Microsoft Azure Service Bus are as follows:

Asynchronous service

The asynchronous service is responsible for posting the Microsoft Dynamics CRM remote execution context to the Microsoft Azure Service Bus. Each post is performed by a system job of the asynchronous service. A user can view the status of each system job by using the Microsoft Dynamics CRM web application.

Plug-ins

There are two kinds of asynchronous registered plug-ins supported by the connection feature: out-of-box (OOB), those plug-ins that are provided with CRM, and custom. For more information about using synchronous plug-ins with Microsoft Azure, see Access the Notification Service.

An Azure-aware plug-in is provided with CRM. This plug-in executes in full trust with the Microsoft Dynamics CRM platform. When registered with Microsoft Dynamics CRM, the plug-in can notify the asynchronous service to post the current request’s context to the Microsoft Azure Service Bus. A developer needs to register a step on this plug-in that identifies the target message and entity to enable the service bus posting functionality.

You can also write your own custom plug-in that is “Azure-aware”. The custom plug-in executes in partial trust mode in the sandbox and can call any Microsoft Dynamics CRM SDK methods. A custom plug-in can initiate posting of the Microsoft Dynamics CRM context to the service bus by including some standard lines of code that notifies the asynchronous service to post the request context. This cloud-specific code makes the plug-ins “Azure-aware”. For more information about plug-ins in general, see Write a plug-in. For more information about Azure-aware plug-ins, see Write a custom Azure-aware plug-in.

For the CRM and Azure connection to work there must be at least one solution in an Microsoft Azure Service Bus solution account, where the solution contains one or more service endpoints. For a relay endpoint contract, a listener that is “CRM-aware” must be actively listening on the endpoint for the CRM request on the service bus. For a queue endpoint contract, a listener doesn’t have to be actively listening. A listener is made “CRM-aware” by linking it to the Microsoft.Xrm.Sdk assembly so that type RemoteExecutionContext is defined. More information: Write a listener for a Microsoft Azure solution

The solution rules must be configured to allow the Microsoft Dynamics CRM remote execution context to be posted to the service bus. To enable this posting, ACS needs to recognize the CRM deployment as a supported issuer. More information: Configure Azure integration with Microsoft Dynamics CRM.

Important

To develop a solution listener for the Microsoft Azure platform, you need to install the Microsoft Azure SDK version 1.7 or 1.8. on your development computer.

A CRM-to-service bus scenario

Let us now identify a scenario that implements the previously mentioned connection components. As a prerequisite, ACS has been configured to recognize Microsoft Dynamics CRM as the supported issuer and the Microsoft Azure Service Bus solution configured with rules to allow Microsoft Dynamics CRM to post to the endpoint where the listener is.

The following diagram shows the physical elements that make up the scenario.

The sequence of events as identified in this diagram are as follows:

A listener is registered on a Microsoft Azure Service Bus solution endpoint and begins actively listening for the Microsoft Dynamics CRM remote execution context on the service bus.

A user performs some operation in Microsoft Dynamics CRM that triggers execution of the registered OOB plug-in or a custom Azure-aware plug-in. The plug-in initiates a post, through an asynchronous service system job, of the current request context to the service bus.

ACS authenticates the claims posted by Microsoft Dynamics CRM. The service bus then relays the remote execution context to the listener. The listener processes the context information and performs some business-related task with that information. The service bus notifies the asynchronous service of a successful post and sets the related system job to a completed status.

Establish a contract between CRM and an Azure solution

For each solution endpoint, you configure a contract that defines the handling of these remote execution context “messages” on the service bus and the security that should be used on that endpoint. Service bus messages are received at an endpoint using one of the supported contracts listed here.

Queue

A queue contract provides a message queue in the cloud. With a queue contract, a listener doesn’t have to be actively listening for messages on the endpoint. For queues, there is a destructive read and a non-destructive read. A destructive read reads an available message from the queue and the message is removed. A non-destructive read doesn’t remove a message from the queue.

There are two types of queues supported in Microsoft Dynamics CRM: a message buffer queue, and a persistent queue. For message buffer queues, messages in the queue are automatically deleted if not read within a pre-configured length of time that typically is less than 10 minutes. Persistent queues have a much longer message availability duration that can be specified in code.

One-way

A one-way contract requires an active listener. If there is no active listener on an endpoint, the Microsoft Dynamics CRM post to the service bus fails. Microsoft Dynamics CRM will retry the post in exponentially larger and larger time spans until the asynchronous system job that is posting the request is eventually aborted and its status is set to “Failed.”

Two-way

A two-way contract is similar to a one-way contract except that a string value can be returned from the listener to Microsoft Dynamics CRM.

REST

A REST contract is similar to a two-way contract on a REST endpoint.

Topic

Similar to a queue except that one or more listeners can subscribe to receive messages from the topic.

Important

To use these contracts, you must write your listener applications using the Microsoft Azure SDK v1.7 or 1.8.

Message buffer queues are deprecated and won’t be supported in a future release of the Microsoft Dynamics CRM SDK.

Identifying the kind of security a contract uses is part of the contract’s configuration. A contract can use Transport security, which uses Secure Sockets Layer (SSL) (https).

Claims authentication is used for secure access to the service bus. The claim used to authenticate to the service bus is generated in Microsoft Dynamics CRM and signed by the AppFabricIssuer certificate specified in the Microsoft Dynamics CRM configuration database.

Manage of run-time errors

If an error occurred after a post was attempted to the service bus, check the status of the related system job in the Microsoft Dynamics CRM web application for more information on the error. If the service bus is down or a listener/endpoint isn’t available, the current message being processed in Microsoft Dynamics CRM will not be posted to the bus. The asynchronous service will continue to try to post the message in an exponential pattern where it will try to post frequently at first and then at longer and longer intervals. For an internal Microsoft Dynamics CRM error, message posts are not attempted. For an external service bus or network error, the related system job will be in a “Wait” state.