Extending and customizing the Help in Dynamics 365 Business Central

As part of getting your Dynamics 365 Business Central app validated for AppSource, you are expected to deliver content that helps users understand how to use the functionality that your app provides. Think of this as Help or docs, and you’re off to a good start. But there is more to it than that, and that’s what this blog post will try to help you get onboard with.

The Business Central user assistance model – and what that means to you

We have three levels of user assistance, meaning ways in which the product helps users understand what is going on. You can read about that in the docs, but here are the three things we want you to do:

  • Help users get started
  • Help users get unblocked
  • Help users learn more

Help users get started

The user assistance concept of Get Started is not just about getting started with Business Central on the first day. It’s also about getting started all the other days, and about getting started with infrequent and unfamiliar tasks. Assistance in the shape of wizards is very helpful for setting things up, or filling in data for a complicated report, for example. Designing Home pages that are truly designed for that particular role or job is also very useful in helping users get started with their work every day – they can easily get to their most important tasks, and that means that Business Central helps them get their work done more efficiently.

You’ll also want to make it easy to onboard new customers – and your existing customers’ new employees.  For example, you can prepare a trial version of Business Central that you share with prospects and new users so that they can try out Business Central, or you can do in-hourse training based on such a trial tenant. Add tours or in-product videos, since such content can help with the onboarding.

We don’t have a firm rulebook that you can measure your app against, but we encourage you to design your interface with the intention to help users get started every day in mind.

Help users get unblocked

Even the best designed user interface can still be confusing to some. It can be difficult to predict what users will find confusing, and that is why we have applied tooltips to all (or almost all) controls and actions in the base application. In combination with descriptive captions and instructional text, the tooltips are our current implementation of embedded user assistance, which is an important principle in today’s world of software design.

The tooltips are there to help users unblock themselves by providing an answer to the most likely questions the users might have, such as “What data can I input here?” or “What is the data used for?”. Keep that in mind when you develop the user interface of your solution.

Shows tooltip for a field on a page.

Help users learn more

So, you added the tooltips, you designed a user interface that helps users get started with their work, but the users are still asking for more?

Yes, of course they are – users are people, and people always want more, in case you didn’t know that from your own experience. But that’s not the point of the docs that we publish under the user assistance concept of Learn more. This content is in part intended to answer those questions that the user interface (including the tooltips) can’t answer, such as where that page fits into the bigger workflow, or what comes next, or what would be the alternative, and so on.

We’re publishing our content to an online library (Docs.microsoft.com) so that it can also serve as onboarding material and as feature overviews that you can share with prospects. The content is written in MarkDown, and our source files are available in a public GitHub repo so that you can extend and customize it for your customers. You can read about that in the Contributor Guide.

The link between the Help articles and the various pages in the user interface is managed based a mapping between page objects and target articles, but the configuration of where those targets are published is set at the application level – and that means that you can customize that configuration.

Customize the Help experience

With the April’19 release, we made it easier for you to customize the links to the Help. Your app can hi-jack the configuration of where the content lives for all or specific languages, and you can add context-sensitive, relative links to the Help in your code for individual page objects. If your solution is used on-premises, then you can configure the clients to use either an online library (actually, it can also be a private website) or the legacy Dynamics NAV Help Server.

You don’t have to convert your existing content to MarkDown, but we recommend that you do because it makes your job easier down the road. Working in GitHub and MarkDown means that you have access to a world of open source tools and no longer have a hard dependency on Microsoft providing you with tools. For more information, see Migrate Legacy Help to the Business Central Format.

Configuring for online and on-premises

You can use the same content for both online and on-premises deployments of Business Central – we do that: The same user interface design, the same tooltips, the same Learn more content. But you can also choose to have one set of content published to a public website for your online customers, and another set of content published to your on-premises customers’ own websites.

In fact, you can make things as simple and as complicated as you like. The rulebook is pretty much gone, and the ties are off. You can extend and customize the user assistance so that it works for your solution and your users.

Example

But let’s take a look at what it could like like in your AL app.

App-level configuration

Let’s say that you’re building a localization app, or perhaps you’re building a vertical solution. In both cases, you’ll want to take over the configuration of where the links to find context-sensitive Help. This is done in the app.json file for your app as shown in this example:

"contextSensitiveHelpUrl": "https://mysite.com/{0}/documentation",
"supportedLocales": [
"en-GB", "en-IE
],

 

In this example, the contextSensitiveHelpUrl and supportedLocales properties specify that the links to the Help must go to the mysite.com site when the user is using the product in one of the two specified languages. In contrast, the help property in the app manifest specifies the link that describes the app or solution itself, and it’s used in AppSource.

That’s it.

Page-level configuration

Let’s say you’re building an app that adds a couple of page objects to the base application in Business Central. In this case, you’ll want to add a link to context-sensitive Help to each of your pages as shown here:

page 50101 "Reward Card"
{
PageType = Card;
SourceTable = Reward;
ContextSensitiveHelpPage = 'sales-rewards';

}

 

With relative links like these, you don’t have to publish Help for the base application on your site, just Help for your particular solution. That’s what these object-level links do. The experience for the users is that if they want Help for the Customer Card page, they get Microsoft’s Help. If they want Help for the Rewards page, they get your Help. If they want Help for your Rewards field on the Customer Card page, they get your Help as well. Easy, isn’t it?

On-premises configuration

For on-premises deployments, you have access to configuration and customization in a different way. On-premises,  you own the end-to-end customization. As mentioned, you have a choice between using the same online library as your app in AppSource uses. Alternatively, use the legacy Dynamics NAV Help Server. For more information, see On-premises deployments.

Third party tools

There is a world of tools and best practices out there, isn’t that just great? The hard requirements are gone so that you can pursue the experience that your customers expect. Here are a couple of examples of what you can choose to do:

  • You can add tours based on 3rd party providers such as ClickLearn or WalkMe
  • You can record and publish videos to highlight your features
  • You can create and print a manual
  • You can publish e-learning tutorials to a public or private site

For example, some of you have told me about an Open Source project where you can create content in MarkDown and then publish to an auto-generated website. It’s kind of cool, so check it out at https://www.mkdocs.org/. If you choose MKDocs, then you can configure your solution to use that site as the “online library” described above.

Oon a related note, one of my colleagues has published some tips and tricks for publishing to your own clone of Docs.microsoft.com on his private blog. There, he describes how you can automate the build processes in a way that even I (almost) understand.

Migrating content

For those of you who have been customizing the Help for Dynamics NAV, this is a major change. I hope you’ll agree with me that it’s a change to the better. You don’t have to use file-compare tools to figure out what we have changed in strangely formatted HTML files. You also don’t have to build anything using a particular tool.

On the other hand, some of you have made huge investments to the Help customization for Dynamics NAV. So what about that, now that you’re moving to Business Central? I wrote about this in another blog post: Reusing classic object-based Help on your Dynamics 365 Business Central Help Server.

You can also find links to related content in the docs at Extend, Customize, and Collaborate on the Help for Dynamics 365 Business Central.

PS: This blog post was first published in December 2018 on the Communities platform but has been migrated and updated here on the Dynamics 365 blog.