Configuring Salesforce Classic for use with Context-Sensitive Help

NOTE:

If you are using Salesforce Lightning, refer to Configuring In-Application Context-Sensitive Help.

This solution enables an application user to request help from within the application and return relevant help content from your system. The solution is comprised of two deliverable items:

• CSH solution file(s)
• CaptureEngine configuration file

This document will describe each aspect and explain how to use them as part of the CSH solution.

There are three steps to implement this solution:

1. Configure the solution with the location of your uPerform system.
2. Configure Salesforce to use the solution.
3. Configure the ANCILE CaptureEngine to recognize Salesforce context while recording.

Note that Step 3 ideally should be done before you create uPerform content for Salesforce in order to capture context identifiers automatically while recording. If you already have content created for Salesforce, you can manually add context identifiers to those files. This process is described later in this document. Steps 1 and 2 can be done any time relative to content creation but must be complete before your end users will use the CSH solution for Salesforce.

As soon as Step 2 above is complete, help calls from certain Salesforce pages will be directed to uPerform. Since the solution relies on a Salesforce configuration setting to use an external help content location, it only works for help controls that respect this setting. At this time it is known to work with:

• Standard end-user pages delivered by Salesforce
• Custom object definitions with setting “open the Standard Salesforce.com Help & Training Window” selected
• Salesforce Console, provided the pages in the console are either of the two above

The following page types do not work with this solution:

• Pages in the “Setup” area of Salesforce
• The new Lightning UX

The following page types may work provided you create a help control that points to the uPerform® system. Refer to the “Using This Solution with VisualForce Pages” section later in this document.

• VisualForce created pages

Configuration

After extracting the solution files, configure the solution with the location of the help content within your organization’s network. The help content is either part of an  Express website or is stored within your uPerform Server instance.

To use a uPerform Server instance to house the Salesforce content, you must define a connection profile for use in the solution. Refer to Managing Connection Profiles to the Server to create and edit your connection profile.

NOTE:

When creating your connection profile, the Connector is SAP and the Application is SAP Portal.

1. From the solution files you extracted, open the …\CSH_files\SalesforceCSH.html file in a text editor.
2. Locate the uPConnProfile variable.
3. Copy the URL field from the connection profile you specified in Managing Connection Profiles to the Server.
4. Paste the URL as the value of the uPConnProfile variable, ensuring it is placed between the double-quotation marks, and retain the trailing semi-colon.

   For example: uPConnProfile=”http://yourserver/gm/1.11.XXXX?csh=”;

5. Save changes to the SalesforceCSH.html file.

Installation

After configuring the SalesforceCSH.html file, perform the following steps to install or integrate this solution with the Salesforce application.

1. Identify a web server in your organization to house a single .html file.

   NOTE:

   This file will be used to redirect the Salesforce help links to the uPerform® system. The location can be the same web server that houses your uPerform® application server or uPerform® Express website.

2. Place the SalesforceCSH.html file on the selected webserver and copy the URL of this file.
3. In your Salesforce application go to the Setup area.
4. In the Quick Find search textbox, enter Help Settings.

   NOTE:

   As you type Salesforce will show matching results.

5. Click the Help Settings link under App Setup > Customize > Tab Names and Labels.
6. In the Re-direct Help URL field, enter the URL you copied in Step 2.
7. Click the Save button.

Tagging Content with Context

An integral part of the solution is tagging the content (.udc files) with the appropriate context identifiers. When your authors create new content files for Salesforce they must be “tagged” in order to become part of the CSH solution. Tagging is the process of assigning some information to the .udc file that associates it with a given screen in Salesforce. This tagging can be done manually, or automatically while recording. Auto-tagging is simpler for authors since it requires no additional effort beyond the recordings they will already do when creating the help content with uPerform®. However the auto-tagging does provide less control to the content author. The next section describes the nature of the data used as context in this solution to help you decide which tagging method to use.

Discussion of the Salesforce Context

Our discussion will use a sample Salesforce screen – an Opportunity - as a discussion point.

Many Salesforce screens are relatively complex from a user perspective, meaning there are many tasks or actions a user can take from a given screen. In this example screen there are four help controls: Help for this Page, Activity History Help, Contact Roles Help, and Opportunity Team Help. Each of these help controls has a different context value and when a given help control is clicked by the user, it’s specific, single context value is passed to uPerform®. Using the screen above as an example suppose your organization creates the following help files for tasks a user may do from this screen:

• Edit Opportunity Details
• Log a Call for an Opportunity
• Add Contact Roles to an Opportunity
• Assign a Team to the Opportunity

With auto-tagging, if the user requests help from any of the help controls on this screen, all four of the above help files would be returned by the help call and the user would have to select the one that applies to the task they want to perform. So the user would click twice to get to the actual help content: once on the help control and once to select the specific help file. Conversely if you choose to manually tag the files, you can choose to add a given context value only to the relevant file. For example you would add the context value associated with the Activity History Help control only to the Log a Call for an Opportunity file. Then when the user requests Activity History Help the one relevant help file will be displayed; only a single user click is necessary to get relevant help.

So in general manually tagging provides your more control of the help results at the cost of more effort from your authors, while auto-tagging provides less control but with no additional effort from your authors. Your organization must consider this behavior relative to the number and scope of help documents you will create for tasks that interact with a given screen. Consider these questions when evaluating and deciding which approach to use:

