Share via

Azure integration with Microsoft Dynamics 365

  • Article

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

You can connect Microsoft Dynamics 365 (online & on-premises) with the Microsoft Azure platform by coupling the Dynamics 365 event execution pipeline to the Microsoft Azure Service Bus. Once configured,this connection allows data that’s been processed as part of the current Dynamics 365 operation to be posted to the service bus. Microsoft Azure Service Bus solutions that are “Dynamics 365-aware” can listen for and read the Microsoft Dynamics 365data from the service bus.

This connection between Microsoft Dynamics 365 and the Microsoft Azure platform provides a secure and reliable channel for communicating Dynamics 365 run-time data to external cloud-based line-of-business (LOB) applications.

In This Topic

Key elements of the connection

A Dynamics 365-to-service bus scenario

Establish a contract between Dynamics 365 and an Azure solution

Manage of run-time errors

Key elements of the connection

The key elements that implement the connection between Microsoft Dynamics 365 and the Microsoft Azure Service Bus are described below. A diagram in the next section shows these elements in operation.

  • Data Context
    The data context contains the business data that is being processed as part of the current Dynamics 365 operation. This processing was initiated when a request to perform a certain operation was made by a user, workflow, or application, to the Dynamics 365 platform. The data context is passed to any plug-ins or custom workflow activities that are registered with the event pipeline to execute on the specific request and entity combination that is currently being processed. The data context is of type IPluginExecutionContext when it is being passed along the event execution pipeline and RemoteExecutionContext when it is posted to the service bus.

    The data context contained within the message that is posted to the Microsoft Azure Service Bus can be formatted in XML or JSON in addition to the default .NET binary format. This allows for cross-platform interoperability where Azure hosted non-.NET clients can read Dynamics 365 data from the service bus. This feature was introduced in CRM Online 2016 Update 1 and CRM 2016 Service Pack 1 (on-premises)..

    For more information about the technologies described above see: Understand the data context passed to a plug-in, Event execution pipeline, and Write a listener application for a Microsoft Azure solution.

  • Plug-ins
    Plug-ins are one of two methods used to initiate posting the message containing the data context to the Microsoft Azure Service Bus, the other method being a custom workflow activity. There are two kinds of plug-ins supported by the Dynamics 365-Azure connection feature: out-of-box (OOB), and custom. In either case, it is recommended that you register the plug-in to run asynchronously for best system performance.

    An Azure-aware OOB plug-in is provided with Dynamics 365 and can be registered using the Plug-in Registration Tool in the SDK download. This plug-in executes in full trust with the Microsoft Dynamics 365 platform. You must register a plug-in 'step' in the event execution pipeline that identifies the message and entity combination that triggers the plug-in to execute and perform the posting notification. When executed, the plug-in notifies the asynchronous service, through a service endpoint notification service (IServiceEndpointNotificationService), to post the current request data context to the Microsoft Azure Service Bus.

    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. A custom plug-in can initiate posting of the data context to the service bus through the service endpoint notification service. Adding code to invoke this service makes the plug-in “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.

  • Custom Workflow Activities
    Similarly to plug-ins, custom workflow activities can be written to initiate posting the current request message data context to the Microsoft Azure Service Bus by using the service endpoint notification service (IServiceEndpointNotificationService). More information: Sample: Azure aware custom workflow activity.

  • Asynchronous Service
    Once notified by the service endpoint notification service, the asynchronous service handles posting the data context of the request message currently being processed by the event execution pipeline 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 System Jobs view of the Microsoft Dynamics 365 web application.

    For more information about the asynchronous service see Asynchronous service in Microsoft Dynamics 365.

  • Microsoft Azure Service Bus
    The service bus relays the request messagedata context between Microsoft Dynamics 365 and Microsoft Azure Service Bus solution listener applications. The service bus also provides data security so that only authorized applications can access the posted Dynamics 365 data. Authorization of Microsoft Dynamics 365 to post the data context to the service bus and for listener applications to read it is managed by either Microsoft Azure Active Directory Access Control Service (ACS) or Microsoft Azure Shared Access Signatures (SAS).

    Note

    About SAS authorization: This feature was introduced in CRM Online 2016 Update 1 and CRM 2016 Service Pack 1 (on-premises). SAS is a more modern form of authorization and exhibits better performance when compared to ACS.

    For more information about the service bus see Service Bus. For more information about service bus authorization see Service Bus authentication and authorization.

  • Microsoft Azure Solution
    For the Dynamics 365-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 application that is “Dynamics 365-aware” must be actively listening on the endpoint for the Dynamics 365 request on the service bus. For a queue endpoint contract, a listener doesn’t have to be actively listening. A listener is made “Dynamics 365-aware” by linking it to the Microsoft.Xrm.Sdk assembly so that type RemoteExecutionContext is defined. More information: Write a listener application for a Microsoft Azure solution

    Microsoft Dynamics 365 supports sending event data to an Azure Event Hubs solution. This feature was introduced in CRM Online 2016 Update 1 and CRM 2016 Service Pack 1 (on-premises).. For more information about event hubs see Work with Dynamics 365 event data in your Azure Event Hub solution.

A Dynamics 365-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 365 as the supported issuer and the Microsoft Azure Service Bus solution configured with rules to allow Microsoft Dynamics 365 to post to the endpoint where the listener is.

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

Microsoft Dynamics CRM to Service Bus scenario

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

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

  2. A user performs some operation in Microsoft Dynamics 365 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 data context to the service bus.

  3. The claims posted by Microsoft Dynamics 365 are authenticated. 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 Dynamics 365 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.

    The type of queue supported by Microsoft Dynamics 365 is called a persistent queue. Persistent queues have a long but finite 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 post to the service bus fails. Microsoft Dynamics 365 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 the plug-in or custom workflow activity that initiated the post.

  • 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.

  • Event Hub
    This contract type applies to Microsoft Azure Event Hub solutions.

Important

To use these contracts, you must write your listener applications using the Microsoft AzureSDK v1.7 or later.

Identifying the kind of security a contract uses is part of the contract’s configuration. A contract can use Transport security, which uses Transport Layer Security (TLS) or 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 365 and signed by the AppFabricIssuer certificate specified in the Microsoft Dynamics 365 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 365 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 365 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 365 error, message posts are not attempted. For an external service bus or network error, the related system job will be in a “Wait” state.

See Also

Azure extensions for Microsoft Dynamics 365
Configure Azure integration with Microsoft Dynamics 365
Write plug-ins to extend business processes
Asynchronous service in Microsoft Dynamics 365
AsyncOperation (system job) entity

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright