Add custom help content

 

Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

With Microsoft Dynamics 365 (online & on-premises), administrators can configure what help content page will appear in the entire organization or for specific entities. Organizations that have a highly customized system, especially those that use custom entities, will find that the application help content is of limited use. Administrators can configure the system to override the default help content by specifying a URL to open instead. The page to open might be a static page on a SharePoint site, a webpage on the Internet, or a custom help application created using web resources and included with a solution.

Developers need to understand the options available and what contextual information can be passed with the URL so that they can create pages to display appropriate content. You can also find more information in the topic Customize your CRM system: Customize the Help experience.

Custom help behavior depends on data stored in the Organization entity and the EntityMetadata definitions for each entity as described in the following table.

System or entity setting

Data

Type

Description

System Setting: Use custom help for customizable entities

Organization.GlobalHelpUrlEnabled

Boolean

Indicates whether custom help is enabled for the organization.

System Setting: Global Custom Help URL

Organization.GlobalHelpUrl

String

The global help URL for the organization.

System Setting: Append Parameters to URL

Organization.GlobalAppendUrlParametersEnabled

Boolean

Indicates whether query string parameters with context information are appended to the help URL. More information: Contextual query string parameters

Entity Setting: Use Custom help

EntityMetadata.EntityHelpUrlEnabled

Boolean

Indicates whether custom help is enabled for the entity.

Entity Setting: Help URL

EntityMetadata.EntityHelpUrl

String

The custom help page to display for this entity.

The combination of settings applied controls which help topic will be displayed. The options are described in the following table.

Organization.GlobalHelpUrlEnabled

Organization.GlobalHelpUrl

EntityMetadata.EntityHelpUrlEnabled

EntityMetadata.EntityHelpUrl

Behavior

false

N/A

N/A

N/A

Default Help page opens

true

No

false

N/A

Default Help page opens

true

No

true

No

Default Help page opens

true

No

true

Yes

Entity Help Page opens

true

Yes

true

Yes

Entity Help Page opens

true

Yes

true

No

Global URL page opens

true

Yes

false

N/A

Global URL page opens

System_CAPS_noteNote

When global help is enabled, the custom page will appear whenever any help button in the application is used, including pages not related to any customizable area of the application. Because this hides content that may be valuable to administrators, generally custom help should be applied on a per entity basis.

When Organization.GlobalAppendUrlParametersEnabled is true, the following query string parameter values may be appended to the custom help URL.

Parameter

Description

entrypoint

The type of page that the help was opened from. Possible values are form and hierarchychart. This parameter isn’t included if help is opened from a list view.

formid

The GUID value for the form or hierarchy chart that help was opened from.

typename

The logical name of the entity that the help content was opened from.

userlcid

Language code identifier that is used by the current user. Valid locale ID values can be found at Locale ID (LCID) Chart.

The following HTML provides an example showing how to access these query string values using JavaScript. This page will display a table showing the values for these parameters if they are passed.

<!DOCTYPE html>
<html>
<head>
 <title>Help topic</title>
 <style>
  body {
   font-family: 'Segoe UI';
  }
 </style>
 <script type="text/javascript">
  function getQueryStringParameter(parameter) {
   /// <summary>Parses query string values passed to the page and returns the value for the requested parameter or 'null'</summary>
   /// <param name="parameter" type="String">The parameter value to look for</param>
   /// <returns type="String" />
   var query = window.location.search.substring(1); 
   var params = query.split("&");
   for (var i = 0; i < params.length; i++) {
    var pair = params[i].split("=");
    if (pair[0] == parameter) {
     return pair[1];
    }
   }
   return "null";
  }


  document.onreadystatechange = function () {
   if (document.readyState == "complete") {

    var entrypointValue = getQueryStringParameter("entrypoint");
    var formidValue = getQueryStringParameter("formid");
    var typenameValue = getQueryStringParameter("typename");
    var userlcidValue = getQueryStringParameter("userlcid");

    if ((document.documentMode) && (document.documentMode <= 8))
    {
     //If page is being displayed in IE Compatibility mode
     document.getElementById("entrypointValue").innerText = entrypointValue;
     document.getElementById("formidValue").innerText = formidValue;
     document.getElementById("typenameValue").innerText = typenameValue;
     document.getElementById("userlcidValue").innerText = userlcidValue;
    }
    else
    {
     document.getElementById("entrypointValue").textContent = entrypointValue;
     document.getElementById("formidValue").textContent = formidValue;
     document.getElementById("typenameValue").textContent = typenameValue;
     document.getElementById("userlcidValue").textContent = userlcidValue;
    }


   }
  }

 </script>
</head>
<body>
 <p>This is a custom help topic that can accept query string parameters</p>
 <table>
  <thead><tr><th>Parameter</th><th>Value</th></tr></thead>
  <tbody>
   <tr><td>entrypoint</td><td id="entrypointValue">null</td></tr>
   <tr><td>formid</td><td id="formidValue">null</td></tr>
   <tr><td>typename</td><td id="typenameValue">null</td></tr>
   <tr><td>userlcid</td><td id="userlcidValue">null</td></tr>
  </tbody>
 </table>
</body>
</html>

Using HTML web resources as help content has the advantage that they can be included together in a solution for any custom entities that they describe. It is also possible to use JavaScript in these pages to access Dynamics 365 data and metadata to provide dynamic content that may reflect the current fields in a form or to get information about the privileges assigned to the user.

The Organization.GlobalHelpUrl and EntityMetadata.EntityHelpUrl fields are simple string values without any formatting to require a valid protocol. This allows for using relative path descriptions to the URL representing a web resource so that the reference to the web resource can work without being modified when a solution is used to move the help content from one organization to another. A specific web resource can be referenced using a relative URL like this:

/WebResources/new_/help/content/account.htm
System_CAPS_importantImportant

When a user belongs to more than one organization on a server, this path will always refer to the users default organization. If the user isn’t using the default organization and the expected web resource isn’t included in the user’s default organization, a “File Not Found” error occurs even though the web resource does occur in the organization the user is currently working in. If a web resource with the same name exists in the default organization, the web resource for that organization will be displayed and may not be correct for the current organization.

If this causes problems for users in the organization, the URL values for the settings can be updated to prepend the base organization URL to the relative URL for the web resource in the organization.

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright

Show: