Managing the PeopleSoft Online Library and PeopleBooks

This chapter provides an overview of the PeopleSoft Online Library and discusses how to:

  1. Manage the PeopleSoft Online Library.

  2. Integrate your own documentation into the library.

  3. Configure a Reverse Proxy Server for hosting the PeopleSoft Online Library.

Click to jump to parent topicUnderstanding the PeopleSoft Online Library

This section discusses the:

Click to jump to top of pageClick to jump to parent topicThe PeopleSoft Online Library Website

The PeopleSoft Online Library is a website that enables you to browse various types of PeopleSoft Enterprise and JD Edwards EnterpriseOne documentation, including PeopleBooks and implementation guides. It also provides context- and language-sensitive online help for JD Edwards EnterpriseOne and PeopleSoft Enterprise application users. The library is designed to be flexible so that you can easily add or remove content and control which documentation is browseable, searchable, or used as online help. This document describes how to install new PeopleSoft Enterprise and JD Edwards EnterpriseOne documentation over an existing website, how to control access to individual documentation types and books, and how you can integrate your own documentation into the library.

To take advantage of the flexibility of the PeopleSoft Online Library, you must understand the hierarchical directory structure of the website and how it corresponds to the organizational levels of the documentation on the site.

Click to jump to top of pageClick to jump to parent topicThe Global Level

