Customizing Salesforce Help – Part 2

Salesforce provides a nifty hook for hanging your own “Help for this Page” content on the custom tabs used by your application. When a user clicks “Help for this Page” on your custom tab, you can set the underlying object to Open a Window using a Visualforce page.
If you distribute a large managed package, like Nimble AMS, the “Help for this Page” links are great entry point to your own help site. In this blog series, we are using the Visualforce page to redirect to a external help site.
For more background, see Getting Started with Object-Level Help.

In part 1, we showed using the Visualforce page as a shell that calls a specific method on the page controller. Based on which method is called, the controller then redirects to the help site, going to a page we specify on the Salesforce side.

From the HelpRedirect method in part 1, you can redirect to any page you like. Something like

or

would work just as well.

To avoid hardcoding the name of your help site into Visualforce controller, in part 1, we added a custom setting so that you could change the help site URL in any org without touching any of the mapping code.
Likewise, you might be nervous about hardcoding help page names directly into your Visualforce controller. (I know I am!)
If so, setup a set of aliases on the help site server, and link to the aliases instead of the actual pages. If the pages are revamped, you can just update the alias mappings on the help site server, and touch nothing in Salesforce. 
The nuts and bolts will vary between web servers, but here’s how to do it with Nginx (“Engine X”) using rewrite rules. For more about Nginx, see wiki.nginx.org. (Again, other web servers, like Apache HTTPD, Express, and IIS, all have similar capabilities.)
For help.nimbleams.com, we assign IDs to our topics, rather than names, and for the Affiliations tab, we want to show a file named “a061.html”. Likewise, the Subscription tab maps to our page “a069.html”.
Expressed as Nginx rewrite rules, we end up with configuration settings like:

The (.*) matches the end of the URL, and the $1 puts the beginning of the URL back in again. The regex replacement logic keeps the aliases portable, even if we were to change domains or move the help to a sub site.
We like to be able to maintain the rewrite rules under version control with the help topics, and so the main Nginx configuration includes our rewrite file from the web root.

Salesforce can redirect to any URL, and using similar techniques, you can use any web server. For more about setting up your own web server, see the quick-and-easy Build a Webserver on Amazon EC2, among many other resources.

Salesforce provides three layers of help: Field-Level Help, Object-Level Help, and its own Online Help. Field-level is the tooltips that appear next to data-entry fields, and object-Level is what we’ve been discussing so far.
When you click Help for this Page on a standard component, like Accounts, Chatter, or Reports, Salesforce pops over to help.salesforce.com. Or, with a bit of configuration, it can go to your help site instead.
For more background, see Replacing Online Help on Salesforce.com.
The nasty bit is parsing the parameters that Salesforce passes along to your help site. So, for example, if Salesforce redirects to

we want to present the Accounts page in our own online help.
Again, Nginx rewrite comes to our rescue. At the end of our rewrite.conf file, we include redirects for the standard pages we want to handle ourselves:

Notice that we’re redirecting back to an alias for Accounts, Collaboration, Dashboards, and Reports. In this way, we can manage all the help redirects together, whether they are for standard tabs or custom tabs.
Finally, for any and all other standard pages, we have a catchall:

So we handle Accounts, Chatter, Reports and Dashboards, and the rest fall through to the trusty help.salesforce.com site. ​

At first, implementing Salesforce Object-Level Help and also Replacing Salesforce Help may seem challenging. But, happily, most web servers, like Nginx, have the tools we need to piece it all together.
Do you have your own help site for your customizations? What platform do you use for help content? A CMS? A plain-old-html site? Or do you transform your site from Markdown or DITA?

---

Ted Husted is a Kaizen Squad developer on the Nimble AMS product crew. “We make the good changes that create a great product.”