Localizing and Customizing FileNet P8 Help

This document describes the FileNet P8 documentation translation kit. This kit contains information which you may find useful in translating or customizing portions of the FileNet P8 help. It assumes you have received a FileNet P8 2.0.1 Documentation CD as part of your product distribution.

Below you will find a brief overview of how the FileNet Documentation Department creates those portions of the FileNet P8 help that may be localized for non-English environments or customized by those wanting product help that is geared to their specialized user requirements, interfaces, or environments.

If you have questions about this kit, or if you need information about those portions of the FileNet P8 help that are not covered in this kit, please send email to the FileNet Documentation Department at docs@filenet.com.

Prerequisites

One or more of the following tools will be required, if you use the editing and production methods outlined in this document. Given that most of the FileNet P8 help is produced in HTML, you have the option to merely modify those files directly with your prefered editor.

·         Dreamweaver 4.0 or higher. See www.macromedia.com/software/dreamweaver

Dreamweaver is the HTML editing application used by most FileNet writers producing the user and administrative help.

·         Deva Tools 1.1 or higher. See www.devahelp.com

Deva Tools is an add-on tool for Dreamweaver that most FileNet P8 writers use to generate book indexes.  Deva Tools does not support double-byte languages. You can manually edit the book index files without employing Deva Tools.

·         Perl. You can retrieve a complete Perl distribution from www.activestate.com/Products/ActivePerl/

The FileNet Documentation team uses a Perl script to remove the table of contents (TOC) entries from the HTML help pages prior to indexing those pages for the Search engine.  Removing TOC entries eliminates the chance of "false" hits on those entries when users search the help.  Such removal can be done by hand without Perl but is time-consuming and error prone, and is not recommended by the FileNet Documentation Department.

·         GNU Find utility for Windows. You can retrieve GNU Find from http://unxutils.sourceforge.net/

The FileNet Documentation team uses GNU Find to identify the HTML help files and run the Perl script that removes the TOC entries to enhance search indexing, as noted above.

NOTE  If the Windows find utility is installed on your PC, you may want to rename the GNU find utility to gnufind.exe to prevent any conflicts between the two utilities.

·         JDK 1.3.1 or higher.

 The JDK is required if you intend to update the Search indexes, which will be the case for all localized and customized help that uses the embedded Search feature in the FileNet P8 help.

Overview of Steps

These are the general steps to customize the existing P8 Help. Details are provided in associated subtopics that follow.

NOTE  If you plan to edit the HTML files directly using Notepad or your favorite HTML editor rather than Dreamweaver, you can do steps 1 and 2, and then skip to steps 5 - 10, which are relevant to any localization or customization effort.

1.       Install the existing FileNet P8 help on the documentation server.

2.       Copy files from the documentation CD to your working PC.

3.       Create Dreamweaver projects.

4.       Add custom application help directories.

5.       Edit files. Add new files as needed. Add index entry keywords to new files.

6.       Edit tables of contents (TOCs).

7.       Update the book indexes.

8.       Update the Search index.

9.       Deploy your customized help.

Install the Existing FileNet P8 Help on the Documentation Server

Install the FileNet P8 documentation as a web site on a Java-friendly application server, according to the FileNet P8 Installation Guide instructions. You will later add your customized files to this documentation web site.

NOTE  Because of the way web sites are deployed, it is easier to copy your new files into the existing web site than to create a web site from scratch.

Copy Files from the Documentation CD to Your Working PC

As noted later in the "Create Dreamweaver Projects" topic, you will need to break the help into defined help projects, each of which requires a distinct set of directories and files. For that reason, you must copy the directories and files in a particular way to your working PC, as follows:

1.       For Workplace help:  Copy the \ecm_help\ae_help\workplace directory and its subdirectories to a top-level location. This will be used as a separate Dreamweaver site for FileNet P8 Workplace help.

2.       For adminstrative help:  Copy all the FileNet P8 help source files from these directories on the documentation CD to your working PC for customization. Be sure to include any subdirectories.

ecm_help

admin

ae_help    (Do NOT include the \workplace directory or its subdirectories)

appint_help

ce_help

css

directory

glossary

images

Library

pa_help

pe_help

po_help

search

Templates

Wcm_help

NOTE  We do not expect you will be localizing or customizing the following ecm_help subdirectories, and therefore have included no special instructions in this document for them:

developer_help              (help for the various FileNet P8 APIs)

installation                     (FileNet P8 Installation Guide)

tranksit                         (directions for customizing or localizing help)

verity                             (documentation provided to FileNet by Verity Corp.)

WEB-INF                   (files required for deploying the help on a web server)

Create Dreamweaver Projects

Depending on the areas of the FileNet P8 help you intend to localize or customize, you will need to create up to two separate Dreamweaver projects (sites), as follows:

FileNet P8 Workplace site – We expect most localization and customization to occur here, in the general user help. For that reason, the FileNet Documentation team developed this site as a stand-alone subset of the overall help for your convenience.

FileNet P8 general (ecm_help) site – This site would include all non-Workplace user and administrative help.

