Connect to Microsoft Dataverse
Note
Azure Active Directory is now Microsoft Entra ID. Learn more
This article 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'll find your environments. 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 currencies that each company uses. Business Central companies can connect to a Dataverse environment that has a base currency that's different than their local currency. To learn more about how to handle multi-currency setups, go to Allow for different currencies.
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're using Business Central on-premises and aren't using a Microsoft Entra 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're using a Microsoft Entra account, the integration user account is not required or displayed. The integration user will be set up automatically and does not require a license.
Link your Business Central and Dataverse environments
Businesses want to keep their data safe and secure within their privacy boundary, and especially when their business management application integrates with other apps. By linking Business Central and Dataverse environments, you’ll not only achieve those considerations, but also give your administrators an easier way to create and maintain your integrations with other Dynamics 365 apps.
In the Business Central admin center, you can link your Business Central environment to your Dataverse environment. Business Central can use the information from the link to make it easier, and more secure, to integrate with other Dynamics 365 apps, such as Sales and Field Service. For example, the linked Dataverse environment URL is available by default on the Dataverse Connection Setup page and when you run the Dataverse Connection Setup assisted setup guide.
Allow for different currencies
Business Central companies can connect to a Dataverse environment that has a base currency that's different than their local currency.
Note
Synchronizing multiple currencies requires that you're using a unidirectional synchronization, from Business Central to Dataverse.
To learn more about the base currency in Dataverse, go to Transaction Currency (currency) entity.
To learn more about currencies in Business Central, go to Currencies in Business Central.
To allow for different currencies, before you connect, be sure that you've specified the following settings:
- The base transaction currency setting in Dataverse has the currency code that's specified on the Currencies page in Business Central.
- There's at least one exchange rate specified for the currency in Business Central on the Currency Exchange Rates page.
When you enable the connection to Dataverse, Business Central adds its local currency to the Currency entity in Dataverse. The local currency uses the exchange rate from the Currency Factor field on the Currency Exchange Rates page.
Because currency synchronization is unidirectional, from Business Central to Dataverse, monetary amounts convert and synchronize as follows:
- If in the Dataverse base currency, amounts convert to the Business Central local currency based on the latest exchange rate synchronized from Business Central.
- If in the Business Central local currency, amounts synchronize with the Business Central local currency in one of the additional, non-base currencies in Dataverse.
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 can't be synchronized because it depends on a row or table that has the No synchronization recommendation. For example, if customers can't be synchronized, then data for contacts that depends on the customer data can't 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 aren't prompted to sign in with your administrator account, it's 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. The Dataverse Connection Setup page is where you manage integration settings.
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'll find them 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'll find it. Enabled Start using the integration. If you don't enable the connection now, the connection settings will be saved but users won't 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, an administrator can enter criteria to couple records based on matches. You can start the algorithm for matching records 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 you start the match-based coupling process from a master data list, a coupling job is scheduled after you specify the coupling criteria.
The Dataverse Full Synch. Review page.
When the full synchronization process detects uncoupled records in Business Central and Dataverse, a Select Coupling Criteria link appears for the integration table.
You can start the Run Full Synchronization process from the Dataverse Connection Setup and Dynamics 365 Connection Setup pages. You can also start it in the Set up a connection to Dataverse assisted setup guide when you complete your setup.
When you start the match-based coupling process from the Dataverse Full Synch. Review page, a coupling job is scheduled after you complete the setup.
The Integration Table Mappings list.
Select a mapping, choose the Coupling action, and then choose Match-Based Coupling.
When you start the match-based coupling process from an integration table mapping, a coupling job runs for all uncoupled records in the mapping. You can also select uncoupled records in the list to run the job only for those 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 the fields to use to match Business Central records with Dataverse entities. You can specify whether the match is case-sensitive.
Specify whether to synchronize after you couple records. If records use bidirectional mapping, you can also specify 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. Business Central will search for a match in ascending order based on the value in the Match Priority field. A blank value in the Match Priority field equals priority 0, which is the highest priority. Fields with the 0 priority are 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 records failed to couple, you can choose the value in the Failed column to open a list of errors that describe why that happened.
Typically, coupling fails for the following reasons:
No matching criteria was defined
Run the match-based coupling again, but remember to define coupling criteria.
No match was found for the fields specified in the matching criteria
Repeat the coupling using different fields.
Multiple matches were found for several records based on the the fields specified in the matching criteria
Repeat the coupling using different fields.
A match was found, but the record is already coupled to a record in Business Central
Repeat the coupling using different fields, or investigate why that Dataverse entity is coupled to the 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 record is coupled to a Dataverse entity. You can use the Coupled to Dataverse field to filter the list of records you're synchronizing.
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. You must use 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 secrets for authentication.
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
- 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. It should take less than a minute to sign in.
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.
To connect using a Microsoft Entra account, you must register an application in Microsoft Entra ID. You'll have to 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're setting up your server to have a different home page, you can change the URL. The client secret will be saved as an encrypted string in your database.
To register an application in Microsoft Entra ID for connecting from Business Central to Dataverse
The following steps assume that you use Microsoft Entra ID to manage identities and access. For more information about registering an application in Microsoft Entra ID, 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 ID 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 Microsoft Entra ID (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 aren't 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.