Connect to Microsoft Dataverse

Note

Effective November 2020:

  • Common Data Service has been renamed to Microsoft Dataverse. Learn more
  • Some terminology in Microsoft Dataverse has been updated. For example, entity is now table and field is now column. Learn more

This topic describes how to set up a connection between Business Central and Dataverse. Typically, businesses create the connection to integrate and synchronize data with another Dynamics 365 business app, such as Dynamics 365 Sales.

Before You Start

There are a few pieces of information to have ready before you create the connection:

  • The URL for the Dataverse environment that you want to connect to. If you use the Dataverse Connection Setup assisted setup guide to create the connection we will discover your environments, but you can also enter the URL of another environment in your tenant.
  • The user name and password of an account that has administrator permissions in Business Central and Dataverse.
  • If you have an on-premises Business Central 2020 release wave 1, version 16.5, read the Some Known Issues article. You'll have to complete the described workaround before you can create your connection to Dataverse.
Important

Your Dataverse environment must not be in Administration mode. Administration mode will cause the connection to fail because the integration user account for the connection does not have administrator permissions. For more information, see Administration mode.

Note

These steps describe the procedure for Business Central online. If you are using Business Central on-premises and are not using Azure Active Directory account to connect to Dataverse, you must also specify a user name and password of a user account for the integration. This account is referred to as the "integration user" account. If you are using an Azure Active Directory account the integration user account is not required or displayed. The integration user will be set up automatically and does not require a license.

Set Up a Connection to Dataverse

For all authentication types other than Microsoft 365 authentication, you set up your connection to Dataverse on the Dataverse Connection Setup page. For Microsoft 365 authentication, we recommend that you use the Dataverse Connection Setup assisted setup guide. The guide makes it easier to set up the connection and specify advanced features, such as the ownership model and initial synchronization.

Important

During the setup of the connection to Dataverse, the administrator will be asked to give following permissions to a registered Azure application named Business Central Integration to Dataverse:

  • Access Dataverse as you permission is needed so Business Central can, on behalf of administrator, automatically create non-licensed non-interactive Business Central Integration application user, assign security roles to this user and to deploy Business Central Integration Solution to Dataverse. This permission is used only once during set up of connection to Dataverse.
  • Have full access to Dynamics 365 Business Central permission is needed so automatically created Business Central Integration application user can access Business Central data that will be synchronized.
  • Sign in and read your profile permission is needed to verify user logging in actually has System Administrator security role assigned in Dataverse.

By giving consent on behalf of organization, the administrator is entitling the registered Azure application called Business Central Integration to Dataverse to synchronize data using automatically created Business Central Integration application user's credentials.

To use the Dataverse Connection Setup assisted setup guide

The Dataverse Connection Setup guide can make it easier to connect the applications, and can even help you run an initial synchronization. If you choose to run initial synchronization, Business Central will review the data in both applications and provide recommendations for how to approach initial synchronization. The following table describes the recommendations.

Recommendation Description
Full synchronization Data exists only in Business Central, or only in Dataverse. The recommendation is to synchronize all data from the service that has it to the other service.
No synchronization Data exists in both applications, and running full synchronization would duplicate the data. The recommendation is to couple records.
Dependency not satisfied Data exists in both applications, but the row or table cannot be synchronized because it depends on a row or table that has the No synchronization recommendation. For example, if customers cannot be synchronized, then data for contacts that depends on the customer data cannot be synchronized either.
Important

Typically, you only use full synchronization when you're integrating the applications for the first time, and only one application contains data. Full synchronization can be useful in a demonstration environment because it automatically creates and couples records in each application, which makes it faster to start working with synchronized data. However, you should only run full synchronization if you want one row in Business Central for each row in Dataverse for the table mappings. Otherwise, the result can be duplicate records.

  1. Choose the Lightbulb that opens the Tell Me feature icon, enter Assisted Setup, and then choose the related link.
  2. Choose Set up a connection to Microsoft Dataverse to start the assisted setup guide.
  3. Fill in the fields as necessary.
Note

If you are not prompted to sign in with your administrator account, it is probably because pop-ups are blocked. To sign in, allow pop-ups from https://login.microsoftonline.com.

To create or maintain the connection manually

