Migrate Legacy Help to the Dynamics 365 Business Central Format

The standard version of Business Central follows a user assistance model with tooltips to explain all fields and actions and conceptual descriptions of functionality that is published to a public website. If you are building an app, you are expected to comply with this model. However, there are many ways in which you can migrate and reuse any existing Help that you might have.

Reusing existing web content

When you move to Business Central, you can reuse your existing product Help solution in most situations, especially if the content is already published to an internal or external website. In that case, all you have to do is to add that website to the configuration of Business Central online or on-premises. For more information, see Configuring the Help Experience.

More specifically, if you have content that you created for Dynamics NAV then you can choose to reuse that for your Business Central solution.

For example, you have a Dynamics NAV Help Server website with HTML files that describe your solution according to the Microsoft Dynamics NAV 2013 R2 documentation model and format. In that scenario, you can reuse the Help Server website and rebrand that and the content accordingly. You then connect your Business Central solution with that Help Server website.

However, Business Central does not support the field-based approach to context-sensitive Help that Dynamics NAV 2017 and earlier use. Instead, you must use the Business Central page-based approach to context-sensitive Help. You do not have to convert your existing Help, but you do need to populate the Page Documentation table. For more information, see Adding page-level UI-to-Help mapping to the system table.

Note

For apps for Business Central online, you must apply tooltips to controls and actions in both page objects and page extensions, and you must supply context-sensitive links. For more information, see Configuring the Help Experience.

Converting existing content

If your existing content is in a different format, such as PDF files, Word documents, or printed manuals, you must decide if you want to keep the content as-is, or if you want to convert it to a format that can be accessed from inside Business Central. There are third party tools available that can help you migrate to other formats, depending on the the current format and the target format.

If you are migrating your solution from Microsoft Dynamics NAV 2013 R2 or later versions of Dynamics NAV then you most likely have been using the Dynamics NAV Help Server, and your Help content is in HTML format. That means that you can reuse your existing content as-is, or you can use publicly available third-party solutions to convert some or all of your HTML files to MarkDown, if you want to follow similar processes to the ones the Microsoft team follows. For more information, see the Moving to MarkDown section.

If you are migrating from an earlier version of Dynamics NAV then you can choose to first migrate to the Microsoft Dynamics NAV 2013 R2 format, and then migrate again to MarkDown or similar formats. For more information, see Upgrading Your Existing Help Content in the legacy docs for Microsoft Dynamics NAV 2013 R2.

If you are migrating your solution from Dynamics GP, you might have content in PDF files. In that case, you can choose to convert the content to MarkDown as described in the Moving to MarkDown section, and then publish to a new online library on your current website, for example.

Converting legacy Dynamics NAV field Help to tooltips

For the default version of Business Central, Microsoft extracted the first paragraph from the HTML files of the Dynamics NAVHelp for table fields, and then imported the text into the page objects of the base application as tooltips. You can build a similar tool if you want to reuse your existing content in the same way.

The tooltips play an important role as part of the Business Central user assistance model, and we encourage you to apply tooltips to your controls and actions as well.

Moving to MarkDown

The Microsoft team converted a subset of the legacy Help for Dynamics NAV to build the new Help library at https://docs.microsoft.com/dynamics365/business-central/. 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 related repos with translations into the supported languages. The readme.md file in the source repo provides tips and tricks for working with the Microsoft GitHub repos and MarkDown.

Converting your existing content to MarkDown can be done using third-party tools, including but not limited to PanDoc or the Writage plugin for Word.

When you have converted your content to MarkDown, you can use a Git repo in Azure DevOps as your source repository, create a private or public repo in GitHub, or set up a project in MkDocs, for example. Then you can use open source tools such as DocFx to generate content for your website. In general, working in MarkDown means that you have access to a world of open source tools and do not have a hard dependency on Microsoft providing you with tools.

If you do not yet have a website that you publish content to, then there are several ways in which you can create such a site. The MkDocs project generates a website for you, but you can also work with a web designer to build a site that resembles the Docs.microsoft.com site, if that is what your customers will prefer.

See Also

Configuring the Help Experience
User Assistance Model
Development of a Localization Solution
System Requirements