Posted on 28. November 2014

Separate Content from Code

Back in the On-Prem CRM 3/4 days I would regularly customise the Dynamics CRM help files to add new topics and amend existing ones to match a company's solution. Context sensitive help was also possible by linking specific entities to specific help topics. With CRM2011 and the advent of the 'getting started pane' help became more of an inline experience with links being displayed above grids of records however customising the online help was no longer supported. CRM2013 removed the 'getting started pane' and so it was much harder to provide a customised help experience. I'm really pleased that the Dynamics CRM team has invested in this area in CRM 2015 in the form of the 'Custom Help URL' feature.

Global Help URL

If you navigate to Settings->Administration->System Settings you'll see the new Custom Help URL options. To use this new feature you must first enable 'Use custom Help for customizable entities'


You then have the option to provide a global help URL that will be used when users click the '?' icon on the top right of any refreshed UI page. It is also used when user click on the 'classic' style help icon on non-refreshed pages.

If the help button is clicked on an entity form then some contextual parameters are passed. For the Case entity the following are added to the Global Help URL:

entrypoint=form&formid=4a63c8d1-6c1e-48ec-9db4-3e6c7155334c&typename=incident&userlcid=1033

Solution Deployment vs. Content Management

You have the option to use either a relative URL that points to a WebResource as shown in the screenshot above but you can also use an absolute URL to content hosted outside of CRM. You can also then create a help URL per entity in the entity customisation properties as shown below.

The disadvantage with this external URL per entity approach is that this URL is likely to be different in your DEV/UAT/PROD environments and since this URL will be transferred with each solution deployment we'll have to update this setting every time we deploy.

I've found that although the software development lifecycle is usually a regulated release process, the help content authoring process tends to be more of an evolving one. With the CRM2011 getting started pane being linked to Web resources I always found it much harder to get this content updated due to the rigor of the deployment process. For this reason I now recommend not coupling your company's help content to your CRM solution's web resources but rather use an external content management system such as SharePoint. This allows you to then regular release updates and new content without having to schedule a new release and the down time associated to this.

But how do we avoid having to update the entity URLs on each DEV/UAT/PROD environment? We use only the Global Help URL in combination with the typename querystring parameter and not use the entity Help URL at all.

To do this in SharePoint:

1. First we must enable embedding of code into SharePoint pages.

2. Edit the SharePoint page that is the default landing page in the Global Help URL (e.g. SitePages/Home.aspx)

3. On the Insert ribbon tab, select 'Embed Code'

And paste the following code:

<script>
function getQueryStringArray(){
    var assoc=[]; 
    var items = window.location.search.substring(1).split('&'); 
    for(var j = 0; j < items.length; j++) { 
       var a = items[j].split('='); assoc[a[0]] = a[1]; 
    }
    return assoc;
}
var qs = getQueryStringArray();

if (qs.typename!=null)
{
  window.location.href = '/SitePages/' + qs.typename + '.aspx';
}
</script>

Now when CRM opens your Global Help URL it will redirect to the specific page for that entity passed on the typename. You can then create pages for each typename in the Site Pages library:

Since the Global Help URL is not solution aware, you can deploy your solution to multiple environments without having to change all those URLS with each deploy.

You can read more about this on Bryce Holmes' post on this feature. Read the Online Help about this feature and read Magnetism's blog on this feature.

Hope this helps!

@ScottDurow