The following procedure describes how to set up the connection manually on the Dataverse Connection Setup page. This is also the page where you manage settings for the integration.

  1. Choose the Lightbulb that opens the Tell Me feature icon, enter Dataverse Connection Setup, and then choose the related link.

  2. Enter the following information for the connection from Business Central to Dataverse.

    Field Description
    Environment URL If you own environments in Dataverse, we will find those for you when you run the setup guide. If you want to connect to a different environment in another tenant, you can enter the administrator credentials for the environment and we will discover those.
    Enabled Start using the integration. If you do not enable the connection now, the connection settings will be saved but users will not be able to access Dataverse data from Business Central. You can return to this page and enable the connection later.

  3. In the Ownership Model field, choose whether you want a team table in Dataverse to own new records, or one or more specific users. If you choose Person, you must specify each user. If you choose Team, the default business unit will display in the Coupled Business Unit field.

    |

  4. To test the connection settings, choose Connection, and then Test Connection.

    Note

    If data encryption is not enabled in Business Central, you will be asked whether you want to enable it. To enable data encryption, choose Yes and provide the required information. Otherwise, choose No. You can enable data encryption later. For more information, see Encrypting Data in Dynamics 365 Business Central in the developer and administration help.

  5. If Dataverse synchronization is not already set up, you will be asked whether you want to use the default synchronization setup. Depending on whether you want to keep records aligned in Dataverse and Business Central, choose Yes or No.

Connecting On-Premises Versions

To connect Business Central on-premises to Dataverse, you must specify some information on the Dataverse Connection Setup page.

If you want to connect using an Azure Active Directory (Azure AD) account, you must register an application in Azure AD, and provide the application ID, key vault secret, and the redirect URL to use. The redirect URL is pre-populated and should work for most installations. You must set up your installation to use HTTPS. For more information, see Configuring SSL to Secure the Business Central Web Client Connection. If you are setting up your server to have a different home page, you can always change the URL. The client secret will be saved as an encrypted string in your database.

Prerequisites

Dataverse must use one of the following authentication types:

To register an application in Azure AD for connecting from Business Central to Dataverse

The following steps assume that you use Azure AD to manage identities and access. For more information about registering an application in Azure AD, see Quickstart: Register an application with the Microsoft identity platform. If you do not use Azure AD, see Using Another Identity and Access Management Service.

  1. In the Azure Portal, under Manage on the Navigation Pane, choose Authentication.

  2. Under Redirect URLs, add the redirect URL that is suggested on the Dataverse Connection Setup page in Business Central.

  3. Under Manage, choose API permissions.

  4. Under Configured permissions, choose Add a permission, and then add delegated permissions on the Microsoft APIs tab as follows:

    • For Business Central, add the Financials.ReadWrite.All permissions.
    • For Dynamics CRM, add the user_impersonation permissions.
    Note

    The name of the Dynamics CRM API might change.

  5. Under Manage, choose Certificates & Secrets, and then create a new secret for your app. You will use the secret either in Business Central, in the Client Secret field on the Dataverse Connection Setup page, or store in a secure storage and provide it in an event subscriber as described earlier in this topic.

  6. Choose Overview, and then find the Application (client) ID value. This is the Client ID of your application. You must enter it either on the Dataverse Connection Setup page in the Client ID field, or store it in a secure storage and provide it in an event subscriber.

  7. In Business Central, on the Dataverse Connection Setup page, in the Environment URL field, enter the URL for your Dataverse environment.

  8. To enable the connection to Dataverse, turn on the Enabled toggle.

  9. Sign in with your administrator account for Azure Active Directory (this account must have a valid license for Dataverse and be an administrator in your Dataverse environment). After you sign in you will be prompted to allow your registered application to sign in to Dataverse on behalf of the organization. You must give consent to complete the setup.

    Note

    If you are not prompted to sign in with your administrator account, it is probably because pop ups are blocked. To sign in, allow pop-ups from https://login.microsoftonline.com.

Using Another Identity and Access Management Service

If you are not using Azure Active Directory to manage identities and access, you will need some help from a developer. If you prefer to store the app ID and secret in a different location, you can leave the Client ID and Client Secret fields blank and write an extension to fetch the ID and secret from the location. You can provide the secret at runtime by subscribing to the OnGetCDSConnectionClientId and OnGetCDSConnectionClientSecret events in codeunit 7201 "CDS Integration Impl."

To disconnect from Dataverse

  1. Choose the Lightbulb that opens the Tell Me feature icon, enter Dataverse Connection Setup, and then choose the related link.
  2. On the Dataverse Connection Setup page, turn off the Enabled toggle.

See Also

View the Status of a Synchronization

Note

Can you tell us about your documentation language preferences? Take a short survey.

The survey will take about seven minutes. No personal data is collected (privacy statement).