Enterprise Content Integration Services …..... 93 Makinganewtemplateavailable ..... 94...

Enterprise Content IntegrationServices Administration Guide

Version 5.3 SP2January 2006

Contains software developed by the Apache Software Foundation . Distribution subject to the Apache Software License. Contains the HTTPClient Library, © 1996-1998, Ronald Tschalaer. Distribution subject to the GNU Library General Public License. Contains the Cryptix library,Copyright © 1995-2001 The Cryptix Foundation Limited. All rights reserved. Distribution subject to the Cryptix General License. Contains theMM.MySQL driver. Copyright (c) 1998-1999 Mark Matthews. Distribution subject to the GNU Library General Public License. Contains thePager-Taglib, Copyright © 2002 James Klicman <[email protected]>. Distribution subject to the GNU Library General Public License. PortionsCopyright © 2000 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et enAutomatique, Keio University). All Rights Reserved.Copyright © 1994-2006 EMC Corporation. All rights reserved.

Table of Contents

Preface ........................................................................................................................... 9

Chapter 1 Accessing Admin Center ....................................................................... 11Connecting to Admin Center....................................................................... 11Logging on................................................................................................. 11Admin Center home page ........................................................................... 12Logging out ............................................................................................... 13

Chapter 2 Information Source Conguration and Organization ............................. 15Managing domains ..................................................................................... 15Creating domains ................................................................................... 16Selecting existing domains ...................................................................... 16Editing domains ..................................................................................... 16Deleting domains ................................................................................... 17

Managing information sources .................................................................... 17Creating information sources .................................................................. 17Selecting existing information sources...................................................... 18Editing information sources .................................................................... 18Deleting information sources................................................................... 19

Chapter 3 Information Source Status .................................................................... 21Monitoring information sources .................................................................. 21Monitoring results of information sources ................................................ 21Information sources ................................................................................ 22

Setting preferences ..................................................................................... 22Scheduling ............................................................................................. 22Notifying ............................................................................................... 23Setting priorities (Information Sources) .................................................... 23

Chapter 4 Servers Conguration ........................................................................... 25Integration Server ....................................................................................... 25Server configuration ............................................................................... 25Proxy settings..................................................................................... 26Proxy Authentication settings.............................................................. 26Alert Service settings .......................................................................... 27Adapters settings................................................................................ 27Web front-end settings ........................................................................ 28RMI settings ....................................................................................... 29Scheduled Queries settings.................................................................. 31Security settings ................................................................................. 32Directory Service settings .................................................................... 32Database and Account settings ............................................................ 34SSL CA Certificate settings .................................................................. 38Diagnose settings ............................................................................... 38Server UI settings ............................................................................... 39

Enterprise Content Integration Services Administration Guide 3

Table of Contents

Internal settings.................................................................................. 40Client configuration ................................................................................ 41Results settings................................................................................... 41Localization settings ........................................................................... 42Email alert settings ............................................................................. 42Multilingual search settings ................................................................ 44Web Assistant settings ........................................................................ 44Setting linguistic server properties ................................................... 45Setting client configuration.............................................................. 45Customizing Web Assistant result window ...................................... 46

Clustering settings.............................................................................. 47Security settings ................................................................................. 48Personalized Relevance Ranking settings ............................................. 48Query Service settings ........................................................................ 49Query Service Location settings ........................................................... 49Query Service Proposal settings........................................................... 50Query Service Language Resource settings........................................... 50Query Service Resource settings .......................................................... 51

Multilingual configuration ...................................................................... 51Attribute configuration ........................................................................... 52Attribute description .......................................................................... 52Attribute translation ........................................................................... 53

Web Server................................................................................................. 53Web Server configuration ........................................................................ 53Configuration of the Web Server with the Integration Server ..................... 54Proxy Settings .................................................................................... 55Proxy Authentication Settings ............................................................. 55RMI Settings ...................................................................................... 56Default Account ................................................................................. 56Domains Settings................................................................................ 56Domains Icon Settings ........................................................................ 57Results Settings .................................................................................. 57Export Settings ................................................................................... 58Diagnose Settings ............................................................................... 59

Customizing ECI Services look and feel ....................................................... 59

Chapter 5 Logs Reporting ...................................................................................... 63Integration Server ....................................................................................... 63Web Server................................................................................................. 65Admin Center Server .................................................................................. 66

Chapter 6 Accounts Management .......................................................................... 67Monitoring accounts ................................................................................... 67ID.............................................................................................................. 67Name......................................................................................................... 68LDAP ........................................................................................................ 68Queries ...................................................................................................... 68Locked reasons........................................................................................... 68Creating accounts ....................................................................................... 68Changing passwords .................................................................................. 69Deleting account......................................................................................... 69

Chapter 7 Servers Operation ................................................................................. 71

4 Enterprise Content Integration Services Administration Guide

Table of Contents

Managing the ECI Server ............................................................................ 71

Chapter 8 Uploading .............................................................................................. 73Uploading information sources ................................................................... 73Uploading libraries..................................................................................... 73Uploading images ...................................................................................... 74

Appendix A Installing and Conguring Netegrity SiteMinder 6.0 .............................. 75ECI Services and Netegrity SiteMinder integration ....................................... 75Netegrity SiteMinder Plug-In configuration.................................................. 76Installing Web Front-End ........................................................................ 76Installing and configuring ECI Services .................................................... 76Configuring the ECI SiteMinder Plug-In................................................... 79Configuring the ECI client................................................................... 79Configuring the ECI server.................................................................. 80

Troubleshooting Netegrity SiteMinder ......................................................... 81

Appendix B Conguring and Customizing Admin Center ......................................... 83Configuration............................................................................................. 83web.xml ................................................................................................. 83Login and password ........................................................................... 83Upload feature ................................................................................... 84Size of the uploaded file ..................................................................... 84Maximum size of the visible part of log files ......................................... 84Command to launch servers ................................................................ 85

admin.xml ............................................................................................. 85Configuration files .............................................................................. 85Log files ............................................................................................. 86Uploaded files .................................................................................... 86

Customization............................................................................................ 87Customization without editing JSP pages ................................................. 87Customization editing JSP pages ............................................................. 87

Appendix C Report Generator ................................................................................... 89Using RTL to create a Report Template ........................................................ 89Main characteristics of RTL ..................................................................... 90Source and target files......................................................................... 90

Template structure.................................................................................. 90Header and Footer description ................................................................ 91Results description ................................................................................. 91List of results...................................................................................... 91Displaying an attribute by using its name............................................. 91Displaying a message only if a predefined attribute has a value ............. 92Displaying an attribute without using its name..................................... 92

Grammar ............................................................................................... 93Making a new template available................................................................. 94Testing a Report Template ........................................................................... 95Using the Report Generator......................................................................... 96

Appendix D Conguring External Databases ............................................................ 99JDBC database properties............................................................................ 99MySQL ................................................................................................ 100Oracle .................................................................................................. 100SQLServer............................................................................................ 101


Table of Contents

Downloading the driver for SQLServer .............................................. 102Initialize accounts tables ........................................................................... 102Manage accounts with JDBC database........................................................ 103Migrate account from one database to another............................................ 103

Appendix E Load Balancing (Optional) ................................................................... 105A typical load-balanced system on a Windows platform ............................. 113Advanced load-balancing configuration ..................................................... 113Troubleshooting load-balanced systems ..................................................... 115

Appendix F Troubleshooting with Admin Center .................................................... 117

Appendix G More Troubleshooting ......................................................................... 119Testing the communication with a backend ................................................ 119Troubleshooting adapter backend configurations........................................ 122Incorrect proxy configuration .................................................................... 123Getting status information on server internals ............................................ 124Handling low memory conditions ............................................................. 125Configuration of Tomcat Server ................................................................. 126Server with an external name different from the default machinename ....................................................................................................... 127

Appendix H Multilingual Search * (Optional) ........................................................... 129External servers ........................................................................................ 129Multilingual properties in ECI Services ...................................................... 130Specify your multilingual backends ....................................................... 130How to add a specific dictionary............................................................ 131XeLDA failure analysis ......................................................................... 131ECI Services multilingual search example .............................................. 131

Appendix I ECI Services Multilingual Server (MLS) ............................................... 133XeLDA installation ................................................................................... 133Launching the XeLDA server .................................................................... 133On Windows ........................................................................................ 133On Solaris ............................................................................................ 134

Launching the XeLDA RMI proxy ............................................................. 134On Windows ........................................................................................ 134On Solaris ............................................................................................ 135


Table of Contents

List of Tables

Table 1–1. Links in the Admin Center home page ............................................................. 12Table A–1. Troubleshooting Netegrity SiteMinder ............................................................. 81Table C–1. Definition of terms.......................................................................................... 89Table C–2. Template structure.......................................................................................... 90Table E–1. Troubleshooting load-balanced systems ......................................................... 115Table G–1. Low memory error troubleshooting diagnostic ............................................... 125Table I–1. Launching the XeLDA Server ........................................................................ 134Table I–2. Launching the XeLDA RMI proxy ................................................................. 135


Table of Contents


Preface

The Enterprise Content Integration Services Administration Guide contains procedures and informationfor setting up and managing Enterprise Content Integration Services (ECIS). This manual assumesyou have already installed ECIS components by following the instructions in the Enterprise ContentIntegration Services Installation Guide.

Intended audienceThis guide shows administrators how to manage ECI Services. It serves as a reference forthe configuration of the server and the organization of the sources of information withinthe domains tree. The guide assumes a working knowledge of HTML and Java.

This guide contains several references to Xtrim and askOnce files or programs. Xtrim isthe development and runtime foundation of ECI Services (formerly named askOnce) andis included as a part of the file name in many circumstances. For easy understanding,you can assume that ECI Server, askOnce, and Xtrim are synonymous.

Revision historyThe following changes have been made to this document.

Revision date Description

January 2006 Initial Release

Features of ECI ServicesEnterprise Content Integration (ECI) Services provides the following features:• Multi-Docbase searches• Search capabilities within external repositories• Cross-repository searches• Multi-repository attribute display


Preface

• Results relevancy• Support SSO/PKI• Term Highlighting in Webtop

With ECI Services, you’ll be able to:• Import content• Save queries• Extend simple searches to allow for cross-repository and virtual repository searches• Expand search results to display content from all repositories• Display relevance and location• View content from any repository• Import or include content from any repository into a DCTM repository

Access to this functionality is provided from within Documentum 5.3 through anextended search capability within Webtop 5.3. By integrating ECI Services into theDocumentum platform, all WDK-based Documentum solutions have access to ECIfeatures. All WDK-based applications such as Webtop, WDK for Portlets, DAM, DCM,and WP are now able to take advantage of ECI features. Users can collaborate on searchresults and incorporate external objects in EDM, WCM, DCM, Process Portal, or RecordsManagement solutions.


Chapter 1Accessing Admin Center

This chapter begins with a list of features of Enterprise Content Integration Services (ECIS) and thengoes on to describe how you can access Admin Center.

Connecting to Admin CenterTo launch the Admin Centre Web Server in Windows use aOAdminCenter windowsservice. Refer to the Enterprise Content Integration Services Installation Guide for theinstallation procedure for this service.

Note: Alternatively, go to <ECIS installation repository>/bin, and launch the aOAdminscript to run the Admin Center Web Server.

The Admin Center Web Server is accessible through a particular server port number.This is automatically computed from the ECI Services port server number, as follows:<admin center port number> = <ECIS port number> + 3The ECI Services port number that can be changed during installation is set by default to3000 and the Admin Center port number by default is set to 3003.

For example, if the ECI Server port is set to 2828, then the Admin Center port isautomatically set to 2831.

Logging onTo access the Admin Center logon page:

• Type the URL https://<server name>:<admin center port number>/AdminCenter in the browser.

(The URL https://genepi.gresivaudan.com:3003/AdminCenter is an example.)

The Admin Center logon page appears.

Accessing Admin Center

To log on to Admin Center:

1. Type the administrator logon ID and password.

Note: The default logon and password are admin and ecis respectivelyand can be changed when you install the ECI Service. You can alsochange the values by editing web.xml located at <Documentum ECISdirectory>/admin/webapps/WebBasedAdmin/WEB-INF/.

2. Click OK.

The Admin Center home page appears.

If you have not logged out and attempt to access Admin Center from another machine,you will be denied access unless you do a force login. When you do a force login, youcan log on but you will be logged out of the first machine.

To do a force login:

1. Type the administrator logon ID and password.

2. Check the Force login checkbox.

3. Click OK.

The Admin Center home page appears.

Admin Center home pageThe Admin Center home page has links that take you to the various web pages as shownin the table below. The rest of this guide deals with each of these pages in detail, onechapter for each page.

Table 1-1. Links in the Admin Center home page

Click To

Information Source Configuration andOrganization

Add, edit, and delete domains andinformation sources

Set preferences for scheduling, notifying,and managing information sources

Information Source Status Monitor results and information sources


Servers Configuration Configure server operations forIntegration Server and Web Server

This includes:

Server configuration, page 25

Client configuration, page 41

Multilingual configuration, page 51

Logs Reporting Understand and diagnose misconfig-urations and run-time problems inIntegration Server, Web Server, andAdmin Center Server

Accounts Management Monitor and create user accounts

Servers Operation Stop and restart the server

Uploading Upload information sources, libraries,and images

Admin Center Logout Log out

Logging outYou can log out from the session by clicking Admin Center Logout in the home page.


Chapter 2Information Source Conguration andOrganization

This chapter describes how you can create, select, edit, and delete domains and information sources.

A domain may regroup information sources that belong to the same topic of interest. For example, adomain called News regroups some sources like CNN, Yahoo, Reuters, etc. The sources are accessiblethrough a mechanism of adapters. Each source has its own adapter, which is a connector that allowsthe end-user to communicate with a source of information. The adapter uses the search capabilitiesoffered by the source.

The locale-independent domain hierarchy (domains.conf) defines the source hierarchy that appears inthe end-user domain browser. The domain hierarchy is defined in a locale-independent way (usuallyin English), and translated domain hierarchies are automatically generated for each supportedlanguage/locale. A domain can be composed of other sub-domains and individual backends definedby the administrator. When a particular adapter bundle fits the needs of end users “as-is” and doesnot require any more specific configuration, the domain can directly use the name of the adapterbundle. This is called an implicit backend (all the default configuration values defined in the bundlewould apply as they are), which differs from the usual explicit backend (a corresponding backend filewhich defines some specific configuration values).

An adapter is composed of a bundle file and an optional backend file. An adapter bundle file (witha jar extension) holds all generic mechanism (code and configuration) to talk to a remote sourceof a given type, while an adapter backend file extends the adapter bundle to work with a specificinformation source.

Managing domainsThis section explains how you can create domains, add new domains to existing ones,and edit and delete domains.


Information Source Conguration and Organization

Creating domains

To create a new domain:

1. Click the Add button. The Add page opens.

2. Click Create new domain. The Create a new domain page appears.

3. Type a name in the box provided.

4. Click Next. The localized settings page appears.

5. Type the name and description in the respective boxes.

6. Click Finish. The submit page appears along with a message informing you thatthe domain hierarchy will be updated with the new settings if you click Next. Themessage also informs you that you will need to start the servers with the Serversoperation link in the home page to take the new settings into account.

7. Click Next.

8. Click Servers operation in the home page.

Selecting existing domains

To select an existing domain:

1. Click the Add button. The Add page opens.

2. Click Select existing domain. The Select an existing domain page appears.

3. Select the domain from the list.


5. Click Next.


Editing domains

To edit a domain:

1. Click the Edit button. The localized settings page appears.



2. Edit the required information.


4. Click Next.


Deleting domains

To delete a domain:

1. Select the domain to be deleted.

2. Click the Delete button. The submit page appears along with a message informingyou that the domain hierarchy will be updated with the new settings if you clickNext. The message also informs you that you will need to start the servers with theServers operation link in the home page to take the new settings into account.

3. Click Next.


Managing information sourcesThis section describes how you can create, select, edit, and delete information sources.

Note: The Enterprise Content Integration Services Adapter Installation Guide has moreinformation about how you can create adapter backends on these information sources,for core adapters like DocumentumFC, eRoom, EX, and AX.

Creating information sources

To create a new information source:

1. Click the Add button. The Add page appears.

2. Click Create new information source. The Create a new information source pageappears.

3. Type the name of the information source in the box provided.



4. Select the type of the information source either from the Intranet or Internet sourcelists.

5. Click Next. The Localized settings page appears.

6. Type the information source’s name and description in the respective boxes.

7. Click Next. The properties page appears.

8. Type the required details and click Finish. The page appears with the settings andproperties details of the new information source.

9. Click Submit. The submit page appears along with a message informing you thatthe domain hierarchy will be updated with the new settings if you click Next. Themessage also informs you that you will need to start the servers with the Serversoperation link in the home page to take the new settings into account.

10. Click Next.


Selecting existing information sources

To select an existing information source:

1. Click the Add button. The Add page appears.

2. Click Select existing information source. The Select an existing information sourcepage appears.

3. Select the name of the information source from the list.


5. Click Next.


Editing information sources

To edit an information source

1. Click the Edit button. The Localized settings page appears.

2. Edit the required information.




4. Click Next.


Deleting information sources

To delete an information sources

1. Select the information source to be deleted.

2. Click the Delete button. The submit page appears along with a message informingyou that the domain hierarchy will be updated with the new settings if you clickNext. The message also informs you that you will need to start the servers with theServers operation link in the home page to take the new settings into account.

3. Click Next.



Chapter 3Information Source Status

This section discusses the Information Source Status page and the two activities—monitoring andsetting preferences that can be performed here.

Monitoring information sourcesThe Monitoring page allows you to monitor information sources and comprises twosections—Results of information sources and Information sources.

Monitoring results of information sources

This section allows you to monitor the following details:

• Cumulated analysis

— Beginning date

— Latest request date

— Latest good result date

— Total number of requests

— Total number of results

— Average time to retrieve data

— Average results by request

— Requests with at least one result

— Occurred exceptions• Last analysis

— Analysis date


Information Source Status

— Latest request date

— Latest good result date

— Total number of requests

— Total number of results

— Average time to retrieve data

— Average results by request

— Requests with at least one result

— Occurred exceptions

Information sources

This section displays the list of adapters along with status and priority as set in thePreference page.

Setting preferencesThis page has three sections—Scheduling, Notifying, and Managing information sources.

Scheduling

This section allows you to schedule a daily, weekly, or monthly analysis.

Using the Preferences page, you can:

• Select the None option if you do not want to set a scheduling preference.• Select the Daily option to schedule the analysis once in a certain number of days.

You’ll then need to specify the number of days in the box provided.

For example, if you want to schedule the analysis for once every three days, in whichcase, you’ll need to type 3 in the box provided.

• Select theWeekly option to schedule the analysis once in a week. You’ll then need toselect the day from list.

For example, if you might want to schedule the analysis for every Sunday, in whichcase, you’ll need to select Sunday from the list.



• Select theMonthly option to schedule the analysis for a particular date once in acertain number of months. You’ll then need to select a specific date from the listprovided and specify the number of months in the box provided.

For example, you might want to schedule the analysis for the 1st of every threemonths, in which case, you’ll need to select Day 1 from the list and then type 3 inthe month(s) box.

Notifying

This section helps the administrator in sending email notifications of the scheduledanalysis to recipients.

To send an email notification:

1. Check Send an e-mail after each scheduled analysis.

2. Type the email address of the recipient in the box provided.

3. Click the Add button to add more recipients.

4. Click OK.Note: Sending email notifications is optional.

Setting priorities (Information Sources)

This section allows you to set the priorities of the adapters listed and empty the historydetails. You will be able to view the priorities you set in the Information Source sectionof the Monitoring page. You can set the default priorities of the adapters by checkingUse auto priority. To set your own priority for a particular adapter, choose from Low,Medium, and High from the Priorities list.

To empty history details, check Empty history for that particular adapter.

If you wish to set the priority or empty history for the whole list of adapters, you canselect all of them together by clicking Select all. To unselect all the adapters in the list,click Unselect.



Note: Click OK to save the changes made in this page.


Chapter 4Servers Conguration

This chapter helps you to configure server operations in the Servers Configuration page of AdminCenter.

This page has the following sections:• Integration Server, page 25• Web Server, page 53

Integration ServerThis section of the Servers Configuration page, allows you to do the following:• Server configuration, page 25• Client configuration, page 41• Multilingual configuration, page 51• Attribute configuration, page 52

Server conguration

In this part of the Servers Configuration page, you can configure the following:• Proxy settings, page 26• Proxy Authentication settings, page 26• Alert Service settings, page 27• Adapters settings, page 27• Web front-end settings, page 28• RMI settings, page 29• Scheduled Queries settings, page 31


Servers Conguration

• Directory Service settings, page 32• Database and Account settings, page 34• SSL CA Certificate settings, page 38• Diagnose settings, page 38• Server UI settings, page 39• Internal settings, page 40

Proxy settings

You can set the proxy host and proxy port, to allow the user to go outside the firewall.

• xtrim.proxySet

This property is used to go outside the firewall. Default = false.

• xtrim.proxyHost

This is the name of the proxy. Default = None.

• xtrim.proxyPort

This is the proxy port. Default = 80.

Proxy Authentication settings

This setting is used to authenticate the user to go outside the firewall.

• xtrim.proxyAuthenticationSet

This is used to set an authenticated user ID and user password on the proxy for theuser to go outside the firewall. Default = false.

For example, if you select true from the list, then you should type a user ID and apassword in the proxyUserID and proxyUserPassword respectively for it to allowthe user to go outside the firewall.

• xtrim.proxyUserID

The user ID set here is used for authentication. Default = None.


Servers Conguration

• xtrim.proxyUserPassword

The password set here is associated with the user ID for authentication on theproxy. Default = None.

Alert Service settings

This is used to set an email address and the alert services.

• xtrim.adminMailAddress

This is used to type the email address of the administrator. Default = None.

• xtrim.userAgentIdentification

As a courtesy to external web sites, the system includes the email address of theadministrator in every HTTP request. If privacy is a concern, disable this property.Default = No.

• xtrim.mailServer

This property is used to name the mail server that will be used by the alert service.

• xtrim.sendInitializationMailToAdmin

This property is used for you to indicate whether you would like to receive a testemail while initializing the alert service. Default = true.

Adapters settings

Adapter Settings includes the following properties:

• xtrim.brokers

This property is used to set the maximum number of brokers to launch. When morenumber of brokers are set, the server handles more number of searches concurrently.Default = 10.

• xtrim.maxActionFailure

This property, which is set to ’5’ by default is used to set the maximum number oftimes to try a process action that keeps failing. The retry time increases exponentiallywith each retry.


Servers Conguration

For example, if the attribute is set to ’5’, and the adapter reports a network error, itretries the action four times. The retry time is 4 seconds, 8 seconds, 16 seconds,and 32 seconds.

The value is set to ’5’ by default and must not exceed 30, in which case, there will beno retries. If you do not want any retry, set the value to ’1’.

• xtrim.adapterReloadDelay

This is the minimum time between two checks of the ADK and adapters changes ondisk. Default = 60000 ms.

• jwrap.classifier.repairingLevel

This property indicates the policy to be followed for adapter repairing. (such assaving of repaired grammar on disk). Default = 1, in which case, repairing is enabledonly for the current page. If ’0’ is selected, no repairing takes place.

• xtrim.http.resolveDNSHostName

This property allows you to control the amount of DNS activity the server performs.Default = Off, which means that it prevents the server from doing any DNSresolution (better performance). If you set it to ’On’, then the server does a lookup ifnecessary to transform the IP address of the client into a DNS hostname.

• xtrim.httpDataMaxSize

This property is used to set the maximum size of the data that can be loaded. Ifthe server returns the data supported by the ECI Server, which exceeds the sizespecified, then the data retrieved from the source is truncated. But the adapter canchoose either to truncate the data from processing or allow the data to be processed.Default = 2097152 (2 MegaBytes).

Web front-end settings

Web Front-end Settings includes the following properties:

• xtrim.jsp.host

This property specifies the host name of the ECI Server web front-end. By default inthe "Office" releases, the property name should be the same as the machine hostingthe ECIS server. For example, you can type myOwnHost in the space provided.


Servers Conguration

• xtrim.jsp.port

This property specifies the port of the ECIS web front-end. Default = 2828. Forexample, you can also type 8080.

• xtrim.server.embeddedObjectServletUrl

This property specifies the URL to the servlet-servingembedded objects to the end-user browser.The following two parameters can be used in this property:{0}: The host name of the ECISweb front-end (the value of the property xtrim.jsp.host){1}: The port used by the ECIS web front-end (the value of theproperty xtrim.jsp.port, 2828—default value )Default URL—http://{0}:{1}/getIn detail, the default value would behttp://<web_front_end_host>:<web_front_end_port>/get,where <web_front_end_host> is the machine hosting the ECIS web front-end and<web_front_end_port> is the port used by the ECIS web front-end on that machine.

For example, xtrim.server.embeddedObjectServletUrl=http://myOwnHost:2828/get

RMI settings

RMI Settings includes the following properties:

• xtrim.server.rmi.bindingName

This property is used to bind the RmiApiImpl into the RMI registry. Modify it tocontrol two ECI Servers on the same host. Default = xtrim.RmiApi. For example,to control two ECI servers on the same host you can modify the property toxtrim.rmiApi2.

• xtrim.server.rmi.registryHost

This property is used to name the machine that hosts the rmi registry. This can beused when two ECI Servers share the same registry. Default = localhost.

• xtrim.server.rmi.registryPort

This property is used to set the port number of the rmi registry. This can be usedwhen the default port 1099 is not available. Make sure this value corresponds to theone used in bin/aODatabase. Default = 1099.

Servers Conguration

• xtrim.server.RmiSessionTimeOut

This property is the length in seconds of the Rmi session timeouts. This controls howthe ECI Server RMI sessions get automatically discarded after a given inactivitytime. It is recommended to set this timeout to a larger value than the HTTP sessiontimeouts in the JSP web front-end (see web.xml file). Default = 3900s (65*60 = 65minutes).

• xtrim.server.allowRemoteShutdown

This property indicates whether the server can be remotely shutdown or not. Default= false, if you select false the server ignores remote shutdown command. If youselect true the server remotely shutdowns.

• xtrim.server.remoteShutdownPassword

This property is used to set the password required to shutdown the server remotely.If this property is not present, then the server will ignore any remote shutdowncommand. For example you can type the value as password in the space provided.

• xtrim.server.rmi.codebase

This property is the codebase URL, where the RMI classes registered into the RMIregistry can be downloaded (this property will be set as the java.rmi.server.codebaseproperty. The RMI specs has more details) By default this points to the local ECISbuilt-in HTTP server. For load-balanced systems this might be modified to point toa unique load-balanced http server. Default = “http://<aOServer host>:<aOServerport>/class/xtrim-stubs.jar”

For example, http://centralUrl/xtrim-stubs.jar

• xtrim.server.rmi.forceBinding

Set the property to true to have the ECI Server force the binding of the RMI API evenif another server is detected in the registry (applies only to the Enterprise release).Default = false.

• xtrim.server.rmi.embeddedObjectBufferSize

This property is the size in bytes of the size of the buffer used when returningembedded object content to clients. This value can be adapted to the average speedof information sources and embedded object size. This will affect perceived rate ofembedded object transfer. If the embedded objects are perceived as being transferredby a few large blocks, this value could be decreased to provide a smoother downloadexperience. Default = 32768 (32KB).

Servers Conguration

Scheduled Queries settings

Scheduled Queries Settings includes the following properties:

• xtrim.scheduledQuery.DisabledDays

This property is the list of days when no scheduled query can start. Use the standardEnglish abbreviations for days (Mon, Tue, Wed, Thu, Fri, Sat, and Sun), and separatethem with commas if there are several days. Default = None.

• xtrim.scheduledQuery.maxSimultaneous

This property is the maximum number of scheduled queries running simultaneously.If there are more scheduled queries to update, the remaining queries must wait untilone of the currently running queries stop. Default = 20.

• xtrim.user.maxResultsInScheduledQuery

This property is the maximum number of results that is stored in a scheduled query(a query executed periodically). This is to limit the amount of memory and diskspace used by self-updating queries running daily. Default = 200.

• xtrim.scheduledQueryReport

This property is the name of the default report template used for notification whenscheduled queries are updated. The real file name is obtained using the email alertproperties listed in the file client.conf: xtrim.reportTemplates.

• xtrim.scheduledQueryTimeRange.startHour

This property is the starting hour of the time range when scheduled queries can beupdated each day. Each query scheduled to execute one particular day can onlystart during this time range. Default = 0.

• xtrim.scheduledQueryTimeRange.startMinute

This property is the starting minute of the time range when scheduled queries canbe updated each day. Each query scheduled to execute one particular day can onlystart during this time range. Default = 1.

• xtrim.scheduledQueryTimeRange.endHour

This property is the last hour of the time range when scheduled queries can beupdated each day. Each query scheduled to execute one particular day can onlystart during this time range. Default = 6.


Servers Conguration

• xtrim.scheduledQueryTimeRange.endMinute

This property is the last minute of the time range when scheduled queries can beupdated each day. Each query scheduled to execute one particular day can onlystart during this time range. Default = 0.

Security settings

Security Settings includes the following properties:

• xtrim.security.providers (List of authentication providers)

This property is used to load custom authentication plugin instead of or inaddition to the built-in mechanism. This property should contain a list of commaseparated class names. In addition, it supports aliases for the default plugin:"ldap" and "jdbc". Note that defining "ldap" here is redundant with propertyxtrim.directory.provider.ldap (this property is only kept for compatibility).To support Siteminder plugin, you should add the following property value:xtrim.securityapi.siteminder.server.SiteminderAuthenticationProvider Default =jdbc

• xtrim.security.credentialStore (Credential storage provider)

This property is used to load a custom credential storage plugin instead of or inaddition to the built-in mechanism. This property should contain a unique classname. Default = none

Directory Service settings

The LDAP enables you to collect user accounts of ECI Services automatically from theinternal directory service.

For organizations with a large number of user accounts, ECI Services can be connected toan LDAP-compliant directory service. Each user account registered with the directoryservice is identified automatically within ECI Services.

Directory Service Settings includes the following properties:

• xtrim.directory.provider.ldap

This property allows the users to log on with accounts managed on e-remote LDAPdirectory service (this applies only to the Office and Enterprise releases). Default= No.

• xtrim.directory.provider.ldap.host


Servers Conguration

This property is the Hostname or IP address of the LDAP server (this applies only tothe Office and Enterprise releases). Default = None. For example, you can set thevalue as caucase.grenoble.xrce.xerox.com

• xtrim.directory.provider.ldap.port

This property is the Port number of the LDAP server (this applies only to the Officeand Enterprise releases). Default = 389.

• xtrim.directory.provider.ldap.root

This property is the LDAP root object under which user information is stored.Default = None.

For example, "cn=Recipients, ou=MKMS, o=Xerox, c=US"See below another example, using NT accounts with MS-Exchange.xtrim.directory.provider.ldap.root=cn=Recipients,ou=MKMS,o=TEST

MS-Exchange accepts Windows NT Server credentials in the following format:cn=username,cn=NT domain.As such the root property should simply be of the form:"cn=your_NT_domain"Make sure the following property is turned offxtrim.directory.provider.ldap.root=cn=XRCE

• xtrim.directory.provider.ldap.verify

This property is used to check on startup that root defines a valid LDAP object.Note, that when using NT credentials through MS-Exchange or Active Directory itis necessary to turn this off, since the root is not a valid object but rather an alias.Default = Yes.

• xtrim.directory.provider.ldap.attribute

This property is the main attribute holding the logon name of the user. Note, thatwhen using Netscape Directory Server the value is ’uid’. Default = cn.

• xtrim.directory.provider.ldap.ad.shortLogin

Active directory accepts the following logon syntax ’NTDomain\...\NTDomain\NTLogin’, which does not follow the standard LDAP specification.

If this property is set to Yes, only xtrim.directory.provider.ldap.ad.shortLogin isconsidered to authenticate the user in the Active Directory, xtrim.directory.provider.ldap.root and xtrim.directory.provider.ldap.attribute properties are ignored. Default= No.


Servers Conguration

• xtrim.directory.provider.ldap.ad.domain

This property defines the root domain under which user information is stored (maybe empty). For example, ’documentum\ECIS’. Default = None.

Database and Account settings

ECI Services is bundled with a built-in database—McKoi—to store user accounts.However, ECI Services can also be connected to an external database. This enablesdatabase administrators of companies to use existing tools to manage data of ECIServices users along with existing corporate application data.

ECI Services supports the following JDBC compliant databases: McKoi, MySQL (3.2),Oracle (8) and SQLServer. The database can be used to store user context (queries,preferences) and user accounts that are not stored on a LDAP directory service.

After installation, ECI Services uses the default McKoi database. To use another database,some properties in the server.conf file must be modified. Appendix D, ConfiguringExternal Databases has details about configuring external databases and migratingaccounts from one database to another.

Database and Account Settings includes the following properties:

• xtrim.user.useRmiJdbc

This property is used to access remote database through RmiJdbc. Default = Yes.

— Select Yes, if the RDBMS is InstantDB.

— Select No, if the RDBMS is Oracle, MySQL, McKoi, and SQLServer.

• xtrim.user.jdbcClass

This property is the class for the client driver. Make sure it is in the classpath ofaOServer.

— Select RmiJdbc.RJDriver, if the RDBMS is InstantDB.

— Select com.mckoi.JDBCDriver, if the RDBMS is McKoi.

— Select org.gjt.mm.mysql.Driver, if the RDBMS is MySQL.

— Select oracle.jdbc.driver.OracleDriver, if the RDBMS is Oracle.

— Select com.microsoft.jdbc.sqlserver.SQLServerDriver, if the RDBMS isSQLServer.

• xtrim.user.jdbcUrl


Servers Conguration

This property defines the URL of the JDBC database that stores the account andcontext (this applies only to the Office and Enterprise releases). Default = None.

— Type jdbc:rmi://{0}:{1}/jdbc:idb:{2}/contexts.prp, if the RDBMS is InstantDB,where as the parameters {0}, {1}, and {2} are

— {0} = RMI_REGISTRY_HOST

— {1} = RMI_REGISTRY_PORT

— {2} = CONTEXT_PATH (absolute path to directory www/contexts)

— Type jdbc:mckoi://fraovolagd1d:3006/, if the RDBMS is McKoi.

— Type jdbc:mysql://chichet:1972/aOTest, if the RDBMS is MySQL.

— Type jdbc:oracle:thin:@chevreuse:1521:aOBase, if the RDBMS is Oracle.

— Type jdbc:microsoft:sqlserver://aravis.grenoble.xrce.xerox.com:1433, if theRDBMS is McKoi, Database name should be aOContexts.

• xtrim.user.admin

This property is used to create an account for the database administrator. Default= None.

— Type sadmin, if the RDBMS is InstantDB.

— Type admin_user, if the RDBMS is McKoi.

• xtrim.user.password

This property is used to set the password for the account created for the databaseadministrator. Default = None.

— Type adonf as password, if the RDBMS is InstantDB.

— Type aupass00 as password, if the RDBMS is McKoi.

• xtrim.user.useOracle

This property stores the accounts and queries in the Oracle JDBC database.xtrim.user.useDB property must be set to Yes or it will be ignored.xtrim.user.jdbcClass property must correspond to the Oracle Driver. Default = No.

— Select Yes, if the RDBMS is Oracle.

• xtrim.user.primaryKeyLabel

This property is the label used to define primary keys. Default = UNIQUE PRIMARYKEY.

— Select UNIQUE PRIMARY KEY, if the RDBMS is InstantDB.


Servers Conguration

— Select PRIMARY KEY, if the RDBMS is McKoi, MySQL, Oracle, and SQLServer.

• xtrim.user.primaryKeyCreateIndex

Select Yes for the index to automatically create a primary key. Default = No.

— Select Yes, if the RDBMS is Oracle.

• xtrim.user.uniqueLabel

Label this property to define the unique keys. Default = UNIQUE.

— Select UNIQUE, if the RDBMS is InstantDB and McKoi.

• xtrim.user.noCacheLabel

Label this property to disable row cache. Default = none.

— Select CACHE 0 ROWS, if the RDBMS is InstantDB.

• xtrim.user.longTypeLabel

Label this property to define the long values. Default = LONG.

— Select LONG, if the RDBMS is InstantDB.

— Select BIGINT, if the RDBMS is McKoi and MySQL.

— Select NUMBER(38), if the RDBMS is Oracle.

— Select NUMERIC(28), if the RDBMS is SQLServer.

• xtrim.user.binaryTypeLabel

Label this property to define the large binary data. Default = VARBINARY.

— Select VARBINARY, if the RDBMS is InstantDB.

— Select LONGVARBINARY, if the RDBMS is McKoi.

— Select LONGBLOB, if the RDBMS is MySQL.

— Select BLOB, if the RDBMS is Oracle.

— Select IMAGE, if the RDBMS is SQLServer.

• xtrim.user.varCharLabel

Label this property to define the varchar columns. Default = VARCHAR(1024).

— Select VARCHAR(1024), if the RDBMS is InstantDB and SQLServer.

— Select LONGVARCHAR, if the RDBMS is McKoi.


Servers Conguration

— Select BLOB, if the RDBMS is MySQL.

— Select VARCHAR2(1024), if the RDBMS is Oracle.

• xtrim.user.useXOPEN

This property is used for SQL errors to follow the XOPEN SQLstate convention (forexample, a duplicate returns the error code: 23000). Default = No.

— Select No, if the RDBMS is InstantDB, McKoi, and Oracle.

— Select Yes, if the RDBMS is MySQL and SQLServer.

• xtrim.user.duplicateTupleError

This property displays the error messages reported by the database when the sametuple is inserted twice into a given table (this property is used when useXOPENis set to "No"). Default = none.

— Select the message—already exists in column—if the RDBMS is InstantDB.

— Select the message—Immediate primary Key constraint violation—if the RDBMSis McKoi.

— Select the message—Duplicate entry—if the RDBMS is MySQL (Mode Text).

— Select the message—S1009—if the RDBMS is MySQL (Mode XOpen).

— Select the message—ORA-0000—if the RDBMS is Oracle.

— Select the message—23000—if the RDBMS is SQLServer.

• xtrim.user.maxQueriesInContext

This property is used to save the maximum number of queries in the context. Thisis to limit the amount of disk space used by the user context and the number ofself-updating queries running daily. Default = 10.

• xtrim.user.allowPwdSaving

This property indicates whether the users account logon and password can be savedin the database. Default = true.

— Select—true—to allow the user to check the ’Use account login’ in the MAAsettings instead of entering the logon and password for each MAA backend.

— Select—false—to disable the property. The user has to enter and update eachlogon manually.


Servers Conguration

SSL CA Certicate settings

SSL CA Certificate Settings includes the following properties:

• xtrim.ssl.trustStore

This property is the path to the trusted certificates store. Default = <ECIShome>/www/docs/conf/trustedCerts.cer.

• xtrim.ssl.trustStoreType

This property is the type of the trustStore. Default = jks.

• xtrim.ssl.trustStorePassword

This property is the password of the trustStore. Default = changeit.

• xtrim.ssl.keyStore

This property is the path to the local certificates stores.

• xtrim.ssl.keyStoreType

This property is the type of the keyStore. Default = jks.

• xtrim.ssl.keyStorePassword

This property is the password of the keyStore. Default = changeit.

Diagnose settings

Logs are used in troubleshooting and help in understanding and diagnosingmisconfigurations and run-time problems.

Diagnose Settings includes the following properties:

• xtrim.log.mode

In this property, log files (file option) or standard out (screen) is used to displayserver messages. Default = file.

• xtrim.log.singleTrace

In this property, use “on" to have a single log file with all the message (inchronological order) or "off" to have one file per type of event. Default = off.

Servers Conguration

• xtrim.log.access, xtrim.log.error, and xtrim.log.trace

The xtrim.log.mode property is defined to a file, the following properties definethe storage location of each log file. To avoid creating one of the files, leave theproperty empty.

— xtrim.log.trace=path from ${XTRIMHOME}/www/docs

if the path is incorrect, prints the log file in the current repository.

— xtrim.log.access = /../logs/access.log

— xtrim.log.error=/../logs/error.log

— xtrim.log.trace=/../logs/trace.log

• xtrim.wrapperDebug

This property keeps the HTML documents in xtrim.wrapperDebugPath, if a parseerror occurs (useful for debugging parsers). Default = No.

• xtrim.wrapperDebugPath

This property is used to store HTML documents. Default = /../logs. Optional =C:/Temp.

If the path is incorrect, prints the log file in the current repositoryxtrim.wrapperDebugPath = /../logs

Server UI settings

Server UI Settings includes the following properties:

• xtrim.serverGUI.icon

This property is the path of the search server icon relative to—{Searchserver}/www/docs. Default = None.

• xtrim.serverGUI.logo

This property is the path of the small search server logo relative to—{Searchserver}/www/docs. Default = None.

• xtrim.serverGUI.aboutlogo

This property is the path of the search server logo relative to—{Searchserver}/www/docs. Default = None.


Servers Conguration

• xtrim.serverGUI.showSearches

This property displays search terms in the server console (monitor activity andsuggest additional information sources to better support users). Default = No, forprivacy considerations, only display backends.

Option = Yes, for example xtrim.serverGUI.showSearches = Yes

• xtrim.serverGUI.shutDownWait

This property is used during shutdown. The property value is to be increased if theshutdown isn’t completed (in seconds). Default = 10

• xtrim.server.multiServerMode

This property is used to control the system, which is configured to use multipleservers with load balancing settings (applies only to the Enterprise release). Default= false

• xtrim.defaultWrapperUpdateURL

This property is the default URL for the adapter updater containing updatedadapters. Default = none.

Internal settings

Internal Settings includes the following properties:

• javax.xml.parsers.DocumentBuilderFactory and javax.xml.parsers.SAXParserFactory

Do not modify these properties, they are internally used by the server. Theseproperty setting are used for the default XML parser implementation (DOM).

javax.xml.parsers.DocumentBuilderFactory = org.apache.xerces.jaxp.DocumentBuilderFactoryImpl

javax.xml.parsers.SAXParserFactory = org.apache.xerces.jaxp.SAXParserFactoryImpl


Servers Conguration

Client conguration

This section describes the appearance and default behavior of the ’Integration Server’clients (www/docs/conf/client.conf).

In this part of the Servers Configuration page, you can configure the following:• Results settings, page 41• Localization settings, page 42• Email alert settings, page 42• Multilingual search settings, page 44• Web Assistant settings, page 44• Clustering settings, page 47• Security settings, page 48• Personalized Relevance Ranking settings, page 48• Query Service settings, page 49• Query Service Location settings, page 49• Query Service Proposal settings, page 50• Query Service Language Resource settings, page 50• Query Service Resource settings, page 51

Results settings

Results Settings includes the following properties:

• xtrim.clientVisibleProperties

This is a list of attributes that are transmitted to the clients. You should not change oredit this property as it is used internally. Default = None.

• xtrim.query.refineResults

This property states whether each query started should reuse the results from theprevious search and filter them against the new constraint, or whether all the resultsshould be cleared automatically between one search and another. Default = Yes(Refine the query by reusing previous results still matching). Optionally you canselect No (Always clear results between two searches with the same query).


Servers Conguration

Localization settings

Localization Settings includes the following property:

• xtrim.extraLocales

This property lists the additional supported locales by the system. This is used on theserver-side to prepare the properties for the clients in each of the supported locale.

The format of the locale should be according to the ISO Language Code—lowcasetwo-letter defined by ISO-639, at least ’en’ is required.

The complete list lists—en, fr, de, it, ja, ko, and es. Default = None.

Email alert settings

Email Alert Settings includes the following properties:

• xtrim.reportTemplates

This property is the list of available reports that can be used to generate emailalerts for scheduled queries. Standard reports are MailReport, ShortReport,and LongReport. Furthermore a localized report is available in each languagepack—FrenchReport, GermanReport, ItalianReport, JapaneseReport, KoreanReport,and SpanishReport. Default = None.

For example, xtrim.reportTemplates = MailReport,ShortReport,LongReport

• xtrim.report.MailReport

This property is standard English email report. The path to this file is relativeto—${ECIS}/www/docs/conf. Default = None.

For example, xtrim.report.MailReport = MailerReport_en.rtl

• xtrim.report.ShortReport

This property is standard English short report. The path to this file is relativeto—${ECIS}/www/docs/conf. Default = None.

For example, xtrim.report.ShortReport = MailerReportShort_en.rtl

• xtrim.report.LongReport

This property is standard English complete report. The path to this file is relativeto—${ECIS}/www/docs/conf. Default = None.

For example, xtrim.report.LongReport = MailerReportLong_en.rtl


Servers Conguration

• xtrim.report.FrenchReport

French report available with the French language pack. The path to this file isrelative to—${ECIS}/www/docs/conf. Default = None.

For example, xtrim.report.FrenchReport = MailerReport_fr.rtl

• xtrim.report.GermanReport

German report available with the German language pack. The path to this file isrelative to—${ECIS}/www/docs/conf. Default = None.

For example, xtrim.report.FrenchReport = MailerReport_de.rtl

• xtrim.report.ItalianReport

Italian report available with the Italian language pack. The path to this file is relativeto—${ECIS}/www/docs/conf. Default = None.

For example, xtrim.report.FrenchReport = MailerReport_it.rtl

• xtrim.report.JapaneseReport

Japanese report available with the Japanese language pack. The path to this file isrelative to—${ECIS}/www/docs/conf. Default = None.

For example, xtrim.report.FrenchReport = MailerReport_ja.rtl

• xtrim.report.KoreanReport

Korean report available with the Korean language pack. The path to this file isrelative to—${ECIS}/www/docs/conf. Default = None.

For example, xtrim.report.FrenchReport = MailerReport_ko.rtl

• xtrim.report.SpanishReport

Spanish report available with the Spanish language pack. The path to this file isrelative to—${ECIS}/www/docs/conf. Default = None.

For example, xtrim.report.FrenchReport = MailerReport_es.rtl


Servers Conguration

Multilingual search settings

Multilingual Search Settings includes the following properties:

• xtrim.CLIR.isCLIRSupported

This property enables or disables the multilingual search feature (Requires additionallinguistic libraries and servers). Default = false.

Note: The xelda/rmi-xelda servers are mandatory. Set the xelda connectionparameters in www/docs/conf/xelda.conf.

• xtrim.CLIR.languages

This property lists the list of languages supported as source language in linguisticservers. Default = None.

• xtrim.CLIR.localization

This feature is used to add more languages to the list.

1. Type the language that you are adding to the list and click Add.

2. To delete any language from the list click Delete.

Web Assistant settings

Web Assistant Settings includes the following properties:

• xtrim.WA.isWebAssistantEnabled

This property activates the Web Assistant feature. Default = false.

• xtrim.WA.supportedColors

This property lists the colors available for underlining lexemes and idioms. Default =false.

For example, xtrim.WA.supportedColors =green,lightblue,orange,pink,purple,red,white,yellow

• xtrim.WA.strategy

This property shows the strategy used by Web Assistant to query the linguisticserver (cf linguistic server documentation for syntax). Default = None.

For example, MyBusinessTermino?, genral?


Servers Conguration

• xtrim.WA.nbTranslation

This property list the maximum number of translations displayed by WebAssistant.Default = 0, which means all translations.

To set up Web Assistant in an ECI Services context, the administrator must perform thefollowing tasks:

1. Set the properties to link to linguistic server.

2. Set Linguistic and Web Assistant client configuration.

3. Customize Web Assistant result window.

Setting linguistic server properties

Web Assistant is based on Multilingual Search service. The server used for querytranslations is the same than the one for Web Assistant specific calls.

The linguistic server configuration has been detailed in the previous paragraph dealingwith Multilingual Search.

Setting client conguration

This client side configuration is stored in the "client.conf" file.

Administrator can enable Web Assistant or not, by editing the corresponding property:xtrim.WA.isWebAssistantEnabled=Yes

The list of supported colors is stored in:xtrim.WA.supportedColors=green,lightblue,orange,pink,purple,red,white,yellow

The colors are identified by their English lower case name, and they correspond to thecolor files used in displayed pages, that are stored in the following directory:"www/tomcat/webapps/ao/data/WAresult"

The file corresponding to a <color> identifier is named "<color>_bar.gif".

The color identifiers have to be localized in the localization files "jsp_<Lang>.properties"under "www/docs/i18n/" for end-user displaying in the preferences panel.

If specific terminologies are installed on the linguistic server, the administrator canspecify the strategy to use for Web Assistant translations. #xtrim.WA.strategy=Documentum?,general? Check the linguistic server documentation for details on thesyntax of this parameter.

#xtrim.WA.strategy=Documentum?,general? Check the linguistic server documentationfor details on the syntax of this parameter.

Servers Conguration

The last property is the maximum number of translations to display in Web Assistantresults pages (xtrim.WA.nbTranslation). It must be a positive integer. If this propertydoes not exist or, if its value is lower than 0, then no maximum value is taken intoaccount (All translations from the linguistic server are displayed).

Finally the enriching data files to insert into accessed web pages are located in the datadirectory that has to be accessible from Tomcat configuration (to customize "web.xml"and "server.xml", see TomCat documentation).

First one is named "webAssistant.html". It contains JavaScripts that handle WebAssistant requests.

The file containing the displayed part of the enriching is located into"webAssistantInfo.html". This file defines an HTML table that displays informationabout the way that the current page was enriched (target language, mouse button to useand key modifier, as well as a link to the original non enriched page).

Customizing Web Assistant result window

Web Assistant results are sent back to the end user through a JSP template page.

This template uses data from aWebAsisstantResultBean that is associated to the response.

The administrator can customize the result window by editing the file named"WebAssistantResult.jsp" in "www/tomcat/webapps/ao/jsp" directory (SeeJSP_customization documentation to find out how to compile JSP).

Files are linked relatively to "www/tomcat/webapps/ao/" (according to TomCat’s defaultapplication context). The administrator can define its own JSP page to replace the defaultone, and to display Web Assistant results.

The only thing to do is to change JSP mapping into "www/tomcat/webapps/ao/WEB-INF/web.xml" by updating the "servlet-class" field in "WAResult" servlet definition:<servlet>

<servlet-name>WAResult</servlet-name><servlet-class>WebAssistantResult</servlet-class>

</servlet>

For example, if the new JSP is named "MyResultWindow.jsp", the servlet-class fieldshould be set to "MyResultWindow", without extension.

Caution: Do not change the url-mapping field, as these data is used by ECI Server.

The size of Web Assistant result window can be customized in "www/tomcat/webapps/ao/data/Xwa_Document.js", through the fields "this.resultHeight" and "this.resultWidth".

Servers Conguration

Clustering settings

Clustering Settings includes the following properties:

• xtrim.CLUSTER.isSupported

This property activates the clustering feature. Default = true

• xtrim.CLUSTER.clusterThreshold

This property is used to define the minimal number of results to compute theclusters. Default = 5. Minimal value = 1.

• xtrim.CLUSTER.subClusterThreshold

This property is used to define the minimal number of results in a clusters tocompute the sub clusters. Default = 5. Minimal value = 1.

• xtrim.CLUSTER.minimalDelay

This property is used to define the minimal time to wait for enough results beforecomputing the first set of clusters (in seconds). Default = 0

Note: For the search server standard interface, this must be set to 0, or the clusterframe may not be refreshed until the end of the query.

• xtrim.CLUSTER.defaultRelevantAttributes

This property defines the attributes, which are considered while computing clustersby ’Topics’. At least one attribute is required. Default = title, abstract, body, collection

• xtrim.CLUSTER.notRelevantAttributes

This property defines the attributes, which are not considered while computingclusters. Default = None.

• xtrim.CLUSTER.suffixNotRelevantAttributes

This property defines the suffix attributes, which are not considered while computingclusters. Default = None.

• xtrim.CLUSTER.prefixNotRelevantAttributes

This property defines the prefix attributes, which are not considered whilecomputing clusters. Default = None.


Servers Conguration

Security settings

Security Settings includes the following properties:

• xtrim.server.allowAuthCookie

This property indicates whether clients can bypass logon and pssword authenticationmechanism by using an automatic logon mechanism using a permanent cookie. Thisproperty is shared between the client and the server. Default = true.

• xtrim.server.checkIPForCookie

If the client uses authentication cookie to log into integration server(xtrim.server.allowAuthCookie), then this property indicates whether the clientmust check the IP of the user corresponding to the IP used while logging on the firsttime. User can log from different machine/browser, but the cookie on each of thesebrowsers will be specific to the IP of its machine. This property is shared betweenthe client and the server. Default = true.

Personalized Relevance Ranking settings

Personalized Relevance Ranking Settings includes the following properties:

• xtrim.profile.isSupported

This property activates the relevance ranking feature. Default = true.

• xtrim.profile.relevantAttributes

This property lists all the attributes, which is used for computing the personalizedrelevance ranking on results. Default = All Attributes.

For example, xtrim.profile.relevantAttributes = title, body, abstract, collection,description


Servers Conguration

Query Service settings

Query Service Settings includes the following properties:

• xtrim.QUERYSERVICE.isSupported

This property is used to enable or disable the query service settings. Default = None.

• xtrim.QUERYSERVICE.ServiceAvailable

This property lists all the available services. The first service in the list is the defaultservice. Default = None. To disable this property remove all the available services.

For example, xtrim.QUERYSERVICE.ServiceAvailable = spellchecker, termino, sqlet,collection, authors

• xtrim.QUERYSERVICE.LanguagesService

This property lists all the available languages for services. Standard language isEnglish. Furthermore each language pack provides a language for services. The listis—french, german, italian, spanish. Default = None.

Query Service Location settings

This property shows the location of the query service permitting to execute the services.

1. To add a service, type the service with the location in the respective boxes and clickAdd.

2. To delete, click the Delete button against the listed service.For example,• xtrim.QUERYSERVICE.Class.authors = xtrim.services.query.QueryServiceWrapper• xtrim.QUERYSERVICE.Class.collection = xtrim.services.query.QueryServiceWrapper• xtrim.QUERYSERVICE.Class.spellchecker = xtrim.services.query.spellchecker• xtrim.QUERYSERVICE.Class.termino = xtrim.services.query.eurodicautom.

QueryServiceEurodicautom


Servers Conguration

Query Service Proposal settings

This property is used to check the service proposals before posting them.

For example,• xtrim.QUERYSERVICE.Class.authors = No• xtrim.QUERYSERVICE.Class.collection = No• xtrim.QUERYSERVICE.Class.spellchecker = Yes• xtrim.QUERYSERVICE.Class.termino = No

Query Service Language Resource settings

This property is the setup of dictionaries used by language services. These are the pathsto the dictionaries permitting to execute the spell checker. These paths are relativesto <ECIS dir>/www/tomcat/webapps/ao/

• xtrim.QUERYSERVICE.Dictionary.default

This is the default dictionary used if the client locale is not supported. Default= None.

For example, xtrim.QUERYSERVICE.Dictionary.default = dictionary/default.dic

• xtrim.QUERYSERVICE.Dictionary.english

This is the standard English dictionary. Default = None.

For example, xtrim.QUERYSERVICE.Dictionary.english = dictionary/english.dic

• xtrim.QUERYSERVICE.Dictionary.french

This is the French dictionary available with the French language pack. Default= None.

For example, xtrim.QUERYSERVICE.Dictionary.french = dictionary/french.dic

• xtrim.QUERYSERVICE.Dictionary.german

This is the German dictionary available with the German language pack. Default= None.

For example, xtrim.QUERYSERVICE.Dictionary.german = dictionary/german.dic

• xtrim.QUERYSERVICE.Dictionary.italian

This is the Italian dictionary available with the Italian language pack. Default = None.

Servers Conguration

For example, xtrim.QUERYSERVICE.Dictionary.italian = dictionary/italian.dic

• xtrim.QUERYSERVICE.Dictionary.spanish

This is the Spanish dictionary available with the Spanish language pack. Default= None.

For example, xtrim.QUERYSERVICE.Dictionary.spanish = dictionary/spanish.dic

Query Service Resource settings

This property is used to set miscellaneous properties for each query services.

For example,• xtrim.QUERYSERVICE.Wrapper.authors.backend = computer/ResearchIndex• xtrim.QUERYSERVICE.Wrapper.authors.query = full-text• xtrim.QUERYSERVICE.Wrapper.authors.result = author• xtrim.QUERYSERVICE.Wrapper.authors.timeout = 12• xtrim.QUERYSERVICE.Wrapper.collection.backend = general/OpenDirectory• xtrim.QUERYSERVICE.Wrapper.collection.query = full-text• xtrim.QUERYSERVICE.Wrapper.collection.result = collection• xtrim.QUERYSERVICE.Wrapper.collection.timeout = 12• xtrim.QUERYSERVICE.Wrapper.termino.backend = terminology/Eurodicautom• xtrim.QUERYSERVICE.Wrapper.termino.query = full-text• xtrim.QUERYSERVICE.Wrapper.termino.result = term_source• xtrim.QUERYSERVICE.Wrapper.termino.timeout = 12

Multilingual conguration

This section helps you to configure the Multilingual server operations(www/docs/conf/xelda.conf).

In this part of the Servers Configuration page, you can configure the following:

• xtrim.CLIR.xelda.server

This property shows the host, port, and application name of the linguistic server.Default = None.

For example, xtrim.CLIR.xelda.server = //localhost:1099/XeldaBridgeServer


Servers Conguration

• xtrim.CLIR.keepOriginalTerm

This property is used to keep the original source term when performing dictionarylookups in the same language. This can be overwritten in the configuration of anyinformation source with the property. Default = true.

• xtrim.CLIR.nbTranslation

This property is used to set the maximum number of translation of a lexem oridiom. Default = 2.

• xtrim.CLIR.strategy

This property is used for the Xelda strategy for dictionary lookups. This can beoverwritten in the configuration of any source with the property: strategy. Default =general.

Attribute conguration

This section describes the English attributes and English attributes translation. In thispart of the Servers Configuration page, you can add or delete an English attribute withthe description/translation.

Attribute description

This property describes the English attributes.

To add or delete an attribute with their description:

1. Type the attribute name and its description in the respective boxes.

2. To add, click the Add button.

3. To delete an attribute, click Delete.For example,• AttributeDescription.URL = URL contains an hyper-text link or Internet address

where to find the resource• AttributeDescription._internal-banner-URL = Link to the banner• AttributeDescription._internal-banner-image-URL = Link to the banner image• AttributeDescription._internal-banner-text-body = Body of the banner


Servers Conguration

Attribute translation

This property is used for describing English attribute translation.

To add or delete an attribute with their description:

1. Type the attribute name and its translation in the respective boxes.

2. To add, click the Add button.

3. To delete an attribute, click Delete.For example,• AttributeTranslation.URL = URL• AttributeTranslation._internal-banner-URL = banner-URL• AttributeTranslation._internal-banner-image-URL = banner_image-URL• AttributeTranslation._internal-banner-text-body = banner_body

Web ServerThis section of the Servers Configuration page has two parts—Configuration of the WebServer and Configuration of the Web Server with the Integration Server.

Web Server conguration

These properties are used for the configuration of the Web Server address, and WebServer debug parameters (www/tomcat/conf/server.xml).

• Port

This describes the port of a web front-end. Default = None.

For example, Port = 3000

• Shutdown port

This describes the shutdown port of a web front-end. Default = None.

For example, Shutdown port = 3001

• maxSpareThreads

This property describes the maximum number of the unused request processingthreads that will be allowed to exist until the thread pool starts stopping theunnecessary threads. Default = None.


Servers Conguration

For example, maxSpare Threads = 75

• maxThreads

This property describes the maximum number of request processing threads to becreated by this connector, which therefore determines the maximum number ofsimultaneous requests that can be handled. Default = None.

For example, maxThreads = 150

• minSpareThreads

This property describes the number of request processing threads that is createdwhen this connector is first started. The connector also makes sure it has the specifiednumber of idle processing threads available. This attitude should be set to a valuesmaller than that set for maxThreads. Default = None.

For example, minSpare Threads = 25

• acceptCount

This property describes the maximum queue length for incoming connectionrequests when all possible request processing threads are in use. Any requestsreceived when the queue is full will be refused. Default = None.

For example, acceptCount = 100

• Debug setting

This property allows the setup of the Web Server trace level. Default = None.

For example, Debug setting = 0

Conguration of the Web Server with the IntegrationServer

This section describes the configuration of the Web Server with the ’Integration server’(www/tomcat/webapps/ao/WEB-INF/web.xml).

This section is classified into following parts:• Proxy Settings, page 55• Proxy Authentication Settings, page 55• RMI Settings, page 56• Default Account, page 56• Domains Settings, page 56


Servers Conguration

• Domains Icon Settings, page 57• Results Settings, page 57• Export Settings, page 58• Diagnose Settings, page 59

Proxy Settings

Proxy Settings includes the following properties:

• ASKONCE_PROXY_SET

In this property you can select an attribute—true or false to use a proxy to go outsidethe firewall. Default = None.

• ASKONCE_PROXY_HOST

In this property type the hostname or the IP address of the proxy. Default = None.

For example, ASKONCE_PROXY_HOST = broker.documentum.fr

• ASKONCE_PROXY_PORT

In this property type the TCP/IP port the proxy listens to. Default = None.

For example, ASKONCE_PROXY_PORT = 8000

Proxy Authentication Settings

Proxy Authentication Settings includes the following properties:

• ASKONCE_PROXY_AUTHENTICATION

This property activates the HTTP authentication between the Web Server and theproxy server. Default = None.

• ASKONCE_PROXY_USER_ID

This property sets the user ID to use when the HTTP proxy authentication modeis activated. Default = None.

• ASKONCE_PROXY_USER_PWD

This property sets the user password to use when the HTTP proxy authenticationmode is activated. Default = None.


Servers Conguration

RMI Settings

RMI Settings includes the following properties:

• ASKONCE_RMI_NAME

This property is the name of the integration server RMI module. Default = None.

For example, ASKONCE_RMI_NAME = xtrim.RmiApi

• RMI_REGISTRY_HOST

This property is the name of the machine that hosts the RMI registry. Default = None.

For example, RMI_REGISTRY_HOST = genepi

• RMI_REGISTRY_PORT

This property is the port number of the RMI registry. Default = None.

For example, RMI_REGISTRY_PORT = 3005

Default Account

Default Account includes the following properties:

• DEFAULT_LOGIN_NAME

This property defines the default logon to use when no personal logon is defined.Default = None.

For example, DEFAULT_LOGIN_NAME = guest

• DEFAULT_LOGIN_PASSWORD

This property defines the default password of the default logon. Default = None.

For example, DEFAULT_LOGIN_PASSWORD = askonce

Domains Settings

Domains Settings includes the following properties:

• MAX_NUMBER_OF_SELECTED_DOMAINS

This property defines the maximum number of domain to display in the JSP searchpage. Default = None.


Servers Conguration

For example, MAX_NUMBER_OF_SELECTED_DOMAINS = 10

• JSP_DOMAIN

This property defines the domain name for the JSP client to look for into the ’all’domain. Default = None.

For example, JSP_DOMAIN = JSP

• MAX_DOMAIN_NAME_LENGTH

This property defines the maximum number of letters to display for the domainname in the search panel. Default = None.

For example, MAX_DOMAIN_NAME_LENGTH = 15

Domains Icon Settings

This property is used to set the icons used to display the domains. For each domain, theclient uses two icons on/off, for example, Business is represented by icons/dom06on.gifand icons/dom06of.gif.

To add or delete an attribute to the domains icon settings:

1. To add, type the icon name and its domain name in the respective boxes and clickthe Add button.

2. To delete an attribute, click Delete.For example, icon.Documentum = dom09

Results Settings

Results Settings includes the following properties:

• MAX_BODY_LENGTH

This property defines the maximum body length in the overview view column of theresult panel. Default = None.

For example, MAX_BODY_LENGTH = 150,300

• MAX_DISPLAYED_RESULT

This property defines the maximum number of results to display in the resultpage and consult page in order to avoid browser crash. Default = 5000 (minimumaccepted = 5).


Servers Conguration

For example, MAX_DISPLAYED_RESULT = 2000

• NB_RESULTS_PAGE_LIST

This property defines the number of results to display in the result panel (perpage). A list of strictly positive values is defined. Every value is suggested in thepreferences panel. Default = The default one is the first one.

For example, NB_RESULTS_PAGE_LIST = 100,200,300,400,500

• TOOLTIP_LENGTH_LIST

This property defines the maximum tooltip body length of the result panel. Alist of strictly positive values is defined. The first two values are suggested in thepreferences panel. The default one is the first one.

For example, TOOLTIP_LENGTH_LIST = 500,1000

• SORTABLE_ATTRIBUTES

This property defines the list of attributes available for sorting in the expand view.The attribute name is defined in the internal language—English. Default = None.

For example, SORTABLE_ATTRIBUTES =title,author,collection,date,selection,source,score

• MAIN_CONTROLLER

This property defines the name of the mail integration server controller. It is thisname that is displayed in the integration server URL. This name must match theURL-mapping for the servlet ECIS, but without the leading /. Default = None.

For example, MAIN_CONTROLLER = ecis.jsp

Export Settings

Export Settings includes the following properties:

• exportList (Default = None)• html (Default = None)• pdf (Default = None)• xls (Default = None)• xml (Default = None)• MAX_QUERY_VIEW_RANGE (Default = 5)• JSP_DEBUG (Default = False)


Servers Conguration

• Session timeout (Default = 30)• RESULTS_TIMEOUT (Default = 0)

Diagnose Settings

In this section following can be performed—Logs integration server action URL, POSTparameter are displayed as GET parameters, and Session ID are also logged, so that onecan extract a user session from the log file.

• suffix (Default = None)

• prefix (Default = None)

• directory (Default = None)

• accessLogFilter (Default = None)

Customizing ECI Services look and feelECI Services look and feel may be customized. For example, the home page canbe changed. This page is displayed for guest end users when no search has beenperformed. This page is located in <your_ECIS_dir>www/tomcat/webapps/ao/. It namesintro_en.html for the English version and intro_fr.html for the French version. The datastyle sheet used is style2.css located in <your_ECIS_dir>/www/tomcat/webapps/ao/data/.The only limit to your modifications in this page is to maintain the final line with thecorresponding links:Copyright © 1994-2004 Documentum, a division of EMC. All Rights Reserved.

For the aOdirect interface the home page is named aOintro_en.html for the Englishversion and aOintro_fr.html for the French version. These files are located in the samedirectory as the intro_en.html. However aOintro must not contain any HTML headerneither footer as they are generated by the aOdisplay JSP file. The search and resultsof look and feel can also be configured in web.xml to change the default standardbehavior. This file is located in <your_ECIS_dir>/www/tomcat/webapps/ao/WEB_INF/.For the search panel, you can change the number of domains to display withthe property MAX_NUMBER_OF_SELECTED_DOMAINS. The propertyMAX_DOMAIN_NAME_LENGTH sets the maximum number of letters allowed for thedomains name in the search panel.

Servers Conguration

Example 4-1. Search panel conguration with domains display

<context-param>

<param-name>MAX_NUMBER_OF_SELECTED_DOMAINS</param-name><param-value>10</param-value><description>Define the maximum number of domain to display in the

jsp search page</description></context-param>

<context-param><param-name>MAX_DOMAIN_NAME_LENGTH</param-name><param-value>15</param-value><description>Define the maximum number of letters to display for the

domain name in the search panel</description></context-param>

For the results panel, the number of characters of the body displayed in the ‘overview’column is set in the property MAX_BODY_LENGTH. For the expand view panel, the listattributes available to make a sort is contained in SORTABLE_ATTRIBUTES. The listmust contain ECI Services internal attribute names (that is, no localized value).

Example 4-2. Results and expand view panels conguration

<context-param>

<param-name>MAX_BODY_LENGTH</param-name><param-value>100</param-value><description>Define the maximum body length in the summary view of

the result panel</description></context-param>

<context-param><param-name>SORTABLE_ATTRIBUTES</param-name><param-value>title,author,collection,date,selection,source,score</param-value><description>Define the list of attributes available for sorting

in the expand view</description></context-param>

The content of the overview field can also be customized at the level of each adapter. Bydefault the BODY is built from the result attributes body and abstract. To change or addfurther attributes, the following property should be added in the adapter configurationfile. The Adapter Installation Guide has more details.

client.overview• Description — A comma separated list of attributes which constitutes the overview

field in the HTML interface (For example, abstract, body)• Default value — abstract, body• Mandatory — No

Servers Conguration

• Visible on client — YesFor the login panel, a custom text can be displayed above the login form to add details orexplanation. The text is editable in the localization file (that is, jsp_en.properties for theEnglish version and jsp_fr.properties for the French one).

These files are located in <your_ECIS_dir>/www/tomcat/webapps/ao/data/i18n/. Changeor fill the property AdditionalLoginMsg.

Example 4-3. Login panel conguration in the localization le (jsp_en.properties for theEnglish version)

# Enter text to display a message in the login panel (above the login form)AdditionalLoginMsg=Enter your NT login name

Servers Conguration


Chapter 5Logs Reporting

This chapter helps you to understand and diagnose misconfigurations and run-time problems and isclassified into three sections—Integration Server, Web Server, and Admin Center Server—in keepingwith the way the Logs Reporting page is organized. You’ll need to click the respective View button tosee the contents of the various log files.

Integration ServerThis section describes the three types of log files—trace.log, error.log, and access.log.

• Tracing system interactions

The trace.log file—www/logs/trace.log—is used by developers to trace the systeminteraction. A sample of the log details is shown in the example given below:ActionTimer: exiting... - [Jan 17, 2003 12:42:12 PM]Broker (3): BaseBroker shutting down - [Jan 17, 2003 12:42:12 PM]Broker (4): BaseBroker shutting down - [Jan 17, 2003 12:42:12 PM]Broker (5): BaseBroker shutting down - [Jan 17, 2003 12:42:12 PM]Broker (6): BaseBroker shutting down - [Jan 17, 2003 12:42:12 PM]Broker (7): BaseBroker shutting down - [Jan 17, 2003 12:42:12 PM]Broker (8): BaseBroker shutting down - [Jan 17, 2003 12:42:12 PM]

• Tracing encountered errors

The error.log file—www/logs/error.log— is used to trace errors, like errorsencountered during source wrapping. A sample of the log details is shown in theexample given below:.------------xtrim.adapter.AdapterException: Adapter [computer/Microsoft] raised error oftype [PARSER] with message [unable to parse [{'full-text' CONTAINS 'graphium ab'} => {general/AltaVista, general/AltaVista-France, france/Ecila,general/Excite, general/Excite-France, general/Infoseek, general/Yahoo, general/YahooInktomi, Documentum/ComputerInsite, computer/Microsoft, computer/Netscape, computer/Sun, Documentum/DocumentumInt,


Logs Reporting

Documentum/Documentum, computer/CMPnet, ccomputer/Acm, computer/Calliope, computer/DBLP, computer/Ncstrl,computer/Springer, computer/Usenix, library/BL-Social, library/BL-Science,library/BL-Music, library/BL-Old, library/BL-Books, library/BL-Journals,library/BL-Conf, library/LoC, Documentum/TechLib, Documentum/NutsLib,bsb/BSBOpac}] at level:1custom.computer.Microsoft.rule.ParseException: Encountered "<" at line 1,column 1.Was expecting:

" {general/AltaVista, general/AltaVista-France, france/Ecila,general/Excite, general/Excite-France, general/Infoseek, general/Yahoo,general/YahooInktomi, Documentum/ComputerInsite, computer/Microsoft,computer/Netscape, computer/Sun, Documentum/DocumentumInt,Documentum/Documentum, computer/CMPnet, computer/Acm, computer/Calliope, computer/DBLP, computer/Ncstrl, computer/Springer,computer/Usenix, library/BL-Social, library/BL-Science, library/BL-Music, library/BL-Old, library/BL-Books, library/BL-Journals, library/BL-Conf,library/LoC, Documentum/TechLib, Documentum/NutsLib, bsb/BSBOpac}] at level:1custom.computer.Acm.rule.ParseException: Encountered "<" at line 1, column 1.Was expecting:

"<html>" ...]

-----------

• Storing information on client access to the ’Integration Server’

The access.log file—www/logs/access.log— is used to store the information onclient access to the ECI Server. A sample of the log details is shown in the examplegiven below:13.202.222.66 - RmiSurrogate (Client Id:-1 From:13.202.222.66 state:connected)- [Jan 17, 2003 12:41:30 PM] "CONNECT -1 HTTP/1.0" 200 013.202.222.66 - RmiSurrogate (Client Id:-1 From:13.202.222.66 state:connected)- [Jan 17, 2003 12:41:34 PM] "QUERY Query/-274877906943 from account:-1, name:Query-1, definition:{'full-text' CONTAINS 'test tool'} => {Google, OpenDirectory}HTTP/1.0" 200 0Query/-274877906943 - general/OpenDirectory:processing - [Jan 17, 2003 12:41:37 PM]"FOUND general/OpenDirectory returned 20 results in 1968ms XTRIM/1.5" 200 0Query/-274877906943 - general/Google:processing - [Jan 17, 2003 12:41:39 PM]"FOUND general/Google returned 30 results in 3797ms XTRIM/1.5" 200 0Query/-274877906943 - general/OpenDirectory:processing - [Jan 17, 2003 12:41:41 PM]"FOUND general/OpenDirectory returned 20 results in 4016ms XTRIM/1.5" 200 0Query/-274877906943 - general/OpenDirectory:processing - [Jan 17, 2003 12:41:43 PM]"FOUND general/OpenDirectory returned 20 results in 2219ms XTRIM/1.5" 200 0Query/-274877906943 - general/OpenDirectory:processing - [Jan 17, 2003 12:41:46 PM]"FOUND general/OpenDirectory returned 20 results in 2672ms XTRIM/1.5" 200 013.202.222.66 - RmiSurrogate (Client Id:-1 From:13.202.222.66 state:connected)- [Jan 17, 2003 12:42:12 PM] "SHUTDOWN -1 HTTP/1.0" 200 013.202.222.66 - RmiSurrogate (Client Id:-1 From:13.202.222.66 state:disconnected)- [Jan 17, 2003 12:42:12 PM] "DISCONNECT -1 HTTP/1.0" 200 0

Logs Reporting

Note:Additional files that have adapter names can reside in this repository. They aregenerally HTML files, stored when parsing errors occur. They are very useful to adapterdevelopers who can use the information contained in these files to modify the parsergrammar specifications. The administrator should send these files to the developer, sothat appropriate corrections can be made.

Web ServerThe Web Server portion of the page enables you to view the contents of log files in thewww/tomcat/logs directory.

This portion allows you to view the following:• Trace all requests asked by each user and the date of the requests• Trace system interactions and exceptions• Web server jsp/servlets log• Web server access log• Web server internal logThis section describes the first two of the list given above along with examples.• Tracing all requests asked by each user and the date of the requests

Log files of this type enable you to know the requests raised by users and the dateof these requests. For example,13.202.222.66 - 408059A434894443A40655A220653180 [17/Jan/2003:14:35:59 1000]"GET /ecis.jsp HTTP/1.1" - -13.202.222.66 - 408059A434894443A40655A220653180 [17/Jan/2003:14:36:14 1000]"POST /ECIS.jsp?action=search&stringDomains=General&queryId=0&expression=test tool&actionId=-144212945 HTTP/1.1" - -13.202.222.141 - 392825637085E083704288B8D7A412C3 [17/Jan/2003:14:38:19 1000]"GET /ECIS.jsp HTTP/1.1" - -13.202.222.141 - 392825637085E083704288B8D7A412C3 [17/Jan/2003:14:38:25 1000]"POST /ECIS.jsp?action=search&stringDomains=General&queryId=0&expression=Monde&actionId=-2109643409 HTTP/1.1" - -13.202.222.141 - 392825637085E083704288B8D7A412C3 [17/Jan/2003:14:38:41 1000]"POST /ECIS.jsp?action=search&stringDomains=General&queryId=-549755813887&expression=News&actionId=-2109643409 HTTP/1.1" - -13.202.222.141 - 392825637085E083704288B8D7A412C3 [17/Jan/2003:14:38:52 1000]"GET /ECIS.jsp?action=selectCluster&current=15&actionId=817269704 HTTP/1.1" - -13.202.222.141 - 392825637085E083704288B8D7A412C3 [17/Jan/2003:14:39:05 1000]"GET /ECIS.jsp?action=selectClusterStrategy&actionId=817269704 HTTP/1.1" - -13.202.222.141 - 392825637085E083704288B8D7A412C3 [17/Jan/2003:14:39:09 1000]"POST /ECIS.jsp?action=applyClusterStrategy&selected_strategy=title&actionId=817269704 HTTP/1.1" - -…


Logs Reporting

• Tracing system interactions and exceptions

This is used by developers to trace system interactions and exceptions. For example,2003-01-17 13:09:38 Root causextrim.client.i: No session Id valid and no session, you need to login againat xtrim.client.BasicClient.d(BasicClient.java)at xtrim.client.BasicClient.isPersistentAccount(BasicClient.java)at xtrim.jspapi.bean.LoginBean.isPersistentUser(LoginBean.java)at GlobalFrameset._jspService(GlobalFrameset.java:345)at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:107)at javax.servlet.http.HttpServlet.service(HttpServlet.java:853)at org.apache.catalina.core.ApplicationDispatcher.invoke(ApplicationDispatcher.java:679)at org.apache.catalina.core.ApplicationDispatcher.doForward(ApplicationDispatcher.java:431)at org.apache.catalina.core.ApplicationDispatcher.forward(ApplicationDispatcher.java:355)…

