Configuring the Help Experience for Dynamics 365 Business Central

The default version of Business Central comes with conceptual overviews and other articles that publish to the learn.microsoft.com/dynamics365/business-central/ site. This location is accessible from the Help menu and through the Learn More links in all tooltips. Each extension that you add will include its own tooltips and links to Help that can be accessed through the Learn More links and the Ctrl+F1 keyboard shortcut.

But what if you want to deploy Business Central locally? Or if you have a vertical solution and want to refer your customers to your own website for Help? Or if you have a legacy Help collection based on the Dynamics NAV Help Server? These and other scenarios are also supported in Business Central.

Apps for online tenants

When you build an app for Business Central using the AL developer experience, you are expected to apply tooltips and context-sensitive links to Help content on a website in accordance with the user assistance model. For more information, see the Deploy content to your website section and the Configure Context-Sensitive Help article.

Tip

The website does not have to be publicly accessible, but it must be accessible to all users of the solution that it supports.

You can add Microsoft's content to your website, or you can deploy just your own content. The choice is yours and depends on the requirements of your users, the size of your app, and the amount of customization you want to make.

For inspiration for how to create a website that can host your content, explore this tutorial. The tutorial demonstrates how to create a static web app and add a search service in a few relatively straightforward steps.

On-premises deployments

For deploying Business Central on-premises, you can choose between using any online website or the legacy Dynamics NAV Help Server, and you can configure different Help experience for each Business Central Web Server instance. For supported versions, the legacy Dynamics NAV Help Server component is a simple website that requires your Help to be in a specific format (HTML files). Other types of websites can host any content that you want to make available. Your choice depends on the needs of your solution and your users. If you add configuration for an online library, you must remove any settings for Help Server.

Important

The legacy Dynamics NAV Help Server component was deprecated and removed in 2021 release wave 1 (version 18). We recommend that you invest in a different type of website. For more information, see the deprecation notice.

Tip

The content on the learn.microsoft.com/dynamics365/business-central/ site and in the various GitHub repos reflects the latest version of Business Central, unless otherwise specified.

If, for some reason, you need a copy of Microsoft's content, then get it close to the time the subsequent major version of Business Central becomes available. For example, if you are deploying version 19.4, you could have taken a snapshot of the content in GitHub before version 20.0 became available.

The source repo, dynamics365smb-docs, contains packages of Markdown files for major versions and snapshots of the docs for the previous minor version.

For example, go to https://github.com/MicrosoftDocs/dynamics365smb-docs/releases to get the release that you need for your solution.

Online library

To display content from a website that hosts your user assistance content, specify the URL in the settings for the Business Central Web Server. The navsettings.json file must contain the following setting in the ApplicationIdSettings element:

{
  "NAVWebSettings": {
    // [...more keys]
  },
  "ApplicationIdSettings": {
    //BaseHelpUrl:  The location of Help for this application.,
    "BaseHelpUrl": "https://mysite.com/{0}/documentation/",
     // [...more keys]
  }
}

Note

Replace the value of the BaseHelpUrl key with the URL for your own website. The parameter, {0}, represents the locale of the browser that the user is using, such as en-us or da-dk, and is set automatically at runtime.

For more information, see Configuring Business Central Web Server Instances.

Tip

The website does not have to be publicly accessible, but it must be accessible to all users of the solution that it supports.

For example, if you deploy Business Central on-premises, you might want to set up a dedicated website with customer-specific content that includes customized content from Microsoft. However, Microsoft's content is optimized for the learn.microsoft.com site.

Legacy Help Server

APPLIES TO: 2020 release wave 2 and earlier versions

If you want to use Help Server, then you must specify the server and port in the installation options. The Help Server website can also serve as a starting point for adding a library to your existing website, for example.

Important

In version 18 and later versions, if you use the legacy Dynamics NAV Help Server component as a standalone website, then you must use the settings for the online library that is described in the previous section.

For more information, see Configuring Microsoft Dynamics NAV Help Server in the developer and administration content for Dynamics NAV.

Important

If you use Help Server, context-sensitive Help does not work anymore. Neither the UI-to-Help mapping functionality that is described in Configure Context-Sensitive Help, nor the original Help lookup mechanism that was based on filenames that reflected the object IDs, such as N_123.htm for the page object with the ID 123. For more information, see the blog post Reusing classic object-based Help on your Dynamics 365 Business Central Help Server.

Tip

If you are upgrading from Microsoft Dynamics NAV 2013 R2 or later, you can reuse your existing Help Server content by simply replacing the product name and make any other changes that apply to your Business Central environment. But we encourage you to deploy the content to another website.

You can still download the files that were made available for Microsoft Dynamics NAV 2017. The download consists of 45 CAB files with the content from the Dynamics NAV 2016 DVD rebranded to Microsoft Dynamics NAV 2017. The download includes CAB files with the W1 application Help translated into each of the supported languages plus the local functionality for the country/region where that language is spoken. There are also CAB files with local functionality in English. The files were published as a single download so each administrator could choose exactly the files that they needed at the time. For more information, see Microsoft Dynamics NAV 2017 Classic Help Download.