The top directory of the website (which we'll call <docroot>) constitutes the global level of our library. At the global level are three HTML files: index.htm, f1search.htm, and helptest.htm.

Global level of the PeopleSoft Online Library

When <docroot>/index.htm is opened by the browser, JavaScript logic for this page determines the browser's language setting and redirects the user to a PeopleSoft Online Library home page in that language, if it exists. If no language match is found, English is used as the default language.

The <docroot>/f1search.htm file processes online help requests from the PeopleSoft Enterprise applications. When help is requested from an application page or panel, a URL to <docroot>/f1search.htm is passed to the browser. The URL contains arguments that specify the help context ID and the user's preferred language. If that language exists on the PeopleSoft Online Library website, the documentation in that language is searched for a relevant help topic, and, if one is found, the corresponding page is opened. Here again, English is used as the default language if a preferred language match is not found.

The <docroot>/helptest.htm file is used for testing/troubleshooting online help functionality.

Utility Directories

Also at the global level are four utility directories (htm, img, styles, and js) that contain files that are used at the global level or that are shared by subsequent levels of the PeopleSoft Online Library.

These utility directories appear at lower levels of the library site, too. While it's not important to list or describe most of the files in these directories, one thing is important to understand: At each level of the library is at least one JavaScript utility file that stores information about the structure of the level below. At the global level, the key JavaScript file is <docroot>/js/langs.js, which stores information about the languages that have been installed in the PeopleSoft Online Library.

See Managing Language Support.

Click to jump to top of pageClick to jump to parent topicThe Language Level

Below <docroot> are directories representing each installed documentation language: eng (English), fra (French), por (Portuguese), and so on. Each of these directories represents the language level of the website.

Language levels of the PeopleSoft Online Library

The language level is essentially the top of the PeopleSoft Online Library site as far as users are concerned. When a user navigates to <docroot>/index.htm, that user is redirected to the appropriate language directory, based on his or her browser language. The files at (and below) the language level are all language-specific: PeopleBooks and other content, website display labels, CSS stylesheets, accented character conversion routines, and so on.

Utility Directories

Like the global level, the language level also has utility directories that store files that are used at the language level or that are shared by subsequent levels of the PeopleSoft Online Library.

Click to jump to top of pageClick to jump to parent topicThe Documentation Type Level

Within each language directory are subdirectories that each contains a specific type of documentation. For example, the <docroot>/eng/psbooks directory contains PeopleBooks, and the <docroot>/eng/dftie directory (if delivered) contains online help for self-service applications. Each of these directories represents the documentation type level.

Note. In the remainder of this document, we use eng (English) as the language directory in our example file paths.

Documentation type level (PeopleBooks) of the PeopleSoft Online Library

The files stored at the documentation type level are used for the documentation type home page, for PeopleBooks-specific copyright information, and to provide backwards compatibility with previous PeopleBooks versions.

Utility Directories

Like the language level, the documentation type level also has three utility directories that store files that are used at this level or that are shared by subsequent levels of the PeopleSoft Online Library.

Click to jump to top of pageClick to jump to parent topicThe Book Level

Below the documentation type level are directories for the individual "books" that make up the documentation type. For example, the <docroot>/eng/psbooks/fapy directory contains the PeopleSoft Enterprise Payables PeopleBook.

Book level of the PeopleSoft Online Library

The files found at the book level comprise both the content and the online interface of an individual PeopleBook. Book.htm and chapter.htm are framesets that display the book's content. Idxdata.htm and tocdata.htm contain the index and table of contents of the book. The JavaScript file (xxfiles.js) contains an array that lists the order of the individual HTML files that make up the book’s content. This array is used by the navigation features of the book interface.

Content Directories

Three of the subdirectories below the book level store content-related files:

Utility Directories

At the book level is only one utility directory. The contextids directory contains JavaScript files for online help support.

Click to jump to parent topicManaging the PeopleSoft Online Library

This section provides an overview of PeopleSoft Online Library management and discusses how to:

Click to jump to top of pageClick to jump to parent topicUnderstanding PeopleSoft Online Library Management

When you purchase additional documentation from Oracle, you most likely want to merge that documentation with your existing PeopleSoft Online Library site. You accomplish this by installing the new documentation CD over your existing documentation. All the necessary JavaScript utility files are updated to reflect all the content (new and old) on the website.

You can also edit the PSOL utility files manually to reflect changes that you've made to your website and to limit access to it. For example, for documentation types and book titles, you can control whether they are browseable (by way of a home page table of contents), full-text searchable, or used for online help.

Click to jump to top of pageClick to jump to parent topicInstalling New PeopleSoft Enterprise Documentation

Before installing new PeopleSoft Enterprise documentation, decide if you want to combine your existing documentation with the new documentation. If so, you should copy your existing PeopleSoft Online Library site to the location where you plan to install the new documentation. Then, simply install the new documentation CD over it.

See your installation guide.

Click to jump to top of pageClick to jump to parent topicManaging Language Support

PeopleSoft Online Library language support is controlled by the <docroot>/js/langs.js file, which defines an array of language codes and their corresponding language names. Here is a sample of the JavaScript code: 

languages = new Array(
 "cfr||fc||Fran&ccedil;ais&nbsp;du&nbsp;Canada",
 "eng||en||English",
 "esp||es||Espa&ntilde;ol",
 "fra||fr||Fran&ccedil;ais",
 "dut||nd||Nederlands",
 "por||ps||Portugu&ecirc;s",
 "ita||it||Italiano",
 "ger||de||Deutsch"
);

Each of the array elements contains three values, separated by double pipes (“||”): the language code (also the language directory name), the browser language code, and the language name as it should appear in the PeopleSoft Online Library. This array is used by the PeopleSoft Online Library home page (<docroot>/eng/ index.htm) and the PeopleBooks Library home page (<docroot>/eng/psbooks/index.htm) to display a table of alternate language links that link you to the corresponding home page in a new language.

Alternate language links

The languages array is also used during a PeopleSoft Enterprise application help request to try and match the help documentation language to the language of the user.

If you want to disable one or more languages on the PeopleSoft Online Library:

  1. Open <docroot>\js\langs.js for editing.

    The file text looks something like this:

    languages = new Array(
 "cfr||fc||Fran&ccedil;ais&nbsp;du&nbsp;Canada",
 "eng||en||English",
 "esp||es||Espa&ntilde;ol",
 "fra||fr||Fran&ccedil;ais"
 "dut||nd||Nederlands",
 
);

  2. To disable support for an installed language on your site, precede the appropriate line with a double slash (//).

    Here's an example (new text in bold) :

    languages = new Array(
 "cfr||fc||Fran&ccedil;ais&nbsp;du&nbsp;Canada",
 "eng||en||English",
 "esp||es||Espa&ntilde;ol",
 "fra||fr||Fran&ccedil;ais",
 //"dut||nd||Nederlands",
 
);

  3. Remove the trailing comma from the last uncommented line in the array definition.

    Here's an example (deleted text in strikethrough):

    languages = new Array(
 "cfr||fc||Fran&ccedil;ais&nbsp;du&nbsp;Canada",
 "eng||en||English",
 "esp||es||Espa&ntilde;ol",
 "fra||fr||Fran&ccedil;ais",
 //"dut||nd||Nederlands",
 
);

  4. Save the file.

Note. The order of the array elements determines the order of the language links on the home pages, with the exception of Francais du Canada. For formatting purposes, this link always appears in the third table column or last in the list.

Also, the Asian language link text is actually represented by graphics (located in <docroot>/img) for reasons of character set compatibility. There is special JavaScript code on the home pages (home_nav.htm) to deal with these exceptions.

Click to jump to top of pageClick to jump to parent topicManaging Documentation Types

For each documentation type in a particular language level in the PeopleSoft Online Library, you can enable or disable it for three kinds of functionality: browsing, online help, and full-text searching.

Browsing

For a documentation type to be browseable, it should appear on the PeopleSoft Online Library home page.

Documentation types that appear on the PeopleSoft Online Library home page

Which documentation types appear on the PeopleSoft Online Library home page is controlled by the <docroot>/eng/js/doctypes.js file, which defines an array of documentation type file paths and their corresponding display names. In each line, there are two values separated by double pipes (“||”): the directory name and the display name of the documentation type. 

doctypes = new Array(
 "psbooks||PeopleBooks",
 "hrms_8_sp1_data_models||Data Models"
);

The process of adding or disabling browsing support for a documentation type in the array is similar to adding or disabling language support.

Context Sensitivity

At this level of the PeopleSoft Online Library hierarchy, you not only control which documentation types are browseable, but also you control which documentation types are available as online help. You do this by editing the <docroot>/eng/js/helptypes.

The syntax of the helptypes.js file is similar to that of doctypes.js. All books in the documentation types that are listed in helptypes.js can be searched for a matching help topic during an online help request.

Note. If you add a documentation type to helptypes.js, a file called helplist.js must exist in a js directory below the top level of the documentation type (<docroot>/eng/eut/js/helplist.js), or the help logic will fail.

Searching

The syntax of the colltypes.js file is also similar to that of doctypes.js. The documentation types that are listed in colltypes.js are available as searchable documentation types on the PeopleSoft Online Library Advanced Search page.

Click to jump to top of pageClick to jump to parent topicManaging Individual PeopleBooks

You can remove book titles from the PeopleBooks home page table of contents, disable them as online help, or disable them for searching by editing three JavaScript files. The files that control these functions are, respectively, <docroot>/eng/psbooks/js/booklist.js, helplist.js, and colllist.js.

Browsing

The syntax of the booklist.js file is similar to those previously discussed. However, it doesn't contain an explicit array declaration, only array element assignments. Here is some sample JavaScript code from booklist.js: 


var strPath = top.location.pathname;
 
booknames[booknames.length]="psbooks/famp||PeopleSoft 8.8 Asset Management PeopleBook";
booknames[booknames.length]="psbooks/spog||PeopleSoft 8.8 Purchasing PeopleBook";
 
function getTitle(strProdCode, strDocType) {
 strProdCode = strProdCode.toLowerCase(); ...

The lines between the var strPath and function getTitle declarations are the array assignment lines that define the PeopleBook titles that are browseable in the library.

To remove a title from the PeopleBooks home page, comment it out by preceding that line with a double slash (//).

Context Sensitivity

You can disable a title for online help functionality by editing the <docroot>/eng/psbooks/js/helplist.js file just as you would booklist.js (as described in the previous section).

The syntax of the helplist.js file is identical to that of booklist.js, and you can edit it in the same way. The books that are listed in helplist.js are searched for a matching help topic during an online help request. 

helpnames[helpnames.length]="psbooks/pf||PeopleSoft 8 Application Fundamentals for FSCM PeopleBook";
helpnames[helpnames.length]="psbooks/gl||PeopleSoft 8 General Ledger PeopleBook";
helpnames[helpnames.length]="psbooks/ap||PeopleSoft 8 Payables PeopleBook";

Note. The <docroot>/eng/js/helptypes.js file only specifies that books of a particular documentation type can be used for context sensitivity. But in <docroot>/eng/psbooks/js/helplist.js, you must specify every individual book that is to be used for context sensitivity.

Searching

The psbooks/js/colllist.js file controls which PeopleBooks appear in the list of book titles on the Advanced Search page. The syntax of the colllist.js file is slightly different from the previous two discussed. In addition to a path and title name, a "collections" path is also defined in each string (shown in bold): 

colllist[colllist.length]="psbooks/pf||PeopleSoft 8 Application Fundamentals for FSCM PeopleBook||eng/psbooks/pf/coll||";
colllist[colllist.length]="psbooks/gl||PeopleSoft 8 General Ledger PeopleBook||eng/psbooks/gl/coll||";
colllist[colllist.length]="psbooks/ap||PeopleSoft 8 Payables PeopleBook||eng/psbooks/ap/coll||";

You can prevent a PeopleBook title from appearing on the Advanced Search page by preceding it with a double slash. To disable PeopleBook titles for searching, edit the <docroot>/eng/psbooks/js/colllist.js file just as you would booklist.js. All lines must end with a semicolon.

Important! The original purpose of the colllist.js file has been deprecated. It is no longer used to point to individual book collections. There is now only one collection built per documentation type. However, the colllist.js file is still used to provide book title information when building a PeopleBooks search collection. The syntax of the file must be as shown above, even though the “coll” directories no longer exist.

To keep a particular PeopleBook from being included in a search collection, you could temporarily rename its htm folder before starting the collection build. To keep particular files from being included, you could temporarily rename them with a different file extension before starting the build. These solutions take advantage of the regular expression that the collection builder uses to find the PeopleBooks HTML files.

See Integrating Searching.

Click to jump to parent topicManaging Full-Text Searching

It is easy to rebuild the Verity search collections used for full-text searching. This means that you can add your own documentation to the PeopleSoft Online Library (see the next section) and make it searchable along with PeopleBooks. There are also other improvements to full-text search. First, only one collection is built per documentation type. This eliminates the possibility of hitting Verity's upper limit of 128 collections when searching. Also, you can add META tags to the HTML content files that define custom search fields and values. These search fields can then be used as search filters on the PSOL Advanced Search page.

See Integrating Searching.

Click to jump to top of pageClick to jump to parent topicUsing the PSOL Manager Utility

psolmanager.htm is a file that is delivered with PeopleBooks and installed at the “PSOL” directory level (above the <docroot> folder). This file is password protected. The initial password is set to “password,” but you can customize the password by editing an XML file in the PeopleSoft Online Library site.

Important! You should enable per-session cookies on your browser while using the PSOL Manager, or the password functionality may not work properly, causing a continual prompting for the password.

See Changing the PSOL Manager Password and Specifying a Trusted Client.

To open the PSOL Manager, use your browser to navigate to psolmanager.htm directly under the PSOL folder (for example: http://mydomain/PSOL/psolmanager.htm).

There are four operations that you can perform with this utility. Three of them are for search testing and debugging:

But you will most often perform the Create Collections operation. You will want to rebuild your collections after adding or modifying any searchable content on the PeopleSoft Online Library site.

Note. When installing new PeopleBooks, you are given an option to rebuild search collections during the install. If you select this option, there is no need to use the PSOL Manager to rebuild the collections after installing the new PeopleBook content.

Creating/Recreating Search Collections

After you click the Create Collections link and enter the password, then the following HTML form appears:

You can rebuild the collections for the entire PeopleSoft Online Library website (PSOL Subfolder set to All), or to one or more individual subfolders (docroot directories). Use Ctrl+click to select multiple entries.

Within your subfolders, you can choose which doctypes should be included in the collection build. One default doctype is hardcoded into the form logic: psbooks. If you add new doctype folders, you can edit an XML file so that the new folders also appear in the drop-down list.

See Integrating Searching.

Finally, you can select the language folders that will be parsed in each PSOL subfolder.

When you have made your selections, click the Start button at the bottom of the page. The browser page will update with a status message when the build is complete.

Important! Be sure to have all PeopleSoft Online Library users disconnect or not use full-text searching while you are building collections.

Changing the PSOL Manager Password

The PSOL Manager password is defined in PSOL\WEB-INF\web.xml in the managerpassword parameter. Find this text:

<init-param>
	    <param-name>managerpasswd</param-name>
	    <param-value>password</param-value>
	    <description>
		Password for this servlet. 
		<!-- Note password is clear text. -->
	    </description>
	</init-param>

Change the text inside the <param-value> tags to reflect your new password. Then stop and restart the web server for your change to take effect. You can also set up PeopleSoft Online Library so that a particular client machine is trusted and doesn't need to provide the password.

Specifying a Trusted Client

In the web.xml file, in the <servlet><init-param> section, add this text:

<param-name>trustedclient</param-name>
         <param-value>machine_name</param-value>
         <description>
             <!-- Client that doesn't need password authentication -->
         </description>

where machine_name is the name of the client machine to be trusted. For example, if you plan to access PSOL Manager from the web server machine itself, you could enter “localhost”.

Click to jump to parent topicIntegrating Your Own Documentation into the Library

This section provides an overview of documentation integration and discusses how to integrate:

Click to jump to top of pageClick to jump to parent topicUnderstanding Documentation Integration

Just as you can add new PeopleSoft Enterprise documentation into an existing PeopleSoft Online Library, you can also integrate your own documentation into the site. This may be preexisting internal documentation or new content that you’ve written to supplement PeopleBooks.

We do not encourage you to modify existing PeopleBooks files or to use a copy of an existing PeopleBook to make your changes. Although tempting at first, this approach can lead to substantial overhead for you. Every change that you make to our delivered content may render the table of contents or keyword index obsolete. Updating a PeopleBook table of contents and keyword index is a time-consuming manual task. Also, consider that:

By keeping your documentation in a completely separate directory at the documentation type level, you avoid these issues but can still enable context sensitivity and searching. Also, you don’t have to adhere to the format and layout of PeopleBooks, but can choose any editor and any layout that you prefer.

You can decide if your documentation will be accessible by way of the PeopleSoft Online Library home page and if you want to establish context sensitivity and searching.

Click to jump to top of pageClick to jump to parent topicIntegrating Browsing

To make your documentation browseable in the library:

  1. Create a new documentation type folder below the appropriate language directory in the library site.

    For example: <docroot>/eng/my_psbooks or <docroot>/eng/internal policies.

  2. Add the new documentation type to <docroot>/eng/js/doctypes.js.

    See Managing Documentation Types.

  3. Place the documentation files into the new directory.

  4. Create (or rename) a home page called index.htm at the top directory level of the documentation type.

    This ensures that the automated link to your documentation from the PeopleSoft Online Library home page works. If you already have a home page that you don’t want to rename, you can insert JavaScript into index.htm that automatically redirects users to your home page.

Click to jump to top of pageClick to jump to parent topicIntegrating Context Sensitivity

Any custom documentation in the PeopleSoft Online Library can be used as context-sensitive help for the PeopleSoft Enterprise applications. If you have documented the features and uses of an application that you have modified or built, you can ensure that your users see that documentation when they call help from the application.

Preparing and enabling your documentation for context sensitivity requires more steps than adding a link to your documentation on the PeopleSoft Online Library home page. You must adhere to certain directory structures and file-naming conventions. You might also need to add anchors to your documentation.

Understanding Context Sensitivity

Later we explain how to set up context sensitivity. But before you read that section, you may want to understand what actually happens during a help request. Understanding the reasoning behind the steps involved in enabling online help might aid you in troubleshooting if your context sensitivity doesn't work as expected.

When you request help from your application, 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 stored in the system. Here is an example of the syntax of the string, with variables wrapped in percent signs (%): 

http://docroot/f1search.htm?ContextID=%CONTEXT_ID%&LangCD=%LANG_CD%[&PreContextID=%PRE_CONTEXT_ID%&WideContextID=%WIDE_CONTEXT_ID%]

Note. The two URL arguments within the square braces are used only by JD Edwards EnterpriseOne applications.

We discuss instructions for setting the value of the system help string as part of the discussion about installing PeopleBooks.

See your installation guide.

You can see that the string is a URL pointing to the f1search.htm page, which sits in the <docroot> level of the library site. During the help call, the variables are resolved as follows:

Using the preceding syntax example, if help is called from the PeopleSoft Enterprise PeopleTools Options page by a German user, the resulting URL looks like this (resolved values in bold): 

http://docroot/f1search.htm?ContextID=PSOPTIONS&LangCD=GER

When the help URL is passed to a browser, the f1search.htm page is opened, 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 documentation. The lookup file contents are searched, and when a match is found for the ContextID value, f1search.htm redirects the browser to the related location. If multiple matches are found, a pop-up window displays a list of help topic links from which the user can choose.

Because of the depth of the PeopleSoft Online Library directory structure, the process of loading the lookup files is a bit complex. Following is the JavaScript sequence of events when f1search.htm is opened:

  1. Validate the LangCD value passed to f1search.htm against <docroot>/js/langs.js to see if the preferred language exists in the library.

    If not, substitute ENG (English).

  2. Once the language (<langdir>) is determined, load <langdir>/js/helptypes.js to see which documentation types are enabled as context-sensitive help.

  3. For each path (<typepath>) found in helptypes.js, load <langdir>/<typepath>/js/helplist.js to determine which books within this documentation type are enabled for context sensitivity.

  4. For each book (<bookpath>) found in helplist.js, load <langdir>/<typepath>/<bookpath>/contextids/x.js, where x is the first character of the ContextID value passed.

The following example assumes that you have PeopleSoft Enterprise HRMS PeopleBooks installed and that your documentation is integrated as a separate documentation type:

  1. A user with the language preference English clicks help on the JOB_DATA1 page.

  2. The following URL is passed to f1search.htm:

    http://docroot/f1search.htm?ContextID=JOB_DATA1&LangCD=ENG

  3. The language code of the user’s preferred language is validated against <docroot>/js/langs.js to see if that language exists in the library. 

    <docroot>/js/langs.js:

		languages = new Array(
			"cfr||fc||Fran&ccedil;ais&nbsp;du&nbsp;Canada",
			"eng||en||English"
		);

    See Managing Language Support.

  4. Once the language (<langdir>) is determined, <langdir>/js/helptypes.js is loaded.

    eng/js/helptypes.js:

		helptypes = new Array(
			"psbooks||PeopleBooks",
			"my_documentation_type||My Documentation"
		);

    See Managing Documentation Types.

  5. For each path (<typepath>) found in helptypes.js, <langdir>/<typepath>/js/helplist.js is loaded. 

    eng/psbooks/js/helplist.js:

		helpnames[helpnames.length]="psbooks/hr||PeopleSoft 8.11 Human Resources";

		eng/my_documentation_type/js/helplist.js:
			helpnames[helpnames.length]="my_documentation_type/my_hr_book||Internal Documentation on HR";

    See Managing Individual PeopleBooks.

  6. For each book (<bookpath>) found in helplist.js, <langdir>/<typepath>/<bookpath>/contextids/x.js is loaded, where x is the first character of the ContextID value passed to f1search.htm. 

    eng/psbooks/hrms/contextids/j.js:
		bookmarks[bookmarks.length] = "JOB_DATA1||psbooks/hrms/htm/hrcom001.htm#F1ID_Job_Data1";
		bookmarks[bookmarks.length] = "JOB_DATA2||psbooks/hrms/htm/hrcom001.htm#F1ID_Job_Data2";
...

eng/my_documentation_type/my_hr_book/contextids/j.js:
		bookmarks[bookmarks.length] = "JOB_DATA1||my_documentation_type/my_hr_book/htm/xxxxx.htm#MYF1ID_Job_data1";

  7. Once all lookup files are searched and a match is found for the context ID, the browser is redirected to the location specified in the lookup file.

    If there are multiple matches (as in our example), a pop-up window appears so that the user can decide to which help topic to go.

Pop-up window displaying the available help topics

Preparing Your Documentation

In a help lookup file, a context ID (application page or panel name) can be mapped to a particular location in your documentation. That location can be a file name, or a file and anchor name. Whether you want to specify an anchor name depends on the length of your documentation files. If you document only one application page per HTML file, anchors are probably not necessary. If you document many application pages in an HTML file (as we do in PeopleBooks), you definitely need anchors. Anchors place users as close to their requested information as possible when they call help.

Another good reason for using anchors to denote help documentation locations is that it enables an automated process to build lookup files for you. In the PeopleBooks HTML files, we name every help anchor as F1ID_ followed by the name of the application page that is being documented. For example, at the beginning of the help topic on the PeopleSoft Enterprise PeopleTools options page (PSOPTIONS), the following anchor tag is inserted: <A NAME=“F1ID_PSOPTIONS”></A>. We then run a PERL script that parses our HTML files for F1ID_ anchors and builds the lookup files automatically.

Setting Up the Utility Files

During a help call, there is a strict order in which various JavaScript utility files are found and loaded. It is crucial that all the necessary directories and files exist for the help logic to work properly.

Populating the Lookup Files

A help lookup file contains lines of JavaScript code that assign strings to an array. Each string contains the context ID for a help topic and the relative path to the help topic—separated by two pipes (“||”). The name of the lookup file reflects the first character of all the context IDs stored inside. Here is an example of the syntax of these files: 

bookmarks[bookmarks.length] = "<contextID1>||<path_to_file>#<anchor_name1>";
bookmarks[bookmarks.length] = "<contextID2>||<path_to_file>#<anchor_name2>";
...
bookmarks[bookmarks.length] = "<contextIDN>||<path_to_file>#<anchor_nameN>";

arraycount[arraycount.length] = bookmarks.length - 1;

A context ID corresponds to the name of the application page at which the user clicks help. This context ID is used by f1search.htm to redirect the user to the correct help topic. Therefore, to create a context-sensitive link for a new application page, MY_APPS, you would insert this line into an m.js file: 

bookmarks[bookmarks.length] = "MY_APPS||my_doc_type/my_hr_book/htm/intro_to_hr.htm#my_anchor";

Adhere to these conventions when populating lookup files:

Populating a Chapter List File

Earlier we discussed the xxxxfiles.js file that is found in each PeopleBook folder. This file consists of JavaScript array member assignments. Each line corresponds to a “chapter” file that makes up the PeopleBook. Each line also contains the title of that chapter. This file is used internally for the PeopleBook navigation controls.

See The Book Level.

The chapter list file is also used during the online help call if a context ID is found in more than one lookup file. In this case, the titles of the destination files are pulled from their corresponding chapter list files; they appear in the online help popup window as links.

If there is any possibility that the context IDs in your custom documentation will also be found in PeopleBooks, or found in multiple locations in your own documentation, you must create chapter list files for your documentation. Certain browsers will generate an error if a chapter list file cannot be found for any of the books found to contain a matching help topic.

You can simply copy an xxxxfiles.js file from any PeopleBook folder and modify it to match your files and file titles.

Tips and Tricks

When you document a new application, you would want to edit the helptypes.js file and create a helplist.js, chapter list, and lookup files, as described previously. But if you have documented changes to a delivered application, you have some other choices:

Click to jump to top of pageClick to jump to parent topicIntegrating Searching

When you integrate new content into the PeopleSoft Online Library, you may want to rebuild the PSOL Verity collections so that you can search the new content.

Understanding Searching

Before enabling your documentation to be searchable, you should understand how your documentation type will appear in the search drop-down lists and how Verity finds the field values that help limit a search.

First, the scope of the search forms in the PeopleSoft Online Library is context-sensitive. That is, a different search scope is permitted, depending on how you navigated to the search form. For example, at the PeopleSoft Online Library home page, a search form appears in the lower left frame. If you use this form, all of the documentation types in the entire library (those specified in <docroot>/<langdir>/js/colltypes.js) are searched. However, searching at the PeopleBooks home page searches only within PeopleBooks (<docroot>/<langdir>/psbooks/js/colllist.js). This adjustability of scope is handled by JavaScript, which is inside the forms, that interprets the browser’s URL to find out at what level of the library the user is located.

The Advanced Search page (which you can access by way of either home page) is also context sensitive in this way. However, at the advanced search page, you can change which documentation type that you want to search by selecting from a drop-down list.

Note. A documentation type drop-down list appears in the Advanced Search page only if more than one documentation type is listed in colltypes.js.

You can also filter a search by selecting values from other drop-down lists that appear in the Advanced Search page (for example, Book Title or Product Line):

Drop-down list boxes with searchable PeopleBooks titles and product lines

The drop-down list boxes are populated by dynamically loading the searchfields.js file for each doctype listed in colltypes.js. The searchfields.js file resides in each <doctype>/js folder and is created during the collection build process. Its contents consist of search field names and field values found when parsing the HTML documentation. Here is an example of the searchfields.js contents: 

fieldnames_psbooks = new Array('BKTITLE', 'prodline');

BKTITLE_psbooks_fld = new Array('PeopleTools 8.46 PeopleBook: Verity Query Language Guide V5.0 for PeopleSoft', 'PeopleTools
8.46 PeopleBook: Verity Collection Reference Guide for PeopleSoft', 'PeopleTools 8.46 PeopleBook: Workflow Technology');
prodline_psbooks_fld = new Array('PeopleTools');

The first line in this file defines a fieldnames_<doctype> array that lists the names of the available search fields. The remaining lines define an array for each fieldname listed in the first array. The array members are all the available values for that field. For example, BKTITLE_psbooks_fld contains a list of all the PeopleBooks titles found in colllist.js during the collection build. prodline_psbooks_fld contains the various prodline values found when parsing the HTML content.

You can control the field names and values that appear in this file by adding custom META tags to your HTML documentation. Do not edit searchfields.js manually, as it is overwritten every time you rebuild your collections.

Creating Custom Search Fields

As previously discussed, the fields in searchfields.js are pulled from META tags that appear in the HTML content files that are parsed during a collection build. You can add your own META tags to define custom fields and field values. The META tags must be added in HEAD section of the HTML file. The syntax of the META tags must appear as follows: 

<meta name="filter" content="field_name=field_value">

where field_name is the name of the search field and field_value is the value. For example, if you wanted to create a field for searching by the type of audience for your documentation is intended, you might add one of the following META tags to your HTML files: 

<meta name="filter" content="audience=First Time Users">
OR
<meta name="filter" content="audience=Implementers">
OR
<meta name="filter" content="audience=DBAs">

Note. The collection build process does not currently support multiple values for a single field in an HTML file. For example, if you put all three of the above META tags into one HTML file, only the last would be picked up and used in searchfields.js as the value for the audience field. In future releases, we hope to allow the use of a delimiting character in the content attribute to let you specify multiple field values in one META tag.

Assuming each of the three example META tags was inserted into your custom documentation files, when the collection is rebuilt, the searchfields.js file for your documentation type will contain this code: 

fieldnames_your_doctype = new Array(audience);

audience_your_doctype_fld = new Array('First Time Users',Implementers,'DBAs');

There is no limit to the number of custom fields that you can create, but consider that each of these fields will appear as a drop-down list on the Advanced Search page. Too many fields might make the search form unwieldy to navigate and use.

Note. Certain field names are reserved by Verity and should not be used in your custom META tags. These field names are title, subject, author, from, source, keyword, and keywords. It is wise to create field names with a unique name string as a prefix or suffix (for example: mybooks_author).

When you search across multiple documentation types, the Advanced Search form displays only those search fields that are shared among those documentation types. For example, PeopleBooks are delivered with the BKTITLE (book title) and prodline (product line) fields predefined. If you want to search your custom doc and PeopleBooks simultaneously and to filter those searches by book title and product line, you should add META tags for BKTITLE and prodline to your documentation: 

<meta name="filter" content="BKTITLE=My Custom Book">
<meta name="filter" content="prodline=FSCM">

Creating Custom Search Field Labels

The search field names that you define in the META tags are system names. These names are used internally by the PSOL JavaScript and by Verity. For purposes of translatability, the names that actually appear on the search form are stored in srchlabels.js, a language-specific labels file found in the js directory under each language directory.

See The Language Level.

The JavaScript variables that define the search field labels must have a particular naming structure in order to be found by the search form code. The syntax is: 

strfield_name_fld

where field_name is the name of the field as defined in your META tags. For example, the standard PeopleBook search field, prodline, has a label variable defined in srchlabels.js as: 

 strprodline_fld

Important! The variable names are case-sensitive. The field name included in the variable name must exactly match the capitalization of the field name as defined in the META tags (and searchfields.js).

Setting Up the Utility Files

When the Advanced Search page opens, the colltypes.js file is loaded to find which doctypes are available for searching. To enable your custom documentation type for searching:

  1. Edit <docroot>/<langdir>/js/colltypes.js.

  2. Add a line to make the documentation type searchable.

    Use this syntax:

    "<doctype_dir>||<doctype_name>"[,]

    Do not use a comma after the last array assignment. For example, if you added your own documentation type to colltypes.js, it might look like this (in bold): 

    collections = new Array(
 "psbooks||PeopleBooks",
 "my_documentation_type||My Documentation"
);

See Managing Documentation Types.

If you have created a new doctype directory in PSOL for your documentation, you must also define that doctype directory in the PSOL web.xml file.

Inside the <web-app> tags in that file, add the following text:

<context-param>
            <param-name>doctype.doctype_name</param-name>
            <param-value>reg_expr</param-value>
   </context-param>

where doctype_name is the name of your doctype directory and reg_expr is a regular expression used to find your searchable content below the docroot directory. Save the file and restart the web server.

Note. The following regular expression can be used to find all .htm files (but not .html files) anywhere below your doctype directory: [/\\]doctype_name[/\\].*\.htm$

If you want to be more restrictive on which files are parsed for the collection, adjust the regex accordingly. For example, in PeopleBooks, all searchable HTML content is in an htm directory. So the hardcoded regex for finding PeopleBooks content is [/\\]psbooks[/\\].*[/\\]htm[/\\].*\.htm$

Creating Collections

Once you have added your META tags, added the field labels to srchlabels.js, and updated colltypes.js and web.xml, you are ready to create your collections. Use the PSOL Manager utility.

Click to jump to parent topicConfiguring a Reverse Proxy Server for the PeopleSoft Online Library

A reverse proxy server (RPS) is a web server that acts as a front-end gateway to user requests, usually forwarding transaction requests to a back-end server and hosting the static HTML pages itself. WebLogic and WebSphere both support various popular web servers (Apache, Microsoft IIS, and Sun ONE) as RPS platforms. If you would like to use WebLogic or WebSphere as a back-end server to an RPS, you can configure the RPS to host static PSOL requests and forward PSOL Full-Text Search (servlet) requests to the back-end server. Information on setting up an RPS can be found in the PeopleTools documentation. It is not discussed here. But this section does explain how to configure an installed RPS so that PSOL static HTML is served and servlet requests are forwarded.

Because PeopleSoft Online Library search functionality works only if it's installed into a PeopleSoft Pure Internet Architecture installation, you must create a virtual directory, or alias, on the RPS that points to your PSOL directory.

Click to jump to top of pageClick to jump to parent topicConfiguring a Virtual Directory for the RPS

The following sections explain how to configure a virtual directory for PSOL on the supported RPS platforms: IIS, Apache/IBM Http Server, and Sun ONE Enterprise Server (formerly iPlanet).

IIS

To create a PSOL virtual directory:

  1. Launch the Internet Service Manager.

  2. Select the icon of the applicable website.

  3. From the menu bar, select Action, New, Virtual Directory.

  4. Enter /PSOL/ as the Alias name and click Next.

  5. Enter, or browse to, the full directory path to the PSOL directory and then click Next.

  6. Enable Read Access permissions for this directory, and then click Finish.

  7. Find the PSOL directory in the Internet Service Manger tree structure, right-click it, and select Properties.

  8. Set Execute Permissions to Scripts and Executables.

  9. Add index.htm as a default document for the PeopleBooks root directory.

    1. Select the Documents tab.

    2. Ensure that Enable Default Document is selected and Add 'index.htm' to the list of file names.

  10. Click OK.

Apache/IBM Http Server

To create a PSOL alias:

  1. Edit the APACHE_HOME/conf/httpd.conf file.

  2. Add the following lines of code:

    Alias /PSOL/ "full_path_to_PSOL/"

<Directory "full_ath_to_PSOL">
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

    where full_path_to_PSOL is the file system directory path to the PSOL directory. Use forward slashes and be sure that Alias path ends in a forward slash and that the Directory path does not.

  3. Locate the following line of code:

    DirectoryIndex index.html

    and add a space and then 'index.htm' to the end of the string:

    DirectoryIndex index.html index.htm

  4. Save the httpd.conf file.

Sun ONE Enterprise Server

To create a PSOL virtual directory:

  1. Edit the Sun_ONE_HOME/https-INSTANCE_NAME/config/obj.conf file.

  2. Add this text:

    NameTrans fn=pfx2dir from=/PSOL dir=full_path_to_PSOL

    where full_path_to_PSOL is the file system directory path to your PeopleTools installation. Use forward slashes only.

  3. Save obj.conf.

Click to jump to top of pageClick to jump to parent topicConfiguring the RPS URL Forwarding for WebLogic

WebLogic supports Microsoft IIS, Apache, and Sun iPlanet as RPS platforms. You must specify which URL patterns the RPS will forward on to WebLogic.

Important! All of the following instructions assume that you have already installed and configured an RPS according to the instructions in your PeopleTools documentation.

IIS

WebLogic's IIS plug-in uses an INI file, iisproxy.ini, to map server requests from IIS back to WebLogic. In this file, add this line: WlForwardPath=/PSOL/servlet. If there is already path a WlForwardPath specified, add /PSOL/servlet to the end of the string, preceding it with a comma: WlForwardPath=/ps/,/PSOL/servlet.

Note. If the existing WlForwardPath contains a single slash (/), all requests will be forwarded to WebLogic, making the /PSOL/servlet path meaningless. If your WlForward path is configured this way but you don't want WebLogic to host your PSOL static HTML requests, work with your website administrator to find a more restrictive set of paths that will forward only PeopleSoft Enterprise servlet requests (and /PSOL/servlet) back to WebLogic.

Apache

For Apache, you must modify the http.conf file to specify the URLs to be forwarded to WebLogic. Add this text to the file:

<Location /PSOL/servlet>
       SetHandler weblogic-handler
</Location>

Note. If there is an existing Location directive that uses a single slash (/), all requests will be forwarded to WebLogic, making the /PSOL/servlet Location directive meaningless. If this is the case but you don't want WebLogic to host your PSOL static HTML requests, work with your website administrator to find a more restrictive set of Location directives that will forward only PeopleSoft Enterpriseservlet requests (and /PSOL/servlet) back to WebLogic.

Sun ONE

Edit the obj.conf file and add this text:

<Object name="PSOL_forwarding" 
ppath="*/PSOL/servlet/*">
Service fn=wl_proxy 
WebLogicHost=psol_host 
WebLogicPort=psol_port 
</Object>

where psol_host is the host name portion of the PSOL url and psol_port is the port number.

Note. If there is an existing Object directive that has a ppath attribute with a single slash (/), all requests will be forwarded to WebLogic, making the */PSOL/servlet/* ppath meaningless. If this is the case but you don't want WebLogic to host your PSOL static HTML requests, work with your website administrator to find a more restrictive set of Object directives that will forward only PeopleSoft Enterprise servlet requests (and /PSOL/servlet) back to WebLogic.

Click to jump to top of pageClick to jump to parent topicConfiguring the RPS URL Forwarding for WebSphere

WebSphere has an automated method of configuring the RPS plug-ins that were installed during the web server installation. One configuration file, plugin-cfg.xml, handles the URL forwarding, no matter which RPS is being used.

The easiest way to configure an RPS for Web Sphere is to disable file serving for all servers (PSOL and PIA, if applicable). When file serving is disabled, the plugin-cfg.xml file is automatically written so that only the associated servlet paths are forwarded to Web Sphere. All other URL paths (non-transaction) are then handled by the RPS.

However, your website administrator may not agree to globally disabling file serving for the PIA server. In this case, you must work with the administrator to configure the plugin-cfg.xml file so that not all URL requests are forwarded to Web Sphere (the default behavior when file serving is enabled for PIA), but only specific URLs (static and transaction related), including /PSOL/servlet/.

To disable file serving for the PSOL server:

  1. Edit the PS_HOME\webserv\node_name\peoplesoft.ear\PSOL\WEB-INF\ibm-web-ext.xmi file.

  2. Find the fileServingEnabled attribute and set it to “false.”

  3. Save the file and restart all web servers.

To disable file serving for the PIA server (server1):

  1. Edit the PS_HOME\webserv\node_name\peoplesoft.ear\PORTAL\WEB-INF\ibm-web-ext.xmi file.

  2. Find the fileServingEnabled attribute and set it to “false.”

  3. Save the file and restart all web servers.

To configure the plugin-cfg.xml file:

  1. Make a copy of the WEBSPHERE_HOME\AppServer\config\cells\plugin-cfg.xml file, as a back up of the original.

  2. Edit theWEBSPHERE_HOME\AppServer\config\cells\plugin-cfg.xml file.

  3. Locate the Uri element named “/*”.

    This element is created in the config file when file serving is enabled in the PORTAL web module. The complete tag will look like this: 

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/*"/>

  4. Change the Name value to a more specific URL string that will pick up requests only for the PORTAL module files and servlets.

    For example, use “/ps/*”.

  5. Add other Uri elements as necessary to pick up any additional URL patterns for PORTAL files.

    For example:

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/sqr_images/*"/>

  6. Save the file, and then save the file again under a different name as a backup of your changes.

Note. Do not edit the plugin-cfg.xml file without first consulting with your website administrator.