Admin Center ServerThe Admin Center Server portion of the page enables you to view the contents of logfiles in the admin/logs/logs directory.

This portion allows you to view the following:• Trace system interactions and exceptions• Web server jsp/servlets log• Web server access log• Web server internal log


Chapter 6Accounts Management

This chapter enables you to monitor and create accounts.

ECI Services supports two kinds of accounts—Shared and Individual Accounts. A shared account canbe used for demonstration purposes or by a group of users, while an individual account is associatedwith a single person. Settings for individual accounts remain intact from session to session. ECIServices automatically saves and restores queries and results, as well as the display setup.

When a new account is created, the administrator provides a default password. Registered usersmight later change the password.

This chapter is categorized into four sections• Locked reasons, page 68• Creating accounts, page 68• Changing passwords, page 69• Deleting account, page 69

Monitoring accountsThis page appears when you click the Account Management link in the Home page. Ittabulates the following account details—ID, Name, LDAP, Queries, and Locked reasons.

ID• This column lists the IDs of the accounts created, These IDs are auto generated. If

the account is checked shared while creating, a minus(-) sign is displayed alongsidethe ID.


Accounts Management

Name• This column lists the names of the accounts created.

LDAP• This column lists the existing user accounts with the LDAP information. The system

automatically identifies the existing user accounts listed from the LDAP directoryand displays them.

LDAP is a compliant directory service. Each user account registered withthis directory service is automatically identified within the ECI Services. Fororganizations with a large number of user accounts, ECI Services can be connected toan LDAP-compliant directory service as this enables you to collect the ECI Servicesuser accounts automatically from the internal directory service.

Queries• This column lists the number of queries.

Locked reasons• This column lists existing user accounts with their locked or unlocked status. When

an account is not closed and saved properly, the locked status shows OUTDATED.

Creating accountsThe Account Management page also allows you to create accounts.

To create an account:

1. Click Create. The Create an account page opens.

2. Type the name and password in the respective boxes.

3. Click Create. The account is created.


Accounts Management

Note: If you want the account to be shared by many users at the same time, then selectthe Shared checkbox before clicking Create. However, their queries are neither savednor restored between sessions.

Changing passwordsTo change the password of the user of an account:

1. Click the respective Change the Pwd link in the Accounts Monitoring table.The New Password screen appears.

2. Type the new password in the box.

3. Click Submit.

Deleting accountTo delete an account

1. Click the Delete link in the Accounts Monitoring table

2. A message box appears asking you to confirm that you really wish to delete theselected account.

3. Click OK.


Accounts Management


Chapter 7Servers Operation

This chapter gives you information to manage the ECI server.

Managing the ECI ServerThe Servers Operation page allows you to stop or restart the server.

You can stop or restart the server by clicking the required link:• Restart ECIS with a graphic user interface• Restart ECIS without graphic user interface• Stop ECIS

Note: If ECIS is running as a Windows services, do not use the stop, start, or restartfeatures.


Servers Operation


Chapter 8Uploading

This chapter describes the tasks you can perform from the Upload page. This page allows you toupload information sources, libraries, and images.

Uploading information sourcesThe first section of the Uploading page is Uploading an Information Source. You canupload two types of information sources in this section—Bundle Information Sourceand New Backend Information Source.

To upload a bundle information source:

1. Click Browse to select the JAR file to upload.

2. Select the target repository (www/wrappers/) from the list.

3. Check the Overwrite box to overwrite the file in the repository.

4. Click Upload.

To upload a new backend information source:

1. Click Browse to select the CONF or PROPERTIES file to upload.

2. Select the target repository (www/wrappers/) from the list.


4. Click Upload.

Uploading librariesYou can upload two types of libraries in this section—Integration Server Library andInformation Source Library.


Uploading

To upload an integration server library:

1. Click Browse to select the JAR or ZIP file to upload.

2. Select the target repository (lib/jars) from the list.


4. Click Upload.

To upload an information source library:

1. Click Browse to select the JAR or ZIP file to upload.

2. Select the target repository (lib/wrapper) from the list.


4. Click Upload.

Uploading imagesYou can upload two types of images in this section—Bundle Information Source andDomain Image.

To upload an image of a bundle information source:

1. Click Browse to select the GIF file to upload.

2. Select the target repository (www/tomcat/webapps/ao/data/sources) from the list.


4. Click Upload.

To upload a domain image:

1. Click Browse to select the GIF file to upload.

2. Select the target repository (www/tomcat/webapps/ao/icons) from the list.


4. Click Upload.


Appendix A

Installing and Conguring NetegritySiteMinder 6.0

This appendix provides information on installing and configuring the Netegrity SiteMinder plug-infor ECI Services. In addition, it provides information on how ECI Services integrates with NetegritySiteMinder. It includes the following topics:

• ECI Services and Netegrity SiteMinder integration , page 75• Netegrity SiteMinder Plug-In configuration, page 76• Troubleshooting Netegrity SiteMinder, page 81

ECI Services and Netegrity SiteMinderintegration

ECI Services supports the standard Netegrity SiteMinder web agent. Therefore, itbenefits from any existing customization of SiteMinder authentication screens. ASiteMinder web agent is installed on an HTTP server, which needs to be installed as afront-end of the ECI client. The supported HTTP Server is Apache 2.

After configuring ECI Services, when a user accesses the ECI interface, the followingevents occur:

1. The SiteMinder web agent authenticates the user.

2. The ECI client sends the authentication token to the ECI server.

3. The ECI server revalidates the token and starts a user session.

4. When a query is performed, the ECI server provides the token to the appropriateadapter.

Note: Not all adapters support Netegrity SiteMinder.


Installing and Conguring Netegrity SiteMinder 6.0

Netegrity SiteMinder Plug-In congurationThis section does not provide detailed information on the Policy Server configuration.Therefore, you need to have fair understanding of the Netegrity SiteMinder installationand configuration. Before performing the steps mentioned in this section, make sure thata SiteMinder Policy Server is already set up.

To install a SiteMinder web agent, you need to set up Policy Server for this new agent.You need to do the following:

• Create or reuse an Agent object with a shared secret.• Create an Agent Conf object (Apache type).• Configure specific domain, realm, policy, and/or rules, as appropriate.

Installing Web Front-End

To install web front-end, complete the following steps:

1. Install Apache HTTPD on an ECI machine. You can install it on another machine ifyour deployment requires it.

The latest stable version of Apache is available at http://httpd.apache.org/. Forcompiling Apache on your machine or for using the provided binary versionsavailable from the web site, see the Apache documentation.

2. Install the SiteMinder web agent on the same machine.

The version of the web agent must be 6 QMR2 or higher. You may want to configurePolicy Server objects to protect resource ‘/’ and sub-directory on this Apache instance(directory, domain, realm, and rule).

Note: You should authorize ‘GET’ and ‘POST’ methods because ECI Services usesboth.

3. Test the connection between Apache and Policy Server by accessinghttp://apachehost:apacheport/.

Installing and conguring ECI Services

This section provides information on connecting Apache to ECI Tomcat. If ECI Servicesis not installed, then you need to install it. You can install ECI Services on the samemachine as the Apache HTTPS server or on some other machine.



The procedure to connect the Apache HTTP server to ECI Tomcat is similar to the loadbalancing setup described in the Enterprise Content Integration Services AdministrationGuide.

The Apache HTTP server should be able to communicate with the Tomcat JSP enginethat hosts the ECI Services JSP standard search client. This is done by plugging a Tomcatmodule into Apache. This module is called mod_jk. In addition to Apache, it supportsmost HTTP servers such as iPlanet and Microsoft IIS.

You can obtain mod_jk from http://www.apache.org/dist/jakarta/tomcat-connectors/jk/binaries/. Verify the current version of Tomcat shipped with ECI Services to ensure thatthe mod_jk you install is compatible with the version of Tomcat you use.

Binary executable versions of mod_jk are available for some platforms (currently Win32,Linux, and NetWare). For more information on configuring different web servers forTomcat, refer to the Tomcat documentation.

The Apache standard httpd.conf file is configured for the local installation and includes aconfiguration file specific to Tomcat. For more information on configuring Apache, referto the Apache documentation.

The httpd.conf file is configured so that mod_jk gets loaded by Apache and handlessome of the incoming HTTP requests. In this context, all the incoming requests arehandled by mod_jk. Therefore, the incoming request are dispatched to the ECI ServicesTomcat JSP front-ends. For more information on configuring Tomcat to run on Apache,refer to the Tomcat-Apache documentation.

To complete the ECI Services configuration, complete the following steps:

1. Perform the following changes in the httpd.conf file:

• Below the "Listen: Allows you to bind …" line, insert the following lines:# Change this to Listen on specific IP addresses as shown below to

# prevent Apache from glomming onto all bound IP addresses (0.0.0.0)##Listen 12.34.56.78:80Listen 3000

• Below "# LoadModule foo_module modules/mod_foo.so", insert the followinglines:

#Load mod_jkLoadModule jk_module modules/mod_jk.so

#Indicate to mod_jk its configuration file and error log file for#diagnosisJkWorkersFile conf/workers.propertiesJkLogFile logs/mod_jk.logJkLogLevel error

• Below the "DocumentRoot" line, insert the following lines:


#Specify which HTTP requests are handled by mod_jk and which “worker”#will process thoseJkMount /*.jsp server1JkMount /servlet/* server1

• Below the "ServerName gives the name and …" line, insert the following lines:# Change this to Listen on specific IP addresses as shown below to

# prevent Apache from glomming onto all bound IP addresses (0.0.0.0)#ServerName <your host name>:3000

2. Verify the mod_jk configuration in the workers.properties file.

The workers.properties file defines a set of workers, which handle incoming HTTPrequests (see the following sample). It is located in the folder containing thehttpd.conf file.

## workers.properties#

# In Unix, we use forward slashes:ps=/

# list the workers by name

worker.list=server1

# ------------------------# First Tomcat server# ------------------------worker.server1.port=8009worker.server1.host=<your host name>worker.server1.type=ajp13

# Specify the size of the open connection cache.#worker.aOserver1.cachesize

## END workers.properties#

The mod_jk module transmits assigned HTTP requests to the Tomcat JSP front-endslocated on server1 through the AJP13 protocol. The ports specified in this filecorrespond to the ports mentioned in the ECI Tomcat server.xml file.

3. To configure both the Tomcat JSP front-ends, perform the following changes to thewww/tomcat/conf/server.xml configuration file in the ECI Services installation:

• Uncomment the directives to support the AJP13 protocol.

<Connector port="8009"enableLookups="false" redirectPort="8443" debug="0"^protocol="AJP/1.3" />

• Near line 100, replace:<Engine name="Stand-alone" defaultHost="localhost" debug="0">

with:<Engine jvmRoute="server1" name="Stand-alone" defaultHost="localhost" debug="0">

• To disable the stand-alone http port, comment the following lines:<Connector port="3000"

maxThreads="150" minSpareThreads="25" maxSpareThreads="75"enableLookups="false" redirectPort="2626" acceptCount="100"debug="0" connectionTimeout="20000"disableUploadTimeout="true" useBodyEncodingForURI="true"/>

4. Test the connection between Apache and ECI Tomcat.

5. Start Apache HTTP server and ECI Services, and access http://apachehost:3000/.

Note: SiteMinder authentication is not linked to the ECI authentication. In other words,even after logging on to SiteMinder, you will be considered a guest user to ECI Services.

Conguring the ECI SiteMinder Plug-In

Conguring the ECI client

To configure the ECI client, complete the following steps:

1. In <ECIS INSTALL DIR>/www/tomcat/webapps/ao/WEB-INF/web.xml, setLOGIN_PAGE_LINK to ‘false’.

2. Uncomment filter definition SSOFilter.

<filter><filter-name>ssoFilter</filter-name><filter-class>xtrim.securityapi.siteminder.client.SSOFilter</filter-class><init-param>

<param-name>cookie</param-name><param-value>SMSESSION</param-value><description>Name of the cookie where to find the ticket.</description>

</init-param><init-param>

<param-name>userNameHeader</param-name><param-value>sm_user</param-value><description>Name of the HTTP header where to find the user name.</description>

</init-param>

</filter>

<filter-mapping><filter-name>ssoFilter</filter-name><url-pattern>/ecis.jsp</url-pattern>

</filter-mapping>

Conguring the ECI server

To configure the ECI server, complete the following steps:

1. In Admin Center, edit the server configuration property xtrim.security.providers.

2. Set its value to xtrim.securityapi.siteminder.server.SiteminderAuthenticationProvider.jdbc.

3. Configure SiteMinder plugin in <ECIS INSTALL DIR>/www/docs/conf/siteminder.conf.

This file contains the configuration of the custom SiteMinder agent running in ECIServer.

POLICY_SERVER_IP=<policy server IP address>AGENT_NAME=<agent object name>AGENT_IP=<ECI server IP address>AGENT_SECRET=<agent shared secret>

POLICY_SERVER_IP should contain the IP address of the SiteMinder policy server.

AGENT_NAME should contain the name of the agent object defined in SiteMinderpolicy server. This agent can be different from the web agent installed.

AGENT_IP should contain the IP address of the ECI Server

AGENT_SECRET should contain the shared secret defined in the agent objectconfiguration.

Note: This requires a specific configuration of the agent, where the secret is manuallyspecified by the policy server administrator.

4. Install the SiteMinder libraries. You should install the SiteMinder SDK (availablefrom the Netegrity support site) based on your platform.

5. From the SiteMinder SDK install dir, copy the following file to <ECIS installdir>/lib/jars:

