Connect a custom Help website to the Help pane

Article
04/26/2023

If you deliver custom Help content for a finance and operations solution, you can extend the Help pane so that it consumes that content. You complete this one-time configuration by using the finance and operations development environment in Microsoft Visual Studio. After you've finished, users can select among tabs for task guides, Microsoft Help content, and your Help content.

The process for connecting your custom Help website to the in-product Help pane involves the following steps:

Extend the Help pane in Visual Studio.
Assign an index to a language.
Customize language fallback.

Important

The procedures that follow require the development tools for finance and operations apps in Visual Studio. For more information, see Development tools in Visual Studio.

Extend the Help pane and assign the custom Help indexes to languages

The Help Pane extension folder contains the AzureSearchCustomHelp solution that you can open in the finance and operations development environment. That folder also contains the HelppaneOption.axpp project that you can then import into the solution in Visual Studio.

Extend the Help pane

In the finance and operations development environment, open the AzureSearchCustomHelp.sln solution.
On the Dynamics 365 menu, select Import project.
In the File name field, specify the path of the HelppaneOption.axpp project, and then select OK to complete the import process. Update the references so that no references are missing.
In the HelppaneMacro file, update the values of the following parameters:
- [WebAppName] – Specify the name of the web app that you created in Create a web app. For example, specify MyCustomHelpWebApp.
- Admin key value – Specify the admin key for the Azure Cognitive Search service. You can find the key in Access keys under Settings on the left of the search service in the Azure portal.
- [SearchServiceName] – Specify the name of the search service that you created in Create a search service. For example, specify mycustomhelpsearch.
The following example shows the content of the HelppaneMacro file.
```
#define.webApp('http://[WebAppName].azurewebsites.net/')
#define.queryApiKey('Admin key value')
#define.defaultstring('dashboard')
#define.searchservicename('[SearchServiceName]')
#define.CustomResultError('error')
#define.CustomTabPage('CustomTabPage')
#define.CustomHelp('Custom Help')
#define.CustomTitle('CustomTitle')
#define.htm('html')
```
Optional: If you want to change any of the user interface (UI) strings that appear in the Help pane, edit the Customhelppane.en-US.label.txt file.

Next, you must specify the language that the search index for your custom Help is intended for.

The tools you need to complete this process are available in the https://github.com/microsoft/dynamics365f-o-custom-help/ repo as a downloadable release. You can find them under Releases.

Assign a custom index to a language

Open the Language.config file in the solution.
In the list, find the language of the index, and specify an index name by using the index="", parentindex="", or ultimateindex="" key.

For example, you created search indexes for English (United States) and German (Austria), and you named them myenusindex and mydeatindex, respectively. In this case, here is what your entries will look like.
```
<add language="en-US" ultimateindex="myenusindex" />
<add language="de-AT" parentlanguage="de" index="mydeatindex" />
```
Optional: Customize language fallback for your index, as described in the next section.
Build the AzureSearchCustomHelp solution.

The result is a model that you upload to the Asset library of the customer project or the solution project in Microsoft Dynamics Lifecycle Services (LCS).

Customize language fallback

Language fallback means that the Help pane runs a search in additional languages if the intended language either doesn't return a result or doesn't exist.

Note

A custom index must be available for the additional languages.

The search and fallback order have the following order of priority:

The language that is set in the client (for example, de-AT)
The language that is defined in the parentlanguage attribute for that language (for example, <add language="de-AT" parentlanguage="de" index="mydeindex" />)
The language that the ultimateindex attribute is set for (for example, <add language="en-US" ultimateindex="myenusindex" />)

Important

If the parentlanguage attribute is set, there must be a corresponding parentindex key.

The following scenario is valid, because language="de" has parentindex="indexde", and both de-DE and de-AT are descendants of de.

<add language="de" parentindex="indexde"/>
<add language="de-DE" parentlanguage="de" index=""/>
<add language="de-AT" parentlanguage="de-DE" index="indexdeat"/>

The following sections provide sample configurations.

Help content for one locale

In this configuration, you have Help content only for English (United States). Regardless of the locale that clients are set to, they will show the Help content in English (United States).

<add language="en-US" ulitmateindex="indexenus"/>

Help content for multiple locales

In this configuration, you have Help content for French, German, and English (United States). Clients that are set to the de locale will show the Help content in German, clients that are set to the fr locale will show the content in French, and clients that are set to any other locale will show the content in English (United States).

<add language="en-US" ulitmateindex="indexenus"/>
<add language="fr" parentindex="indexfr"/>
<add language="de" parentindex="indexde"/>

If clients are set to the de or fr locale, but no results are found in the German or French content, respectively, results will be shown in English (United States), if content is available in that language.

Help content that uses parent locales

In this configuration, you have Help content for German, German (Austria), and English (United States). For example, you have several topics that are related specifically to features for Austria, but topics in German can be used otherwise.

<add language="en-US" ulitmateindex="indexenus"/>
<add language="de" parentindex="indexde"/>
<add language="de-AT" parentlanguage="de" index="indexdeat"/>

If the client is set to the de-AT locale, but no results are found in the German (Austria) content, results will be shown in German and English (United States), if content is available in those languages.