Configuring OneDrive integration with Business Central on-premises

This article explains how to configure OneDrive for work or school (formerly known as OneDrive for Business) integration with Business Central on-premises. Unlike Business Central online, the connection between Business Central and OneDrive isn't set up automatically. If the connection isn't configured, users can't use the features for OneDrive.

There are two tasks that need to be done to configure the OneDrive integration.

  • The first task involves registering an application (app) on your Microsoft Entra tenant of your Microsoft 365 plan. The registered app is used for authentication purposes. This task is typically done in the Azure portal and in Business Central web client.
  • The second task involves setting up the connection to the OneDrive URL and turning on the OneDrive features in Business Central. This task is done in the Business Central web client. Version 21 and later use OneDrive Setup instead of the legacy SharePoint Connection Setup used in versions 19 and 20.

Important

Business Central on-premises can only be connected to OneDrive hosted by Microsoft in the cloud. Connecting Business Central on premises to the My Sites repository of SharePoint Server isn't supported.

Register an app in Microsoft Entra ID for OneDrive integration

In this task, you add a registered app for Business Central in the Microsoft Entra tenant of your Microsoft 365 plan. Like other Azure services that work with Business Central, OneDrive requires a registered app in Microsoft Entra ID. The registered app provides authentication and authorization services between Business Central and SharePoint, which is used by OneDrive.

For detailed steps for completing this step, see Register an application in Microsoft Entra ID in the developer and IT pro help.

As you register the application, consider the following points:

  • If you've already registered an application as part of an integration with another Microsoft product, such as Power BI, then you reuse that registered app. In this case, you'll just have to set the SharePoint permissions for the existing registered app.

  • Be sure to configure the registered app with the following delegated permissions to the SharePoint API:

    • AllSites.FullControl
    • User.ReadWrite.All

    For Business Central 2021 release wave 2 (version 19), set these permissions instead:

    • AllSites.Write
    • MyFiles.Write
    • User.Read.All
  • If you're using Business Central version 19 or 20, copy the Application (client) ID and client secret used by the registered app. You'll need this information in the next task.

Get your OneDrive URL

You'll need a URL to make the connection to OneDrive from Business Central. The easiest way to get the URL is to sign in to OneDrive for your organization. In the browser address, you'll see a URL that has the following format:

https://<TenantName>-my.sharepoint.com/personal/<UserName>

For example, https://contoso-my.sharepoint.com/personal/rsimone_contoso_onmicrosoft_com.

You don't need the entire URL. You only use the portion before /personal:

https://<TenantName>-my.sharepoint.com

For example, https://contoso-my.sharepoint.com.

There are other ways to get the URL as well. For more information, see OneDrive URLs for users in your organization in the OneDrive documentation.

Set up the OneDrive connection in version 21 and later

Use this procedure if you're using Business Central 2022 release wave 2 (version 21) or later.

Prerequisites

  • Read permission and at least indirect insert, modify, and delete (imd) permission on table Document Service Scenario