<SiteMinder SDK dir>/bin/*.dll<Sideminder Install dir>/webagent/bin/smerrlog.dll<Sideminder Install dir>/webagent/bin/smjavaagentapi.dll<SiteMinder SDK dir>/java/smjavaagentapi.jar<SiteMinder SDK dir>/java/smjavasdk2.jarThis completes the ECI server configuration.

6. Start the ECI and Apache servers.

Note: If you encounter any problem, look for the error messages in the ECI Servicesconsole or in the ECI Services server log.

Troubleshooting Netegrity SiteMinderThe following table lists the problems that you may encounter while working withNetegrity SiteMinder. You can troubleshoot the problem by referring to the cause andaction against the pertinent problem.

Table A-1. Troubleshooting Netegrity SiteMinder

Problem Cause Action

FATAL ERROR: Exception fromSystem.loadLibrary(smjavaagentapi)java.lang.UnsatisfiedLinkError: C:\ProgramFiles\netegrity\sdk\bin\smjavaagentapi.dll:The specified procedure couldnot be found FATAL ERROR:Exception from AgentAPI.initialize()java.lang.UnsatisfiedLinkError : initialize

Incor-rectSite-minderDLL isused.

Ensure that you copy thecorrect DLL fromNetegrity.You may have to copy theSiteminder DLL from thewebagent folder instead ofthe SDK folder.

Apache displays a 405 HTTP error on clickingany ECI button after waiting for 10 seconds.

Webagentversionis olderthan 6QMR2.

Update the web agent toversion 6 QMR2 or higher.Before the installation, stopall servers (Apache andECI) that use the agent.

javax.servlet.ServletException: Siteminderplugin is misconfigured, no cookie namedSMSESSION found in the request.

Webagentmaybe dis-abled.

Verify that the web agentis enabled. Check theEnableWebAgent variablein the WebAgent.conffile (normally located in<Apache install dir>/conf).

Appendix B

Conguring and Customizing AdminCenter

The Admin Center is your primary means for administering ECI Services. However, you can alsoconfigure and customize Admin Center through individual files.

CongurationIt is possible to configure Admin Center using the web.xml and the admin.xml files.

web.xml

The web.xml is located into <Documentum ECIS directory>/admin/webapps/WebBasedAdmin/WEB-INF/.

It allows the administrator to modify its login and password.

Login and password

The web.xml is located into <Documentum ECIS directory>/admin/webapps/WebBasedAdmin/WEB-INF/.

It allows the administrator to modify its login and password.

At Documentum ECI Services installation, the login and the password are updated.

Login and password configuration:

Conguring and Customizing Admin Center

Example B-1. Conguration of the Login and Password Parameters in the web.xml

<context-param><param-name>ADMIN_LOGIN</param-name><param-value>admin</param-value>

</context-param><context-param>

<param-name>ADMIN_PASSWORD</param-name><param-value>ecis</param-value>

</context-param>

It allows the administrator to disable the Upload feature.

Upload feature

By default, the administrator can upload files in the admin repository through AdminCenter. Considering security reasons, this feature can be disabled.

Example B-2. Conguration of the Upload feature in the web.xml

<context-param><param-name>ENABLE_UPLOAD</param-name><param-value>true</param-value>

</context-param>

Size of the uploaded le

The size of the uploaded file can be limited with the MAX_FILE_SIZE_UPLOADparameter. Set this parameter to −1 if you do not want any limitation. The unit is kbyte.

Example B-3. Conguration of the Uploaded File Size Feature in the web.xml

<context-param><param-name>MAX_FILE_SIZE_UPLOAD</param-name><param-value>10000</param-value>

</context-param>

Maximum size of the visible part of log les

Log files may become big and it will be very time consuming to view them.MAX_LOGPAGE_SIZE defines the maximum number of byte that we consider to berelevant.

Example B-4. Conguration of the MAX_LOGPAGE_SIZE in the web.xml

<context-param><param-name>MAX_LOGPAGE_SIZE</param-name><param-value>50000</param-value>

</context-param>

Command to launch servers

Only relevant for Solaris and Linux systems. Uncomment the LAUNCH_SERVERS_CMDif you want to define the complete path of the executable to launch servers on solaris andlinux. By default, the OPENWINHOME system property and xterm are used.

Example B-5. Conguration of the LAUNCH_SERVERS_CMD in the web.xml

<context-param><param-name>LAUNCH_SERVERS_CMD</param-name><param-value>/bin/sh</param-value>

</context-param>

admin.xml

The admin.xml is located into <Documentum ECIS directory>/admin/webapps/WebBasedAdmin/conf/. It enable the administrator to:

Define reference to integration server and web server configuration files, such asserver.conf and web.xml, that he wants to configure through Admin Center.

Define reference to integration server and web server log files that he wants to viewthrough Admin Center.

Define file types that can be uploaded and theirs admin repository

Conguration les

By default, a ‘Module’ is defined for the integration server and another one for the webserver. A localized description must be supplied for each of them.

Each ‘Module’ contains severals ‘Item’. An ‘Item’ defines the name and location of aconfiguration file and its localized description. Administrator can remove an ‘Item’ if hedoesn’t want to edit its configuration file. It is not possible to add a new ‘Item’.

Example B-6. Integration and Web Server conguration les setup in the admin.xml

<AdminConfiguration>

…<Group name="conf"><Module><description lang="en">Integration Server</description><description lang="fr">Serveur d’intégration</description><item name="server.conf" path="www/docs/conf"><description lang="en">Options of the 'Integration Server'

(HTTP options, traces, persistent queries options,...)</description><description lang="fr">Options du ‘Serveur d’intégration'

(options HTTP, traces, requêtes persistantes,...)</description></item><item …

Log les

Here is the same structure than configuration files but it is applied to log files.

The administrator can remove/add an ‘Item’ if he doesn’t/do want to view its log file.

Integration and web server log files configuration :

Example B-7. Integration and Web Server log les conguration in the admin.xml

<AdminConfiguration>…

<Group name="log"><Module><description lang="en">Integration Server</description><description lang="fr">Serveur d’intégration</description><item name="trace.log" path="www/logs"><description lang="en">Trace system interactions</description><description lang="fr">Trace les interactions systèmes</description>

</item><item …

Uploaded les

Here is the same structure than configuration files but it is applied to file types that canbe uploaded.

The administrator can remove or add an ‘Item’ if he doesn’t/do want to enable theupload a file type. This feature can be disabled, see the Uploaded files section of web.xmlconfiguration for details.

Example B-8. Uploaded les conguration in the admin.xml

<AdminConfiguration>…

<Group name="Upload"><Module>

<description lang="en">Integration Server</description><description lang="fr">Serveur d’intégration</description><item name="*.conf, *.jar" path="www/wrappers"><description lang="en">Upload an information source </description><description lang="fr">Télécharger une source d’information</description>

</item><item …

CustomizationIt is possible to customize the interface with the colors and text font in the data stylesheets and the home, logo and login pages.

Customization without editing JSP pages

The customization is done by changing styles defined in the style sheet and in a javascriptfile, the logo and colors of pictures.

The style.css is located into <Documentum ECIS directory>/admin/webapps/WebBasedAdmin/data/ and contains almost all styles.

tooltip.script, located into <Documentum ECIS directory>/admin/webapps/WebBasedAdmin/data/xml/xsl/, contains only the definition of tooltip background colors.

Pictures like logo, buttons, …, are located into <Documentum ECISdirectory>/admin/webapps/WebBasedAdmin/data/

When a color is changed in style.css , do not forget to update the colors of picturesincluded the standard JSP client.

Customization editing JSP pages

Home, logo and login pages JSP source pages are delivered. They are simpleand can be easily customized. They are located into <Documentum ECISdirectory>/admin/webapps/WebBasedAdmin/.

They must be compiled by Tomcat as soon as you modify them. You have to stop andrestart Tomcat to take into account your changes and you need to have a JDK.

Here are steps to follow that enable Tomcat to compile them:

1. Add tools.jar (from a JDK) in the classpath of aOAdmin scripts.

Note: You can also copy the tools.jar library in the <Documentum ECISdirectory>/admin/lib repository.

2. Edit web.xml in <Documentum ECIS directory>/admin/webapps/WebBasedAdmin/WEB-INF/ to comment the ‘definition of compiled jsp pages’ and the ‘servletURL-mapping’ for these three JSP (see comments in web.xml).

3. Restart aOAdmin, the jsp pages are compiled by Tomcat. The java and compliedversions are located in the directory <Documentum ECIS directory>/admin/work/

Appendix C

Report Generator

The report generator is used by ECI Services to notify users through an email message when newresults are found by scheduled queries. The default report template is “MailerReport”.

System administrators also use it to create specific report templates.

This document explains to the report designer and the system administrator how to create newtemplates and how to configure ECI Services.

You will note several references to Xtrim and askOnce files or programs throughout this document.Xtrim is the development and runtime foundation of ECI Services (named askOnce previously) andhas been included as part of the file names in many circumstances. For purposes of understanding,you may assume that ECI Server, askOnce and Xtrim are synonymous.

Table C-1. Denition of terms

Term Explanation

RTL Report Template Language.

EBNF Extension of Backus Naur Form. (Alanguage, which describes grammar.)

HTML Hypertext Markup Language.

Template descriptor tree A tree that describes the structure of theReport Template.

The Report Generator can display reports in HTML table format or HTML list format.

Using RTL to create a Report TemplateThe ECI Services Report Template Language (RTL) enables you to generate reports. Thissection describes the RTL that is used to create report templates.


Report Generator

The goal of the report template language is to allow you to easily build customizedreports. The reports will be shown in the user’s mailer, and the order of the results in thereport will be the same as the order on the screen.

By referring to The list of results on page 8 we can see that a single declaration for a resultin the report template controls the display of all results in the generated report.

Main characteristics of RTL

The RTL syntax is very similar to that of HTML. For people familiar with XML/XSLT, RTLserves a similar purpose by being specifically tailored to the generation of mail reports.

Source and target les

The report file, which is generated, is called the “target file”. The file written in RTL iscalled the “source file”. HTML is used to display the report. If the generated HTMLcontains a link to a picture then an offline visualization of the report will not displaythis picture.

In the source file, everything that is not specified in the RTL language is considered asplain HTML and is directly copied into the target file.

Template structure

A template report has four parts: •The header description •The results description •Theseparator description •The footer description Table 1Table 1 shows the tags that separatethe different parts of a program written in RTL. The left column gives a summary of anRTL source file, while the right column lists the parts of the program in which theycan be found.

Table C-2. Template structure

SOURCE FILE PART OF THE FILE

[…]HEADER DESCRIPTION

<LOOP_RES> […] </LOOP_RES>RESULTS DESCRIPTION

Report Generator

SOURCE FILE PART OF THE FILE

<SEPARATOR> […] </SEPARATOR>SEPARATOR DESCRIPTION

[…]FOOTER DESCRIPTION

The separator description is “pure HTML”. In other words, the interpreter will copythis part of the source file to the report file without changing anything. The separatordescription begins with the text and ends with .

Header and Footer description

The header is everything from the beginning of the RTL file up to the tag <LOOP_RES>,which, in fact signals the beginning of the results description. The footer is the part of theRTL file which begins after the </SEPARATOR> tag and ends at the end of the file.

In the footer and header description you can use the following predefined tags to displaythe name, the number of results and the definition of the query: <QUERY NAME>,<QUERY NB_RESULTS>, <QUERY DEFINITION>, <QUERY DATE>, <LOCALE>.

Results description

There are two methods of displaying unknown and known attributes. The first methoduses the attribute’s name, and the second method automatically goes through the list ofthe retrieved attributes.

List of results

The results description is the part of the RTL file which begins with <LOOP_RES> andends with </LOOP_RES>. Between these two tags, the presentation of all results isdefined. The description is repeated for all results.

Displaying an attribute by using its name

To use an attribute’s name as the value that is displayed for that attribute, use the syntax:<ATTR_VALUE NAME = “Attribute’s name” >

Report Generator

Example C-1. List of the results’ titles

<LOOP_RES> The TITLE is: <ATTR_VALUE NAME= ”title”> </LOOP_RES>This example will display the title of each result and each title will be preceded by « TheTITLE is ».

Displaying a message only if a predened attribute has a value

Everything between the tag <IF_ATTR_DEF NAME= “Attribute name” > and the tag</IF_ATTR_DEF> will be generated in the report provided that the attribute entitled“Attribute name” has a value.<IF_ATTR_DEF NAME= “Attribute name” >…</IF_ATTR_DEF>Syntax : the “IF_ATTR_DEF”The following example shows how to avoid having a string like: “The Title is:” withouthaving a title written after it.<IF_ATTR_DEF NAME= “title” ><CENTER> The Title is: <ATTR_VALUE NAME= “title”></IF_ATTR_DEF>

Displaying an attribute without using its name

The Report Template Language enables you to display attributes without using theirnames. The user can ask to go through the list of attributes of a result by using the syntax:<LOOP_ATTR>…</LOOP_ATTR>The description between these two tags will be repeated for all the attributes of thecurrent result. In this part of the template, it is possible to access the name and the valueof the current attribute using <CURRENT_ATTR NAME> and then <CURRENT_ATTRVALUE>.

Furthermore, if the value of an attribute is a URL, the behavior of the generator willchange.

Only between the tag <LOOP_ATTR *> and </LOOP_ATTR>

For example, if the attribute value is http://www.documentum.com, the generated text willnot be http://www.documentum.com when <CURRENT_ATTR VALUE> is encountered.Instead, it will be

Report Generator

<A HREF= “http://www.documentum.com”> http://www.documentum.com </A>. In otherwords, when a URL is encountered, a link is automatically built.

Two additional ways of using the tag “LOOP_ATTR” are provided. In order to excludesome attributes from the list, use the syntax:<LOOP_ATTR EXCLUDE = “ name1, name2, …” >…</LOOP_ATTR>In order to exclude attributes that have already been displayed, use the syntax:<LOOP_ATTR REMAINDERS >…</LOOP_ATTR>The following example shows how to emphasize a title. In this example the title iscentered, bold and in a large point size. All the other attributes are shown as a list andthe keyword attribute is never shown.<LOOP_RES><CENTER> TITLE: <ATTR_VALUE NAME= “title”> </CENTER> <LOOP_ATTR EXCLUDE = “title,keyword” > <CURRENT_ATTR NAME> <CURRENT_ATTR VALUE> </LOOP_ATTR></LOOP_RES>

Grammar

This section describes the full definition of the RTL using EBNF grammar. The syntax isnot case sensitive.templateReport := header

theResults[sepResults]footer

header := General

footer := General

General := html| <QUERY NAME>| <QUERY NB_RESULTS>| <QUERY DEFINITION>| <QUERY DATE>| <LOCALE = "localeName">| <WEBHOST>| <WEBPORT>

Report Generator

sepResults := <SEPARATOR> [html] </SEPARATOR>

theResults := <LOOP_RES>result </LOOP_RES>

result := (definedPart | ifDef)*[theAttributes](definedPart | ifDef)*

definedPart := (html | attrValue )

ifDef := <IF_ATTR_DEF NAME=”nameAttr”>definedPart </IF_ATTR_DEF>

attrValue := <ATTRVALUE NAME=”nameAttr”>

theAttributes := loopAttr defaultAttr+ </LOOP_ATTR>

loopAttr := <LOOP_ATTR>| <LOOP_ATTR EXCLUDE =“exclude”>| <LOOP_ATTR REMAINING >

defaultAttr := ( html| <CURRENT_ATTR_NAME>| <CURRENT_ATTR_VALUE> )

exclude := nameAttr (endList)*

endList := , nameAttr

nameAttr := name of the attribute to display

localeName := name of the ISO locale, e.g., fr

html := some html

Making a new template availableReport templates, for example, MailerReport_en.rtl, are stored in the directory{ECIS}\www\docs\conf.

The default report template is “MailerReport” and is configured in{ECIS}\www\docs\conf\server.conf:4# xtrim.scheduledQueryReport: The name of the default report template## used for notification when scheduled queries are updated.## The real file name will be obtained using the email alert properties## listed in the file client.conf: xtrim.reportTemplatesxtrim.scheduledQueryReport=MailReport

Report Generator

Additional reports that will be proposed to the end-users are listed in the file:{ECIS}\www\docs\conf\client.conf. Each report is designed using a unique symbolicname. Each report is associated to an actual file that also defines its locale.## xtrim.reportTemplates: specifies the list of available reports that can## be used to generate email alerts for scheduled queries## Then for each report, a property is used to select the proper template## (see the Report Template Guide in the documentation)##xtrim.reportTemplates=MailReport,ShortReport,LongReport,FrenchReportxtrim.report.MailReport=MailerReport_en.rtlxtrim.report.FrenchReport=MailerReport_fr.rtlxtrim.report.ShortReport=MailerReportShort_en.rtlxtrim.report.LongReport=MailerReportLong_en.rtlA localized description of each report should be provided in the file:{ECIS}\www\tomcat\webapps\ao\data\i18n\jsp_en.properties.ReportDescription.MailReport=Default mail alertReportDescription.ShortReport=Watch report with changesReportDescription.LongReport=Detailed watch reportReportDescription.FrenchReport=Default mail alert in French

Testing a Report TemplateA script in bin named aORTLTester (for Solaris) and aORTLTester.bat (for PC) allowstesting the added report template in order to check the customization.

Example C-2. List of option available for the Report Template Tester named aORTLTester

RTLTester requires -f filename to be givenusage: RTLTester -d domain -f filename [-o outputFile] [-s query string][-a attribute] [-q pattern] [-dump]domain : the domain of your adapterfilename : the rtl file to parseoutputFile: If you want to generate a report, give here

the name of the file that you want to generate.-dump : choose this option if you want to see the rtl tree.

When the report template is successfully tested, the output is as presented below:

Example C-3. Test of TemplateReport2_fr.rtl (a report template) with aORTLTester on Solaris

./aORTLTester -f ../www/docs/conf/TemplateReport2_fr.rtl--- Starting the rtl file ---...--- Parsing finished successfully ---


Report Generator

Using the Report GeneratorThis topic illustrates how to use the report generator.

The following example describes the TableForm template, which has been chosen togenerate the report given below.

Example C-4. File TemplateReport2

<! --- This file is written in RTL ---><HTML><HEAD><TITLE>The Document Company - Documentum: ECIS</TITLE></HEAD><BODY BGCOLOR='#ffffff' TEXT='#000000' LINK='#0000dd' VLINK='#333388' ALINK='#00gg00'><TABLE WIDTH='100%' CELLPADDING=0 CELLSPACING=0><TR><TD><IMG SRC='/images/source.gif' WIDTH='100' HEIGHT='88'></TD><TD ALIGN=left>KN O W L E D G E B R O K E R</TD><TD ALIGN=right VALIGN=bottom>Xerox Research CentreEurope </TD></TR></TABLE><HR noshade> <CENTER><TABLE WIDTH=75%><TR><TD COLSPAN=2></TD></TR><TR><TD COLSPAN=2 BGCOLOR='red'>Query<query name></TD></TR><TR><TD>Definition :</TD><TD><query definition></TD></TR><TR><TD>Performed :</TD><TD><query date></TD></TR><TR><TD>Nb results :</TD><TD><query nb_results></TD></TR></TABLE><table width=80% border = 3><tr><td><CENTER> TITLE </CENTER></td><td VALIGN=TOP><CENTER>SOURCE</CENTER> </td><td VALIGN=TOP><CENTER>REF</CENTER></td></tr><loop_res><tr><td><attrValue name="title"></A></td><td><attrvalue name="source"> </td><td><A HREF="<attrvalue name="href">"> Go and see 2 </td></tr></loop_res></table></CENTER> <table width=100%><tr><td COLSPAN=3><hr noshade></td></tr>

Report Generator

<tr><td COLSPAN=3>Generated by: <var>ECIS</var> </td></tr><tr><td COLSPAN=3>Copyright © 1996-2004 Documentum Inc. All rights reserved.</td></tr></body></html></table>

Report Generator


Appendix D

Conguring External Databases

This appendix supposes that a database has been installed somewhere in the company network. Theadministrator may want to define a specific user for this database, but this is out of the scope ofthis document.

JDBC database propertiesFor each type of database, there is a static set of properties and a configurable set ofproperties.

The administrator should not modify the static properties. They is an internalconfiguration that specifies the type of database used. These properties are listed below:xtrim.user.useOraclextrim.user.useDBxtrim.user.useRmiJdbcxtrim.user.jdbcClassxtrim.user.useXOPENxtrim.user.primaryKeyLabelxtrim.user.primaryKeyCreateIndexxtrim.user.uniqueLabelxtrim.user.longTypeLabelxtrim.user.binaryTypeLabelxtrim.user.varCharLabelxtrim.user.noCacheLabelxtrim.user.duplicateTupleError

The administrator must modify the configurable properties according to the legacydatabase configuration. These properties are listed below:xtrim.user.jdbcUrlxtrim.user.adminxtrim.user.password

The following option allows you to tune the number of queries stored on the database byuser:



xtrim.user.maxQueriesInContext

The configuration for the different types of databases supported are described below:

MySQL## Configurable properties xtrim.user.jdbcUrl=jdbc:mysql://morgins:1972/ACMEDBxtrim.user.admin=sadminxtrim.user.password=adonf

xtrim.user.maxQueriesInContext=15

## Static propertiesxtrim.user.useDB=Yesxtrim.user.useRmiJdbc=Noxtrim.user.jdbcClass=org.gjt.mm.mysql.Driverxtrim.user.useXOPEN=Yesxtrim.user.primaryKeyLabel=PRIMARY KEYxtrim.user.uniqueLabel=xtrim.user.longTypeLabel=BIGINTxtrim.user.binaryTypeLabel=LONGBLOBxtrim.user.varCharLabel=BLOBxtrim.user.duplicateTupleError=S1009

To connect to an existing MySQL database, congurable properties should be changed:

1. xtrim.user.jdbcUrl must be changed to jdbc:mysql://database_hostname:database_port/database_name.

2. xtrim.user.admin must be changed to the login of a database user that has rights tocreate tables and index.

3. xtrim.user.password must be changed to the password of xtrim.user.admin.Static properties should be set to the values listed above.

Oracle## Configurable properties xtrim.user.jdbcUrl=jdbc:oracle:thin:@chevreuse:1521:ACMEDBxtrim.user.admin=sysxtrim.user.password=mkms


## Static propertiesxtrim.user.useOracle=Yesxtrim.user.useDB=Yesxtrim.user.useRmiJdbc=Noxtrim.user.jdbcClass=oracle.jdbc.driver.OracleDriver



xtrim.user.useXOPEN=Noxtrim.user.primaryKeyLabel=PRIMARY KEYxtrim.user.primaryKeyCreateIndex=Yesxtrim.user.uniqueLabel=xtrim.user.longTypeLabel=NUMBER(38)xtrim.user.binaryTypeLabel=BLOBxtrim.user.varCharLabel=VARCHAR2(1024)xtrim.user.noCacheLabel=xtrim.user.duplicateTupleError=ORA-00001

To connect to an existing Oracle database, congurable properties should be changed:

1. xtrim.user.jdbcUrl must be changed to jdbc:oracle:thin:@database_hostname:database_port:database_name.



SQLServer## Configurable properties xtrim.user.jdbcUrl=jdbc:microsoft:sqlserver://aravis.grenoble.xrce.Documentum.com:1433;DatabaseName=aOContextsxtrim.user.admin=saxtrim.user.password=


## Static propertiesxtrim.user.useOracle=Noxtrim.user.useDB=Yesxtrim.user.useRmiJdbc=Noxtrim.user.jdbcClass=com.microsoft.jdbc.sqlserver.SQLServerDriverxtrim.user.useXOPEN=Yesxtrim.user.primaryKeyLabel=PRIMARY KEYxtrim.user.uniqueLabel=xtrim.user.longTypeLabel=NUMERIC(28)xtrim.user.varCharLabel=VARCHAR(1024)xtrim.user.noCacheLabel=xtrim.user.duplicateTupleError=23000

To connect to an existing SQLServer database, congurable properties must be changed:

1. xtrim.user.jdbcUrl must be changed to jdbc:microsoft:sqlserver://database_hostname:database_port;DatabaseName=database_name.





Downloading the driver for SQLServer

Due to licensing reasons, SQLServer JDBC drivers are not distributed with ECI Services.To use SQLServer, the driver must be obtained from Microsoft and the libraries availablein your ECI Services installation.

Downloading the driver for SQLServer

1. Download the driver from Microsoft site: http://www.microsoft.com/downloads/results.aspx?displaylang=en&freeText=JDBC+driver(Please check the license closelybefore installing the driver).

2. Install the driver (depending on the platform chosen, a .exe file must be launched ora tar file must be uncompressed)

3. Once the driver installed, 3 libraries are available in the driver directory:lib/mssqlserver.jar, lib/msutil.jar and lib/msbase.jar. These 3 libraries must be copiedin the ECI Services installation in the lib/jars directory.

Initialize accounts tablesBefore starting ECI Server, you will need to initialize the accounts tables in the externaldatabase and create default accounts.

1. Use the command aOAccountManager to initialize the accounts tables in the externaldatabase.%> aOAccountManager -initialize

ECIS: progress report mode is onWarning: the initialize command erases all existing accounts.Are you sure you want to proceed? (yes/no):

yes

Account repository successfully created:

The account repository has been updated.ECI Server is now using this updated data.

2. Then create default accounts.%> bin/aOAccountManager –create guest shared


http://www.microsoft.com/downloads/results.aspx?displaylang=en&freeText=JDBC+driver


Type the password askonce for guest account:Account successfully created:

Id:-1 name:guest

Manage accounts with JDBC databaseAccounts are managed the same way as the standard database.

Migrate account from one database to anotherThe database shipped with ECI Services—McKoi—is not adapted to manage manyaccounts. For best performance, it is recommended that you use an external databasewhen more than a hundred account are stored.

To migrate user accounts from a database to another, you should:

1. Define the new server.conf for the database to migrate to. The first section in thisappendix explains how to define specific target databases. Keep the previousserver.conf until the migration is completed. In the example below, the newserver.conf is named server-mysql.conf.

2. The target and source database must be running. If this is not the case and one ofthese databases is McKoi, restart it using aODatabase script.

3. Launch aOAccountManager using the “-migrate” option. The first parameter isthe source database server.conf and the second parameter is the target databaseserver.conf.%> aOAccountManager –migrate ../www/docs/conf/server.conf../www/docs/conf/server-mysql.confDatabase migration started...

Create tables in target database.

Copy logins.104 logins copied.

Copy accounts.104 accounts copied.

Copy queries.2,004 queries copied (0 skipped).

Migration has been successful



4. Now, replace the old server.conf with the new configuration file (server-mysql.confin our example).

5. Restart ECI Server to take the new database into account.The target and source database can be any database among McKoi, My-SQL, SQL Serverand Oracle. Using McKoi as both target and source database, it is possible to compact thedatabase (However, 2 aODatabase script must be launched in 2 different environments).


Appendix E

Load Balancing (Optional)

*The load-balancing feature is available only for the ECI Services Enterprise release.

ECI Services Office distribution provides ways to tune the system in order to provide high loads witha single host machine. See for a precise description of the “xtrim.brokers” property.

In addition, the Enterprise version of ECI Services ships with a load-balancing mechanism designed toincrease the load supported by ECI Services system. It is designed to distribute the load over differentmachines. Therefore, by adding new hardware, administrators are able to set up a system thatsupports a much higher load in terms of number of concurrent requests, and number of connectedusers. The mechanism provided by ECI Services makes an ECI Services load-balanced Enterprisesystem appear not different from a standard single host office server.

ECI Services is based on a modular three-tier architecture:• HTTP front end (web server and Tomcat)• ECI Server• User databaseThis modular architecture lets administrators distribute and replicate the HTTP and ECI Servercomponents in order to make best usage of available computing and networking resources. To makethe system look consistent, the user database must not be duplicated (ECI Services user database donot yet support being duplicated and preserving a synchronized state). Since ECI Services supportsdifferent operating systems, each component can be distributed JDBC of the supported platforms(currently, Windows NT/2000, Solaris and Linux). The exact architecture of a load-balanced systemis highly dependent on the available computing and networking resources. However, a typicalexample is presented in the next section.

Example E-1. Typical load-balanced system on Solaris platformIn this example, the network bandwidth of the host (called ‘server1’) is largely sufficient, and thefactor limiting the scalability of the system is the amount of CPU and memory available. Therefore, anew bigger machine (called ‘server2’) is added to the system in order to split the load between thetwo machines. The HTTP server visible to end users is an Apache Web Server configured with the“mod_jk” module, which distributes the load to the two JSP engines (Tomcat) distributed on each host.



Disclaimer: the configuration files provided as part of the sample example should notbe used as-in in a production environment. Especially, they should be made secure byremoving all unnecessary modules or features and patching any known security holes. SeeApache and Tomcat documentation for more details about this. Good starting points arehttp://httpd.apache.org/docs/misc/security_tips.html and more generally http://www.cert.org/

The figure below the following procedure presents the distribution of components over bothmachines. The white boxes represent processes, the arrow represent inter-process networkcommunication, and the two blue boxes represent the different computers. For each process weindicate the bound TCP ports.

Note: On the presented example, the ‘server2’ machine albeit being bigger, is less available than thededicated ‘server1’ (that is, it is more often restarted, can be dedicated to other uses) Consequently,the critical components were installed on the more stable server1 (that is the Apache HTTP front endand the user database components).

Let’s describe in a bit more details how the system would dispatch the load onto the twoserver computers:

1. The end-user browser makes a login request from the URL http://server1:3000

2. The Apache process handles it, and randomly assign either server1 or server2 toprocess the request. Since server2 is a bigger machine, the load-balancing modulewas configured to send twice as many requests to server2 as to server1.

3. Let’s say that server1 gets assigned the request by the load-balancing module.Apache Web Server requests the Tomcat process running on server1 to processthe request. This is done through a special protocol called AJP13 (Apache JakartaProcotol 1.3). The http request is processed by the JSP pages hosted by Tomcat. Thelogin request is sent to ECI Server on the same host through RMI.

4. ECI Server receives the request through RMI, checks that nobody is already loggedin on the server 1 with that same account, and then checks the database. The username and passwords are checked, and in addition the database can indicate whetheranother ECI Server currently handles requests for that same account. If not, theuser is logged in.

Let’s now focus on the installation steps to get this load-balanced ECI Services system. All of thefiles described in this example are available in the ECI Services distribution under the directoryinstall/apache/.

In a first step, we configure two distinct ECI Servers to share the same user database.

First we install two separate ECI Services standard installations on both machines. In our case,the installation on server1 is installed in a directory called “/directory1/ECISServer1” while theinstallation on server2 is on “/directory2/ECISServer2”.

Note: In our cases those files are installed on a networked file system, they could perfectly beinstalled on a local drive.


Then we install an ECI Services enterprise license into the root of the ECI Services installationdirection. See section 2.4 on page 9 for more details about installing ECI Services license files.

We do not use the default database McKoi which is not advised to Enterprise solutions.We supposethat a MySQL database has been installed somewhere in the company network. See section “JDBCdatabase properties:” for more details about configuring the server.conf file to communicate with aMySQL database. In this sample, server1 and server2 use the same database, so the xtrim.user.jdbcUrlproperty located in the server.conf of the server2 must be the same that the xtrim.user.jdbcUrlproperty located in the server.conf of the server1.

The Enterprise license of ECI Services enables ECI Servers to synchronize their use of the userdatabase. In a system with many ECI Servers, each user session is assigned to a unique ECI Server.Consequently, if another client requests to start a new session using that same persistent account, it isredirected to the server currently managing the existing user session. Then, this server handles thenew login request managing busy logins as it the system were a single server system.

Once the license authorizes the enterprise mode, we enable the multi-server mode in the server.conffile of the both installations as shown below.# xtrim.server.multiServerMode (true/false): Controls whether the# system is configured to use multiple servers in a load-balanced# settings (applies only to the Enterprise release).# default: falsextrim.server.multiServerMode=true

We can now start the user database, ECI Server on server1 and server2, and then check that theyshare the same user database.

We start the user database separately to avoid that it gets automatically stopped if the server onserver1 stops. This makes the whole system more tolerant but requires a bit more administration(starting and stopping the user database manually).

Then we can start ECI Server on server1 and server2. Since the user database was already started wespecify the -nodb option to the aOStart launch script.

Example E-2. Starting ECI Server on server1

server1:/opt/[…]/ECISServer1> ./bin/aOStart –nodb &<ao> ECIS account repository ready!> starting the ECIS search server(com.Documentum.ECIS.rmiApi)...<svr> -----------------------------------------------------------<svr> ECIS - V4<svr> -----------------------------------------------------------<svr> Please wait while ECI Server is starting...<svr><svr> ECIS: progress report mode is on<svr> Loading adapters and preparing client-side configurations<svr> for each supported locale...<svr> All adapters loaded. The server is now starting.<svr> <Developer version> for customer: Documentum - MKMS with expiration<svr> date: <none> and server Id: <undefined Id (shared)><ao> ECIS search server (com.Documentum.ECIS.rmiApi) ready!<ao> starting the ECIS web front end (2828)...<jsp> Starting service Tomcat-Stand-alone

<jsp> Apache Tomcat/4.0.6<ao> ECIS web front end (3000) ready!<ao> ready!<jsp> Starting service Tomcat-Apache<jsp> Apache Tomcat/4.0.6

Example E-3. Starting ECI Server on server2The start of ECI Server on server2 is different than the server1. We start the Tomcat and the aoServerseparately.server2:/opt/[…]/ECISServer2> ./bin/aOTomcat

server2:/opt/[…]/ECISServer2> ./bin/aOServer

To check that both servers share the same database, we create an account using the aOAccountManageron the server1’s machine and verify that this account is listed by the same tool on the server2 machine.server1:/opt/[…]/ECISServer1> ./bin/aOAccountManager –create testOnServer1

Type in the password to assign to account testOnServer1:testAccount successfully created:Id: 1 name: testOnServer1The account repository has been updated.ECI Server is now using this updated data.

server2:/opt/[…]/ECISServer2> ./bin/aOAccountManager –list

List of available accounts:Account Id: -1 name: guestAccount Id: 1 name: testOnServer1 (number of queries:0 )

So we now have two ECI Servers sharing the same database and coordinating to handle incomingclient requests. The problem is that to end users, this still appears as two distinct servers. We make itnow look as if this was a single system by appending a load-balanced HTTP server as a single entrypoint to the system. In this example, we chose to use the Apache open-source server.

The latest stable version of Apache is available at: http://httpd.apache.org/ See Apache documentationon how to compile Apache for your machine, or use the provided binary versions available fromthe web site.

Then the Apache HTTP server needs to be able to communicate with the Tomcat JSP engine that hoststhe ECIS JSP standard search client. This is done by plugging a Tomcat module into Apache. Thismodule is called mod_jk and supports most HTTP servers in addition to Apache (such as Iplanet ones,and Microsoft IIS). Mod_jk can be obtained from http://jakarta.Apache.org/tomcat/index.html. Checkthe current version of Tomcat shipped with ECI Services (4 as this document is being written) to makesure that the mod_jk you install is compatible with the version of Tomcat you use. Some binaryexecutable versions of mod_jk are available for some platforms (currently win32, Linux and netware).For convenience, ECI Services provides a binary executable of mod_jk as a dynamic library compiledfor Apache version 2.0.x configured to load dynamically its modules on the Solaris 8 platform. Thiscompiled library is named “mod_jk_406_apache_2042.so” on the ECI Services distribution and is


placed in the libexec/ directory of the Apache installation. Refer to Tomcat documentation for moredetails about configuring different web servers for use with Tomcat.

The Apache standard httpd.conf file is configured for the local installation and includes aconfiguration file specific to Tomcat. Refer to the Apache documentation for more details aboutthe configuration of Apache.

We configure httpd.conf file so that mod_jk gets loaded by Apache, and handles some of the incomingHTTP requests. In our cases, all the incoming requests are handled by mod_jk and thus dispatched tothe ECI Services Tomcat JSP front ends. Refer to the Tomcat-Apache documentation for more detailsabout how to configure Tomcat to run on Apache. Below the "Listen: Allow …" line, insert thefollowing two lines:# Change this to Listen on specific IP addresses as shown below to# prevent Apache from glomming onto all bound IP addresses (0.0.0.0)##Listen 12.34.56.78:80Listen 3000

Below "# LoadModule foo_module modules/mod_foo.so", insert the following lines:#Load mod_jkLoadModule jk_module modules/mod_jk_406_apache_2042.so

#Indicate to mod_jk its configuration file and error log file for#diagnosisJkWorkersFile conf/workers.propertiesJkLogFile logs/mod_jk_406_apache_2042.logJkLogLevel error

Note: You must change mod_jk_406_apache_2042.so to mod_jk_406_apache_2042.dll for Windows.

Below the "DocumentRoot" line, insert the following lines:Specify which HTTP requests are handled by mod_jk and which “worker”#will process thoseJkMount /*.jsp loadbalancerJkMount /servlet/* loadbalancer

Below the "ServerName gives the name and …" line, insert the following lines:Change this to Listen on specific IP addresses as shown below to# prevent Apache from glomming onto all bound IP addresses (0.0.0.0)#ServerName server1:3000

The mod_jk is configured in the workers.properties file that defines a set of workers, which handlesincoming HTTP requests.## workers.properties#

# In Unix, we use forward slashes:



ps=/

# list the workers by name

worker.list=aOserver1,aOserver2,loadbalancer

# ------------------------# First Tomcat server# ------------------------worker.aOserver1.port=8009worker.aOserver1.host=server1worker.aOserver1.type=ajp13


## Specify the load balance factor when used with# a load balancing worker.# Note:# ----> lbfactor must be > 0# ----> Low lbfactor means less work done by the worker.worker.aOserver1.lbfactor=1

# ------------------------# Second Tomcat server# ------------------------worker.aOserver2.port=8009worker.aOserver2.host=server2worker.aOserver2.type=ajp13


## Specify the load balance factor when used with# a load balancing worker.# Note:# ----> lbfactor must be > 0# ----> Low lbfactor means less work done by the worker.worker.aOserver2.lbfactor=2

# ------------------------# Load Balancer worker# ------------------------

## The loadbalancer (type lb) worker performs weighted round-robin# load balancing with sticky sessions.# Note:# ----> If a worker dies, the load balancer checks its state# once in a while. Until then all work is redirected to peer# worker.worker.loadbalancer.type=lbworker.loadbalancer.balanced_workers=aOserver1,aOserver2


## END workers.properties#

The mod_jk module transmits assigned HTTP requests to the Tomcat JSP front ends located onserver1 and server2 through the AJP13 protocol. The ports specified in this file correspond to theones presented in the Architecture of the load-distributed system diagram. Then both Tomcat JSP frontends (parts of ECI Services installation) are configured by editing the www/tomcat/conf/server.xmlconfiguration file in the ECI Services installation. Uncommenting the directives presented below tosupport the AJP13 protocol on the ports specified.

<Connector className="org.apache.ajp.tomcat4.Ajp13Connector"

port="8009" minProcessors="10" maxProcessors="100"acceptCount="50" debug="0"/>

Near Line 100, replace:<Engine name="Stand-alone" defaultHost="localhost" debug="0">

with:<Engine jvmRoute="aOserver1" name="Stand-alone" defaultHost="localhost" debug="0">

Note: For server2, put jvmRoute="aOserver2"

To disable the stand-alone http port, comment following line:<ConnectorclassName="org.apache.catalina.connector.http.HttpConnector" port="3000"minProcessors="10" maxProcessors="100" acceptCount="50" enableLookups="true"redirectPort="2626" debug="0" connectionTimeout="60000"/>

ECI Server must know the HTTP host and port of its web front end in order to support “documentaccess gateway” feature (also called embedded object display). Edit the server.conf of server2 andset xtrim.jsp.host and xtrim.jsp.port properties.xtrim.jsp.host=server1## xtrim.jsp.port: The port on of the ECIS web front end.# default: 3000xtrim.jsp.port=3000

And Let’s now start Apache, if it is done successfully, many http processes are launched as shownbelow, and the Apache logs file do not display any error message.

server1:/opt/[…]/apache/bin>./ startupApache.sh

server1:/opt/[…]/apache/bin>ps –ffromea 11968 11956 0 15:32:11 ? 0:00 /opt/Misc/apache_1.3.12/bin/

httpd -f /opt/buildXtrim/Xtrim/kbserver/apache/conf


fromea 11965 11956 0 15:32:10 ? 0:00 /opt/Misc/apache_1.3.12/bin/httpd -f /opt/buildXtrim/Xtrim/kbserver/apache/conffromea 12102 11956 0 15:33:08 ? 0:00 /opt/Misc/apache_1.3.12/bin/

httpd -f /opt/buildXtrim/Xtrim/kbserver/apache/conffromea 11956 1 0 15:32:10 ? 0:00 /opt/Misc/apache_1.3.12/bin/






httpd -f /opt/buildXtrim/Xtrim/kbserver/apache/conf

server1:/opt/[…]/apache/bin>cat ../logs/ /httpd.log[Mon Mar 5 15:32:11 2001] [notice] Apache/1.3.12 (Unix) mod_jk configured-- resuming normal operationsserver1:/opt/[…]/apache/bin>ls –al ../logs/mod_jk.log-rw-rw-r-- 1 fromea mkms 0 Mar 5 15:32 ../../apache/logs/mod_jk.log

Then we’re ready to test the full system by making HTTP requests to server1 Apache Web Serverrunning on the port 3000. To make sure that the mod_jk load-balancing mechanism works properly,we stop the server2 ECI Services system by closing the GUI console. This way we can make sure thatApache redirects requests to the ECI Services system running on server1. Then, we stop the ECIServices system on server1 (without stopping the database, just by exiting the server GUI console) andcheck that now Apache prints an error for every incoming request. Then we restart the ECI Servicessystem on server2 and check that Apache now redirects requests onto server2.

As described in the test above, the mod_jk load balancing would handle the fact that one of the twoservers is unavailable and not redirect requests to it. Concerning how requests parts of the samesearch session are redirected, the mod_jk modules makes use of the session tracking mechanism setupby the Tomcat JSP front end (usually cookies) to detect that a session was established and routeincoming requests to the JSP front end that initiated the request.

A more visual test that can be performed to verify that the load-balancing system dispatches requestsas expected is to create dummy test HTML files that indicate the name of the server on which they areinstalled. These dummy HTML files can then be placed on the www/tomcat/webapps/ao/ directory.Then using a fresh browser (that is, one on which no session cookie was assigned previously) youshould see that the test HTML page is randomly returned either by server1 or by server2.



A typical load-balanced system on a Windowsplatform

The same example can be setup for the Windows platform using the Microsoft IIS HTTPserver. The first step to have two ECI Servers shared the same database is unchanged onthe windows platform. What differs is the installation of the mod_jk module into the IISserver to be able to provide a single HTTP entry point to the load-balanced system.

The full reference for installing mod_jk on IIS is available from the Jakarta web site at thefollowing URL: http://jakarta.apache.org/tomcat/tomcat-4.0-doc/config/ajp.html

It is recommended that you follow the above documentation step by step. Specialcare should be given to case of strings, and restarting the machine to see the effect ofmodifying files loaded by the isapi_redirect.dll library (restarting IIS was not alwayssufficient to have the updated file be taken into account).

Example E-4. Sample uriwokermap.properties le

# Mount the Servlet context to the ajp13 worker/servlet/*=ajp13

Advanced load-balancing congurationThe modular and distributed architecture of ECI Services lets administrators configuretheir ECI Services system to meet their need. Different architectures can be setup toanswer to specific needs. For instance, the same computer can host more than a ECIServer, a computer could also host a single component (instead of the two HTTP frontend and ECI Server components).

Many combinations are possible and should be driven by objectives and tuning.Choosing the right combination in a given context is outside of the scope of thisdocument. Please contact your Documentum sales person to get an ECI Services expertto provide support and consulting on these advanced configuration tasks.

Following is a short list of the properties can control how each component of an ECIServices system is connected with the other ones.

The JSP standard client hosted by Tomcat JSP engine communicates with ECI Serverthrough RMI. RMI is a protocol that lets ECI Services components call each other fromthe network (the implementation used by ECI Services is based on TCP). The JSP clientcomponent finds the RMI “address” (also called reference) of ECI Server by looking it upby its name into a registry called the RMI registry.



The properties that control these settings are defined in the www/tomcat/webapps/ao/WEB-INF/web.xml file, in the RMI_REGISTRY_HOST, RMI_REGISTRY_PORT,ECIS_RMI_NAME

ECI Server must know the HTTP host and port of the JSP front end in order to support“document access gateway” feature (also called embedded object display). Theembedded object display is implemented in the JSP front end.

The properties that control these settings are defined in the www/docs/conf/server.conffile, and are named xtrim.jsp.host, and xtrim.jsp.port.

ECI Server must access the user database. By default, the user database is the McKoidatabase accessed through JDBC over RMI. Consequently, ECI Server must access theRMI registry in which the user database is registered.

The property that control access to the database is defined in the www/docs/conf/server.conf file, and is named xtrim.user.jdbcUrl.

The user database can work as a stand-alone component; it does not need to know aboutany other document. The only requirement is that it needs to be launched using validinstallation scripts (since it needs to have access to the classes of the components makinguse of it: some ECI Server classes).

At least one RMI registry component is necessary on each computer that hosts an ECIServer or a user database. Both ECI Server and user database handle the creation andshutdown of the local RMI registry as needed.

It is highly recommended to perform a full ECI Services installation on each computerthat should host any of the ECI Services components. It is not advised to only copysome files or to share network installation of ECI Services as the configuration files areedited at the installation time with the name of the computer on which the installationwas performed.

The recommended way to launch stand-alone components (such as the database) is touse the individual scripts available in the bin directory of the ECI Services installation.

The recommended way to launch a set of components (such as a JSP front end andECI Server components) is to use the bin/aOStart script and use the available optionsto pick which component should not skipped. Figure 24 lists the options available inthe aOStart script./>./bin/aOStart –husage: aOStart [-noRegistry] [-noDatabase | -nodb] [-noSearch] [-noWeb] [-d path]

[-l language]



Troubleshooting load-balanced systemsThis section lists the most common problems that can be encountered and explainshow to solve the problems.

Table E-1. Troubleshooting load-balanced systems

Symptom Diagnosis strategy Possible cause Resolution

One of thecomponent refusesto start with amessage such as:

“ FATAL:java.net.BindException:Address already inuse”

or

“unable to bindsocket port 3000”

or

“another RMIregistry is alreadyregistered on port2992”

Check the networkconfiguration of thecomponent.

Check that noprevious instance ofthat component isstill running on themachine, therebylocking the port.

Check that no otherprocess on themachine is alreadyusing the same port.

This componentnetworkconfiguration isincorrect.

Check that thedefined TCPport are notoverlapping withanother componentreserved ports.

The configured portis not available onthe host computerbecause it is usedby an unrelatedprocess (such as asystem daemon).

Fix the invalidconfiguration.

Stop the oldprocesses.

ECI Server refusesto start displayingthe followingmessage:

“xtrim.server.b.i:Impossible toregister with localRMI registry. Thename rmi://13.202.220.73:2992/com.Documentum.ECIS.rmiApi is alreadybound.”

The RMI registryhas already anobject registered forthe reserved nameby ECI Server.

The server was notproperly stoppedand could notunregister fromthe RMI registry.

Two servers areconfigured torun on the samecomputer withthe same RMIregistration name.

Restart the databasewhich hosts theRMI registry.

If a single ECIServer must beconfigured to runon the computer,set the xtrim.server.rmi.forceBindingproperty inserver.conf toTRUE.

Edit the xtrim.server.rmi.



Symptom Diagnosis strategy Possible cause Resolution

bindingNameproperty of one ofboth ECI Serversthat share thesame computerto have differentregistration names.

A user accountappears a busywhereas to clientseems connectedwith that account.

Use the “aOAc-countManager –list–locks” commandto list the availableaccounts and bywhich client theaccount is used

The aOServerwas not properlyshutdown and thuscould not mark inthe user databasethat the user isnot logged in anylonger.

Retry to login, pos-sibly by forcingthe login. Use the“aOAccountMan-ager –list –locks”command to re-move outdatedlocks

The queries of auser account are notupdated at night

Scheduled queriesare not updatedwhen a user islogged on withthe account of thescheduled queries.Check symptom“The queries of auser account are notupdated at night”

The aOServerwas not properlyshutdown and thuscould not indicatein the user databasethat the user isnot logged in anylonger.

The load-balancing support in ECI Services is currently limited by its lack of centraladministration: central monitoring and server administration tasks. Until supportgets developed for those needs, administrator must monitor and administrate eachcomponent or group of components individually.


Appendix F

Troubleshooting with Admin Center

Use this section for manual configuring in case the service does not start.

To manually add a new backend:

1. Get the administrator to create a backend configuration file (e.g.www/wrappers/acme/ExternalDocuShare.conf) that describes the technical aspect ofyour information sources (network location and parameters) and that associates itwith the corresponding standard adapter. For instance, to add your local DocuSharedocument server running on the host http://docuShare.acme.com the administratorcreates a backend file reproduced below. The Adapter Installation Guide has more onadding other types of standard information sources.bundle=core/Docushare.jarhost=docuShare.acme.com

# Geographical location: Rochester, NY, USA Lat, Lon: 43.169, -77.616# Note: thanks to UIUC (http://cello.cs.uiuc.edu/cgi-bin/slamm/ip2ll/)# for the IP address to Latitude/Longitude servicelocation=38,-75

2. You can carefully edit the www/docs/conf/domains.conf file and check the adapterbackend created by the administrator as shown below:xtrim.domains=JSP

xtrim.domain.JSP=Acme,General,Press,Tech,International

xtrim.domain.Acme=acme/marketingDocuShare, acme/financeDocuShare,acme/ExternalDocuShare[…]

3. Create a backend description file to describe the information source and how to use it.This results in creating a file named www/wrappers/acme/DocuShare_en.propertieswith the content below.description=DocuShare repository for ACME headquarter based in Grenoble, France


Troubleshooting with Admin Center

4. Update the domainDescription_en.properties file with a description for the newlycreated acme domain

DomainDescription.Acme=Local sites for the whole Acme headquarters(public site, marketing intranet, and finance intranet)

5. Optionally, create a customized image for this source. To do this, youcan use your favorite image editor to create a 50*50 pixels image. Youcan change this size but the ratio between height and width should bekept under 2 for best display. Then, save your image into the Tomcatapplication directory: www/tomcat/webapps/ao/data/sources, with the name:source-<your_backendName>.gif if the property “image” of the backend was leftunchanged. Otherwise ask the administrator to define this property to the name ofyour modified image.

6. Ask the administrator to restart your ECI Server. The next client to connectautomatically sees the updated information source hierarchy.

Appendix G

More Troubleshooting

This appendix deals with the following issues:• Testing the communication with a backend, page 119• Troubleshooting adapter backend configurations, page 122• Incorrect proxy configuration, page 123• Getting status information on server internals, page 124• Handling low memory conditions, page 125• Handling low memory conditions, page 125• Server with an external name different from the default machine name, page 127

Testing the communication with a backendIt is possible to test the network connection with a backend using the commandaOWrapperTester:usage: AdapterTester -n <backend> [-a <attribute> -q <pattern>] [-s <query string>][-login <backendLogin> <>] [-p <home path>] [-silent] [-empty] [-loadingtrace][-CLIRSourceLanguage <sourceLanguage>]-n <backend> the fully-qualified name of the backend,

e.g., general/AltaVista-a <attribute> the attribute to search against,

e.g., title, body, "full-text"-q <pattern> a boolean expression the search attribute

should match e.g., "knowledge and sharing"-s <query string> a complex search expression combining multiple

attributes e.g., "{title,contains,'billy'}{keyword,equals,'novel'}{date,after,'1997-07-20'}{price,<,'29'}"

-login <backendLogin> <backendPassword> name and password to useduring logon step (simulate search with access control)

-valid Validate the property for the client side.-loadingtrace Show all the properties find in the configuration file

of your backend.-CLIRSourceLanguage <sourceLanguage> Enable the query translation in

the backend language. <sourceLanguage> must specify the language of the query.

Additionnal options for developers of adapters[-p <path>] [[-local/-localArchive/-fetch/-fetchArchive] -f <filename>][-tokenArchive <token> -z <zipname>] [-embeddedArchive -z <zipname> -d<dirname>] [-silent] [-empty]-p <home path> root directory containing the configuration files,e.g., C:\ecis\www\docs

-local test the first-level of the results usinga sample HTML file available locally

-fetch collect a sample HTML file(to be used with option -local)

-localArchive test the results recovering using a set of sample HTMLfiles organized by level

-fetchArchive collect a set of sample HTML files (to be usedwith -localArchive) and organized them by level

-f <filename> name of the file used to load from or to store tothe results of a search, e.g., test/knowledge.html(option -local), test/sharing.zip (option -localArchive)

-silent do no print performance information.-empty no results are expected from this test search.-loadingtrace print loading information of bundles and backends-tokenArchive <token> -z <zipname> collect a set of sample token

files (to be used with -embeddedArchive) and organized them by result number.-embeddedArchive -z <zipname> -d <dirname> test the adapter using

a set of sample embedded tokens organized by result number.e.g., <zipname>=test/tokens1.zip

-z <zipname> name of the zip archive file used to load fromor to store the embedded tokens,e.g., test/tokens1.zip (options -tokenArchive,-embeddedArchive)

-d <dirname> name of the file used to store tothe embedded objects,e.g., test/embeddedobject (option -embeddedArchive)

-emptyToken no tokens are expected from this test embedded objectrecovering.

-iterate <number> execute multiple time the search sequenceallow to see cleanUp is well performed.

-stopAfter <number> stop the current executed adapter after<number>ms allow to test if the adapter really stop

####################DESCRIPTION##############-n option is mandatory#############################################

For example, to send a query to the source AcmeDocushare, run the following command:aOWrapperTester –n acme/AcmeDocushare –a author –q conan

The following results are displayed:

acme/Docushare: search results =1: [source = Doc-XRCE] [title = Meeting Minutes - February 16th, 1999][summary = ] [abstract = ] [keywords = KB Xtrim] [owner_href =http://docushare.acme.com/ViewProps/User-42] [author = conan][owner = conan] [date = 1999-03-01] [last_modified_date = 1999-03-01][site = docushare.acme.com] [href = http://docushare.acme.com/Get/


File-2245/WeeklyMeeting.htm] [type = text/html] [size = 6K][collection_href = http://docushare.acme.com/View/Collection-527][collection = Internal Meeting Minutes]2: [source = Doc-XRCE] [title = Meeting Minutes - January 12th 1999][summary =] [abstract = ] [keywords = KB Annual Plans] [owner_href =http://docushare.acme.com/ViewProps/User-42] [author = conan][owner = conan] [date = 1999-01-19] [last_modified_date = 1999-01-19][site = docushare.acme.com] [href = http://docushare.acme.com/Get/File-2017/WeeklyMeeting.html] [type = text/html] [size = 6K][collection_href = http: //docushare.acme.com/View/Collection-527][collection = Internal Meeting Minutes]3: [source = Doc-XRCE] [title = KB Adapter Service Specification(PS version)] [summary = ] [abstract = ] [keywords = adapter serviceranking summarization query language sumbsumption] [owner_href =http://docushare.acme.com/ViewProps/User-42] [author = conan][owner = conan] [date = 1999-01-08] [last_modified_date = 1999-01-08][site = docushare.acme.com] [href = http://docushare.acme.com/Get/File-1954/WS.ps] [type = application/postscript] [size = 996K][collection_href = http://docushare.acme.com/View/Collection-524][collection = Adapter Service]

Note: The aOWrapperTester tool displays the number of discarded results (usuallybecause they were returned by the source but not matching the query constraints), butnot the content of those results. In some cases, it might be interesting to know why thoseresults were discarded. In these cases, use the “filter” property in the adapter backendconfiguration file to temporary disable the filtering on the source. Then all results aredisplayed. By comparing the list of results when filtering is enabled or disabled, you candeduce which results where discarded.

For Web sources, it is possible to get a trace of the HTTP protocol using the secondcommand aOVerboseWrapperTester.aOVerboseWrapperTester –n acme/AcmeDocushare –a author –q conanECIS: progress report mode is onECIS: debug adapter mode is on [C:\ECIS\www\logs]ECIS: redirect logs to consoleConn: Creating Socket: docushare.acme.com:80Demux: Initializing Stream Demultiplexor (2027311)Demux: Timeout Thread[SocketTimeout-1-2027311,10,main] starting (2027311)Conn: Sending Request:

POST /ApplySearch HTTP/1.1Host: docushare.acme.comConnection: Keep-Alive, TETE: gzip, deflate, compress, chunkedUser-Agent: ECIS (Documentum Research Centre Europe; Java-1.1.6; October 1997) RPT-HTTPClient/0.3Accept-Encoding: gzip, deflate, compressContent-type: application/x-www-form-urlencodedContent-length: 400

Demux: Opening stream 2027111 (Thread[main,5,main])Conn: Request sentResp: Reading Response headers 2027111 (Thread[main,5,main])Demux: Setting timeout to 390000 ms


Resp: Parsing Response headers from Request "POST /ApplySearch": (2027111) (Thread[main,5,main])

Troubleshooting adapter backendcongurations

Some configuration mistakes in adapter backends might be subtle sometimes (suchas a typing mistake made in a file name). Therefore the ECI Services adapter testingtool (described in section 6.2) provides a diagnosis mode. To troubleshoot invalidconfiguration of an adapter bundle, use the aOWrapperTester command using the“–loadingtrace” as shown below:aOWrapperTester –n acme/AcmeDocushare -loadingtrace

This displays the following traces helping you understand which files were loaded inwhich order and point the problem out.| Load the explicit backend <Doc-Public> in:C:\ECIS\www\adapters\core\

docushareBackends\Doc-Public.conf.| Load CONF : C:\ECIS\www\adapters\core\docushareBackends\Doc-Public.conf| ___________________________________________________________| | <bundle>=<core/DSWebDAV.jar>| | <image>=<docushare>| | <location>=<41,-78>| | <host>=<docushare.Documentum.com>| |___________________________________________________________| ___________________________________________________________| | Load the bundle <DSWebDAV> in:C:\ECIS\www\adapters\core\DSWebDAV.jar.| | Load class :custom/core/DSWebDAV/

DSWebDAVTranslator.class| | Load class :custom/core/DSWebDAV/rule/

LogonParser.class| | Load class :custom/core/DSWebDAV/DSWebDAV.class| | Load unlocalized properties file:custom/core/DSWebDAV/DSWebDAV.conf| | ___________________________________________________________| | | <Collection.ViewCommand>=</dscgi/ds.py/View>| | | <supportsLogin>=<true>| | | <trusted>=<body>| | | <query>=<title,owner,abstract,keywords,date,object_type,

full-text,body>| | | <File.ViewCommand>=</dscgi/ds.py/Get>| | | <location>=<41,-78>| | | <result>=<title,URL,abstract,description,keywords,owner,

date,last_modified_date,| | | collection,collection-URL,object_type,type,author,

size,file_name,modified_by>| | | <host>=<docushare.Documentum.com>| | | <method2>=<post>| | | <method1>=<post>| | | <dateformat>=<yyyy-mm-dd'T'HH:mm:ss'Z'>| | | <action2>=</dscgi/ds.py/Search>

| | | <action1>=</dscgi/ds.py/Login>| | | <modified_dateformat>=<EEE, dd MMM yyyy HH:mm:ss zzz>| | | <port>=<80>| | ___________________________________________________________| | Load localized properties file :custom/core/DSWebDAV/DSWebDAV_

en.properties| | ___________________________________________________________| | | <description>=<DocuShare 2.0 HTTP/XML adapter>| | ___________________________________________________________| | Load class :custom/core/DSWebDAV/rule/

DSWebDAVParser.class| | Entry class of this bundle is :custom.core.DSWebDAV.DSWebDAV| | QML file of this bundle is :DSWebDAV.qml| | Mandatory property :| | ___________________________________________________________| | | <query>=<title,owner,abstract,keywords,date,object_type,

full-text,body>| | | <result>=<title,URL,abstract,description,keywords,owner,

date,last_modified_date,| | | collection,collection-URL,object_type,type,

author,size,file_name,modified_by>| | |__________________________________________________________| ___________________________________________________________| Load PROPERTIES: C:\ECIS\www\adapters\core\docushareBackends/

Doc-Public_en.properties| ___________________________________________________________| | <description>=<DocuShare Live! - Documentum DocuShare official site >| |___________________________________________________________| Load PROPERTIES: C:\ECIS\www\adapters\core\docushareBackends/

Doc-Public_fr.properties| ___________________________________________________________| | <description>=<DocuShare Live! - Le site officiel de Documentum DocuShare>| |___________________________________________________________| Bundle of this backend is :C:\ECIS\www\adapters\core\DSWebDAV.jar| Mandatory property :| __________________________________________________________| | <query>=<title,owner,abstract,keywords,date,object_type,full-text,body>| | <result>=<title,URL,abstract,description,keywords,owner,date,

last_modified_date,| | collection,collection-URL,object_type,type,author,

size,file_name,modified_by,source,site>| |___________________________________________________________|___________________________________________________________

Incorrect proxy congurationIn case your server relies on an HTTP proxy to cross a corporate firewall and the proxyis not available (due to a wrong hostname or a wrong port number). The followinginformation is displayed:general/AltaVista-France: unable to reach or to get data from[/cgi-bin/query] through the proxy [foo.Documentum.fr:80]


Make sure the proxy hostname and the proxy port are valid

-------------------------------------------------------xtrim.adapter.AdapterException: Adapter [general/AltaVista-France] raisederror of type [NETWORK] with message [failed to get data from[http://www.altavista.com:80/cgi-bin/query], [/cgi-bin/query]

Getting status information on server internalsThe “File/List thread” menu of ECI Server can help troubleshooting by displaying serverinternal status on the server text console as illustrated in the example below. This canprovide the exact list of connected clients, the list of active and stopping adapters.

Example G-1. Typical output of the server internal status

-------------------------------------------------------java.lang.ThreadGroup[name=main,maxpri=10]

Thread[main,1,main]Thread[AWT-EventQueue-0,5,main]Thread[AWT-Windows,5,main]Thread[Httpd: waiting... ( about 1 pending requests, and 20 free workers),5,

main]Thread[Thread-1,10,main]Thread[Screen Updater,4,main]java.lang.ThreadGroup[name=HttpWorkers,maxpri=5]

Thread[HttpWorker (1):waiting,5,HttpWorkers]Thread[HttpWorker (2):waiting,5,HttpWorkers]Thread[HttpWorker (3):waiting,5,HttpWorkers]Thread[HttpWorker (4):waiting,5,HttpWorkers]Thread[HttpWorker (5):waiting,5,HttpWorkers]Thread[HttpWorker (6):waiting,5,HttpWorkers]Thread[HttpWorker (7):waiting,5,HttpWorkers]

[…]Thread[HttpWorker (20):waiting,5,HttpWorkers]

java.lang.ThreadGroup[name=Surrogates,maxpri=5]Thread[Surrogate ( Id:-1 From:127.0.0.1 ),5,Surrogates]

java.lang.ThreadGroup[name=Brokers,maxpri=1]Thread[Broker (1),1,Brokers]Thread[Broker (2),1,Brokers]

[…]Thread[Broker (24),1,Brokers]Thread[computer/Netscape:processing,1,Brokers]Thread[general/AltaVista:processing,1,Brokers]Thread[Documentum/Documentum:processing,1,Brokers]Thread[computer/Sun:processing,1,Brokers]Thread[Documentum/Documentum:processing,1,Brokers]Thread[computer/Sun:processing,1,Brokers]Thread[computer/Netscape:processing,1,Brokers]Thread[computer/Sun:stopping,1,Brokers]Thread[computer/Netscape:stopping,1,Brokers]Thread[general/AltaVista:processing,1,Brokers]Thread[Broker (49),1,Brokers]



Thread[computer/Netscape:stopping,1,Brokers]Thread[SocketTimeout,1,Brokers]

-------------------------------------------------------

Handling low memory conditionsIn some cases, a low memory condition might appear when ECI Server cannot obtainenough memory to handle normally its processing. The following message is displayedon the server console and in logs when this condition arises:Low memory error condition detected. Please check the logs to verify normalbehavior of the system. If this error reproduces, please get the list ofactive adapters and report it to your adapter provider and Documentumsupport. Check the troubleshooting section in the ECIS Administrator’sguide for more details.

The following table summarizes the causes, diagnosis and actions to take whenencountering low memory conditions.

Table G-1. Low memory error troubleshooting diagnostic

Cause How to diagnose How to fix the problem

The number of concurrentthreads (called brokers andHTTP workers) was set toa very large number.

Check the serverconfiguration file(server.conf) properties

xtrim.http.workers andxtrim.brokers for valuesmuch higher than defaultvalues (x3 or x4)

Increase the maximummemory allocated to theserver process or reduce thevalues of those properties.

The number of adaptersis higher than defaultconfiguration (e.g. 100different adapters).

Check the numberof backends inthe domains.confconfiguration file.

Increase the maximummemory allocated to theserver process or reducethe number of adapters.



Cause How to diagnose How to fix the problem

An adapter needs unusualamount of memory to workproperly.

Check the error log files forerrors with that adapter.Increase memory for theserver and check that theproblem disappears. If thisdoes not solve the problem,see the adapter providerfor complete diagnosis.

Increase the maximummemory allocated to theserver process.

An adapter has aflaw, which leads itto consuming a lot ofmemory.

The adapter cannot bestopped: it always appearsin the list of active threadsand is very long to returnor never stop properly.

Contact the adapterprovider for maintainingthe adapter.

To allocate more memory to ECI Server, editing manually the aOServer.bat (aOServeron Solaris and Linux) necessary. The -mx option controls the maximum amount ofmemory that ECI Server can request to the system as illustrated in the example below.The default value—mx256m—specifies that ECI Services can consume up to 256 MB ofRAM on the host system. Change this option to a higher value to increase memoryallocated to ECI Services.

Example G-2. Extract from aOServer.bat startup le

:launch%JAVACMD% -Xms64m –Xmx256m -Xbootclasspath/a:%XTRIMHOME_NT%\lib\Cryptix -classpath%PREFIXPATH%%CPATH% %OTHERCMD% xtrim.server.control.ServerStartUp -d %CONFHOME% %*

Note: To avoid swapping of the host system, the maximum amount of memory allocatedto ECI Services must be smaller than the amount of physical memory of the hostmachine. While not dangerous for the system stability, swapping can cause performancesto drop and ECI Server response time to be unusually high.

Conguration of Tomcat ServerIn order to obtain more information about Tomcat server, use two properties in thefile ECIS/www/tomcat/conf/server.xml.

Set ’debug’ to ’9’ instead of ’0’ as shown below.

Then restart aOTomcat. More information is available on the Tomcat console and logfiles (located in ECIS/www/tomcat/logs).

Original parameters in ’server.xml’:


<Context path=""docBase="ao"debug="0"reloadable="true">

</Context>

Parameters for debug in ’server.xml’:<Context path=""

docBase="ao"debug="9"reloadable="true">

</Context>

Server with an external name different from thedefault machine name

If the server on which ECI Services is installed has an external name (ex.:"demo.askOnce.com") different from its internal name (ex.: "python"), some of the linksin the html pages might not work. To overcome this problem, two configuration filesmust be modified:• server.conf:

— xtrim.server.rmi.registryHost=my.external.name

— ex.: xtrim.server.rmi.registryHost=demo.askOnce.com• web.xml:

— <param-name>RMI_REGISTRY_HOST</param-name><param-value>my.internal.name</param-value>

— ex: <param-name>RMI_REGISTRY_HOST</param-name><param-value>python</param-value>

Appendix H

Multilingual Search * (Optional)

The multilingual search function is an ECI Services option.

This function enables the user to choose the query language. The query is then automaticallytranslated before databases are contacted.

The multilingual search is based on XeLDA, powerful linguistic tools. The settings specific toXeLDA are stored in ECI Services within configuration files. They are defined when ECI Servicesis installed with the multilingual option. The administrator can specify the language to contact thesource. The XeLDA server translates the query from the user language (chosen in ECI Services)to the query language of the source.

For example, a user chooses ’French’ as language in the multilingual panel. The query contains thekeyword ’maison’. XeLDA translates ’maison’ into ’casa’ or ’casata’ before contacting a source withthe property queryLanguage=Italian. The results from this source contain ’casa’ or ’casata’.

The translation used is displayed in the monitor (history tab).

External serversThe multilingual search needs XeLDA components: a XeLDA server and a XeLDARMI Proxy.

The servers must be launched in the following order:

1. XeLDA servercf ANNEXE (XELDA installation and launching )

2. XeLDA RMI Proxycf ANNEXE (XELDA installation and launching)

3. aOstart (to run ECI Server)


Multilingual properties in ECI ServicesIf you have installed ECI Services by specifying that you use the Cross Lingual Search,you just need to check the procedure below. Otherwise you must specify the appropriateinformation regarding XeLDA RMI Proxy.

1. The Cross lingual Information Retrieval should be enabled:

a. Locate the <your_ECIS_directory>/www/docs/conf directory.

b. Edit the client.conf file.

c. Put the value “true” to the xtrim.CLIR.isCLIRSupported property.

d. Check in the same time, the supported languages.

2. Configure the XeLDA RMI Proxy in ECI Services:

a. Locate the <your_ECIS_directory>/www/docs/conf directory.

b. Edit the Xelda.conf file.

c. Specify:• the host on which has been launched the XeLDA RMI Proxy, cf ANNEXE

(XELDA installation and launching ) –rmi-host option• the port of the XeLDA RMI Proxy, cf ANNEXE (XELDA installation and

launching ) –rmi-port option• the name of the XeLDA RMI Proxy, cf ANNEXE (XELDA installation and

launching ) –rmi-name optionChevreuse is the name of the machine supporting the XeLDA RMI Proxy. The nameof this server is XeldaBridgeServer and its port is 1099 (which are the default valuesduring the XeLDA installation).

Specify your multilingual backends

The default multilingual backends (defined in the list of domains ) are:general/Google-French,general/Google-English,general/Google-German,general/Google-Italian,general/Google-Spanish

For a multilingual backend, the configuration file must contain the properties“queryLanguage” and “strategy”:• queryLanguage

describes in which language the queried source is. It is mandatory. For example, inGoogle-Italian.conf, we have:queryLanguage=Italian

• Strategy

specifies which type of strategy is used by XeLDA for the dictionary lookup. Defaultis general. For example:Strategy=LifeScience

In this case, the dictionary uses a customized dictionary dedicated to the Life Sciencedomain.

How to add a specic dictionary

To add a specific dictionary to an adapter, add the required dictionary in XeLDA (see theXeLDA installation guide) and specify a dictionary strategy with the property ’strategy’in the backend configuration file.

XeLDA failure analysis

To verify if the XeLDA servers are running correctly, see the log file:<your_ECIS_directory>/www/logs/trace.log

Example H-1. Example extract from trace.log after a failure occurred: a query withtranslation has been started, whereas the rmi XeLDA server stopped

"name:user1 Query definition:{'title' CONTAINS 'catalogue'} => {Google-English}HTTP/1.0" 200 0Error (Thread: general/Google-English:processing, at:Mon Feb 05 17:25:55 CET 2001) :unable to execute Xelda request [lingua/Translation],caught java.rmi.ConnectException:Connection refused to host: 13.202.220.112; nested exception is:java.net.ConnectException: Connection refused: no further information"

ECI Services multilingual search example

Let’s make a multilingual search by using ECI Services web client.


To use the ECI Services web client to create a multilingual search:

1. Specify in the ‘Advanced Search’ panel that we want to use the cross lingualinformation retrieval by selecting the “Enable query translation” checkbox in the‘Multilingual’ section. We specify that our queries are made in English.

2. Select the international sources in the ‘Domains’ panel.

3. Make a query on “Business Intelligence” on the International domain which containssources from different countries.

The search is translated into different languages according to the queried sources.


Appendix I

ECI Services Multilingual Server (MLS)

XeLDA installationThis section describes how to install XeLDA.

To install XeLDA

1. To begin the installation process:• On Windows, double click on XeldaSetup.exe• On Solaris, run the script XeldaSetup (check this file is executable, type chmod

u+x XeldaSetup otherwise)2. Follow the installation wizard screens. Enter the destination directory where XeLDA

is installed, the XeLDA application requires 1.2 Gb.

Note: The first step for the installation wizard is to copy all files in the destinationdirectory. A first log file named ‘install.log’ is created in this directory; it canbe consulted at the end of the installation process. In the second step, when theinstallation wizard has completed copying all files, it configures automatically theXeLDA launcher scripts. A second log file is created named ‘configure.log’; it can beconsulted at the end of the installation process.

Launching the XeLDA server

On Windows

A shortcut to launch the XeLDA server is available in the ‘Start’ menu:Start > Program >ECIS > MLS > Xelda Server

The launcher script can be found directly at the following path:[Installation directory of XeLDA]/bin/XeldaServer.bat

If you have any problem launching the XeLDA server:

1. Check these files are executable.


2. Check that you have copied your XeLDA license into [Installation directory ofXeLDA]/config

The XeLDA server can also be launched directly in the command line with specificoptions (such as the server port):

Optionally, run the script “XeldaServer.bat –help” to see which options you can specify.

On Solaris

The launcher script can be found at the following path:[Installation directory of XeLDA]/bin/XeldaServer

This script starts the XeLDA server, and the other one launches the RMI Bridge requiredby ECI Services.


1. Check this script is executable (type chmod u+x <filename>

2. Verify that your DISPLAY environment variable is correctly set (type setenvDISPLAY <host>:0.0).

3. Check that you have copied your XeLDA license into [Installation directory ofXeLDA]/config

The XeLDA server can also be launched with specific options (such as the server port).

Optionally, run the script “XeldaServer –help” to see which options you can specify.

Table I-1. Launching the XeLDA Server

Option Description Default Value

-port <port_number> Socket port number to use 40002

Launching the XeLDA RMI proxy

On Windows

A shortcut launches the XeLDA RMI Proxy required by ECI Services: Start > Program >ECIS > MLS > XeldaBridgeServer

The launcher script can be found directly at the following path:[Installation directory of XeLDA]/java/XeldaBridgeServer.bat


1. Check this file is executable.

2.

The XeLDA RMI Proxy server can also be launched directly in the command line withspecific options (such as the rmi port).

Optionally, run the script “XeldaBridgeServer.bat –help” to see which options you canspecify.

On Solaris

The launcher script can be found at the following path:[Installation directory of XeLDA]/java/XeldaBridgeServer

This script starts the XeLDA RMI Proxy server required by ECI Services.

If you have any problem launching the XeLDA RMI Proxy server:

1. Check this script is executable (type chmod u+x <filename> otherwise).

2. Verify that your DISPLAY environment variable is correctly set (type setenvDISPLAY <host>:0.0).

The XeLDA RMI Proxy server can also be launched with specific options (such as thermi port).

Optionally, run the script “XeldaBridgeServer –help” to see which options you canspecify.

Table I-2. Launching the XeLDA RMI proxy


-rmi-port

<rmi_port_number>

The port number of theRMI registry.

1099

-rmi-host <rmi_host> The host (local or remote)where the RMI registry isrunning.

localhost

-rmi-name <rmi_name> Amnemonic name for yourproxy. Proxy is bonded tothe registry with this name.

XeldaServer

-port <port_number> The port number of theXelda Server (local orremote.

40002

-server <host_name> The host where XeldaServer is running.

localhost

Example I-1. XeLDA RMI proxy launching with custom settings

XeldaBridgeServer -rmi-port 3200 -rmi-name SampleProxy -connection-type directThis script may fail if your "java" command is not public. If so, then edit theXeldaBridgeServer file and replace "java" with the full path of your java command (E.g.:/usr/java1.2/bin/java ).

Index

Aaccess, 11accounts, 67

creating, 68monitoring, 67

adapter backend configurationstroubleshooting, 122

Admin Centeraccess, 11configuration, 83home page, 12troubleshooting, 117

admin.xml, 85configuration files, 85log files, 86uploaded files, 86

advancedload balancing, 113

Bbalancing

load, 105

Cclient configuration

Web Assistant, 45client.overview

customizing, 60communication with a backend

troubleshooting, 119configuration, 83

Admin Center, 83web.xml, 83

configuration filesadmin.xml, 85

create a report templateusing RTL, 89

customization, 83, 87editing JSP pages, 87

without editing JSP pages, 87customize result window

Web Assistant, 46customizing

client.overview, 60look and feel, 59

Ddatabase

properties for JDBC, 99dictionary

specifying for a multilingualsearch, 131

directory servicesLDAP, 32

display an attributeusing its name in RTL, 91without using its name in RTL, 92

display an messageRTL, 92

domainmanaging, 15

Eediting JSP pages

customization, 87external database

store accounts, 34external name

troubleshooting, 127external servers

multilingual search, 129

Ggenerating

reports, 89grammar

RTL, 93


Index

Hheader and footer

RTL, 91home page, 12

Iimages

uploading, 74information source

managing, 15, 17status, 21

information sourcesuploading, 73

initialize accounts tablesJDBC database, 102

JJDBC database

initialize accounts tables, 102manage accounts, 103migrate account, 103properties, 99

JDBC database configurationdownloading SQLServer driver, 102MySQL, 100Oracle, 100SQLServer, 101

Llaunch servers

web.xml, 85launching XeLDA

multilingual server, 133RMI Proxy, 134Solaris, 134Windows, 133

LDAPdirectory services, 32

librariesuploading, 73

linguistic server propertiesWeb Assistant, 45

loadbalancing, 105

load balancingadvanced, 113troubleshooting, 115

Windows, 113log files

admin.xml, 86troubleshooting, 38, 63

loginweb.xml, 83

look and feelcustomizing, 59

low memory conditionstroubleshooting, 125

Mmaking a new template available

RTL, 94manage accounts

JDBC database, 103maximum size

web.xml, 84migrate account

JDBC database, 103multilingual backends

multilingual search, 130multilingual search, 129

external servers, 129multilingual backends, 130properties, 130specifying a dictionary, 131XeLDA failure analysis, 131

multilingual server, 133launching XeLDA, 133launching XeLDA— RMI Proxy, 134launching XeLDA— Solaris, 134launching XeLDA—Windows, 133XeLDA installation, 133

MySQLJDBC database configuration, 100

NNetegrity SiteMinder, 75

OOracle

JDBC database configuration, 100

Ppassword

web.xml, 83


Index

preferences, 22properties

JDBC database, 99linguistic server properties, 45multilingual search, 130

proxy configurationtroubleshooting, 123

RReport Generator, 89

using, 96results

RTL, 91RMI Proxy

launching XeLDA, 134RTL

characteristics, 90create a report template, 89display an attribute using its name, 91display an attribute without using its

name, 92display an message, 92grammar, 93header and footer, 91making a new template available, 94results, 91template structure, 90testing a template, 95

RTL characteristicssource files, 90target files, 90

Ssearch

multilingual, 129security, 32server

multilingual, 133server internals

troubleshooting, 124Servers Configuration

attribute configuration, 52client configuration, 41integration server, 25multilingual configuration, 51server configuration, 25Web Server, 25, 53

size uploaded file

web.xml, 84Solaris

launching XeLDA, 134source files, 90specifying a dictionary

multilingual search, 131SQLServer

downloading driver for JDBCdatabase, 102

JDBC database configuration, 101store accounts

external database, 34

Ttarget files, 90template structure

RTL, 90testing a template

RTL, 95Tomcat server

troubleshooting, 126troubleshooting, 119

adapter backend configurations, 122Admin Center, 117communication with a backend, 119external name, 127load balancing, 115log files, 38low memory conditions, 125Netegrity SiteMinder, 81proxy configuration, 123server internals, 124Tomcat server, 126

Uupload

web.xml, 84uploaded files

admin.xml, 86using

Report Generator, 96

WWeb Assistant

client configuration, 45customize result window, 46linguistic server properties, 45

web.xml


Index

configuration, 83launch servers, 85login, 83maximum size, 84password, 83size uploaded file, 84upload, 84

Windowslaunching XeLDA, 133

load balancing, 113

XXeLDA failure analysis

multilingual search, 131XeLDA installation

multilingual server, 133


Enterprise Content Integration Services …..... 93 Makinganewtemplateavailable ..... 94...

Documents

Transcript of Enterprise Content Integration Services …..... 93 Makinganewtemplateavailable ..... 94...