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 https://docs.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.

But what if you want to deploy Business Central locally? Or if you have a vertical solution so that you 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. The custom Help toolkit includes tools that can help you prepare and deploy content. For more information, see Custom Help Toolkit.

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 example, use the Custom Help Toolkit to help you deploy content to an Azure Web App. 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 is deprecated 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 and the Custom Help Toolkit section.

Tip

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

We recommend that you get your version of Microsoft's content close to the time the subsequent major version of Business Central becomes available. For example, if you are deploying version 16.4, you could have taken a snapshot of the content in GitHub before version 17.0 became available.

Both the source repo, dynamics365smb-docs, and the translation repos, such as dynamics365smb-docs-pr.da-dk, dynamics365smb-docs-pr.de-de and dynamics365smb-docs-pr.it-it, contain packages of MarkDown files for major versions and snapshots of the docs for the previous minor version. This is particularly useful if you deploy Business Central on-premises, since the repos by default reflect the latest version of Business Central online.

For example, navigate to the equivalent of https://github.com/MicrosoftDocs/dynamics365smb-docs-pr.da-DK/releases, and then 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.

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.

The following content in this section applies to using Help Server as it was originally intended to be used. However, this type of usage is no longer supported, starting with 2021 release wave 1.

The navsettings.json file must contain the following settings in the NAVWebSettings element:

{
  "NAVWebSettings": {
    //HelpServer: Name of the Dynamics NAV Help Server to connect to,
    "HelpServer": "https://myserver.com",
    //HelpServerPort:  The listening TCP port for the Dynamics NAV Help Server. Valid range: 1-65535,
    "HelpServerPort": "49000",
    // [...more keys]
  },
  "ApplicationIdSettings": {
    // [...more keys]
  }
}

In the example, https://myserver.com represents the URL to the Help Server instance, and the value of the HelpServerPortsetting determines that port 49000 on that webserver is where the content is. 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, the UI-to-Help mapping functionality that is described in Configure Context-Sensitive Help does not work. Neither does 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 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. Alternatively,deploy your existing content to an online library.

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.

Important

Specifically for the preview of Business Central in India, the installation of Help Server fails due to missing files on the installation media. The solution is to install Help Server without the HTML files for local functionality and instead pick up the content from GitHub. For more information, see Get updates from Microsoft.

Deploy content to your website

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:

You can see an example of how to deploy content to an Azure web app in the article Deploy custom help to Azure, which supports the custom Help toolkit for Dynamics 365 finance and operations apps. That article also describes how you can build a search service for your website. This step is currently not relevant for Business Central, but you might find the guidance helpful anyway.

Optional: Get Microsoft's content

If you deploy a solution that is based on Microsoft's default application, then you might want to include a customized version of Microsoft's business functionality content on your website. 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. For other languages, pull files based on a commit before the next major version.

Tip

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

Both the source repo, dynamics365smb-docs, and the translation repos, such as dynamics365smb-docs-pr.da-dk, dynamics365smb-docs-pr.de-de and dynamics365smb-docs-pr.it-it, contain packages of MarkDown files for major versions and snapshots of the docs for the previous minor version. This is particularly useful if you deploy Business Central on-premises, since the repos by default reflect the latest version of Business Central online.

For example, navigate to the equivalent of https://github.com/MicrosoftDocs/dynamics365smb-docs-pr.da-DK/releases, and then get the release that you need for your solution.

Let's take an example: You are deploying version 17.4 on-premises for a customer in Belgium in June 2021. Back in March 2021, you knew that version 18.0 was coming up, so you ran the custom help toolkit's HtmlFromRepoGenerator tool to get the latest version of Microsoft's source files from the relevant repos. In this example, you would configure the tool to process the following repos:

Tip

The HtmlFromRepoGenerator tool generates HTML files for you that you can choose to customize before you deploy them to the relevant website. Starting with 2021 release wave 1, the tool can get content based on the release-specific packages in GitHub. For more information, see Custom Help Toolkit and Extend, Customize, and Collaborate on the Help.

Alternatively,use any tool or script that you prefer. If you want to create your own tooling and processes around DocFx, you can see examples in the Build HTML files section of the contributor guide.

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 either the source repo in English (US) at https://github.com/MicrosoftDocs/dynamics365smb-docs, or one of the repos that contain translations. For more information, see Extend, Customize, and Collaborate on the Help and Custom Help Toolkit.

See Also

User Assistance Model
Adding Help Links from Pages, Reports, and XMLports
Migrate Legacy Help to the Business Central Format
Building 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