Reusing classic object-based Help on your Dynamics 365 Business Central Help Server

If you are upgrading customers from Dynamics NAV 2017 or earlier versions to the latest version of Dynamics 365 Business Central, then you probably have an existing Help solution for the customized functionality in their old Dynamics NAV solution. However, Business Central does not support the field-based approach to context-sensitive Help that Dynamics NAV 2017 and earlier use. So what to do?

The difference between Help in Dynamics NAV and Dynamics 365 Business Central

In this blog post, I will suggest a couple of options. None of them are particularly simple or easy workarounds, because Business Central understands Help in a completely different way compared to Dynamics NAV. It’s far easier to extend and customize the Help for Business Central than it was for Dynamics NAV 2009, for example – at least, I think so. The structure for the Help for the base application in Dynamics NAV was easy to understand but annoying to maintain: We shipped thousands of HTML files with each release, and you then had to guess which of them were completely new, which had been updated, and what that meant for your customized Help.

Here’s a list that I have shared before that outlines the journey the docs have been on since 1999:

Many of you never cared what Microsoft did with the Help, such as those of you who never installed the Microsoft content, or if you gave your customers PDF files rather than installed Help. That’s totally fine, and this blog post is not meant for you. Instead, I recommend that you read our content on how to migrate your content.

The rest of this blog post is for those of you who have existing content in the object-based format for a version of Dynamics NAV. In other words, you were planning to use the familiar Help Server with files such as T_12345.htm, T_12345_1.htm, N_12345.htm, R_12345.htm, and B_12345.htm.

But for Business Central, that no longer works for context-sensitive Help. Business Central relies on tooltips for the field descriptions and a mapping between page objects and conceptual Help for the description of features and workflows. So again: What to do?

Option 1: Use the object-based content as-is

This option is for those of you who prefer to keep things as-is until Microsoft comes up with a magic solution of some sort. That’s a perfectly legitimate approach, but it would mean that your Business Central customers would not get access to context-sensitive Help for your functionality.

If that’s an acceptable experience for your customers, then you can deploy a Help Server instance, populate it with your HTML files, and make sure that as much as possible is listed in the ToC.xml file so that users can find the relevant Help through navigation.

On a related note, 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.

Option 2: Update the Page Documentation system table with page-level UI-to-Help mapping

This option is for those of you who like to play around with PowerShell. I don’t, so I haven’t been able to give you an example of who to populate that mysterious system table that in the current version of Business Central provides a UI-to-Help mapping between page objects and Help.

In the current version, table 2000000198 Page Documentation, lists all page objects in the default version of Business Central and associates each of them with a target Help article. This means that multiple page objects can be associated with the same Help article, such as when a specific workflow involves multiple pages.

The table associates page IDs with target articles, but the URL to where to find the target article is specified at the application level that defaults to the https://docs.microsoft.com/en-us/dynamics-365/blog/business-central/ site. In an extension, you can overrule this URL so that all calls for Help go to your site instead, for example. For more information, see Configuring the Help Experience for Dynamics 365 Business Central.

Caution: The following content is intended as an example. You can choose to do things differently, and while you can use these scripts as inspiration, reusing the Dynamics NAV legacy Help, the legacy Dynamics NAV Help Server, and populating the system table, Page Documentation, is not the recommended path going forward. We recommend that you convert any existing content to the Business Central format instead, and that you fork our GitHub repos.

The way that Microsoft populated the system table was based on an Excel sheet in the following format:

In this example, you want to replace the values of the fields in the Relative Path column with classic page-level Help files:

With the Windows client and C/SIDE with the Object Designer soon gone, you cannot run that table anymore from the development environment. But you can find it in the SQL Server database and manipulate it there, for example. Or use PowerShell to set the ContextSensitiveHelpPage property on the relevant AL page objects, for example.

This option means that your users get context-sensitive Help on a page level, and you can then let them rely on Search and links to find information about tables, fields, and reports, if that is important to them and to you.

Option 3: Squeeze your field-level Help into tooltips and ditch the rest

This option is for those of you who want to deliver an experience that complies with the Business Central user assistance model but are fed up waiting for us to deliver you tools to help you achieve that. We might still surprise you in that area, but I can’t blame you for thinking you’re better off figuring it out on your own.

Again, this is where my lack of skills in PowerShell scripting comes into play. But I know it’s possible to write a script that takes the opening paragraph from a field topic such as T_12345_1.htm and puts that into the TooltipML property on the relevant page object. Or even better: Port the field description into the Tooltip property elements in the XLIFF file for your app, using whatever third party tool you use to process XLIFF files.

The following snippet illustrates what this might look like in an XLIFF file.

<ding="utf-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:xliff:document:1.2 xliff-core-1.2-transitional.xsd">
  <file datatype="xml" source-language="en-US" target-language=”da-DK” original="ALProject1">
    <body>
      <group id="body">
      <trans-unit id="PageExtension 3469146285 - Control 2143966609 - Property 1295455071" maxWidth="999" size-unit="char" translate="yes" xml:space="preserve">
        <source>Specifies the company's taxpayer identification number.</source>
        <target>Specificerer firmaets skatteydernummer.</target>
        <note from="Xliff Generator" annotates="general" priority="3">Page - Page</note>
      </trans-unit>
      </group>
    </body>
  </file>
</xliff>

Yes, you guessed it: We’re still working on getting our tooltips into XLIFF files.

Is this yet another breaking change?

No, it’s not. Business Central was born as a cloud-first offering, and the Business Central user assistance model serves that purpose. Getting from the Dynamics NAV 2016 Help experience to the Business Central user assistance model is not even as big a challenge as when we dropped the application manuals – and that wasn’t all that big a change to begin with because most of you kept the manuals from Navision Financials and shared them with your customers, if you were working on the product back then.

Then why is it so complicated, you may ask. Well, I might answer, it’s isn’t all that complicated. Here I have outlined a couple of scenarios, and there are probably many more. Depending on your particular solution and which format your existing Help is, things are either a bit tough or smooth and easy. Just like the code behind your solution – code customization makes upgrades more difficult, that’s just how it is. With the Help, you can even take it by degrees, slowly reworking the content you already have.

To make things easier going forward, join us in GitHub! For more information, see Extend, Customize, and Collaborate on the Help for Dynamics 365 Business Central.

Wait! What about Dynamics NAV 2018?

Oh, yeah … As you hopefully know, we were working on Dynamics NAV 2018 and Business Central at the same time, and as a result, the code change that disabled the classic way of looking up context-sensitive Help based on object IDs trickled back into Dynamics NAV 2018.

We did it on purpose at the time as part of a simplification effort that aimed at making things better for Business Central online, but we forgot that it would affect Dynamics NAV 2018 customers.

The good news is that you can use your classic object-based Help on a Help Server instance for both Dynamics NAV 2018 and Business Central on-premises. But as explained above, the website cannot give your users context-sensitive Help.

I hope we will have good news about context-sensitive Help in a few months, so cheer up, and let’s move forward.

Eva Dupont

Dynamics 365 Patterns & Practices Content Lead

Senior Content PM & profession lead for Dynamics SMB in Microsoft Business Applications Content Experience org. Working on next-gen user assistance experience.

See more articles from this author