Extending and customizing the Help
As part of getting your 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. If you didn’t hear me talk about it at Directions this season. But what do we expect of you, then? Well, here’s what:
- 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.
Here’s one for a field in a FactBox:
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.
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 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.
The link between the Help articles and the various pages in the user interface is managed based on a system table. You can add your own entries to that system table using a PowerShell script, for example. This mapping is 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.
With the October’18 release, we made it possible for you to customize the links to the Help. Your app can hi-jack the configuration of where the content lives for specific languages, and you can add direct 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.
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, the ties are off, and you can extend and customize the user assistance so that it works for your solution and your users.
But let’s take a look at what it could like like in your AL app.
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:
In this example, the helpBaseUrl and supportedLocales specify that the links to the Help must go to the mysite.com site when the user is using the product in either Danish or English (US). In contrast, the helpproperty specifies the link that describes the app or solution itself, which is used in AppSource.
That’s it. Unless, of course, you’re building a vertical solution, in which case you’ll also want to add mapping for your page objects to the Page Documentation system table.
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 each of your pages as shown here:
With links like these, you don’t have to add mapping for your pages to the Page Documentation system table – you don’t want 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 Micrsoft’s Help. If they want Help for the MyPage page, they get your Help. Easy, isn’t it?
For on-premises deployments, you have access to configuration and customization in a different way because 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, but you can also 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? I’ll continue to publish content that you will hopefully find useful, and so will the rest of our team. But the bottom line is that we’re letting go of a bunch of hard requirements so that you can pursue the experience that your customers expect. You can add tours based on 3rdparty providers such as WalkMe or ClickLearn, you can record and publish videos to highlight your features, you can print a manual, and you can publish e-learning tutorials to a public or private site.
For those of you have been customizing the Help for Dynamics NAV, this is a major change, and I really 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, and you don’t have to build anything using a particular tool. On the other hand, I know that some of you are struggling to figure out what to do about the investments you’ve made to the Help customization for Dynamics NAV now that you’re moving to Business Central. I hope this blog post and one that I’ll be posting in a few days will help you find the way forward.
Re-posted from Microsoft | Dynamics 365 Business Central Blog by Eva D.