Run OneDrive setup

  1. Select Search (Alt+Q) in the upper-right corner, enter OneDrive Setup, and then choose the related link.

  2. Select Next. If the Your privacy page appears, read the information and, if you agree to the terms, choose Agree to continue.

  3. On the Configure OneDrive file handling page, you have the following options to choose from:

    OptionDescription
    Use with app featuresIf you turn on this option, the Open in OneDrive and Share actions are made available on files in Business Central, like files attached to documents or in the Report Inbox. These actions let users copy, open, and share files in OneDrive. <ul><li>Business Central features that store or capture documents and other files, and offer Open in OneDrive and Share actions to bring those files out of Business Central, such as Incoming Documents and record attachments.</li><li>Line of business features that generate custom Excel workbooks, such as Sales Budgets.</li><li>Reports sent to the Report Inbox.</li><li>If you have installed any customizations or extensions, these may add more features that use OneDrive.</li></ul>For more information, see Opening and Sharing Business Central Files in OneDrive.
    Use with system featuresTurning on this option activates the following features:<ul><li> The Open in Excel and Edit in Excel actions on list pages will automatically copy the Excel file to OneDrive, then open it in Excel Online. For more information, see Viewing and Editing in Excel.</li><li> Sending a report to an Excel or Word file will automatically copy the file to OneDrive, then open it in Excel or Word online. For more information, see Saving a report to a file.</li></ul>
  4. Select Next. If you turned on either option, enter OneDrive's URL in the OneDrive URL field on the Configure Business Central page. If both options are off, select Done to finish without configuring a connection.

    How do I find my OneDrive URL?

  5. Choose Test connection and wait for the results.

    • If the test succeeds, choose Done, then you're ready to go.
    • If the test fails, you get a message that describes the problem. Typically the problem has to do with the URL that you provided. Choose OK to return to the Configure Business Central page, verify the URL, and try again.
    • If you haven't already set up the Microsoft Entra ID registered app, the Set Up Microsoft Entra ID guide opens.
  6. When completed, the privacy notice for OneDrive integration is agreed to. If you have permission to approve notices for the organization, that approval applies to all users. Otherwise, it applies only to you. To let users decide individually, an administrator can go to Privacy Notices Status and select Let User Decide for the OneDrive integration. Users are then prompted to agree or disagree with the privacy notice the first time they use the OneDrive features. Learn more in Privacy notices.

Set up the connection in Business Central versions 19 and 20

Use this procedure if you're using Business Central 2022 release wave 1 (version 20) or 2021 release wave 2 (version 19).

Important

By configuring this feature, you also enable legacy features that send files to OneDrive.\

  • The Open in Excel feature will automatically copy the Excel file to OneDrive, then open it in Excel Online.
  • Exporting any report to a file will automatically copy the file to OneDrive, then open it in Excel Online, Word Online or OneDrive.
  • Other features may also automatically open in OneDrive.
  1. Select Search (Alt+Q) in the upper-right corner, enter Microsoft SharePoint Connection Setup, and then choose the related link.

  2. In the Description field, enter a description for the connection, like OneDrive.

  3. In the Folder field, enter Business Central.

  4. In the Location field, enter the URL for your OneDrive.

    How do I find my OneDrive URL?

  5. In the Client ID field, enter the client ID from your registered app.

  6. In the Client Secret field, enter the secret from your registered app.

Important

In versions 19 and 20, the SharePoint Connection Setup page configures multiple legacy features. The General section configures the connection to OneDrive, and the Shared Documents section redirects files to SharePoint instead. This setup is deprecated. We recommend that you don't configure the Shared Documents section. For current versions, use OneDrive Setup. Learn more in Deprecated features in the Base App.

After upgrade to version 21

For upgrades to versions 21 and 22, the existing connection configured on the legacy SharePoint Connection Setup page can continue to work. Use OneDrive Setup to switch to the new integration and manage the OneDrive features that are accessible to users. The following sections describe that migration process.

Switching from legacy SharePoint to new OneDrive integration

To switch to the new OneDrive integration, you run the OneDrive Setup assisted setup guide, which you can open directly or from the legacy SharePoint Connection Setup page. The OneDrive Setup assisted setup leads you through the transition, providing information about the changes being made along the way.

The references to SharePoint Connection Setup in this section apply only to older versions where that page is available. In current versions, open OneDrive Setup directly.

Before you get started with the switch or as you're doing it, refer to the next section to learn about some aspects and considerations about the process.

About switching to the new OneDrive integration

In addition to OneDrive integration, Business Central can also integrate with other services, like Power BI and Universal print. Integration with these other services also requires a registered Microsoft Entra app for authentication. The Microsoft Entra app used by these other services is configured in the Set up your Microsoft Entra accounts assisted setup. When you switch from the legacy SharePoint connection setup, the new OneDrive Setup assisted setup changes your OneDrive integration to also use the Set up your Microsoft Entra accounts assisted setup&mdash;so all integrations use the same Microsoft Entra app.

This change has implications when switching to the new OneDrive integration, depending on whether there's already a Microsoft app configured in the Set up your Microsoft Entra accounts assisted setup.

Important

