Migrate Legacy Help to the Dynamics 365 Business Central Format

If you are building an app for Business Central, we expect you to comply with the user assistance model. That means that tooltips and callouts explain all fields and actions, and conceptual descriptions of functionality are published to a website. Fortunately, there are many ways in which you can migrate and reuse your existing Help within this model.

Reusing existing web content

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

More specifically, if you have content 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 decide to reuse the Help Server website and rebrand the website and the content. Finally, you 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

Your existing content might be 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.

In this example, you are migrating your solution from Dynamics GP, and you have content in PDF files. You choose to convert the content to MarkDown as described in the Moving to MarkDown section. Then, you publish to a new online library on your current website. Sounds too easy? Well, it doesn't have to be more complicated, and it's a one-off project.

Migrating from Dynamics NAV

If you are migrating your solution from Microsoft Dynamics NAV 2013 R2, Microsoft Dynamics NAV 2017, or a version in between, then you most likely have been using the Dynamics NAV Help Server, and your Help content is in HTML format. That means that you have a free choice of what to do:

  • Reuse your existing content as-is but redeployed to a new website
  • Use the Custom Help Toolkit to get new HTML files to supplement your existing content
  • 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.

You can 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, 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. At Microsoft, we went through a similar process when we converted our field Help into tooltips. We find Excel useful because you can sort and filter, and then copy content to other fields, for example.

In the base application, tooltips are in the page objects, so 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 code. 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 the following articles:

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 from where you can publish to your website, such as the following:

  • A Git repo in Azure DevOps
  • A private or public repo in GitHub
  • A project in MkDocs

Use open-source tools such as DocFx to generate content for your website. By working in MarkDown, you have access to a world of open-source tools. But our Custom Help Toolkit can help you prepare content for publishing.

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. For example, the MkDocs project generates a website for you. You can also work with a web designer to build a site to host your content. We recommend deploying to an Azure web app. Business Central does not require a special design of your website, unlike the now deprecated Dynamics NAV Help Server. It's your choice what the website looks like, including the styling.

See Also

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