However, you must switch to the UI-to-Help mapping functionality that is described in Configure Context-Sensitive Help.

Deploy content to your website

Currently, Business Central has no firm requirements for the website that hosts your online library for your Business Central online or on-premises. You can deploy your content using any tool and process including the following:

• Azure Static Web Apps
• Azure App Service
• Third-party services

You can explore an example of how to deploy content to an Azure web app in the article Deploy custom help to Azure. That article also describes how you can build a search service for your website. Another example is in the Overview of adding search to a website with Python tutorial in the Azure docs. The step for adding a search service is currently not relevant for Business Central, but you might find the guidance helpful anyway.

Important

Currently, search in the Business Central Help pane cannot access sites other than the learn.microsoft.com site, including Microsoft Learn.

However, to help prepare for the day when partner-provided and customer-provided content can also be indexed and found by in-product search and the help pane, get your content deployed to a website and make it discoverable.

In versions older than 2022 release wave 1, the in-product search includes searching content on the learn.microsoft.com/dynamics365/business-central site. In 2022 release wave 1 and later, this search is replaced by the search capabilities of the Help pane. But the restrictions remain the same.

Optional: Get Microsoft's content

If you deploy a solution that customizes Microsoft's default application, then you might want to include a customized version of Microsoft's business functionality content on your website. In most other cases, such as if you build an add-on app, you do not need Microsoft's content. Your own content will supplement Microsoft's content in the same way that your code supplements Microsoft's code. For more information, see Configure Context-Sensitive Help.

Important

The remainder of this section is for those people who need a copy of Microsoft's content to deploy to a website along with their own content. In many cases, you do not need to customize Microsoft's content, and this section is irrelevant for you. However, if you deploy a customized solution on-premises or in a closed environment, then you might need to include Microsoft's content in your Help website.

We encourage you to use apply the ROBOTS: NOINDEX, NOFOLLOW metadata to any customized versions of Microsoft's content. The intent is that search engines will find Microsoft's original content on the learn.microsoft.com site rather than any customizations that you and hundreds of other may have published. Set the metadata in the individual files, or set it in the globalMeta section of docfx.json if you build using docfx.exe. For an example, see the ui-work-with-notes.md file in GitHub, which we have deprecated but kept in the repo as an example.

If you use the docfx.json file to build HTML files for non-Microsoft functionality, then set the value of the ROBOTS property when you build Microsoft's content. You can also add other global metadata, or metadata that applies to specific subfolders.

Microsoft's source files are available as downloadable packages for each major release in the https://github.com/MicrosoftDocs/dynamics365smb-docs/ GitHub repo in English (US) only.

Tip

The content on the learn.microsoft.com/dynamics365/business-central/ site and in the various GitHub repos reflects the latest version of Business Central, unless otherwise specified.

The source repo, dynamics365smb-docs, contains packages of Markdown files for major versions and snapshots of the docs for the previous minor version.

For example, go to https://github.com/MicrosoftDocs/dynamics365smb-docs/releases to get the release that you need for your solution.

Use any tool or script that you prefer.

Important

We encourage you to use apply the ROBOTS: NOINDEX, NOFOLLOW metadata to any customized versions of Microsoft's content. The intent is that search engines will find Microsoft's original content on the learn.microsoft.com site rather than any customizations that you and hundreds of other may have published. Set the metadata in the individual files, or set it in the globalMeta section of docfx.json if you build using docfx.exe. For an example, see the ui-work-with-notes.md file in GitHub, which we have deprecated but kept in the repo as an example.

If you use the docfx.json file to build HTML files for non-Microsoft functionality, then set the value of the ROBOTS property when you build Microsoft's content. You can also add other global metadata, or metadata that applies to specific subfolders.

We suggest that your website clearly indicates what is under Microsoft's copyright and what is under your own copyright. You are still welcome to make any relevant customizations of Microsoft's content, and to deploy this customized content to your own website. But to help users clearly identify whether a given search result applies to their Business Central experience or not, do not apply a title suffix such as Microsoft Docs. We also discourage reproduction of the visual styling of the learn.microsoft.com site for the same reason.

Fork the Microsoft repos, and customize or extend the content

If you want to customize or extend the Microsoft Help, you can fork our public repo for the source repo in English (US) at https://github.com/MicrosoftDocs/dynamics365smb-docs. For more information, see Contribute to the Help.

Related information

User Assistance Model
Adding Help Links from Pages, Reports, and XMLports
Migrate Legacy Help to the Business Central Format
Build your first sample extension with extension objects, install code, and upgrade code
Building an Advanced Sample Extension
Development of a Localization Solution
Resources for Help and Support
Blog post: Extending and customizing the Help
Blog post: Collaborate on content for Business Central
Blog post: Reusing classic object-based Help on your Dynamics 365 Business Central Help Server
Working with Dynamics NAV Help Server
Docs Contributor Guide
Docs Authoring Pack for Visual Studio Code