• How important is obtaining help content in one-click versus two-clicks?
• Do I want my authors to spend the time necessary to manually identify the context value for the relevant part of each screen in every uPerform® document they create?
• What value do I place on “auto-scrolling?” When auto-scrolling is used the help content opens at the location relevant to the user’s current screen versus simply at the top of the help content. Refer to the Introduction To Context-Sensitive Help for more information about “auto-scroll.”
• How much effort am I willing to apply in order to benefit from auto-scrolling? Auto-scroll functionality requires context values be stored in the .udc at the step level: auto-tagging does this automatically but it can be done manually.

You may also want to review the following sections on auto-tagging and manually tagging to understand the specific actions each author would have to take to collect the necessary context values.

Configuring CaptureEngine for Auto-tagging Context

The CaptureEngine is the application component that captures the author’s actions while recording a .udc file. The CaptureEngine must be configured to enable it to collect the Salesforce context while recording.

NOTE:

The CaptureEngine collects context automatically only when recording Salesforce in Microsoft Internet Explorer.

We recommend performing the steps below on a single computer first to confirm proper operation before distributing the configuration update to all of your authors who will record Salesforce. Once you decide to distribute the CaptureEngine configuration update to your authors, they will only need to do Steps 1 and 2 below.

1. Install ANCILE Capture Engine v6.30 or later.

   NOTE:

   This step is done automatically when installing the uPerform Client 5.20 or later application.

2. Apply configuration file to the CaptureEngine instance.
3. Copy the “CEA” folder that was delivered with this solution.
4. Navigate to the %appdata%\Roaming\ANCILE\CaptureEngine\ folder in Windows Explorer.
5. Double-click the folder that matches the installed CaptureEngine version.
6. Navigate to the configuration\data\Settings subfolder.
7. Paste the CEA folder into the Settings folder.

   NOTE:

   If you already have a CEA folder in this location, choose to “merge” the contents when prompted by Windows.

8. Record a step on a screen in your Salesforce system that has more than one help control.

   NOTE:

   The screen for a specific opportunity in Salesforce is a good example since by default it has many help controls.

9. Stop recording.
10. Review the captured context identifiers for your recorded steps.
11. In the uPerform® Editor, double-click the relevant step to display Step Properties.
12. Select the Context Information panel.
13. Review the Primary: field value.

    NOTE:

    For a step recorded on a Salesforce page with multiple help controls, the Primary field should include multiple items, each separated by a colon character. The exact set may vary depending on your system configuration but in general the number of values separated by colons should approximately equal the number of help icons/links on the Salesforce page. For example, for a typical Opportunity page the Primary: field value may look similar to this: opp_def.htm:products_def.htm:quotes_create.htm:activities_open_and_history.htm:activities_open_and_history.htm:contactroles_edit.htm:salesteam_def.htm:competitors.htm:campaigns_influence_using.htm:notes.htm:stage_history.htm:accessibility_overview.htm

Manually Collecting Context

Although automatically tagging uPerform® files with context is the most efficient approach, content creators may manually tag the pertinent .udc files with the relevant context identifiers from the application screens. Scenarios where manually tagging may be applicable are:

• If you have existing uPerform content that you want to use with the Salesforce CSH solution.
• If you must use a browser other than Microsoft Internet Explorer when recording Salesforce.

The context values can be added to a .udc either at the document or step level. If context values are added at the document level, when a user calls help and the resulting uPerform content is opened, the content opens at the top of the document. If context values are added at the step level, the difference is when the resulting content is opened the help content will automatically scroll to the step in the content that is associated with the screen from which the user requested help. Refer to Recording a Document and Making It Available for Context-Sensitive Help.

NOTE:

Manually adding context identifiers at the step level requires uPerform version 5.20.4 or later.

NOTE:

Multiple uPerform files may contain steps relevant to, and therefore the context identifier of, a single Salesforce screen. Conversely a single uPerform file may contain steps related to, and therefore the context identifiers of, multiple Salesforce screens.

Using This Solution with VisualForce Pages

If you have pages that were created with VisualForce, these can be used with this CSH solution. However you must add a help control to the page(s) that has specific behavior. To make the help call from your page work with this solution, simply ensure the help control opens a URL with the following characteristics:

• URL of the SalesforceCSH.html page in your environment (see the Installation section in this document)
• The URl contains the following query string name/value combination: target=[contextID].htm, where [contextID] can be any alphanumeric string of characters.

The value of “target” acts as the unique identifier for a given VisualForce page so the main criteria is that you use a different value for [contextID] for each help control on each VisualForce page.

In the following example the unique identifier is “home_activities”

http://YourWebServerHosNameHere/SalesforceCSH.html?target=home_activities.htm

If you want the context identifiers for VisualForce pages to be collected automatically while recording, the help control must match additional characteristics. The help control must:

• Be an <a> tag
• Have a child <img> element
• The <img> element must have a class attribute with a value of “helpIcon”
• The help URL containing the “target” query string parameter must be part of the <a> tag attributes

The example below, from a standard, not VisualForce, Salesforce page follows this HTML structure with the pertinent characteristics bolded.

<a class="linkCol" href="javascript:openPopupFocusEscapePounds(%27http://ancdevvmn77.prod.shield.com//SalesforceCSH.html?loc=help&amp;target=activities_open_and_history.htm&amp;section=Activities%27, %27Help%27, 1024, 768, %27width=1024,height=768,resizable=yes,toolbar=yes,status=yes,scrollbars=yes,menubar=yes,directories=no,location=yes,dependant=no%27, false, false);">

<span class="linkSpan">Activity History Help</span>

<img title="Activity History Help (New Window)" class="helpIcon" alt="Activity History Help (New Window)" src="/s.gif">

</a>

As a test start a new recording. As you record, context identifiers should be captured automatically.

Continue to the next article Creating A Template.