Setting up the Business Central Add-in for Excel in Business Central On-premises

This article provides guidance for how to configure Business Central on-premise so that users can edit data in Excel by using the Business Central add-in for Excel.

Note

This article does not apply to the older Excel add-in that was available for installation with the Dynamics NAV Client connected to Business Central client by using the Business Central Setup in versions older than 2019 release wave 2.

Overview

You can set up the Business Central deployment to support an add-in that enables users in the Business Central client to work with data from list pages in Excel. Users can get fresh data from Business Central into Excel and push updated data from Excel to Business Central.

Without this add-in, users can open a list page in Excel from the Open in Excel action on the page. But the Open in Excel action doesn't allow them to push changed data back to Business Central. When this add-in is set up, the Edit in Excel action is added. The add-in is based on the Microsoft Dynamics Office Add-In available from the Office Store.

For more information about how users work with Excel from Business Central, see Viewing and Editing in Excel From Business Central.

Note

The Excel add-in is not available in the mobile apps.

Prepare Business Central

Your on-premises deployment must meet the following prerequisites:

Expose the Business Central application Web API in Azure AD

When Business Central is configured for Azure AD authentication, the Business Central application is registered as an application in an Azure AD. Before the Excel add-in can be configured, you must configure the Business Central application in Azure AD to expose its Web API.

Note

The API may have already been exposed as part of the Azure AD authentication setup. You can also use the following steps to verify.

  1. Sign in to the Azure portal.
  2. Search for and select Azure Active Directory.
  3. Under Manage, select App registrations, then select the app registration for Business Central authentication.
  4. Under Manage, select Expose API.
  5. On the Expose API page, if the Application ID URI box is filled out, then API is already exposed, so you don't have to do anything else. Otherwise, select Set to expose the API.

For information about how to expose the Web API, see Quickstart: Configure an application to expose web APIs.

Register and configure an application in Microsoft Azure

When Azure AD authentication was set up for your Business Central deployment, an Azure AD tenant was created in Microsoft Azure, and an application for Business Central was registered in the tenant. The Excel add-in requires that you add (register) a separate Azure AD application in the Azure AD tenant. For more guidelines, see Register your application with your Azure Active Directory tenant.

  1. Sign in to the Azure portal.

  2. Search for and select Azure Active Directory.

  3. Under Manage, select App registrations > New registration.

  4. On the Register an application page, fill in the following information, then select Register.:

    Setting Description
    Name The name of your application as it will display to your users, such as Excel Add-in for Business Central.
    Supported account types Specifies which accounts that you would like your application to support. For purposes of this article, select Accounts in this organizational directory only.
  1. Modify the app's manifest to configure OAuth2 implicit grant flow and an spa type reply URL for the Excel add-in.

    1. From the application's Overview, select Manifest.

    2. In the editor, set "oauth2AllowIdTokenImplicitFlow" and "oauth2AllowImplicitFlow" keys to true:

      "oauth2AllowIdTokenImplicitFlow": true,
      "oauth2AllowImplicitFlow": true,
      
    3. In the "replyUrlsWithType":[] key, add the following lines:

      {
          "url": "https://az689774.vo.msecnd.net/dynamicsofficeapp/v1.3.0.0/*",
          "type": "Spa"
      }
      

      Remember to add a comma before or after this entry, depending on where you add it in the list.

    4. Select Save.

  2. Grant the Excel add-in application permission to access the Business Central application Web API.

    Give the Azure AD application for the Excel add-in delegated permission to access the Business Central application Web API, which you exposed earlier in this article. This permission allows users of the Excel add-in to access the OData web services to read and write data.

    1. From the application's Overview page, select API Permissions.
    2. Select the Add a permission
    3. On the APIs my organization uses, select the Business Central application.
    4. Select Delegated permission.
    5. Search for Business Central API by using registered application's name or application ID.
    6. Select the permission from the list, then select Add Permission.

    For information, see Quickstart: Configure a client application to access web APIs.

  1. On the application's Overview page, copy the Application (Client) ID that is assigned to Excel add-in application.

    You'll need it to configure the Business Central Server instance.

You've completed the work you have to do in the Azure portal. The next configuration is done on the Business Central Server instances.

Configure the Business Central Server instance

You add the Excel add-in to the Business Central Server instances in your deployment. You can use either the Business Central Server Administration tool or Set-NAVServerConfiguration cmdlet in the Business Central Administration Shell.

  1. In the Business Central Server Administration tool, in the Azure Active Directory section, set the Excel add-in AAD client ID field to the application (client) ID for the Excel add-in application that you copied from the Azure portal.

    If you're using the Set-NAVServerConfiguration cmdlet, set the ExcelAddInAzureActiveDirectoryClientId key.

    Set-NAVServerConfiguration -ServerInstance <Business Central server instance> -KeyName ExcelAddInAzureActiveDirectoryClientId -KeyValue <application ID>
    

    Note

    Make sure the Azure AD App ID URI is set to the App ID URI of the registered app for Business Central in the Azure AD tenant.

  2. In the Client Services section, set the Web Client Base URL field to the base URL of the Business Central Web client.

    This value is the root portion of all URLs that are used to access pages in the web client. The value must have the format https://[hostname:port]/[instance], such as https://MyBCWebServer/BC or https://cronusinternationltd.onmicrosoft.com/BC200.

    If you're using the Set-NAVServerConfiguration cmdlet, set the PublicWebBaseUrl key.

    Set-NAVServerConfiguration -ServerInstance <Business Central server instance> -KeyName PublicWebBaseUrl -KeyValue <web client URL>
    
  3. In the OData Services section, configure or verify the following settings:

    1. Set the OData Base URL field to the public URL for accessing OData services.

      The URL must have the following format https://<hostname>:<port>/<instance>/ODataV4/, such as https://localhost:7048/BC200/ODataV4/.

      With the Set-NAVServerConfiguration cmdlet, set the PublicODataBaseUrl key.

      Set-NAVServerConfiguration -ServerInstance <Business Central server instance> -KeyName PublicODataBaseUrl -KeyValue <OData URL>
      
    2. Select the Enable API Services check box.

      If you're using the Set-NAVServerConfiguration cmdlet, set the ApiServicesEnabled key to true.

      Set-NAVServerConfiguration -ServerInstance <Business Central server instance> -KeyName ApiServicesEnabled -KeyValue true
      

Prepare devices and network for the Excel Add-In

Network services such as proxies or firewalls must allow routing between each client device on which the add-In is installed and many service endpoints. For a list of endpoints, see Preparing your network for the Excel Add-In.

Next steps

The next step is to get the add-in installed in Excel of the users. As an administrator, you can set up Centralized Deployment in Microsoft 365 admin center to automatically install the add-ins to users in your organization. Or, you can allow users to install it themselves from the Office Store. For more information, see Get the Business Central Add-in for Excel in the business functionality help.

See Also

Configuring Business Central Server
Authenticating Users with Azure Active Directory