After you switch to the new OneDrive setup, you can no longer use the SharePoint Connection Setup page to configure OneDrive integration.

How the changes affect the integration

The OneDrive Setup assisted setup will always use the app that's configured in the Set up your Microsoft Entra accounts assisted setup, if there's one. When you run the OneDrive Setup assisted setup, it compares the app configured in Set up your Microsoft Entra accounts with your current app configured in SharePoint Connection Setup.

Tip

In the SharePoint Connection Setup page and Set up your Microsoft Entra accounts assisted setup, the Microsoft Entra app is identified by the client ID.

  • If the app in Set up your Microsoft Entra accounts is different than the app in SharePoint Connection Setup, the OneDrive integration changes to use the app in Set up your Microsoft Entra accounts.

    In OneDrive Setup while making the switch, you get a message similar to the following text:

    The Microsoft Entra application used for authentication will be configured for all Business Central integrations. This means the client id will change to NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN, you may want to test it has the correct permissions.

    NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN represents the client ID of the app in Set up your Microsoft Entra accounts that OneDrive integration has been switched to.

    Important

    For new OneDrive integration to work after you make the switch, you have to grant the app permission to the SharePoint API in Azure portal. You can do this step before or after you switch to the new OneDrive setup. Learn more in the section Register an app in Microsoft Entra ID for OneDrive integration.

  • If the app in Set up your Microsoft Entra accounts is the same as the app in SharePoint Connection Setup, the OneDrive integration uses the same app as before, except from the configuration in the Set up your Microsoft Entra accounts setup.

    In OneDrive Setup while making the switch, you get a message similar to the following text:

    The Microsoft Entra application used for authentication will be configured for all Business Central integrations. This has already been configured with the same client id (00001111-aaaa-2222-bbbb-3333cccc4444).

  • If there's no app configured in the Set up your Microsoft Entra accounts setup, the OneDrive integration uses the same app as before.

    The OneDrive Setup assisted setup copies app configuration to the Set up your Microsoft Entra accounts setup, so it's used for other integrations in that might set up later.

    In OneDrive Setup while making the switch, you get a message similar to the following text:

    The Microsoft Entra application used for authentication will be configured for all Business Central integrations.

Run OneDrive setup to switch to the new OneDrive integration

  1. Open either the OneDrive Setup page or the SharePoint Connection Setup page.

  2. If you're using the SharePoint Connection Setup page, choose Go to new OneDrive setup in the notification at the top of the page.

  3. Follow the OneDrive Setup assisted setup guide.

  4. When you get to the Configure OneDrive file handling page, choose one of the following options for turning on features:

    OptionDescription
    Use with app featuresIf you turn on this option, the Open in OneDrive and Share actions are made available on files in Business Central, like files attached to documents or in the Report Inbox. These actions let users copy, open, and share files in OneDrive. <ul><li>Business Central features that store or capture documents and other files, and offer Open in OneDrive and Share actions to bring those files out of Business Central, such as Incoming Documents and record attachments.</li><li>Line of business features that generate custom Excel workbooks, such as Sales Budgets.</li><li>Reports sent to the Report Inbox.</li><li>If you have installed any customizations or extensions, these may add more features that use OneDrive.</li></ul>For more information, see Opening and Sharing Business Central Files in OneDrive.
    Use with system featuresTurning on this option activates the following features:<ul><li> The Open in Excel and Edit in Excel actions on list pages will automatically copy the Excel file to OneDrive, then open it in Excel Online. For more information, see Viewing and Editing in Excel.</li><li> Sending a report to an Excel or Word file will automatically copy the file to OneDrive, then open it in Excel or Word online. For more information, see Saving a report to a file.</li></ul>
  5. The Configure Business Central page shows the same URL that's used by the existing OneDrive integration. You can change the URL as needed.

  6. Select Test connection and follow the instructions.

    If the test succeeds, select Done, and you're ready to go. Otherwise, use the messages on the page to help you fix the problem.

Business Central and OneDrive Integration
Opening Business Central Files in OneDrive
OneDrive FAQ

Find free e-learning modules for Business Central here