Data export service
Note
Effective November 2021, Data Export Service was deprecated. Data Export Service will continue to work and will be fully supported until it reaches end-of-support and end-of-life in November 2022. More information: https://aka.ms/DESDeprecationBlog
Data Export is an add-on service made available as a Microsoft Dataverse solution that adds the ability to replicate Dataverse data to a Microsoft Azure SQL Database store in a customer-owned Microsoft Azure subscription. The supported target destinations are Microsoft Azure SQL Database and Microsoft Azure SQL Server on Microsoft Azure virtual machines. Data Export intelligently synchronizes the entire Dataverse schema and data initially and thereafter synchronizes on a continuous basis as changes occur (delta changes) in Dataverse.
The Data Export service provides an interface for managing configuration and ongoing administration of this service from within Dataverse. For more information, see Replicate data to Azure SQL Database. This topic explains the corresponding programmatic interface and issues for this service.
Prerequisites for using the Data Export Service
Because this service requires access to an external Microsoft Azure SQL Database from Dataverse, a number of prerequisites must be satisfied before you can successfully access this service. The following perquisites are more fully explained from an administrator's perspective in the section Prerequisites for using Data Export Service.
Your Dataverse environment must be configured so that:
The tables that will be exported are enabled with change tracking. For more information, see Use change tracking to synchronize data with external systems.
Code is run in the context of a user with the System Administrator security role.
Note
The programmatic access to this service does not require the installation of the associated Data Export managed solution.
The target Azure SQL Database must be configured so that:
The subscription must support the volume of data being replicated from your Dataverse instance.
Firewall settings must allow access from the IP address of your Data Export service. For more information, see Configure an Azure SQL Database server-level firewall rule using the Azure Portal.
It is recommended that option “Allow access to azure services” be enabled.
The database user, specified in the data export connection string, must have the proper create and alter permissions on the target database. At minimum these include:
CRTB,CRTY,CRVW,CRPR,ALUS, and 'VWDS'. For more information, see Permissions (Database Engine).At least one user have extensive permissions on the schema. The following script creates such a new user.
USE MASTER;
CREATE LOGIN NewUser WITH PASSWORD='newpassword';
USE DESTINATIONDATABASE;
CREATE USER NewUser FOR LOGIN NewUser
GRANT CREATE TABLE, CREATE TYPE, CREATE VIEW, CREATE PROCEDURE, ALTER ANY USER to NewUser
GRANT ALTER, REFERENCES, INSERT, DELETE, UPDATE, SELECT, EXECUTE ON SCHEMA::dbo TO NewUser
For online solutions and services, Azure provides a Key Vault service to safeguard cryptographic keys, passwords, and other secrets. To use Azure Key Vault, this customer-owned service must be configured so that permission is granted to "Dynamics 365 Data Export Service", which is used to safely store the SQL Azure connection string. To perform this configuration with a PowerShell script, see How to set up Azure Key Vault. Alternately, this service can be managed through its REST API; see Key Vault management.
It is also advised that you add the domain https://discovery.crmreplication.azure.net/ to the trusted sites list in your browser and to enable pop-ups for this site.
Programming for the Data Export Service
The Data Export Service exposes a REST-based API that is divided into two groups: a set of Metadata operations for exploring Dataverse organizational structure, relationships, and connection information; and a set of Profiles operations for configuring and managing each data replication. This API is fully defined and documented at the following Swagger URLs:
| Swagger endpoint | Description |
|---|---|
| https://discovery.crmreplication.azure.net/swagger/docs/2016-01-01 | JSON definition of the Data Export Service API for use by developer tools and dynamic processes |
| https://discovery.crmreplication.azure.net/swagger/ui/index# | The user-friendly version of this API for developer reference |
API Quick Reference
For the reader's convenience, these interfaces are summarized in the following tables.
Metadata operations (https://discovery.crmreplication.azure.net/crm/exporter/metadata/)
| Resource | Methods | Description |
|---|---|---|
| organizations | GET | Get organizational details for all organizations that the current user belongs to |
| discover | GET | Get organizational details for the specified organization. |
| connector | GET | Get connector details for the specified organization. |
| entities | GET | Get all exportable public tables for the specified organization. |
| relationships | GET | Get all exportable relationships for the specified organization. |
| hasorgacceptedprivacyterms | GET | Check if the associated organization has accepted the privacy terms. |
| acceptprivacyterms | POST | Accept the specified org for data access. |
Profiles operations ([ConnectorURL]/crm/exporter/)
| Resource | Methods | Description |
|---|---|---|
| profiles | GET, POST | Get all profiles for specified organization, create a new export profile. |
| profiles/{id} | GET, PUT, DELETE | Get, update or delete a specific profile. |
| profiles/{id}/activate | POST | Activate a profile, which starts replication of both the associated table definitions and data. |
| profiles/{id}/activatemetadata | POST | Activate profile for table definitions replication only. |
| profiles/{id}/activatedata | POST | Activate profile for data replication only. |
| profiles/{id}/deactivate | POST | Deactivate a profile. |
| profiles/{id}/test | GET | Perform test operations on an existing profile. |
| profiles/validate | POST | Perform test operations on a profile description before creating it. |
| profiles/{id}/failures | GET | Get the connection string to a blob that contains failure details for a given profile. |
Gain Access
Because only Dataverse System Administrators are authorized to perform data export operations, these APIs enforce caller authorization through the use of Microsoft Entra ID security tokens. The following code snippet demonstrates generating such a token for a web application. You must replace the resource and AppId values with those values appropriate to your service. This approach can be used for development and testing, but more secure means should be used for production, such as the use of Azure Key Vault.
using Microsoft.Identity.Client;
string resource = "https://contoso.api.crm.dynamics.com"; // Target environment
var AppId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
var redirectUri = "http://localhost"; // Loopback for the interactive login.
// MSAL authentication
var authBuilder = PublicClientApplicationBuilder.Create(AppId)
.WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
.WithRedirectUri(redirectUri)
.Build();
var scope = resource + "/user_impersonation";
string[] scopes = { scope };
// Use interactive username and password prompt
AuthenticationResult token =
authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync().Result;
string accessToken = token.AccessToken;
For instructions on how to obtain a AppId see Authorize access to web applications using OAuth 2.0 and Microsoft Entra ID. For more information about Azure user security, see Authentication Scenarios for Microsoft Entra ID.
Error handling and failure processing
Once a profile is correctly configured, the synchronization process is typically highly reliable. However, if a record fails to synchronize, the following failure processing is applied:
After the configured retry interval, another attempt is made to synchronize the record. This is repeated up to the configured maximum number of retries.
The record is marked as processed.
A corresponding failed record entry is written to the error log.
The next record is processed.
Because the record is marked as processed, no future attempt is made to synchronize the record until its value or schema changes. (Note that writing identical values back into a table also marks it as modified.)
The entries in the error log are write-only. Future successes or failures during synchronization of the same record do not result in the alteration of past entries for this record. For example, a failure entry will remain in the error log even after the record has been successfully synchronized during some later synchronization cycle.
Caution
This error processing logic is subject to change in future releases of this service.
These failure entries can be retrieved through the Get the failure details for a given Profile request. The response returns a URI to an Azure blob that contains the failure information. Each line has the following comma-separated fields (newlines added for clarity):
Entity: <entity-name>,
RecordId: <”N/A” | guid>,
NotificationTime: <datetime>,
ChangeType: <sync-type>,
FailureReason: <description>
For example:
Entity: lead,
RecordId: N/A, NotificationTime: , ChangeType: Trigger Initial Export, FailureReason: There is already an object named 'hatest201_lead' in the database.
Entity: account, RecordId: b2a19cdd-88df-e311-b8e5-6c3be5a8b200, NotificationTime: 8/31/2016 6:50:38 PM, ChangeType: New, FailureReason: Invalid object name 'dbo.hatest201_account'.