NOTE  The FileNet P8 Installation Guide and Developer Help are NOT included in this site . Both were produced using other tools and methods not discussed in this document.

To create the workplace site

1.       Start Dreamweaver.

2.       Select Site > New Site.

3.       Name the site workplace.

4.       Set the local root folder to the top-level \workplace directory.

5.       Do not enter an HTTP address.

6.       Turn on Enable Cache.

7.       Click OK.

To create the main (administrative) ecm_help site

1.       Start Dreamweaver.

2.       Select Site > New Site.

3.       Name the site ecm_help.

4.       Set the local root folder to the \ecm_help directory.

5.       Do not enter an HTTP address.

6.       Turn on Enable Cache.

7.       Click OK.

NOTE  Dreamweaver creates a _notes directory in each subdirectory of your site. You do not need to copy these directories to your web server when you deploy your finished Help. These directories are only used by Dreamweaver for synchronization, and are not needed to view or access a live Help system.

NOTE  If you will be using Deva Tools to update the book index for a section of the administrative help, you may decide to create additional sites for subdirectories to work with the book indexes. If so, copy the subdirectories to a new location and create a new Dreamweaver site for the new directory before generating the updated index. For example, if you need to update the index for the Security Guide, it may be easier to copy the \ecm_help\admin\security folder to a new location and create a new Dreamweaver site just for this folder. For more information, see the “Update the Book Indexes” topic below.

Add Custom Application Help Directories into FileNet P8 Help

To add custom help topics to the main FileNet P8 help directory strucure, simply create new files and folders as needed, and edit the various tables of contents (TOCs) and book indexes. For best results, use the Dreamweaver Site Files window to move files from one directory to another when needed. Dreamweaver will update links for you when you move files using the Site Files window.

For example, you can easily add new topics to the Workplace help. For topics that are not context-sensitive, create the new files and folders, and then edit the topic TOCs and the book index (wp_index.htm). Context-sensitive help topics must be named correctly in order for the context-sensitive links to work.

NOTE  Refer to the Web Application Toolkit developer’s help for information on creating context-sensitive help for your custom application's JSP pages. See “Using Context-Sensitve Help Features” located in ecm_help\developer_help\web_app_toolkit\guide\customHelp_ov.htm for details.

Edit Help Files

Use Dreamweaver (or any text editor) to edit the new or existing Help files. The Help files use a combination of Dreamweaver templates and library items to create a consistent look across the entire Help system. The library items are used for boilerplate text, the TOC list in each topic, and the body of the book indexes.

While you can detach the Help files from their templates or library items, we do not recommend this. Edit the library items or templates, and then use the Dreamweaver commands to apply the changes to all affected files.

If you will be using Deva Tools to update the book indexes, be sure to add any new book index entires (keywords) to the <head></head> section of each file. You must work directly in the source view of Dreamweaver to edit the header section. Keyword entries use this format:

<meta name=”keywords” content=”term 1;term 2;term 3:subterm 3;”>

where term 1, term 2, term 3, and subterm 3 are words that you want to include in the index. The terms can be listed in any order.

Separate terms with a semicolon (;).

Separate nested entries with a colon (:)

The example above will look like this after you generate the index:

term 1
term 2
term 3
            subterm 3

Apple
Banana bread
Orange
            Navel

You will use Deva Tools to update and edit the index later.

Edit Tables of Contents (TOCs)

You can either update the Dreamweaver library items or manually create new entries. Each HTML page has a static TOC in the left column. The TOC entries are created as library items to save time when updating a section of the TOC. If you change your TOC structure, you need to update the TOC entries.

To update TOC entries in Dreamweaver

1.       Open a file containing a TOC that must be changed in Dreamweaver.

2.       Click anywhere in the TOC to select the library item.

3.       If the Properties window is not displayed, select it from the Windows menu.

4.       In the properties window, click Open to edit the library item. Make your changes to the TOC library item. Make sure to apply the correct style to the text and the <a></a> tag. Refer to the existing TOC for examples. Some of the existing TOC entries use tables and some use <ul></ul>.

5.       Save your changes. You will be prompted to apply the changes to all affected documents. Click Yes.

6.       Close the library item window.

7.       Save any changes to the file you opened in Step 1.

To update TOC entries in an HTML editor

1.       Open a file containing a TOC that must be changed.

2.       Edit the text of the TOC, duplicating the styles and format of existing entries. You will need to change the TOC on every page where it appears.

Update the Book Indexes

The indexes in the FileNet P8 help are generally specific to each general component. For example, you would update workplace\wp_index.htm to add new topics to the Workplace index.

NOTE  The indexing process will change the date-stamp on all your source files, even though your content is untouched. We recommend creating a duplicate folder and Dreamweaver site for indexing to preserve the time-stamp on your html files. For example, \workplaceindex.

To update the book indexes using Dreamweaver and Deva Tools

1.       Install Deva Tools according to the instructions.

2.       Start Dreamweaver. Select the site for which you want to create an index. You can either specify a separate site for each subdirectory that has its own *_index.htm file, or you must select from the Site window the specific files or folders you want included in the site.

3.       Select Deva > Generate Index. If Generate Index is grayed out, then select New Project first.

4.       In the Generate Index dialog box, select either Entire Site or Selected Files in Site Window for the Generate from field.

5.       Select the Replace and Keywords options.

6.       Click OK.

7.       Click OK in the confirmation message box.

8.       After a brief delay, the Edit Deva TOC/Index window opens. If the Index list is not displayed, click the Index tab.

9.       Review your index entries. If you need to make corrections, edit the keywords in the files and regenerate the index.

CAUTION  If you edit the index entries using this window, the changes are NOT carried back to the source files and will be lost the next time you regenerate the index.

10.   Close the Edit Deva TOC/Index window.

11.   From Dreamweaver, select Deva > Create Output.

12.   In the Category column, select Library Item.

13.   Turn on (check) Save Index as Library Item.

14.   Type a name for the library item. Do not include an extension. For example, wp_index for the workplace index.

15.   Click OK.

16.   Click OK in the finished message box.

17.   Open the index file for the section you are working on. For example, open wp_index.htm to update the workplace index.

18.   Click anywhere inside the index library item.

19.   Select Modify > Library > Update Current Page.

20.   Save your changes.

21.   Optional. If you  used a duplicate Dreamweaver site and folder to create the index, copy both the index library item and the updated index file to your main help location. For example, copy \workplaceindex\Library\wp_index.lbi and \workplaceindex\wp_index.htm to your working help location.

To update the book indexes using an HTML editor (rather than Deva Tools)

1.       Open the appropriate index file. For example, \workplace\wp_index.htm.

2.       Add your index entries. Be sure to duplicate the styles and formatting used for existing entries.

CAUTION  If you edit the index entries in this way, the changes are NOT carried back to the source files. Therefore, they will be lost if you ever decide to use Deva tools later to regenerate the index, as described in the previous procedure.

Update the Search Index

Follow the steps below to create a Lucene index.

NOTE  Always work on a copy of your source files because the search indexing process removes hypertext links from the files.

1. Copy the files to be indexed for searching

When you are ready to index the contents of the Help files, make a copy of your complete set of help files, including the workplace files and all your new files. Make sure that you place the \workplace directory inside \ecm_help\ae_help.

2. Strip links to other topics

In order to make search results more precise, hypertext links within the help topics need to be replaced with asterisks (for example, <a href="my_topic.htm">My Topic</a> is replaced with **********). By doing this, the indexer does not index TOC entries and other links that would result in unwanted search hits.

1.       Copy the ecm_help directory to a temporary location. For example, \temp\ecm_help.

2.       Open a Command Prompt Window.

3.       Change to the \temp\ecm_help directory (for example, cd c:\temp\ecm_help).

4.    Run the following command:
gnufind . -name *.htm* -exec perl -0pi.bak -e "s(<a[^>]+href=.+?</a>)(**********)gims;" {} ;

NOTE  Enter this command all on one line. The command will take 20 minutes or longer to complete.

3. Set Up the Lucene indexer's script file

The indexFiles.bat file is a script that launches the Java-based indexer (indexFiles.sh for UNIX-based systems). You may have to modify the script depending on the location of your JRE and your indexing needs. The script is located in this directory: <root_directory>\search. You can modify the script with a text editor.

By default, the indexing options are set to index all of the content directories starting from the root directory (ecm_help by default), and to write the index to this directory: <root_directory>/search/index/core.

Note, however, that you have the option to use more than one index directory. Using more than one index directory is, in effect, the same as spreading out a single index across multiple index directories. When you execute a query, the search engine searches across all of the multiple index directories.

Use mulitple index directories when a single index directory is inconvenient for your needs. For example, if you were to add new content directories to your documentation server at a later time, you could index the new content to a separate index directory, rather than reindex the old content with the new to the single existing index directory. Another potential scenario is localization, where part of your content may be English and part may be non-English. In this case, you would index the English and non-English content to separate index directories.

To use multiple index directories, you must do the following:

4. Run Lucene indexer

1.       From the command line, change the directory to the location of ..\search\indexFiles.bat or ../search/indexFiles.sh. For example:

cd c:\temp\ecm_help\search

2.       Open the indexFiles script file and set the location of your JRE. You can also set your indexing options, such as the configuration files for excluding directories or files. Command line syntax is described in indexFiles.

3.       Run the script file.

5. Copy the search index files

1.       In your main \ecm_help directory (not the temporary directory), delete the contents of \ecm_help\search\index.

2.       Copy the \temp\ecm_help\search\index directory to your main ecm_help directory (the source for your deployment).

Deploy Your Customized Help

1.       On the documentation web server, undeploy the ecm_help web application.

2.       Delete the contents of \ecm_help\search\index.

3.       Copy the updated files from your final \ecm_help directory to \ecm_help directory of the deployed ecm_help web application on the web server. This should include the updated search indexes. You do not need to copy any \_notes subdirectories.

4.       For WebSphere servers, delete the temp \ecm_help folder under your WebSphere install directory:

WebSphere/AppServer/temp/Server_node/Default_Server/ecm_help

5.       Redeploy the ecm_help web application.