PeopleBooks and the PeopleSoft Online Library

Managing the PeopleSoft Online Library and PeopleBooks

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

Manage the PeopleSoft Online Library.
Manage full-text searching.

Understanding the PeopleSoft Online Library

This section discusses the:

PeopleSoft Online Library website.
Global level.
Language level.
Documentation type level.
Book level.

The PeopleSoft Online Library Website

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

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.

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

The htm directory contains common HTML files used in the PeopleSoft Online Library interface.
The img directory contains graphic files.
The styles directory contains cascading style sheet files.
The js directory contains JavaScript files.

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.

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

The styles directory contains cascading style sheet files.
The js directory contains JavaScript files.

Information about the next organizational level below the global level (documentation type level) is stored in three separate JavaScript files.

See Managing Documentation Types.

The files are:
- <docroot>/eng/js/colltypes.js, which specifies which documentation types can be full-text searched.
- <docroot>/eng/js/doctypes.js, which specifies which documentation types appear on the PeopleSoft Online Library home page.
- <docroot>/eng/js/helptypes.js, which specifies which documentation types support online help.
Also in the language level js directory are several *labels.js files that contain translatable text variables used throughout the PeopleSoft Online Library site.

The 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 PeopleSoft 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:

The img directory contains graphics files.
The styles directory contains cascading style sheet files and information about the PeopleBook hierarchy.

The hierarchy, and suite/categories for the books are controlled by two files:
- TopTOCStyle.xml, which specifies the hierarchy or groupings that the books should be displayed on the PeopleBooks library page.
- content.css contains the related stylesheet information.
The js directory contains JavaScript files.

Information in the next organizational level (book level) is stored in three JavaScript utility files:
- <docroot>/eng/psbooks/js/booklist.js, which specifies which books in a documentation type appear on the documentation type home page.
- <docroot>/eng/psbooks/js/helplist.js, which specifies which books in a documentation type are to be used for context sensitive help.
- <docroot>/eng/psbooks/js/colllist.js, which specifies which books in a documentation type can be full-text searched.
The coll directory contains search collections that can be used by engines such as Verity for searching the website.

This directory is created or recreated when you install PeopleBooks or use the PSOL Manager utility.

See Managing Full-Text Searching.

The 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 content of the book. Idxdata.htm and tocdata.htm contain the index and table of contents of the book. The JavaScript file (xxxxfiles.js) contains an array that lists the order of the individual HTML files that make up the content of the book. 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:

The htm directory contains the individual HTML files that make up the content of the book.
The img directory contains graphics referenced by the HTML files.
The pdf directory contains Adobe Acrobat files containing other book content.

Utility Directories

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

See Managing Full-Text Searching.

Managing the PeopleSoft Online Library

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

Install new PeopleSoft Enterprise documentation.
Manage language support.
Manage documentation types.
Manage individual PeopleBooks.

Understanding PeopleSoft Online Library Management

When additional documentation is made available, you may want to merge that documentation with your existing PeopleSoft Online Library (PSOL) 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 Manager 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 users can browse (by way of a home page table of contents), perform a full-text searchable, or used for online help.

Installing New PeopleSoft Enterprise Documentation

Before installing new or additional 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 to the same location. Newer files overwrite the older files of the same name.

See your installation guide.

Managing 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",
 "dut||nd||Nederlands",
 "eng||en||English",
 "esp||es||Espa&ntilde;ol",
 "fra||fr||Fran&ccedil;ais",
 "ger||de||Deutsch",
 "ita||it||Italiano",
 "por||ps||Portugu&ecirc;s",
 "zhs||zh||Simplified Chinese"
 );

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 in the PeopleSoft Online Library:

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",
 
);

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",
 
);

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",
 
);

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. Special JavaScript code is available on the home pages (home_nav.htm) to deal with these exceptions.

Managing 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

To enable browsing as a documentation type, 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, two values are separated by double pipes (“||”): the directory name and the display name of the documentation type.

doctypes = new Array(
 "psbooks||PeopleBooks",
 "hrms_9.1_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.

To disable (hide) a documentation type, precede it with a double slash (//).
To add a type, add a new line to the array declaration (before the closing parenthesis).

Remember that the last element in the array must not be followed by a comma.

Context Sensitivity

At this level of the PeopleSoft Online Library hierarchy, you not only control which documentation types are browsable, 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.

Managing Individual PeopleBooks

You can remove book titles from the PeopleBooks library table of contents, disable them as online help, or remove the books from the search collections by editing three JavaScript files. The files that control these functions are:

<docroot>/eng/psbooks/js/booklist.js — controls the display of book titles on the table of contents, so that users can browse through the list of available PeopleBooks.
<docroot>/lang/psbooks/styles/TopTOCStyle.xml — controls the display of the book hierarchy or book suites on the PeopleBooks library.
helplist.js — controls context sensitivity, allowing users to access the books through online help in the application.
colllist.js — controls the availability users to search a book when using the advanced search options.

Browsing

The ability to browse through a list of available books is controlled by two primary means. The booklist.js controls the display of books on the table of contents, and the TopTOCStyle file controls how they display.

The syntax of the booklist.js doesn't contain an explicit array declaration, only array element assignments. Here is some sample JavaScript code from booklist.js:

booknames[booknames.length]="psbooks/tpsq||Enterprise PeopleTools 8.50 PeopleBook:⇒
 PeopleSoft Query";
booknames[booknames.length]="psbooks/tsum||Enterprise PeopleTools 8.50 PeopleBook:⇒
 PeopleSoft Setup Manager";
 
function getTitle(strProdCode, strDocType) {
 strProdCode = strProdCode.toLowerCase(); ...

The lines preceding the function getTitle declaration are the array assignment lines that define the PeopleBook titles that users are able to browse in the library.

To remove a title from the PeopleBooks library home page, comment it out by preceding that line with a double slash (//). To add a book however, you must also add it to the TopTOCStyle.xml file which controls the category hierarchy of book titles on the home page. If you simply add a book title to the booklist.js, helplist.js and colllist.js JavaScript files it will appear at the bottom underneath the categorized book hierarchy list.

The display of the book hierarchy and grouping/categories on the PeopleBooks library page is controlled by the TopTOCStyle.xml file in conjunction with the stylesheet in the content.css file. Both TopTOCStyle.xml and content.css files are located in the lang/psbooks/styles directory.

The syntax of the TopTOCStyle.xml file consists of two elements:

Element Type	Attributes
Heading element	Contains book elements and text data for category title. The following attributes are available: class: Specify CSS class that is defined in content.css style: CSS style can be specified here without using class defined in CSS file
Book element	The following attributes are allowed: bookcode (required): Specify book code to be listed. prefix (optional): This value is added in front of the book title. class: Specify CSS class that is defined in content.css style: CSS style can be specified here without using a class defined in content.css file. sortas: This value is used for sort to list book titles if it exists. This is required for Japanese books.

Element Type

Attributes

Heading element

Contains book elements and text data for category title. The following attributes are available:

class: Specify CSS class that is defined in content.css
style: CSS style can be specified here without using class defined in CSS file

Book element

The following attributes are allowed:

bookcode (required): Specify book code to be listed.
prefix (optional): This value is added in front of the book title.
class: Specify CSS class that is defined in content.css
style: CSS style can be specified here without using a class defined in content.css file.
sortas: This value is used for sort to list book titles if it exists. This is required for Japanese books.

The following example of TopTOCStyle.xml illustrates PeopleBooks hierarchy and categories for Financials.

Context Sensitivity

You can disable a title from 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/famp||PeopleSoft Enterprise Asset Management⇒
 9.1 PeopleBook";
helpnames[helpnames.length]="psbooks/fsbk||PeopleSoft Enterprise Banks Setup and⇒
 Processing 9.1 PeopleBook";
helpnames[helpnames.length]="psbooks/sbil||PeopleSoft Enterprise Billing 9.1⇒
 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 (shown in bold) must be defined in each string:

colllist[colllist.length]="psbooks/ccrm||PeopleSoft Enterprise CRM 9.1 Application⇒
 Fundamentals PeopleBook||eng/psbooks/ccrm/coll||";
colllist[colllist.length]="psbooks/cbom||PeopleSoft Enterprise CRM 9.1 Business⇒
 Object Management PeopleBook||eng/psbooks/cbom/coll||";
colllist[colllist.length]="psbooks/ccal||PeopleSoft Enterprise CRM 9.1 Call Center⇒
 Applications PeopleBook||eng/psbooks/ccal/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. Now, only one collection is 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.

Managing Full-Text Searching

This section provides an overview of the PeopleSoft Online Library full-text search capabilities and an overview of the PSOL Manager Utility.

See Integrating Searching.

Understanding PeopleSoft Online Library Full-Text Searching

You can rebuild the Verity search collections used for full-text searching. You can add your own documentation to the PeopleSoft Online Library and make it, as well as PeopleBooks, searchable. Full-text search capabilities include:

The system builds only one collection per documentation type, which eliminates the possibility of reaching the Verity upper limit of 128 collections when searching.
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.

Enabling PSOL Manager Utility

The PSOL Manager Utility is delivered with PeopleBooks when you install it. Instructions for enabling and using the utility, creating search collections, changing the PSOL Manager password, and specifying trusted clients are included in your PeopleTools install instructions.

If you create new documentation, or customize existing documentation, then you should recreate the search collection, so that users can search the desired set of books.

See Enterprise PeopleTools 8.50 Installation for <your database platform>, Appendix: Installing PeopleBooks, Administering PeopleBooks.