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 what we refer to here as 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 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 current format and the target format.

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.

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, 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.

Converting legacy Dynamics NAV field Help to tooltips

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.

For the default version of Business Central, Microsoft extracted the first paragraph from the HTML files of the Dynamics NAV Help 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. For Microsoft, it was a three-step process.

  1. The starting point for us was two .TXT files, one file with all application objects, and one file with the first paragraph from HTML files with the field Help plus the ID of the table field. A tool then mapped the content from the HTML files to the page and control IDs in the application objects based on regular expressions to help with the mapping (step 2).

    For example, in Dynamics NAV 2016, the field topic for the Dimension 1 Code field on the Analysis View table had this first paragraph:

    <p>Specifies one of the four dimensions that you can include in an analysis view. By entering a dimension here, you will be able to filter entries in the Analysis by Dimensions window, which will allow you to investigate and monitor relationships between entries and the dimension information attached to them. To select a dimension code, choose the field.</p>
    

    The field has the ID 3 on table 363, giving it a unique ID of T_363_13, which was used as the file name for the field help. A tool would extract this information into a text file in the following format:

    T363-C13-P8631-A1033-L999:Specifies one of the four dimensions that you can include in an analysis view. By entering a dimension here, you will be able to filter entries in the Analysis by Dimensions window, which will allow you to investigate and monitor relationships between entries and the dimension information attached to them. To select a dimension code, choose the field.

    The ID of the tooltip, T363-C13-P8631-A1033-L999, is based on the Translate Export format for Dynamics NAV and specifies the table, the field, the property, the language, and the field length. For more information, see How to: Add Translated Strings By Importing and Exporting Multilanguage Files in the docs for Microsoft Dynamics NAV 2016.

  2. The second step mapped that table field ID to the corresponding control on the Analysis View page object. This step was required because tooltips are not supported on table fields, only on controls on page objects.

    The mapping is not always straightforward because the same table is often used by two or more pages. As a result, the page ID could be many numbers away from the table ID. So we did much cleaning up and shuffling around in Excel after the conversion.

  3. The last step was to get the edited tooltips into the metadata for the relevant page objects.

    During our conversion, the application objects were still based on C/AL and C/SIDE, so we used the tools for working with C/AL objects in .TXT format. But the same can work for AL-based objects where the tooltips are stored in the ToolTip property.

    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.

After the conversion

Now that the tooltips are in the page objects, we work with them using Excel. Excel makes it easy to bulk-apply and bulk-edit strings because you can sort and filter the data. Due to the requirement of getting the text into Tooltip properties on page objects, we had to make it easy to do this work in a large Git enlistment in Azure DevOps, so the tooling is surrounded by a bunch of PowerShell scripts. We cannot share our current tooltip tool either, but it uses an open-source tool, https://closedxml.codeplex.com/, to handle the Excel integration - creating, opening, and saving an Excel workbook. The tool is then surrounded by PowerShell cmdlets scripts to populate the new Excel file with the existing page objects and their existing tooltips, and import the changed tooltips into the page objects.

You can also 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 original 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.

Moving to MarkDown

The Microsoft team converted a subset of the legacy Help for Dynamics NAV to build the new Help library at /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. 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