Connect to Common Data Service
This topic describes how to set up a connection between Business Central and Common Data Service. 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 Common Data Service environment that you want to connect to. If you use the CDS 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 Common Data Service.
Note
These steps describe the procedure for the online version of Business Central. If you are using Business Central on-premises and are not using Azure Active Directory account to connect to Common Data Service, 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 Common Data Service
For all authentication types other than Office 365 authentication, you set up your connection to Common Data Service on the CDS Connection Setup page. For Office 365 authentication, we recommend that you use the Set up Common Data Service connection assisted setup guide. The guide makes it easier to set up the connection and specify advanced features, such as ownership model and initial synchronization.
Important
During the setup of the connection to Common Data Service, the administrator will be asked to give following permissions to registered Azure application named Business Central Integration to Common Data Service:
- Access Common Data Service 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 Base CDS Integration Solution to Common Data Service. This permission is used only once during set up of connection to Common Data Service.
- 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 Common Data Service.
By giving consent on behalf of organization, the administrator is entitling the registered Azure application called Business Central Integration to Common Data Service to synchronize data using automatically created Business Central Integration application user's credentials.
To use the Set up Common Data Service connection assisted setup guide
- Choose the
icon, enter Assisted Setup, and then choose the related link. - Choose Set up Common Data Service connection to start the assisted setup guide.
- Fill in the fields as necessary.
To create or maintain the connection manually
The following procedure describes how to set up the connection manually on the CDS Connection Setup page manually. This is also the page where you manage settings for the integration.
Choose the
icon, enter CDS Connection Setup, and then choose the related link.Enter the following information for the connection from Business Central to Common Data Service.
Field Description Environment URL If you own environments in Common Data Service, 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 Common Data Service 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 entity in Common Data Service 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 BCI_Company will display in the Coupled Business Unit field.
Enter the following advanced settings.
Field Description Business Central Users Must Map to CDS Users If you are using the Person ownership model, specify whether Business Central user accounts must have a matching user accounts in Common Data Service. The Office 365 Authentication Email of the Business Central user must be the same as the Primary Email of the Dynamics 365 Sales user.
If you set the value to Yes, Business Central users who do not have a matching Dynamics 365 Sales user account will not have Business Central integration capabilities in the user interface. Access to Dynamics 365 Sales data directly from Business Central is done on behalf of the Dynamics 365 Sales user account.
If you set the value to No, all Business Central users will have Dynamics 365 Sales integration capabilities in the user interface. Access to Dynamics 365 Sales data is done on behalf of the Dynamics 365 Sales connection (integration) user.Current Business Central Salesperson is Mapped to a User Indicates whether your user account is mapped to an account in Dynamics 365 Sales 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 Common Data Service 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 Common Data Service and Business Central, choose Yes or No.
Show Me the Process
The following video shows the steps to connect Business Central and Common Data Service.
Connecting On-Premises Versions
To connect Business Central on-premises to Common Data Service, you must specify some information on the Common Data Service 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.
To register an application in Azure AD for connecting from Business Central to Common Data Service
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.
In the Azure Portal, under Manage on the Navigation Pane, choose Authentication.
Under Redirect URLs, add the redirect URL that is suggested on the Common Data Service 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 Common Data Service 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 Common Data Service 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 Common Data Service Connection Setup page, in the Environment URL field, enter the URL for your Common Data Service environment.
To enable the connection to Common Data Service, turn on the Enabled toggle.
Sign in with your administrator account for Azure Active Directory (this account must have a valid license for Common Data Service and be an administrator in your Common Data Service environment). After you sign in you will be prompted to allow your registered application to sign in to Common Data Service 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 Common Data Service
- Choose the icon, enter CDS Connection Setup, and then choose the related link.
- On the CDS Connection Setup page, turn off the Enabled toggle.