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.
- The local currency for the company in Business Central must be the same as the base transaction currency in Dataverse. After a base transaction is set in Dataverse it cannot be changed. For more information, see Transaction Currency (currency) entity. This means that all Business Central companies you connect to a Dataverse organization must use the same currency.
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.
- Choose the
icon, enter Assisted Setup, and then choose the related link. - Choose Set up a connection to Microsoft Dataverse to start the assisted setup guide.
- 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.
Choose the
icon, enter Dataverse Connection Setup, and then choose the related link.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. 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.
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.
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.
Customize the Match-Based Coupling
Starting in 2021 release wave 2, you can couple records in Business Central and Dataverse based on matching criteria defined by the administrator.
The algorithm for matching records can be started from the following places in Business Central:
List pages that show records that are synchronized with Dataverse, such as the Customers and Items pages.
Select multiple records, and then choose the Related action, choose Dataverse, choose Coupling, and then choose Match-Based Coupling.
When the match-based coupling process is started from a master data list, a coupling job will be scheduled right after you have selected the coupling criteria.
The Dataverse Full Synch. Review page.
When the full synchronization process detects that you have uncoupled records both in Business Central and in Dataverse, a Select Coupling Criteria link appears for the relevant integration table.
You can start the Run Full Synchronization process from the Dataverse Connection Setup and Dynamics 365 Connection Setup pages, and it can be initiated as a step in the Set up a connection to Dataverse assisted setup guide when you choose to complete setup and run full synchronization at the end.
When the match-based coupling process is started from Dataverse Full Synch. Review page, a coupling job will be scheduled right after you completed the setup.
The Integration Table Mappings list.
Select a mapping, choose the Coupling action, and then choose Match-Based Coupling.
When the match-based coupling process is started from an integration table mapping, a coupling job will run for all uncoupled records in that mapping. If it was run for a set of selected records from the list, it will run only for the selected uncoupled records.
In all three cases, the Select Coupling Criteria page opens so that you can define the relevant coupling criteria. In this page, customize the coupling with the following tasks:
Choose which fields to match Business Central records and Dataverse entities by, and also choose whether the match on that field will be case-sensitive or not.
Specify whether to run a synchronization after coupling records, and, if the record uses bidirectional mapping, also choose what happens if conflicts are listed in the Resolve Update Conflicts page.
Prioritize the order in which records are searched by specifying a match priority for the relevant mapping fields. The match priorities make the algorithm search for a match in a number of iterations as defined by the Match Priority field values in ascending order. A blank value in the Match Priority field is interpreted as priority 0, so fields with this value fill be considered first.
Specify whether to create a new entity instance in Dataverse in case no unique uncoupled match can be found by using the match criteria. To activate this capability, choose the Create New if Unable to Find a Match action.
View the results of the coupling job
To view the results of the coupling job, open the Integration Table Mappings page, select the relevant mapping, choose the Coupling action, and then choose the Integration Coupling Job Log action.
If there are any records that were not coupled, you can drill down on the value in the Failed column, which will open a list of errors that specifies why the records failed to couple.
Failed coupling often happens in the following cases:
No matching criteria was defined
In this case, run the match-based coupling again, but remember to define coupling criteria.
No match was found for a number of records, based on the chosen matching fields
In this case, repeat the coupling with some other matching fields.
Multiple matches were found for a number of records, based on the chosen matching fields
In this case, repeat the coupling with some other matching fields.
A single match was found, but the matching record is already coupled to another record in Business Central
In this case, repeat the coupling with some other matching fields, or investigate why that Dataverse entity is coupled to that other record in Business Central.
Tip
To help you get an overview over the progress of the coupling, the Coupled to Dataverse field shows whether a specific record is coupled to a Dataverse entity or not. You can filter the list of records that are being synchronized with Dataverse by this field.
Upgrade Connections from Business Central Online to Use Certificate-Based Authentication
Note
This section is relevant only for Business Central online tenants that are hosted by Microsoft. Online tenants hosted by ISVs, and on-premises installations, are not affected.
In April, 2022, Dataverse is deprecating the Office365 authentication type (username/password). For more information, see Deprecation of Office365 authentication type. Additionally, in March, 2022, Business Central is deprecating the use of client secret based service-to-service authentication for online tenants, and will require the use of certificate-based service-to-service authentication for connections to Dataverse. Business Central online tenants that are hosted by ISVs, and on-premises installations, can continue to use client secret authentication to connect to Dataverse.
To avoid disrupting integrations, you must upgrade the connection to use certificate-based authentication. Although the change is scheduled for March, 2022, we strongly recommend that you upgrade as soon as possible. The following steps describe how to upgrade to certificate-based authentication.
To upgrade your Business Central online connection to use certificate-based authentication
Note
Certificate-based authentication is available in Business Central 2021 release wave 1 and later. If you are using an earlier version, you must schedule an update to Business Central 2021 release wave 1 before March, 2022. For more information, see Scheduling updates. If you experience issues, contact your partner or support.
- In the Business Central administration center, verify that you are using Business Central 2021 release wave 1 or later (version 18 or later).
- Depending on whether you integrate with Dynamics 365 Sales, do one of the following:
- If you do, open the Microsoft Dynamics 365 Connection Setup page.
- If you don't, open the Dataverse Connection Setup page.
- Choose Connection, and then Use Certificate Authentication to upgrade the connection to use certificate based authentication.
- Sign in with administrator credentials for Dataverse. Sign in should take less than a minute.
Note
You must repeat these steps in each Business Central environment, including both production and sandbox environments, and in each company where you have a connection to Dataverse.
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:
Office365 (legacy)
Important
Effective April 2022, Office365 (legacy) will no longer be supported. For more information, see Important changes (deprecations) coming in Power Apps, Power Automate and customer engagement apps.
Office365 (modern, OAuth2 client secret based)
OAuth
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.
In the Azure Portal, under Manage on the Navigation Pane, choose Authentication.
Under Redirect URLs, add the redirect URL that is suggested on the Dataverse Connection Setup page in Business Central.
Under Manage, choose API permissions.
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.
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.
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.
In Business Central, on the Dataverse Connection Setup page, in the Environment URL field, enter the URL for your Dataverse environment.
To enable the connection to Dataverse, turn on the Enabled toggle.
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.
To disconnect from Dataverse
- Choose the icon, enter Dataverse Connection Setup, and then choose the related link.
- On the Dataverse Connection Setup page, turn off the Enabled toggle.