You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: powerapps-docs/developer/common-data-service/azure-integration.md
+51-41Lines changed: 51 additions & 41 deletions
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
title: "Azure Integration (Common Data Service) | Microsoft Docs"
3
3
description: "<Description>"
4
4
ms.custom: ""
5
-
ms.date: 10/31/2018
5
+
ms.date: 06/01/2019
6
6
ms.reviewer: ""
7
7
ms.service: powerapps
8
8
ms.topic: "article"
@@ -25,7 +25,7 @@ The Azure Service Bus provides a secure and reliable communication channel betwe
25
25
26
26
The key elements that implement the connection between Common Data Service and the Azure Service Bus are described later. A diagram in the next section shows these elements in operation.
27
27
28
-
### Data Context
28
+
### Data Context
29
29
30
30
The *data context* contains the business data that is being processed as part of the current Common Data Service 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 <xref:Microsoft.Xrm.Sdk.IPluginExecutionContext> when it is being passed along the event execution pipeline and <xref:Microsoft.Xrm.Sdk.RemoteExecutionContext> when it is posted to the service bus.
31
31
@@ -48,87 +48,97 @@ The Azure Service Bus provides a secure and reliable communication channel betwe
-[Write a listener application for a Microsoft Azure solution](write-listener-application-azure-solution.md).
50
50
51
-
### Plug-ins
52
-
Plug-ins are one of two methods used to initiate posting the message containing the data context to the 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.
51
+
### Plug-ins
52
+
53
+
Plug-ins are one of two methods used to initiate posting the message containing the data context to the Azure Service Bus, the other method being a custom workflow activity. There are two kinds of plug-ins supported by the Common Data Service-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.
53
54
54
-
An Azure-aware OOB plug-in is provided with Common Data Service and can be registered using the Plug-in Registration Tool. This plug-in executes in full trust with the Common Data Service 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 (<xref:Microsoft.Xrm.Sdk.IServiceEndpointNotificationService>), to post the current request data context to the Azure Service Bus.
55
+
An Azure-aware OOB plug-in is provided with Common Data Service and can be registered using the Plug-in Registration Tool. This plug-in executes in full trust with the Common Data Service 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 (<xref:Microsoft.Xrm.Sdk.IServiceEndpointNotificationService>), to post the current request data context to the Azure Service Bus.
55
56
56
-
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”.
57
+
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”.
57
58
58
-
For more information about plug-ins in general, see [Writing a Plug-in](write-plug-in.md). For more information about Azure-aware plug-ins, see [Write a Custom Azure-aware Plug-in](write-custom-azure-aware-plugin.md).
59
+
For more information about plug-ins in general, see [Writing a Plug-in](write-plug-in.md). For more information about Azure-aware plug-ins, see [Write a Custom Azure-aware Plug-in](write-custom-azure-aware-plugin.md).
59
60
60
-
### Custom Workflow Activities
61
-
Similarly to plug-ins, custom workflow activities can be written to initiate posting the current request message data context to the Azure Service Bus by using the service endpoint notification service. More information: [Workflow extensions](workflow/workflow-extensions.md)
61
+
### Custom Workflow Activities
62
+
63
+
Similarly to plug-ins, custom workflow activities can be written to initiate posting the current request message data context to the Azure Service Bus by using the service endpoint notification service. More information: [Workflow extensions](workflow/workflow-extensions.md)
62
64
63
-
### Asynchronous Service
64
-
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 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 PowerApps web application.
65
+
### Asynchronous Service
66
+
67
+
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 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 PowerApps web application.
65
68
66
-
For more information about the asynchronous service see [Asynchronous service](asynchronous-service.md).
69
+
For more information about the asynchronous service see [Asynchronous service](asynchronous-service.md).
67
70
68
-
### Microsoft Azure Service Bus
69
-
The service bus relays the request message data context between Common Data Service and 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 Common Data Service to post the data context to the service bus and for listener applications to read it is managed by Azure Shared Access Signatures (SAS).
71
+
### Microsoft Azure Service Bus
72
+
73
+
The service bus relays the request message data context between Common Data Service and 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 Common Data Service to post the data context to the service bus and for listener applications to read it is managed by Azure Shared Access Signatures (SAS).
70
74
71
75
72
76
For more information about the service bus, see [Service Bus](https://azure.microsoft.com/en-us/services/service-bus/). For more information about service bus authorization, see [Service Bus authentication and authorization](https://azure.microsoft.com/en-us/documentation/articles/service-bus-authentication-and-authorization/).
73
77
74
-
### Microsoft Azure Solution
78
+
### Microsoft Azure Solution
75
79
76
-
For the Common Data Service and Azure connection to work, there must be at least one solution in an Azure Service Bus solution account, where the solution contains one or more service endpoints. For a relay endpoint contract, a listener application that is “Common Data Service-aware” must be actively listening on the endpoint for the Common Data Service request on the service bus. For a queue endpoint contract, a listener doesn’t have to be actively listening. A listener is made Common Data Service-aware by linking it to the <xref:Microsoft.Xrm.Sdk> assembly so that type <xref:Microsoft.Xrm.Sdk.RemoteExecutionContext> is defined. More information: [Write a Listener for a Microsoft Azure Solution](write-listener-application-azure-solution.md)
80
+
For the Common Data Service and Azure connection to work, there must be at least one solution in an Azure Service Bus solution account, where the solution contains one or more service endpoints. For a relay endpoint contract, a listener application that is “Common Data Service-aware” must be actively listening on the endpoint for the Common Data Service request on the service bus. For a queue endpoint contract, a listener doesn’t have to be actively listening. A listener is made Common Data Service-aware by linking it to the <xref:Microsoft.Xrm.Sdk> assembly so that type <xref:Microsoft.Xrm.Sdk.RemoteExecutionContext> is defined. More information: [Write a Listener for a Microsoft Azure Solution](write-listener-application-azure-solution.md)
77
81
78
-
Common Data Service supports sending event data to an Azure Event Hubs solution. More information about event hubs, see [Work with event data in your Azure Event Hub solution](work-event-data-azure-event-hub-solution.md).
82
+
Common Data Service supports sending event data to an Azure Event Hubs solution. More information about event hubs, see [Work with event data in your Azure Event Hub solution](work-event-data-azure-event-hub-solution.md).
79
83
80
84
<aname="bkmk_describing"></a>
81
85
82
86
## Common Data Service to service bus scenario
83
87
84
-
Let us now identify a scenario that implements the previously mentioned connection components. As a prerequisite, SAS has been configured to recognize Common Data Service as the supported issuer and the Azure Service Bus solution configured with rules to allow Common Data Service to post to the endpoint where the listener is.
88
+
Let us now identify a scenario that implements the previously mentioned connection components. As a prerequisite, SAS has been configured to recognize Common Data Service as the supported issuer and the Azure Service Bus solution configured with rules to allow Common Data Service to post to the endpoint where the listener is.
85
89
86
-
The following diagram shows the physical elements that make up the scenario.
90
+
The following diagram shows the physical elements that make up the scenario.
87
91
88
-
![Dynamics 365 to Service Bus scenario](media/crm-v5s-az.png"Common Data Service to Service Bus scenario")
92
+
![Dynamics 365 to Service Bus scenario](media/crm-v5s-az.png"Common Data Service to Service Bus scenario")
89
93
90
-
The sequence of events as identified in this diagram are as follows:
94
+
The sequence of events as identified in this diagram are as follows:
91
95
92
96
1. A listener application is registered on a Azure Service Bus solution endpoint, and begins actively listening for the Common Data Service remote execution context on the service bus.
93
97
94
98
2. A user performs some operation in Common Data Service 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.
95
-
96
99
3. The claims posted by Common Data Service 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.
97
100
98
101
<aname="bkmk_establising"></a>
99
-
100
-
## Establish a contract between Common Data Service and an Azure solution
101
-
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.
102
+
103
+
## Establish a contract between Common Data Service and an Azure solution
104
+
105
+
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.
102
106
103
-
**Queue**
104
-
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.
107
+
### Queue
108
+
109
+
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.
105
110
106
-
The type of queue supported by Common Data Service is called a persistent queue. Persistent queues have a long but finite message availability duration that can be specified in code.
111
+
The type of queue supported by Common Data Service is called a persistent queue. Persistent queues have a long but finite message availability duration that can be specified in code.
107
112
108
-
**One-way**
109
-
A one-way contract requires an active listener. If there is no active listener on an endpoint, the post to the service bus fails. Common Data Service 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.”
113
+
### One-way
114
+
115
+
A one-way contract requires an active listener. If there is no active listener on an endpoint, the post to the service bus fails. Common Data Service 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.”
110
116
111
-
**Two-way**
112
-
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.
117
+
### Two-way
118
+
119
+
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.
113
120
114
-
**REST**
115
-
A REST contract is similar to a two-way contract on a REST endpoint.
121
+
### REST
122
+
123
+
A REST contract is similar to a two-way contract on a REST endpoint.
116
124
117
-
**Topic**
118
-
Similar to a queue except that one or more listeners can subscribe to receive messages from the topic.
125
+
### Topic
126
+
127
+
Similar to a queue except that one or more listeners can subscribe to receive messages from the topic.
119
128
120
-
**Event Hub**
121
-
This contract type applies to Azure Event Hub solutions.
129
+
### Event Hub
130
+
131
+
This contract type applies to Azure Event Hub solutions.
122
132
123
133
> [!IMPORTANT]
124
134
> To use these contracts, you must write your listener applications using the [Azure SDK](http://www.windowsazure.com/develop/downloads/) v1.7 or later.
125
135
126
-
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).
136
+
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).
127
137
128
-
Claims authentication is used for secure access to the service bus. The claim used to authenticate to the service bus is generated in Common Data Service and signed by the AppFabricIssuer certificate specified in the Common Data Service configuration database.
138
+
Claims authentication is used for secure access to the service bus. The claim used to authenticate to the service bus is generated in Common Data Service and signed by the AppFabricIssuer certificate specified in the Common Data Service configuration database.
129
139
130
140
<aname="bkmk_management"></a>
131
141
132
142
## Manage run-time errors
133
143
134
-
If an error occurred after a post was attempted to the service bus, check the status of the related system job in the 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 Common Data Service 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 Common Data Service error, message posts are not attempted. For an external service bus or network error, the related system job will be in a “Wait” state.
144
+
If an error occurred after a post was attempted to the service bus, check the status of the related system job in the 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 Common Data Service 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 Common Data Service error, message posts are not attempted. For an external service bus or network error, the related system job will be in a “Wait” state.
0 commit comments