Add custom help content

Article
11/28/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.

In this topic

Custom help options

Contextual query string parameters

Use web resources to provide help content

Custom help options

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

Note

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.

Contextual query string parameters

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.

Accessing query string values

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>

Use web resources to provide help content

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

Important

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.

Share via

Add custom help content

In this topic

Custom help options

Contextual query string parameters

Accessing query string values

Use web resources to provide help content

See Also

Additional resources