Salesforce Help Options

Picture

What are your alternatives for customizing Salesforce help?
One of the marvels of working with Salesforce is the seamless way customizations blend together on the Force.com platform. From the user’s perspective, custom capabilities and standard capabilities all look-and-feel alike.

One exception can be “Help for this Page” (HFTP). Much of the Force.com UI is composed of tab controls that are collected into “apps”. Users can switch between apps to quickly access different sets of tabs. Each tab can provide its own documentation via “Help for this Page” link at the top-right corner of each tab.

On standard tabs, HFTP bounces over to a relevant topic on help.salesforce.com — now part of the truly useful Salesforce Success Community. For custom tabs, HFTP defaults to a generic “Defining Custom Objects” topic.

A tab is associated with an object, and each custom object has a “Context-Sensitive Help Setting” with three options, including the default behavior.

  1. Open the standard Salesforce.com Help & Training window
  2. Open a window using a custom s-control
  3. Open a window using a Visualforce page

Custom s-controls are deprecated. Moving forward, your only real custom option is a Visualforce page. In turn, there are a couple of ways you can leverage the Visualforce page.

  1. Deploy the help topic as a Visualforce page.
  2. Use the Visualforce page to link to a shared document.
  3. Use the Visualforce page to jump to an external help site. (Salesforce itself uses an external site.)

Using either Visualforce straight-up or using a shared document are fair options if you only need to provide a single Help page for each tab. For many apps, certainly, one page can be sufficient. Other apps justify more extensive documentation.

For more background, see Getting Started with Object-Level Help.

 If you you have extensive documentation, and want to maintain it all in one place, the better approach can be to use the Visualforce page to redirect to an external help site. Let’s have a look.


Force.com Prerequisites

Before you can configure your org to use a custom help site, there are three prerequisites to create (plus having the help site).

  1. Custom setting to point to your help site.
  2. Visualforce page controller (Apex class), to route to your help site.
  3. Visualforce page for each object that to call the corresponding method on the controller.

Custom Help Setting

Create a custom setting to point to your help site. By using a custom setting, we can avoid hard-coding the name of an external site into code that can be cumbersome to change.

  • Object Name: ExampleSettingsManager
  • Field Label: Help URL
  • Field Name: HelpURL
  • Data Type: URL
  • API Name: HelpURL__c
  • Description: Root host name for the site to use with “Help for this page” link for custom objects. In development, this setting might be changed to http://localhost:5000 or such.
  • Help Text: Enter the Help site URL, such as http://help.example.com

Strictly speaking, the setting is optional. But I strongly recommend giving yourself the flexibility of pointing to a different URL from a central location.

HelpRedirect Apex Class

Create an Visualforce page controller, to route to your help site. Note that I’m choosing to redirect to an URL like “help.nimbleams.com/Affiliations”, but you can use whatever URL works for you. Just have your PageReference methods return something different. We also keep all the literal reference to the help site in this one class. If the help site is ever revamped, this class is the only component that needs to change. ​

HelpRedirect Visualforce Page Template.

Create a HelpRedirect Visualforce page for each object to call the corresponding method on the controller. We chose to keep the Visualforce pages simple and defer the logic to the controller. All the page does here is call a method on controller, and the controller does the rest. ​

Adding Help For This Page to a Custom Tab

Link a custom tab to an online help via a custom Visualforce page.

  • Create a custom tab for the object.
  • Create a new help topic, using your own approach or the approach, covered from the fabled Part 2 this blog, and note the page name. For testing purposes, any website URL will do.
  • Edit the HelpRedirect controller class to add a method for the new tab, in the same form as the sample default method. The “Section” name is the plural form of the tab or object name.
  • Copy the HelpRedirect page as a new Visualforce page for the tab, and change the page action to match the method you added to the HelpRedirect controller. You do need to include the form to appease the platform. You do not need to update the form, since the action will redirect control.
  • Open the custom object and update the Help Settings to use the new Visualforce page.
  • If the changes to help are deployed to a development site first, update the Help URL on the Configure page.

Although, we don’t create the help site until part 3, you can test the scaffolding by using any-old URL.
How often do you use Salesforce Help for this Page? Should more managed applications provide integrated help? Or does linking to a PDF work just as well?


Ted Husted is a release engineer for Nimble AMS. “It’s my job to make sure that we ship everything that’s done, but not before its ready.” ​