Configuring Context-Sensitive Help Using a Locally Installed Online Help Website

This section discusses how the context-sensitive help works in the locally installed PeopleSoft Online Help. When you request help from a PeopleSoft application page, the software generates a URL and passes it to your default web browser. This URL is generated by resolving two variables into a string value that is stored in the system. Here is an example of the syntax of the string, with variables wrapped in percent signs (%):

http://example.com:5080/help-PB/help.html?ContextID=%CONTEXT_ID%&LangCD=%LANG_CD%

The string is a URL pointing to the help.html page, which is in the global (docroot) level of the online help site. During the help call, the variables are resolved as follows:

• %CONTEXT_ID% is replaced with the name of the page from which help is called.

• %LANG_CD% is replaced with the user’s preferred language code, such as ENG (English).

Using the preceding syntax example, if an English user calls help from the PeopleTools Options page, the resulting URL looks like this, with the resolved values (PSOPTIONS and ENG) in bold:

http://example.com:5080/help-PB/help.html?ContextID=PSOPTIONS&LangCD=ENG

When the help URL is passed to a browser, the help.html page opens, and the JavaScript logic inside uses the two passed arguments (Context ID and LangCD) to load the appropriate context ID lookup files. These files map valid application context IDs to locations in the help system. The lookup file contents are searched and, when a match is found for the ContextID value, the help.html file redirects the browser to the correct location using the following rules:

• If only one destination is retrieved for the context ID, display the page with the retrieved URL.

• If multiple destinations are retrieved, open a new browser window and display a list of links to the possible destinations.

• If no context ID is found, display a “No Help Found” message.

• If the var altHelpURL value is specified in the common.js file, the page is redirected to that URL. If the context ID exists at that site, the corresponding help page appears.

To configure context-sensitive help for multiple libraries, such as Human Capital Management (HCM) and PeopleTools, you need to choose one site as the main source of context-sensitive help. Then you re-create the help index in the main site to include context IDs for the other sites that you want to include.

For example, suppose you want to provide help for both HCM and PeopleTools. Each product family has a separate help site. When you initially set up context-sensitive help for your applications, you choose the HCM help site as the main source of context-sensitive help. Then you re-create the help index on the HCM site to include context IDs for the PeopleTools site. If you don’t re-create the help index, users who click the Help link on a PeopleTools page will receive a “No Help Found” message.

The main site must meet both of the following conditions:

• The site must be for PeopleSoft 9.2 or PeopleTools 8.55 or later.

• The docroot/js/common.js file must be revision 151995 or higher.

  To find the revision number, open the file in a text editor. The revision number is at the beginning of the file. For example:

  /**  
  * common.js  
  * $revision: 151995$  
  **/

To enable Help links:

1. Sign in to your PeopleSoft applications.

2. Select PeopleTools > Web Profile > Web Profile Configuration.

3. Click Search and select the profile name that you specified during your PeopleSoft installation.

4. On the General page, enter the help URL in the following format:

   http://webserver:port/help_folder/help.html?ContextID=%CONTEXT_ID%&LangCD=%LANG_CD%

   Replace webserver:port and help_folder with the values for your locally installed online help website.

   Example:

   http://myserver.example.com:8080/help-PB/help.html?ContextID=%CONTEXT_ID%&LangCD=%LANG_CD%

   Note: To have the help search across multiple libraries, such as HCM and PeopleTools, see Including Multiple Online Help Sites for PeopleSoft 9.2 and PeopleTools 8.53 and Later and Including Multiple Online Help Sites for PeopleSoft 9.1 and PeopleTools 8.52 and Earlier.

5. Save your changes.

6. Restart your web server.

7. Test the links by clicking the Help link on at least one page in each of the PeopleSoft applications that you defined in the help URL.

To enable the F1 help:

1. Sign in to your PeopleSoft applications.

2. Select PeopleTools > Utilities > Administration > PeopleTools Options.

3. In the Help Options section, enter the F1 URL in the following format:

   http://webserver:port/help_folder/help.html?ContextID=%CONTEXT_ID%&LangCD=%LANG_CD%

   Replace webserver:port and help_folder with the values for your locally installed online help website.

   Example:

   http://myserver.example.com:8080/help-PB/help.html?ContextID=%CONTEXT_ID%&LangCD=%LANG_CD%

   Note: To have the help search across multiple libraries, such as HCM and PeopleTools, see Including Multiple Online Help Sites for PeopleSoft 9.2 and PeopleTools 8.53 and Later and Including Multiple Online Help Sites for PeopleSoft 9.1 and PeopleTools 8.52 and Earlier.

4. Save your changes.

5. If Application Designer is running, quit and restart it.

6. Open Application Designer.

7. Test the help by opening a definition, such as a page or dialog box, and pressing F1.

The PeopleSoft Online Help site contains a precompiled context-sensitive help index containing all context IDs for the product family. To have the help processor deliver help pages from other product families, you need to re-create this help index to include the context IDs for all applicable product families.

