Migrate Legacy Help to the Dynamics 365 Business Central Format

Business Central implements a user assistance model where tooltips explain all fields and actions, and articles with conceptual descriptions of functionality are published to a 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 your existing Help within this model.

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 online library, which is 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 content 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. You can reuse the Help Server website and rebrand the website and the content. You then connect your Business Central solution with the Help Server website. For more information, see Configuring the Help Experience.

Business Central does not support the field-based approach to context-sensitive Help that Dynamics NAV 2017 and earlier versions 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 make the content available. For more information, see the Converting existing content section.

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 your content, depending on the current format and the target format.

For example, if you are migrating your solution from Dynamics GP, you might have content in PDF files. 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.

Migrating from Dynamics NAV

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, you can use the Custom Help Toolkit to get new HTML files to supplement your existing content, 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. For more information, see Upgrading Your Existing Help Content in the legacy docs for Microsoft Dynamics NAV 2013 R2.

Converting legacy Dynamics NAV field Help to tooltips

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.

If you would like to reuse text from your Dynamics NAV Help for table fields, the FieldTopicTextExtractor tool can extract the first paragraph from your Dynamics NAV Help topics for table fields. The resulting spreadsheet will help you copy and paste the text from your Dynamics NAV Help topics into the ToolTip property of your controls.

Mapping the table fields to page controls is not always straightforward because the same table is often used by two or more pages. As a result, the page ID can be many numbers away from the table ID. It requires knowledge of the actual solution to determine which tooltips are relevant for which pages. The FieldTopicTextExtractor tool generates an Excel file that you can use for this purpose, since you can sort and filter, and then copy content in Excel.

In the base application, tooltips are in the page objects, so, at Microsoft, we edit code to edit tooltips. You do not have to do the same. You can choose to work with tooltips in the translation files or straight in the .AL files. Different solutions require different processes, so pick the process that is more efficient for you. We chose to associate the "What is this field?"-content with the user interface, meaning the controls on page objects. In the Dynamics NAV Help model, we chose a different approach, focusing on the database structure. Both approaches have their advantages and disadvantages, but the Business Central user assistance model currently focuses on the user interface with tooltips on page objects. For more information, see User Assistance Model.

For more information, see Working with Application Objects as Text Files in the docs for Microsoft Dynamics NAV 2016, How to Add Translated Strings By Importing and Exporting Multilanguage Files in the docs for Microsoft Dynamics NAV 2018, and Working with Translation Files for Business Central.

Moving to 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.

Once you have converted your content to MarkDown, we recommend storing your content in a repository, such as a Git repo in Azure DevOps, a private or public repo in GitHub, or a project in MkDocs. 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. The Custom Help Toolkit can help you prepare content for publishing. For more information, see Custom Help Toolkit.

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 to host your content. We recommend deploying to an Azure web app.

See Also

Configuring the Help Experience
Extend, Customize, and Collaborate on the Help
User Assistance Model
Development of a Localization Solution
System Requirements