Including Other PeopleSoft Online Help Sites in Context-Sensitive Help Lookups

To configure the context-sensitive help in your PeopleSoft Applications to deliver help from multiple help sites, you need to specify the URLs for all sites that you want to include and re-create the help index.

This section discusses how the context-sensitive help works in the 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%

Your installation documentation contains instructions for setting the value of the system help string. See PeopleSoft 9.2 Application Installation for your database platform, “Installing PeopleSoft Online Help.”

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 PeopleSoft Enterprise Components 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.

    To customize this message, see Customizing the “No Help Found” Messages.

  • 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.

    See Including Multiple Online Help Sites for PeopleSoft 9.1 and PeopleTools 8.52 and Earlier for more information about the common.js file.

Context-Sensitive Help Processor Files

The context-sensitive help processor uses the following files:

Field or Control

Definition

docroot/help.html

This is the entry page for the help processor.

docroot/js/help.js

Contains JavaScript for the help processor.

docroot/idx/filename.json

Contains indexes for context ID searches.

docroot/language/product family/helpid.txt

Contains all context IDs that are specified in all help pages within the product family folder.

docroot/language/product family/pchelp.dat

Contains all PeopleCode context IDs that are specified in all help pages within the product family folder.

To configure context-sensitive help for multiple sites, 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 Human Capital Management (HCM) 9.2 and PeopleTools 8.55. 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$  
    **/

Note: The other help sites that you include when re-creating the index must be for PeopleSoft 9.2 or PeopleTools 8.53 or later. You use a different procedure to include help sites for PeopleSoft 9.1 or PeopleTools 8.52 or earlier. See Including Multiple Online Help Sites for PeopleSoft 9.1 and PeopleTools 8.52 and Earlier.

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.

Note: This procedure does not support help sites for PeopleSoft 9.1 and PeopleTools 8.52 and earlier. To include help sites for those releases, see Including Multiple Online Help Sites for PeopleSoft 9.1 and PeopleTools 8.52 and Earlier.

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.

    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.

Note: This procedure is not recommended for PeopleSoft 9.2 and PeopleTools 8.53 and later. To include help sites for those releases, see Including Multiple Online Help Sites for PeopleSoft 9.2 and PeopleTools 8.53 and Later.

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

Field or Control

Definition

altHelpURL

Enter the help URL that you entered when you enabled context-sensitive help during the applications installation. To find the URL:

  1. Log in to your PeopleSoft application in a browser.

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

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

  4. Copy the URL from the Help URL field on the General page.

    Example for a hosted site: http://www.oracle.com/pls/topic/lookup?id=%CONTEXT_ID%&ctx=hcm92pbr6

    Example for a locally installed site: http://example.com:5080/htmldoc/f1search.htm?ContextID=%CONTEXT_ID%&LangCD=%LANG_CD%

Note: You can enter only one URL for this 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.

Customizing the Message for Application Pages

Edit the docroot/language/helpNotFound.xml file.

Use the %Context_ID% variable as a placeholder for the name of the page from which the help is called.

Customizing the Message for PeopleCode Pages

Edit the docroot/language/pcHelpNotFound.xml file.

Use the %Context_ID% string as a placeholder for the name of the page from which help is called. Use the %LANGREF_NAME% string as a placeholder for the name of the class from which help is called, if specified.