To re-create the context-sensitive help index:

1. Make sure that Java version 1.7 or higher is installed.

2. Open a command prompt or terminal and change the directory to the folder where you originally extracted the online help zip file when installing the online help for the site that will be the main source of context-sensitive help.

   For more information on which site should be the main source of context-sensitive help, see Understanding Context-Sensitive Help Configuration for Multiple Libraries.

   The folder where the online help was extracted is usually different from the docroot folder for the online help site.

   For example:

   Operating System	Example Command
   Microsoft Windows	cd c:\temp\elm92pbr3
   Unix or Linux	cd /tmp/elm92pbr3

3. Enter the command to run the index utility.

   You run this utility using the batch file or shell script for your operating system. Alternatively, if you’re familiar with the Java command line, you can also run the utility from the Java command line on any platform.

   Note: If your help server URLs use https, ensure that the SSL certificates are valid and correctly installed. If they are not, the build script will fail with SSL-related errors.

   Operating System or Platform	File or Command	Example Command
   Microsoft Windows	buildindex.bat (without arguments) Note: If one or more online help servers are located outside the firewall, edit buildindex.sh to set the proxy server URL and proxy server port to the variables httpProxyHost and httpProxyPort (or httpsProxyHost and httpsProxyPort), respectively.	c:\temp\elm92pbr3>buildindex.bat
   Unix or Linux	buildindex.sh (without arguments) Note: If one or more online help servers are located outside the firewall, edit buildindex.sh to set the proxy server URL and proxy server port to the variables httpProxyHost and httpProxyPort (or httpsProxyHost and httpsProxyPort), respectively.	$ sh ./buildindex.sh
   Java (any operating system)	java -jar psHelpIndexBuilder.jar -u urllist helprootpath Use the following arguments: urllist: Enter the URLs of all PeopleSoft product line help sites that you want to include, separated by commas. helprootpath: Enter the online help folder path to create the context-sensitive help index. Note: If one or more online help servers are located outside the firewall, add the system properties http.proxyHost and http.proxyPort (or https.ProxyHost and https.ProxyPort)) for the proxy server URL and proxy server port, respectively.	When all help servers inside the firewall: $ java -jar psHelpIndexBuilder.jar -u http://example.com/pt855pbr0/eng/pt,http://example.com/elm92pbr3/eng/elm $PS_HOME/webserv/peoplesoft/applications/peoplesoft/PORTAL.war/elm92pbr3 With one or more help servers outside the firewall: $ java -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=80 -jar psHelpIndexBuilder.jar -u http://example.com/pt855pbr0/eng/pt,http://example.com/elm92pbr3/eng/elm $PS_HOME/webserv/peoplesoft/applications/peoplesoft/PORTAL.war/elm92pbr3

4. (Batch file or shell script only) When prompted for the product line help page URLs, enter a comma-separated list of the URLs of all help sites that you want to include (PeopleSoft 9.2 and PeopleTools 8.53 and later).

   Enter the URLs for the product-line level folders, rather than the root folders.

   Also include the URL for the current help site where you’re running this procedure.

   For example:

   http://example.com/pt855pbr0/eng/pt,http://example.com/elm92pbr3/eng/elm

5. (Batch file or shell script only) When prompted for a help folder path, enter the path to the global (docroot) folder for the current help site where you’re running this procedure.

   This path is for the folder containing the help.html file and the images, js, and styles folders. See Global Folder Level.

   This is where the context-sensitive help index will be created.

   For example:

   Operating System or Platform	Example Path
   Microsoft Windows	%PS_HOME%\webserv\peoplesoft\applications\peoplesoft\PORTAL.war\elm92pbr3
   Unix or Linux	$PS_HOME/webserv/peoplesoft/applications/peoplesoft/PORTAL.war/elm92pbr3

To have the context-sensitive help look up context IDs for PeopleSoft 9.1 or PeopleTools 8.52 (or earlier), you can set up the context-sensitive help to look up context IDs in a previous PeopleBook Library website if it can’t find the context ID in the PeopleSoft Online Help website.

To do this, modify the docroot/js/common.js file to set the following variable:

The following example shows the common.js file with a hosted site specified for the altHelpURL variable (highlighted in bold):

/**  
* common.js  
**/ 
var searchURL = "http://example.com:7777/search/query/";          //http://host:port/search/query
var altHelpURL = "http://www.oracle.com/pls/topic/lookup?id=%CONTEXT_ID%&ctx=hcm92pbr6";         //http://www.oracle.com/pls/topic/lookup?id=%CONTEXT_ID%&ctx=hcm92pbr6
                      //"http://host/path/help.html?ContextID=%CONTEXT_ID%&LangCD=%Lang%
var searchOpt = "group=pt855";          //group=pt853
var queryTextParamName = "q"; //q

If no help is found for an application or PeopleCode page, a default message appears. You can customize the message text using standard HTML5 elements.