Microsoft Dynamics CRM 2015 Custom Help

Roshan Mehta, 19 November 2014

The ability to provide contextual custom help content for users is a very important piece of any CRM implementation, big or small. Microsoft Dynamics CRM 2015 now makes it easy to configure and manage help content, whether you are using CRM out of the box with a few minor customizations, or a highly customized CRM system.

CRM administrators can configure what help content will be displayed to the entire organization or for specific customizable entities. An important thing to note is that customizable help is not available for Microsoft Dynamics CRM for tablets.

To configure custom help in your CRM system:

1.  Define your custom help content and host it somewhere. You could host the content on a SharePoint Site, a custom built help portal, an external Knowledge Base application, or within HTML Web Resources hosted inside CRM.
2.  Turn on customized help for the organization and provide a URL to the location where the help content is hosted
3.  Turn on customized help for specific customizable entities (optional)

Globally turn on custom Help

To turn on customized help for the organization, navigate to Settings > Administration > System Settings. On the General tab, scroll down to the section titled Set Custom Help URL.

Use Custom Help for customizable entities – This option turns on global help for all customizable entities in the system.

Global custom Help URL – specifies the URL to the location where our custom help content is hosted. Relative URLs are supported if you wish to host custom help inside HTML Web Resources.

Append parameters to URL – Setting this option to “Yes” will automatically include contextual information in our custom Help URL. The following parameters can be included:

•  entrypoint – The type of page that help was opened from. Note that this parameter is not included if help is opened from a list view. Valid values include form, hierarchychart, and formid. The formid parameter refers to the GUID of the form or hierarchy chart that help was opened from
•  typename – The logical name of the entity that help was opened from
•  userlcid – The language code that is used by the current logged in user

Note: If custom help is turned off, the default help content will be displayed. For example, navigating to help for the Account entity will display the following window:

No help will be provided for any custom entities we have, since the default help content knows nothing about our customizations. If I open up help for a custom Event entity, the following window will be displayed:

Now let’s see what happens when we turn custom help on. I have specified the following properties in System Settings:

Use custom Help for customizable entities: Yes

Global custom Help URL: http://crmhelp.magnetismsolutions.com

Append parameters to URL: Yes

Note: You will need to refresh CRM in the browser once you have updated the System Settings.

If I navigate to help for the Account entity, CRM opens up a new window with the following URL which includes the entity name and language code of the current logged in user. We can simply build a web page which can read this information and display contextual help in the correct language.

http://crmhelp.magnetismsolutions.com/?typename=account&userlcid=1033

If I now try to navigate to help for our custom Event entity, we will see the following URL:

http://crmhelp.magnetismsolutions.com/?typename=rosh_event&userlcid=1033

Turn on custom Help at the entity level

Custom help can also be turned on at the entity level. This would be useful in scenarios where you might have purchased add-ons for CRM and the help URL would take you to the website of the vendor who developed the add-on. Another scenario would be the case where you have one HTML Web Resource per entity. For example, account.html would contain the help information for the Account entity, while contact.html would surface information about Contacts.

To turn on custom help at the entity level, navigate to Settings > Customizations > Customize the System and open up the entity definition for any customizable entity.

If I was building an Events module for CRM which I intend to sell as an add-on, I would configure a different URL for custom Help.

Note: You don’t need to publish the entity for the changes to take effect. Simply save the entity definition and refresh CRM in the browser before clicking on the help button.

The resulting help URL would look like this:

http://events.magnetismsolutions.com/?typename=rosh_event&userlcid=1033

Hosting Help Content in HTML Web Resources

The ability to host custom help content within HTML web resources has the following advantages over other methods:

•  They are solution-aware so are packaged up when moving customizations to other systems. This simplifies the deployment process.
•  They can be used together with JavaScript web resources to fetch values and provide dynamic content
•  The global Help URL or entity Help URL can reference HTML web resources via a relative path. e.g. /webresources/rosh_/help/content/account.html

The CRM 2015 SDK describes the following caveat to using HTML Web Resources.

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.

Stay tuned for future posts where we will see how we can implement custom help in various ways.