Edit

Custom Help overview

  • Article
  • 4 minutes to read

Important

The functionality noted in this article is currently available in both the stand-alone Dynamics 365 Human Resources and the merged Finance infrastructure. Navigation might be different than noted while we make updates. If you need to find a specific page, you can use Search.

Finance and operations apps are often customized and extended to fit an organization's needs. If your solution is based on Microsoft Dynamics 365 Finance, Dynamics 365 Supply Chain Management, or Dynamics 365 Commerce, you can connect solution-specific and customer-specific Help content to the Help pane in the finance and operations client. This article describes the main steps and decision points.

Note

Users of finance and operations apps can create custom task guides to supplement conceptual content that describes the functionality of their solution. These conceptual descriptions are also referred to as Help and can be provided by Microsoft, partners, and an organization itself. For more information, see Help system.

The following illustration, and this article in general, use the term Help for conceptual descriptions that either include or exclude how-to guides. The term task guides refers to in-product task guides.

Customized Help solution and the Help pane.

Custom Help content

Custom Help content typically originates from one of three sources:

  • Microsoft documentation repositories (repos)

    Microsoft's content in the various GitHub repos is optimized for the learn.microsoft.com site and the tools that are used for this site. It is not intended to be customized directly but to be supplemented by articles on your local website. However, depending on your solution, you might need a copy of Microsoft's content.

    You can use the HTMLFromRepoGenerator tool from the Custom Help Toolkit to clone content from any of the finance and operations repositories and generate corresponding HTML files. Those files can then be updated with content that is specific to your solution.

    Important

    The HTMLFromRepoGenerator tool is being deprecated. To generate HTML files from Markdown, use another tool, such as DocFX.

    The language-specific repositories are also being deprecated, and will no longer be available from the end of the 2022 calendar year.

  • Existing customized Dynamics AX content

    You can convert Dynamics AX custom Help content so that it can be used in Dynamics 365.

  • HTML files that are created specifically for your solution

    Learn more about the metadata that must be added to your HTML files for context-sensitive Help and search to work correctly.

Process

The end-to-end process depends on the actual customer solution and the users' expectations. A typical process involves the following steps:

  1. Create the custom Help content.
  2. Publish the content on a website.
  3. Index the content by using a search service.
  4. Connect the custom Help pane to the website and the search service.

Microsoft provides a toolkit that can help you generate HTML files from the Microsoft Help repositories, generate JavaScript Object Notation (JSON) files for search services, and change the locale of HTML files so that it matches the locale of your solution.

You're welcome to share your knowledge by contributing to this documentation through the link at the bottom of the page or by joining the Dynamics 365 community.

The following table outlines the main objectives that admins typically have for configuring the Help experience.

Objective Learn more
I want to give my users a customized in-product Help experience that reflects their actual solution. See the Custom Help websites section of this article and Create documentation or training with Task Recorder.
I want to use the Microsoft Help content as a baseline for Help content that is specific to my solution. See Custom Help Toolkit: The HtmlFromRepoGenerator tool.
I want to contribute to the Microsoft Help content. See Extend, customize, and collaborate on the Help.
I want to reuse my existing Dynamics AX content. See Convert Dynamics AX custom Help for use in Dynamics 365.
I want to set up a website for my Help content. See the Custom Help websites section of this article.
I want to add my content to the Help pane. See Connect a custom Help website to the Help pane.
Our technical writers want guidance that will help them convert our earlier content into Markdown so that it becomes easier for them to customize the Microsoft content. See Moving to Markdown.

Custom Help websites

Before the product can connect to your Help content, you must customize the in-product Help pane so that it shows your content. The following conditions must be met:

  • Your content must be available on a website.

    You can deploy your content to an existing website, or you can set up a dedicated website to host your content. The website can be private or public, but we recommend that you do not require users to sign in to access your content.

  • Your content must be indexed by a search service.

    If you use the AzureSearchCustomHelp solution that is part of the Custom Help Toolkit for context-sensitive Help, the Help pane will generate a query that must be run against the search service's index. The query depends on specific metadata in the Help topics. For more information, see Metadata requirements for custom Help topics.

The Deploy custom Help to Azure article describes an approach for hosting content on Azure. It includes information about how to set up a search service that indexes your content so that it can be found by the in-product Help pane. If you don't have an Azure subscription, create an account before you begin. You can start with a free account for 12 months. For more information, see Create your Azure free account today.

See also

Connect a custom Help website to the Help pane
Deploy custom Help to Azure
Custom Help Toolkit
Language and locale descriptors in the product and in Help
Configure the Help experience for finance and operations apps
Help system