EMC Documentum Federated Search Services

Transcription

1 EMC Documentum Federated Search Services Version 6.5 Administration Guide P/N A01 EMC Corporation Corporate Headquarters: Hopkinton, MA

2 Copyright EMC Corporation. All rights reserved. Published October 2008 EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up to date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. All other trademarks used herein are the property of their respective owners. Contains software developed by the Apache Software Foundation. Distribution subject to the Apache Software License. Contains the HTTP Client Library, , Ronald Tschalaer. Distribution subject to the GNU Library General Public License. Contains the Cryptix library, Copyright The Cryptix Foundation Limited. All rights reserved. Distribution subject to the Cryptix General License. Contains the MM.MySQL driver. Copyright (c) Mark Matthews. Distribution subject to the GNU Library General Public License. Contains the Pager Taglib, Copyright 2002 James Klicman <james@jsptags.com>. Distribution subject to the GNU Library General Public License. Portions Copyright 2000 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

3 Table of Contents Preface Chapter 1 Introduction Features available to most Federated Search client applications Features unique to Discovery Manager Chapter 2 Accessing Admin Center Connecting to Admin Center Logging in Admin Center home page Logging out Chapter 3 Information Source Configuration and Organization Managing domains Creating domains Selecting existing domains Editing domains Deleting domains Managing information sources Creating information sources Selecting existing information sources Editing information sources Deleting information sources Chapter 4 Information Source Status Monitoring information sources Monitoring results of information sources Information sources Setting preferences Scheduling Notifying Setting priorities for information sources Chapter 5 Servers Configuration Integration Server Server configuration Proxy settings Proxy authentication settings Alert service settings Adapters settings Web front end settings RMI settings Scheduled queries settings Security settings EMC Documentum Federated Search Services Version 6.5 Administration Guide 3

4 Table of Contents Directory service settings Database and account settings SSL CA Certificate settings Diagnose settings Server UI settings Client configuration Results settings Localization settings Alert settings Clustering settings Security settings Personalized Relevance Ranking settings Query Service settings Query Service Location settings Query Service Proposal settings Query Service Language Resource settings Query Service Resource settings Attribute configuration Attribute description Attribute translation Web Server Web Server configuration Configuration of the Web Server with the Integration Server Proxy settings Proxy Authentication settings RMI settings Default Account Domains settings Domains Icon settings Results settings Export settings Diagnose Settings Chapter 6 Indexing management Overview of the FS2 Indexing functionality Prerequisites and initial configuration Installing the Indexer Configuring the Indexing for the first time Supported environments Supported file systems Supported file formats Collections Configuration possibilities and limitations Access to the results Security Running the Indexing as a Windows Service Prerequisites Sizing guidelines Administering the Indexing Configuring the Indexing Configuring adapter backends Advanced configuration Optimizing the indexing performance Troubleshooting Webapps log files Backup copies EMC Documentum Federated Search Services Version 6.5 Administration Guide

5 Table of Contents Chapter 7 Logs Reporting Integration Server Web Server Admin Center Server Chapter 8 Accounts Management Monitoring accounts Creating accounts Changing passwords Deleting account Chapter 9 Servers Operation Chapter 10 Uploading Chapter 11 Configuring Admin Center web.xml Login and password Upload feature Size of the uploaded file Maximum size of the visible part of log files Command to launch servers admin.xml Configuration files Log files Uploaded files Chapter 12 Customization Customizing Admin Center Customization without editing JSP pages Customization using JSP pages Customizing Discovery Manager Appendix A Installing and Configuring CA SiteMinder CA SiteMinder integration CA SiteMinder plug in configuration Installing the web front end Installing and configuring Federated Search Services Configuring the FS2SiteMinder plug in Configuring the Federated Search Services client Configuring the Federated Search server Troubleshooting CA SiteMinder Appendix B Report Generator Using RTL to create a report template Main characteristics of RTL Template structure Header and footer description Results description Displaying an attribute by using its name Displaying a message only if a predefined attribute has a value Displaying an attribute without using its name Grammar EMC Documentum Federated Search Services Version 6.5 Administration Guide 5

6 Table of Contents Making a new template available Testing a report template Using the report generator Appendix C Configuring External Databases Downloading the driver for SQL Server Initialize accounts tables Migrate account from one database to another Appendix D Troubleshooting Troubleshooting with Admin Center Testing communication with a backend Troubleshooting adapter backend configurations Incorrect proxy configuration Getting status information on server internals Handling low memory conditions Configuration of Tomcat server Server with an external name different from the default machine name Managing timeouts Appendix E Load Balancing Typical load balanced system on Solaris platform Sharing the load between two servers Installing a load balanced system Typical load balanced system on Windows platform Advanced load balancing configuration Troubleshooting load balanced systems EMC Documentum Federated Search Services Version 6.5 Administration Guide

7 Table of Contents List of Figures Figure 1. Admin Center Home page Figure 2. Information Source Configuration and Organization page Figure 3. Servers configuration page Figure 4. Account Management page Figure 5. Uploading page Figure 6. Timeouts in Federated Search Services EMC Documentum Federated Search Services Version 6.5 Administration Guide 7

8 Table of Contents List of Tables Table 1. Links in the Admin Center home page Table 2. xtrim.proxyset Table 3. xtrim.proxyhost Table 4. xtrim.proxyport Table 5. xtrim.proxyauthenticationset Table 6. xtrim.proxyuser Table 7. xtrim.proxyuserpassword Table 8. xtrim.adminmailaddress Table 9. xtrim.useragentidentification Table 10. xtrim.mailserver Table 11. xtrim.sendinitializationmailtoadmin Table 12. xtrim.brokers Table 13. xtrim.maxactionfailure Table 14. xtrim.adapterreloaddelay Table 15. jwrap.classifier.repairinglevel Table 16. xtrim.http.resolvednshostname Table 17. xtrim.httpdatamaxsize Table 18. xtrim.jsp.host Table 19. xtrim.jsp.port Table 20. xtrim.server.embeddedobjectservleturl Table 21. xtrim.server.rmi.bindingname Table 22. xtrim.server.rmi.registryhost Table 23. xtrim.server.rmi.registryport Table 24. xtrim.server.rmisessiontimeout Table 25. xtrim.server.allowremoteshutdown Table 26. xtrim.server.remoteshutdownpassword Table 27. xtrim.server.rmi.codebase Table 28. xtrim.server.rmi.forcebinding Table 29. xtrim.server.rmi.embeddedobjectbuffersize Table 30. xtrim.scheduledquery.disableddays Table 31. xtrim.scheduledquery.maxsimultaneous Table 32. xtrim.user.maxresultsinscheduledquery Table 33. xtrim.scheduledqueryreport Table 34. xtrim.scheduledquerytimerange.starthour Table 35. xtrim.scheduledquerytimerange.startminute Table 36. xtrim.scheduledquerytimerange.endhour Table 37. xtrim.scheduledquerytimerange.endminute EMC Documentum Federated Search Services Version 6.5 Administration Guide

9 Table of Contents Table 38. xtrim.security.providers Table 39. xtrim.security.credentialstore Table 40. xtrim.rmi.ssl.enabled Table 41. xtrim.rmi.ssl.keystore Table 42. xtrim.rmi.ssl.keystorepassword Table 43. xtrim.directory.provider.ldap Table 44. xtrim.directory.provider.ldap.host Table 45. xtrim.directory.provider.ldap.port Table 46. xtrim.directory.provider.ldap.root Table 47. xtrim.directory.provider.ldap.verify Table 48. xtrim.directory.provider.ldap.attribute Table 49. xtrim.directory.provider.ldap.ad.shortlogin Table 50. xtrim.directory.provider.ldap.ad.domain Table 51. xtrim.user.usermijdbc Table 52. xtrim.user.jdbcclass Table 53. xtrim.user.jdbcurl Table 54. xtrim.user.admin Table 55. xtrim.user.password Table 56. xtrim.user.useoracle Table 57. xtrim.user.primarykeylabel Table 58. xtrim.user.primarykeycreateindex Table 59. xtrim.user.uniquelabel Table 60. xtrim.user.nocachelabel Table 61. xtrim.user.longtypelabel Table 62. xtrim.user.binarytypelabel Table 63. xtrim.user.varcharlabel Table 64. xtrim.user.usexopen Table 65. xtrim.user.duplicatetupleerror Table 66. xtrim.user.maxqueriesincontext Table 67. xtrim.user.clearoutqueriesperiod Table 68. xtrim.user.allowpwdsaving Table 69. xtrim.user.cachedloginname Table 70. JDBC Database static properties Table 71. JDBC Database xtrim.user.jdbcurl property Table 72. xtrim.ssl.truststore Table 73. xtrim.ssl.truststoretype Table 74. xtrim.ssl.truststorepassword Table 75. xtrim.ssl.keystore Table 76. xtrim.ssl.keystoretype Table 77. xtrim.ssl.keystorepassword Table 78. xtrim.log.mode Table 79. xtrim.log.singletrace Table 80. xtrim.log.access EMC Documentum Federated Search Services Version 6.5 Administration Guide 9

10 Table of Contents Table 81. xtrim.log.error Table 82. xtrim.log.trace Table 83. xtrim.wrapperdebug Table 84. xtrim.wrapperdebugpath Table 85. xtrim.servergui.icon Table 86. xtrim.servergui.logo Table 87. xtrim.servergui.aboutlogo Table 88. xtrim.servergui.showsearches Table 89. xtrim.servergui.shutdownwait Table 90. xtrim.server.multiservermode Table 91. xtrim.defaultwrapperupdateurl Table 92. xtrim.clientvisibleproperties Table 93. xtrim.query.refineresults Table 94. xtrim.extralocales Table 95. xtrim.reporttemplates Table 96. xtrim.report.mailreport Table 97. xtrim.report.shortreport Table 98. xtrim.report.longreport Table 99. xtrim.report.<language>report Table 100. xtrim.cluster.issupported Table 101. xtrim.cluster.clusterthreshold Table 102. xtrim.cluster.subclusterthreshold Table 103. xtrim.cluster.minimaldelay Table 104. xtrim.cluster.defaultrelevantattributes Table 105. xtrim.cluster.notrelevantattributes Table 106. xtrim.cluster.suffixnotrelevantattributes Table 107. xtrim.cluster.prefixnotrelevantattributes Table 108. xtrim.server.allowauthcookie Table 109. xtrim.server.checkipforcookie Table 110. xtrim.profile.issupported Table 111. xtrim.profile.relevantattributes Table 112. xtrim.queryservice.issupported Table 113. xtrim.queryservice.serviceavailable Table 114. xtrim.queryservice.languagesservice Table 115. xtrim.queryservice.dictionary.default Table 116. xtrim.queryservice.dictionary.<language> Table 117. Port Table 118. Shutdown port Table 119. maxsparethreads Table 120. maxthreads Table 121. minsparethreads Table 122. acceptcount Table 123. Debug setting EMC Documentum Federated Search Services Version 6.5 Administration Guide

11 Table of Contents Table 124. ASKONCE_PROXY_SET Table 125. ASKONCE_PROXY_HOST Table 126. ASKONCE_PROXY_PORT Table 127. ASKONCE_PROXY_AUTHENTICATION Table 128. ASKONCE_PROXY_USER_ Table 129. ASKONCE_PROXY_USER_PWD Table 130. ASKONCE_RMI_NAME Table 131. RMI_REGISTRY_HOST Table 132. RMI_REGISTRY_PORT Table 133. RMI_SSL_ENABLED Table 134. RMI_SSL_KEYSTORE Table 135. RMI_SSL_KEYSTORE_PASSWORD Table 136. DEFAULT_LOGIN_NAME Table 137. DEFAULT_LOGIN_PASSWORD Table 138. MAX_NUMBER_OF_SELECTED_DOMAINS Table 139. JSP_DOMAIN Table 140. MAX_DOMAIN_NAME_LENGTH Table 141. MAX_BODY_LENGTH Table 142. MAX_DISPLAYED_RESULT Table 143. NB_RESULTS_PAGE_LIST Table 144. TOOLTIP_LENGTH_LIST Table 145. SORTABLE_ATTRIBUTES Table 146. MAIN_CONTROLLER Table 147. exportlist Table 148. MAX_QUERY_VIEW_RANGE Table 149. JSP_DEBUG Table 150. Session timeout Table 151. RESULTS_TIMEOUT Table 152. suffix Table 153. prefix Table 154. directory Table 155. accesslogfilter Table 156. Account parameters Table 157. Uploading files Table 158. client.overview Table 159. Troubleshooting CA SiteMinder Table 160. Definition of terms Table 161. Template structure Table 162. Low memory error troubleshooting diagnostic Table 163. Troubleshooting load balanced systems EMC Documentum Federated Search Services Version 6.5 Administration Guide 11

12 Table of Contents 12 EMC Documentum Federated Search Services Version 6.5 Administration Guide

13 Preface This guide contains procedures and information for setting up and managing Federated Search Services (FS2). This guide assumes you have already installed Federated Search Services components by following the instructions in the Federated Search Services Installation Guide. Intended audience This guide is intended for administrators who are responsible for managing Federated Search Services. It serves as a reference for configuring the server and organizing the sources of information within the domains tree. The guide assumes a working knowledge of HTML and Java. This guide contains several references to ECIS, Xtrim and askonce files or programs. Xtrim is the development and runtime foundation of Federated Search Services (formerly named askonce and then ECI Services) and is included as a part of the filename in many circumstances. For easy understanding, you can assume that Federated Search Services, ECI Services, ECIS, askonce, and Xtrim are synonymous. If not otherwise specified, relative paths in this guide refer to <FS2 installation directory>. For example, on Windows systems, the default installation directory for Federated Search Services is C:\Program Files\Documentum\fs2. Revision history The following changes have been made to this document. Revision history Revision date October 2008 Initial Release EMC Documentum Federated Search Services Version 6.5 Administration Guide 13

14 Preface 14 EMC Documentum Federated Search Services Version 6.5 Administration Guide

15 Chapter 1 Introduction This chapter describes the Federated Search Services (FS2) product offering, detailing the following features: Features available to most Federated Search client applications, page 15 Features unique to Discovery Manager, page 16 Federated Search Services (FS2) is Documentum s federated search technology. FS2 enables users to securely search an unlimited number of information sources inside and outside the organization. Federated Search Services product offering consists of the following components: Federated Search server: it brokers queries across an unlimited number of information sources. The server is packaged with a core set of adapters. Discovery Manager: primary standalone user interface. Federated Search Adapters: of optional adapters that provide access to additional information sources. Federated Search SDK (Software Development Kit): APIs to create custom applications and an integrated environment to create and maintain adapters. In addition to Discovery Manager, FS2 is available to WDK based clients such as Webtop, DAM, WCM as well as through DFC and DFS. Features available to most Federated Search client applications The following features of the federated search functionality are available in most client applications: Single interface to access heterogeneous content Secure access using security in place Multi repository attribute display Results ranking and filtering Intelligent query conversion and query language compensation Saved queries (including the result set) Viewing content from any repository Importing results from any application Results clustering: groups results into dynamic concept categories to ease navigation. EMC Documentum Federated Search Services Version 6.5 Administration Guide 15

16 Introduction Search templates Real time monitoring of the query status Please refer to the documentation of the client application to know which features are supported. Features unique to Discovery Manager The following features are only available for Discovery Manager: Spell checking: suggests an alternative spelling that will generate more relevant search results. Document snapshot: displays extracted key sentences and keywords. Exporting results set: results can be exported to others applications such as eroom and Documentum. Reporting on results set: keeps track of the search results in a separate document and allows for the exchange of results. Scheduled queries with notification: tracks changes on critical information 16 EMC Documentum Federated Search Services Version 6.5 Administration Guide

17 Chapter 2 Accessing Admin Center This chapter describes the following: Connecting to Admin Center, page 17 Logging in, page 17 Admin Center home page, page 18 Logging out, page 20 Connecting to Admin Center To launch the Admin Center web server in Windows, use aoadmincenter Windows service. The Federated Search Services Installation Guide provides the installation procedure for this service. Note: Alternatively, go to <FS2 installation directory>/bin, and launch the aoadmin script to run the Admin Center Web Server. The Admin Center web server is accessible through a particular server port number, which is automatically computed from the FS2 port server number, as follows: <admin center port number> = <FS2 port number> + 3 The default FS2 port number, which can be changed during installation, is 3000; the default Admin Center port number is For example, if the FS2 port number is set to 2828, then the Admin Center port is automatically set to Logging in To access the Admin Center login page, type the following URL in the browser: name>:<admin center port number>/admincenter in the browser. (The URL is an example.) On your first access, the web browser may indicate certificate errors, accept the certificate. You may get this error if you indicated localhost instead of the server name. The Admin Center login page appears. EMC Documentum Federated Search Services Version 6.5 Administration Guide 17

18 Accessing Admin Center To log on to Admin Center 1. Type the administrator login and password. Note: The default login and password are admin and ecis, respectively. You can change the values when you install Federated Search Services. You can also change the values by editing web.xml located at <FS2 installation directory>/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, you can log on but you will be logged out of the first machine. To do a force login 1. Type the administrator login and password. 2. Select the Force login checkbox. 3. Click OK. The Admin Center home page appears. Admin Center home page The Admin Center home page has links that take you to the various web pages as shown in Table 1, page 19. The rest of this guide deals with each of these pages in detail, one chapter for each page. 18 EMC Documentum Federated Search Services Version 6.5 Administration Guide

19 Accessing Admin Center Table 1. Links in the Admin Center home page Click Information Source Configuration and Organization Information Source Status Servers Configuration To Add, edit, and delete domains and information sources. Set preferences for scheduling, notifying, and managing information sources. Monitor results and information sources. Configure server operations for Integration Server and Web Server. This includes: Server configuration, page 32 Client configuration, page 57 Logs Reporting Accounts Management Servers Operation Uploading Admin Center Logout Configure Indexing servers to index share drives. Understand and diagnose misconfigurations and runtime problems in Integration Server, Web Server, and Admin Center Server. Monitor and create user accounts. Stop and restart the server. Upload information sources, libraries, and images. Log out. EMC Documentum Federated Search Services Version 6.5 Administration Guide 19

20 Accessing Admin Center Figure 1. Admin Center Home page Logging out To log out from the session, click Admin Center Logout in the home page. 20 EMC Documentum Federated Search Services Version 6.5 Administration Guide

21 Chapter 3 Information Source Configuration and Organization This chapter describes how to 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, a domain called News regroups some sources like CNN, Yahoo, Reuters, etc. The sources are accessible through a mechanism of adapters. Each source has its own adapter, which is a connector that allows the end user to communicate with a source of information. The adapter uses the search capabilities offered by the source. The locale independent domain hierarchy (domains.conf) defines the source hierarchy that appears in the end user domain browser. The domain hierarchy is defined in a locale independent way (usually in English), and translated domain hierarchies are automatically generated for each supported language/locale. A domain can consist of other subdomains and individual backends defined by the administrator. When a particular adapter bundle fits the needs of end users as is and does not require any specific configuration, the domain can directly use the name of the adapter bundle. This is called an implicit backend (all the default configuration values defined in the bundle apply as they are), which differs from the usual explicit backend (a corresponding backend file that defines some specific configuration values). An adapter consists of a bundle file and an optional backend file. An adapter bundle file (with a jar extension) holds all generic mechanisms (code and configuration) to communicate with a remote source of a given type, while an adapter backend file extends the adapter bundle to work with a specific information source. Managing domains This section describes the following: Creating domains, page 22 Selecting existing domains, page 23 Editing domains, page 23 Deleting domains, page 23 EMC Documentum Federated Search Services Version 6.5 Administration Guide 21

22 Information Source Configuration and Organization Figure 2. Information Source Configuration and Organization page Creating domains To create a new domain: 1. Click Information source configuration and organization in the Home page of Admin Center. 2. Click Add. The Add a new domain or a new information source page opens. 3. Click Create new domain. The Create a new domain page appears. 4. In the Name of the domain field, type a name. 5. Click Next. The localized settings page appears. 6. In the appropriate fields, type the name and description for the localization information. 7. Click Finish. The Submit page appears along with a message informing you that the domain hierarchy will be updated with the new settings if you click Next. The message also informs you that you must start the servers with the Servers operation link in the home page for the new settings to take effect. 8. Click Next. 9. Click Servers operation in the home page. 22 EMC Documentum Federated Search Services Version 6.5 Administration Guide

23 Information Source Configuration and Organization Selecting existing domains To select an existing domain: 1. Click Information source configuration and organization in the Home page of Admin Center. 2. Click Add. The Add a new domain or a new information source page opens. 3. Click Add. The Add page opens. 4. Click Select existing domain. The Select an existing domain page appears. 5. Select the domain from the list. 6. Click Finish. The Submit page appears along with a message informing you that the domain hierarchy will be updated with the new settings if you click Next. The message also informs you that you must start the servers with the Servers operation link in the home page for the new settings to take effect. 7. Click Next. 8. Click Servers operation in the home page. Editing domains To edit a domain: 1. Click Information source configuration and organization in the Home page of Admin Center. 2. Click Edit. The Localized settings page appears. 3. Edit the required information. 4. Click Finish. The Submit page appears along with a message informing you that the domain hierarchy will be updated with the new settings if you click Next. The message also informs you that you must start the servers with the Servers operation link in the home page for the new settings to take effect. 5. Click Next. 6. Click Servers operation in the home page. Deleting domains To delete a domain: 1. Click Information source configuration and organization in the Home page of Admin Center. 2. Select the domain to be deleted. 3. Click Delete. The Submit page appears along with a message informing you that the domain hierarchy will be updated with the new settings if you click Next. The message also informs you that you must start the servers with the Servers operation link in the home page for the new settings to take effect. 4. Click Next. EMC Documentum Federated Search Services Version 6.5 Administration Guide 23

24 Information Source Configuration and Organization 5. Click Servers operation in the home page. Managing information sources This section describes the following: Creating information sources, page 24 Selecting existing information sources, page 25 Editing information sources, page 25 Deleting information sources, page 26 Note: The Federated Search Services Adapter Installation Guide provides more information about the creation of adapter backends on these information sources, for core adapters like DocumentumFC, eroom, Xtender, ApplicationXtender, JDBC or the FS2 Indexing. Creating information sources To create a new information source: 1. Click Information source configuration and organization in the Home page of Admin Center. 2. Click Add. The Add a new domain or a new information source page appears. 3. Click Create new information source. The Create a new information source page appears. 4. In the appropriate field, type the name of the information source. 5. Select the type of the information source either from the Intranet or Internet source lists. 6. Click Next. The Localized settings page appears. 7. In the appropriate fields, type the information source name and description. 8. Click Next. The Properties page appears. Refer to the corresponding Adapter Installation Guide for more information about the adapter properties. 9. Type the required details and click Finish. The page appears with the settings and properties details of the new information source. 10. Click Test. The Test of the information source page appears. 11. Provide the required details to test the information source: Test Constraint: from left to right, type the attribute, the operator and the value of the constraint. Login Options: if a login name and password are required to authenticate with the source, type them in the corresponding fields. Multilingual Option: if required, type the source language. Debug Option: select Display with more information debug traces to identify possible errors in the configuration of the information source. 12. Click Test. The test results appear below the test parameters. If the test failed, click Back to modify the configuration. If the test passes, proceed to next step. 24 EMC Documentum Federated Search Services Version 6.5 Administration Guide

25 Information Source Configuration and Organization 13. Click Submit. The Submit page appears along with a message informing you that the domain hierarchy will be updated with the new settings if you click Next. The message also informs you that you must start the servers with the Servers operation link in the home page for the new settings to take effect. 14. Click Next. 15. Click Servers operation in the home page. Selecting existing information sources To select an existing information source: 1. Click Information source configuration and organization in the Home page of Admin Center. 2. Click Add. The Add page appears. 3. Click Select existing information source. The Select an existing information source page appears. 4. Select the name of the information source from the list. 5. Click Finish. The Submit page appears along with a message informing you that the domain hierarchy will be updated with the new settings if you click Next. The message also informs you that you must start the servers with the Servers operation link in the home page for the new settings to take effect. 6. Click Next. 7. Click Servers operation in the home page. Editing information sources To edit an information source: 1. Click Information source configuration and organization in the Home page of Admin Center. 2. Click Edit. The Localized settings page appears. 3. Edit the required information. 4. Click Next. The Properties page appears. Refer to the corresponding Adapter Installation Guide for more information about the adapter properties. 5. Type the required details and click Finish. The page appears with the settings and properties details of the new information source. 6. Click Test. The Test of the information source page appears. 7. Provide the required details to test the information source: Test Constraint: from left to right, type the attribute, the operator and the value of the constraint. Login Options: if a login name and password are required to authenticate with the source, type them in the corresponding fields. Multilingual Option: if required, type the source language. EMC Documentum Federated Search Services Version 6.5 Administration Guide 25

26 Information Source Configuration and Organization Debug Option: select Display with more information debug traces to identify possible errors in the configuration of the information source. 8. Click Test. The test results appear below the test parameters. If the test failed, click Back to modify the configuration. If the test passes, proceed to next step. 9. Click Submit. The Submit page appears along with a message informing you that the domain hierarchy will be updated with the new settings if you click Next. The message also informs you that you must start the servers with the Servers operation link in the home page for the new settings to take effect. 10. Click Next. 11. Click Servers operation in the home page. Deleting information sources To delete an information sources: 1. Click Information source configuration and organization in the Home page of Admin Center. 2. Select the information source to be deleted. 3. Click Delete. The Submit page appears along with a message informing you that the domain hierarchy will be updated with the new settings if you click Next. The message also informs you that you must start the servers with the Servers operation link in the home page for the new settings to take effect. 4. Click Next. 5. Click Servers operation in the home page. 26 EMC Documentum Federated Search Services Version 6.5 Administration Guide

27 Chapter 4 Information Source Status This section describes the two activities that can be performed in the Information Source Status page: Monitoring information sources, page 27 Setting preferences, page 28 Monitoring information sources The Monitoring page allows you to monitor information sources and describes the following: Monitoring results of information sources, page 27 Information sources, page 28. Monitoring results of information sources This section displays specific details and generates statistics and analyses on information sources. The following information is available for cumulated or last analysis: 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 for the configuration, the network, the query and the parser. The Beginning date of the cumulated analysis and the Analysis date of the last analysis are also indicated. EMC Documentum Federated Search Services Version 6.5 Administration Guide 27

28 Information Source Status Information sources The Information sources section in Admin Center displays the list of adapters along with status and priority as set in the Preferences page. The status of information sources is calculated on error types and priority. By default, priority is set according to the number of queries that are run on information sources. It can be high, medium, or low. There are four levels describing the Status: Reliable Designates an excellent work, even if it may include some errors. Satisfying Designates a good work. Defective Indicates that many errors occurred. Broken Means that information sources could not be used due to errors. Setting preferences This section describes the following: Scheduling, page 28 Notifying, page 29 Setting priorities for information sources, page 29 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 must specify the number of days in the appropriate field. For example, if you want to schedule the analysis for once every three days, in which case, you must type 3 in the appropriate field. Select the Weekly option to schedule the analysis once in a week. You must select the day from the list. For example, if you might want to schedule the analysis for every Sunday, in which case, you must select Sunday from the list. Select the Monthly option to schedule the analysis for a particular date once in a certain number of months. You must then select a specific date from the list provided and specify the number of months in the box provided. For example, suppose you want to schedule the analysis for the 1st of every three months. You would select Day 1 from the list and then type 3 in the Month(s) field. 28 EMC Documentum Federated Search Services Version 6.5 Administration Guide

29 Information Source Status Notifying Sending notifications of the scheduled analysis is optional. To send an notification: 1. In the Preferences page, select Send an e mail after each scheduled analysis. 2. In the Recipient s E mail field, type the address of the recipient. 3. Click Add to add more recipients. 4. Click OK. Setting priorities for information sources You can use this section to set the priorities of the listed adapters and empty the history details. You will be able to view the priorities you set in the Information Sources section of the Monitoring page. To set the default priorities of the adapters, select Use auto priority. To specify the priority for a particular adapter, select from Low, Medium, or High from the Priorities list. To delete the history details for a particular adapter, select Empty history for that adapter. If you want to set the priority or empty history for all listed adapters, click Select all. To clear the selection of all the adapters in the list, click Unselect. Click OK to save the changes made in this page. EMC Documentum Federated Search Services Version 6.5 Administration Guide 29

30 Information Source Status 30 EMC Documentum Federated Search Services Version 6.5 Administration Guide

31 Chapter 5 Servers Configuration This chapter describes how to configure server operations in the Servers Configuration page of Admin Center. The file locations indicated in this chapter are relative to the installation directory of Federated Search Services. The sections Integration Server, page 31 and Web Server, page 66 describe the configuration settings. Figure 3. Servers configuration page Integration Server This section of the Servers Configuration page allows you to do the following: Server configuration, page 32 EMC Documentum Federated Search Services Version 6.5 Administration Guide 31

32 Servers Configuration Client configuration, page 57 Attribute configuration, page 65 Server configuration In this part of the Servers Configuration page, you can configure the following: Proxy settings, page 32 Proxy authentication settings, page 33 Alert service settings, page 34 Adapters settings, page 35 Web front end settings, page 36 RMI settings, page 37 Scheduled queries settings, page 40 Security settings, page 42 Directory service settings, page 43 Database and account settings, page 45 SSL CA Certificate settings, page 52 Diagnose settings, page 53 Server UI settings, page 55 The server configuration settings are stored in the file www/docs/conf/server.conf. Proxy settings You can set the proxy host and proxy port to allow users to go outside the firewall. Table 2. xtrim.proxyset xtrim.proxyset Set this property to true to allow the user to go outside the firewall. False Table 3. xtrim.proxyhost xtrim.proxyhost Specify the name of the proxy. None 32 EMC Documentum Federated Search Services Version 6.5 Administration Guide

33 Servers Configuration Table 4. xtrim.proxyport xtrim.proxyport Specify the proxy port. 80 Proxy authentication settings The following settings authenticate the user to go outside the firewall. Table 5. xtrim.proxyauthenticationset xtrim.proxyauthenticationset Specify an authenticated user and password on the proxy for the user to go outside the firewall. For example, if you set this value to true, you should type a user and password in the proxyuser and proxyuserpassword fields to allow the user to go outside the firewall. False Table 6. xtrim.proxyuser xtrim.proxyuser Specify the user when the HTTP proxy authentication mode is activated. None Table 7. xtrim.proxyuserpassword xtrim.proxyuserpassword Specify the password to associate with the user for authentication when the HTTP proxy authentication mode is activated. None EMC Documentum Federated Search Services Version 6.5 Administration Guide 33

34 Servers Configuration Alert service settings The following settings let you specify an address and the alert services. Table 8. xtrim.adminmailaddress xtrim.adminmailaddress Enter the address of the administrator. None Table 9. xtrim.useragentidentification xtrim.useragentidentification As a courtesy to external websites, the system includes the address of the administrator in every HTTP request. If privacy is a concern, disable this property. No Table 10. xtrim.mailserver xtrim.mailserver Enter the name of the mail server that the alert service will use. None Table 11. xtrim.sendinitializationmailtoadmin xtrim.sendinitializationmailtoadmin Specify whether you want to receive a test while initializing the alert service. True 34 EMC Documentum Federated Search Services Version 6.5 Administration Guide

35 Servers Configuration Adapters settings The following tables describe the properties for the Adapter settings. Table 12. xtrim.brokers 10 xtrim.brokers Specify the maximum number of brokers to launch. When you specify a greater number of brokers, the server handles a greater number of searches concurrently. Table 13. xtrim.maxactionfailure xtrim.maxactionfailure Specify the maximum number of times to try a process action that keeps failing. The retry time increases exponentially with each retry. 5 For example, if the value is set to 5, and the adapter reports a network error, it retries the action four times. The retry time is 4 seconds, 8 seconds, 16 seconds, and 32 seconds. The value must not exceed 30, in which case, there will be no retries. If you do not want any retry, set the value to 1. Table 14. xtrim.adapterreloaddelay xtrim.adapterreloaddelay Specify the minimum time ( in ms) between two checks of the Federated Search SDK and adapters changes on disk. Table 15. jwrap.classifier.repairinglevel 1 jwrap.classifier.repairinglevel This property indicates the policy to use for repairing adapters (such as saving repaired grammar on disk). When set to 1, repairing is enabled only for the current page. Specify 0 if you do not want repairing to occur. EMC Documentum Federated Search Services Version 6.5 Administration Guide 35

36 Servers Configuration Table 16. xtrim.http.resolvednshostname xtrim.http.resolvednshostname This property allows you to control the amount of DNS activity the server performs. By default, it prevents the server from doing any DNS resolution (better performance). If you set it to On, then the server does a lookup, if necessary, to transform the IP address of the client into a DNS hostname. Off Table 17. xtrim.httpdatamaxsize xtrim.httpdatamaxsize Specify the maximum size of the data that can be loaded. If the server returns the data supported by the Federated Search Server, which exceeds the size specified, then the data retrieved from the source is truncated. But the adapter can choose either to truncate the data from processing or allow the data to be processed (2 MB) Web front end settings The following tables describe the properties for the Web Front end settings. Table 18. xtrim.jsp.host xtrim.jsp.host Specify the hostname of the Federated Search Server web front end. The host on which the search server runs. Table 19. xtrim.jsp.port xtrim.jsp.port Specify the port of the FS2 web front end EMC Documentum Federated Search Services Version 6.5 Administration Guide

37 Servers Configuration Table 20. xtrim.server.embeddedobjectservleturl xtrim.server.embeddedobjectservleturl Specify the URL to the servlet serving. For example, xtrim.server.embeddedobjectservleturl= myownhost:2828/get where <web_front_end_host> is the machine hosting the FS2 web front end (the value of the property xtrim.jsp.host) and <web_front_end_port> is the port used by the FS2 web front end on that machine (the value of the property xtrim.jsp.port). RMI settings The following tables describe the properties for the RMI settings. It is possible to launch two FS2 servers on the same host, the second server creates a new RMI registry overriding the first one. Table 21. xtrim.server.rmi.bindingname xtrim.server.rmi.bindingname Use this property to bind the RmiApiImpl into the RMI registry. Modify it to control two Federated Search Servers on the same host. For example, to control two Federated Search Servers on the same host, modify the property to xtrim.rmiapi2. xtrim.rmiapi Table 22. xtrim.server.rmi.registryhost xtrim.server.rmi.registryhost Specify the name of the machine that hosts the RMI registry. You can use this when two Federated Search Servers share the same registry. localhost EMC Documentum Federated Search Services Version 6.5 Administration Guide 37

38 Servers Configuration Table 23. xtrim.server.rmi.registryport 1099 xtrim.server.rmi.registryport Specify the port number of the RMI registry. You can use this when the default port 1099 is not available. Make sure this value corresponds to the one used in bin/aodatabase. Table 24. xtrim.server.rmisessiontimeout xtrim.server.rmisessiontimeout Specify the length in seconds of RMI session timeouts. This controls how the Federated Search server RMI sessions get automatically discarded after a given inactivity time. It is recommended to set this timeout to a larger value than the HTTP session timeouts in the JSP web front end (see web.xml file) (= 65 minutes) Table 25. xtrim.server.allowremoteshutdown xtrim.server.allowremoteshutdown Use this property to specify whether the server can be remotely shutdown. If you select False, the server ignores the remote shutdown command. If you select True, the server remotely shuts down. False Table 26. xtrim.server.remoteshutdownpassword xtrim.server.remoteshutdownpassword Specify the password required to shut down the server remotely. If this property is not present, then the server will ignore any remote shutdown command. None 38 EMC Documentum Federated Search Services Version 6.5 Administration Guide

39 Servers Configuration Table 27. xtrim.server.rmi.codebase xtrim.server.rmi.codebase This property is the codebase URL, where the RMI classes that areregistered into the RMI registry can be downloaded (this property will be set as the java.rmi.server.codebase property. The RMI specification has more details.) By default, this points to the local FS2 built in HTTP server. For load balanced systems, you might modify the URL to point to a unique load balanced HTTP server. For example, stubs.jar host>:<aoserver port>/class/xtrim stubs.jar Table 28. xtrim.server.rmi.forcebinding xtrim.server.rmi.forcebinding Set this property to true to have the Federated Search server force the binding of the RMI API even if another server is detected in the registry. False Table 29. xtrim.server.rmi.embeddedobjectbuffersize xtrim.server.rmi.embeddedobjectbuffersize Specify the size in bytes of the buffer used when returning embedded object content to clients. This value can be adapted to the average speed of information sources and embedded object size. This will affect perceived rate of embedded object transfer. If the embedded objects are perceived as being transferred by a few large blocks, decrease this value to provide a smoother download experience ( = 32 KB) EMC Documentum Federated Search Services Version 6.5 Administration Guide 39

40 Servers Configuration Scheduled queries settings The following tables describe the properties for the Scheduled Queries settings. Table 30. xtrim.scheduledquery.disableddays xtrim.scheduledquery.disableddays Specify the list of days when no scheduled query can start. Use the standard English abbreviations for days (Mon, Tue, Wed, Thu, Fri, Sat, and Sun), and separate them with commas if there are several days. None Table 31. xtrim.scheduledquery.maxsimultaneous 20 xtrim.scheduledquery.maxsimultaneous Specify the maximum number of scheduled queries running simultaneously. If there are more scheduled queries to update, the remaining queries must wait until one of the currently running queries stops. Table 32. xtrim.user.maxresultsinscheduledquery 200 xtrim.user.maxresultsinscheduledquery Specify 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 disk space used by self updating queries running daily. Table 33. xtrim.scheduledqueryreport xtrim.scheduledqueryreport Specify the name of the default report template used for notification when scheduled queries are updated. The real filename is obtained using the alert properties listed in the file client.conf: xtrim.reporttemplates. MailReport 40 EMC Documentum Federated Search Services Version 6.5 Administration Guide

41 Servers Configuration Table 34. xtrim.scheduledquerytimerange.starthour 0 xtrim.scheduledquerytimerange.starthour Specify the starting hour of the time range when scheduled queries can be updated each day. Each query scheduled to execute one particular day can only start during this time range. Table 35. xtrim.scheduledquerytimerange.startminute 1 xtrim.scheduledquerytimerange.startminute Specify the starting minute of the time range when scheduled queries can be updated each day. Each query scheduled to execute one particular day can only start during this time range. Table 36. xtrim.scheduledquerytimerange.endhour 6 xtrim.scheduledquerytimerange.endhour Specify the last hour of the time range when scheduled queries can be updated each day. Each query scheduled to execute one particular day can only start during this time range. Table 37. xtrim.scheduledquerytimerange.endminute 0 xtrim.scheduledquerytimerange.endminute Specify the last minute of the time range when scheduled queries can be updated each day. Each query scheduled to execute one particular day can only start during this time range. EMC Documentum Federated Search Services Version 6.5 Administration Guide 41

42 Servers Configuration Security settings The following tables describe the properties for the Security settings. Table 38. xtrim.security.providers xtrim.security.providers Specify the list of authentication providers. It is used to load a custom authentication plug in instead of or in addition to the built in mechanism. This property should contain a list of comma separated class names. In addition, it supports aliases for the default plug in: ldap and jdbc. Note that defining ldap here is redundant with property xtrim.directory.provider.ldap (this property is only kept for compatibility). To support the Siteminder plug in, you should add the following property value: xtrim.securityapi.siteminder.server. SiteminderAuthenticationProvider. jdbc Table 39. xtrim.security.credentialstore xtrim.security.credentialstore Use this property to load a custom credential storage plug in instead of or in addition to the built in mechanism. This property should contain a unique class name. None Table 40. xtrim.rmi.ssl.enabled xtrim.rmi.ssl.enabled Use this property to enable encryption (SSL) of request sent to the server (including credentials for sources) for data exchanged through RMI. False Table 41. xtrim.rmi.ssl.keystore xtrim.rmi.ssl.keystore Specify a keystore where is the Federated Search server certificate and keys and all the remote client trusted certificates. This keystore is a file available locally on the machine where the Federated Search server resides. The default JVM keystore file 42 EMC Documentum Federated Search Services Version 6.5 Administration Guide

43 Servers Configuration Table 42. xtrim.rmi.ssl.keystorepassword xtrim.rmi.ssl.keystorepassword Specify the password for the keystore file. None Directory service settings The LDAP enables you to collect user accounts of Federated Search Services automatically from the internal directory service. For organizations with a large number of user accounts, Federated Search Services can be connected to an LDAP compliant directory service. Each user account registered with the directory service is identified automatically within Federated Search Services. The following tables describe the properties for the Directory Service settings. Table 43. xtrim.directory.provider.ldap xtrim.directory.provider.ldap Specify whether users can log in with accounts managed on e remote LDAP directory service. No Table 44. xtrim.directory.provider.ldap.host xtrim.directory.provider.ldap.host Specify the hostname or IP address of the LDAP server. None Table 45. xtrim.directory.provider.ldap.port xtrim.directory.provider.ldap.port Specify the port number of the LDAP server. 389 EMC Documentum Federated Search Services Version 6.5 Administration Guide 43

44 Servers Configuration Table 46. xtrim.directory.provider.ldap.root xtrim.directory.provider.ldap.root Specify the LDAP root object under which user information is stored. For example, ʺcn=Recipients, ou=mkms, o=xerox, c=usʺ The following example uses Windows 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 off xtrim.directory.provider. ldap.root=cn=xrce None Table 47. xtrim.directory.provider.ldap.verify xtrim.directory.provider.ldap.verify Use this property to check on startup that root defines a valid LDAP object. Note, that when using NT credentials through MS Exchange or Active Directory it is necessary to turn this off, since the root is not a valid object but rather an alias. Yes Table 48. xtrim.directory.provider.ldap.attribute xtrim.directory.provider.ldap.attribute Specify the main attribute holding the login name of the user. Note, that when using Netscape Directory Server the value is uid. cn 44 EMC Documentum Federated Search Services Version 6.5 Administration Guide

45 Servers Configuration Table 49. xtrim.directory.provider.ldap.ad.shortlogin xtrim.directory.provider.ldap.ad.shortlogin Active Directory accepts the login 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 is considered to authenticate the user in the Active Directory, xtrim.directory.provider.ldap.root and xtrim.directory.provider.ldap.attribute properties are ignored. No Table 50. xtrim.directory.provider.ldap.ad.domain xtrim.directory.provider.ldap.ad.domain This property defines the root domain under which user information is stored (may be empty). For example, documentum\fs2. None Database and account settings Federated Search Services is bundled with a built in database McKoi to store user accounts. However, Federated Search Services can also be connected to an external database. This enables database administrators to use existing tools to manage data of Federated Search Services users along with existing corporate application data. Federated Search Services supports the following JDBC compliant databases: McKoi, MySQL (3.2), Oracle (8), and SQL Server. 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, Federated Search Services uses the default McKoi database. To use another database, you must modify some properties in the server.conf file. Appendix C, Configuring External Databases, has details about external databases and migrating accounts from one database to another. Note: If you use an external database, the aodatabase service is useless. If the external database is running, the FS2 server will connect the database instance thanks to the parameters defined in server.conf. The following tables describe the properties for the Database and Account settings. The tables Table 70, page 51 and Table 71, page 52, at the end of this section, provide the required values for configuring external databases. EMC Documentum Federated Search Services Version 6.5 Administration Guide 45

46 Servers Configuration Table 51. xtrim.user.usermijdbc xtrim.user.usermijdbc Use this property to access remote database through RmiJdbc. Yes Table 52. xtrim.user.jdbcclass xtrim.user.jdbcclass Specify the class for the client driver. Make sure it is in the classpath of aoserver. None Table 53. xtrim.user.jdbcurl xtrim.user.jdbcurl Specify the URL of the JDBC database that stores the account and context. None Table 54. xtrim.user.admin xtrim.user.admin Specify the login of a database user that has rights to create tables and index, that is the database administrator. It is the login that was specified when installing the database. For McKoy, the predefined value is: xtrim.user.admin=admin_user None 46 EMC Documentum Federated Search Services Version 6.5 Administration Guide

47 Servers Configuration Table 55. xtrim.user.password xtrim.user.password Specify the password for the account created for the database administrator. It is the password that was specified when installing the database. For McKoy, the predefined value is: xtrim.user.password=aupass00 None Table 56. xtrim.user.useoracle 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. No Table 57. xtrim.user.primarykeylabel xtrim.user.primarykeylabel Specify the label used to define primary keys. UNIQUE PRIMARY KEY Table 58. xtrim.user.primarykeycreateindex xtrim.user.primarykeycreateindex Select Yes for the index to automatically create a primary key. No Table 59. xtrim.user.uniquelabel xtrim.user.uniquelabel Label this property to define the unique keys. UNIQUE EMC Documentum Federated Search Services Version 6.5 Administration Guide 47

48 Servers Configuration Table 60. xtrim.user.nocachelabel xtrim.user.nocachelabel Label this property to disable row cache. None Table 61. xtrim.user.longtypelabel xtrim.user.longtypelabel Label this property to define the long values. LONG Table 62. xtrim.user.binarytypelabel xtrim.user.binarytypelabel Label this property to define the large binary data. VARBINARY Table 63. xtrim.user.varcharlabel xtrim.user.varcharlabel Label this property to define the varchar columns. VARCHAR(1024) Table 64. xtrim.user.usexopen xtrim.user.usexopen Use this property to for SQL errors to follow the XOPEN SQLstate convention (for example, a duplicate returns the error code: 23000). No 48 EMC Documentum Federated Search Services Version 6.5 Administration Guide

49 Servers Configuration Table 65. xtrim.user.duplicatetupleerror xtrim.user.duplicatetupleerror This property displays the error messages reported by the database when the same tuple is inserted twice into a given table. (This property is used when usexopen is set to No). None Table 66. xtrim.user.maxqueriesincontext 10 xtrim.user.maxqueriesincontext Specify the maximum number of queries in the context to save. This is to limit the amount of disk space the user context consumes and the number of self updating queries running daily. Table 67. xtrim.user.clearoutqueriesperiod xtrim.user.clearoutqueriesperiod As part of the security policy, you can set a period of time after which results are cleared out and only the constraint of the saved query is kept. When the user loads a saved query, if the period of time elapses, then a message is displayed stating that the query is too complex and did not collect any results, or that the results were cleared out because of the security policy set up by the administrator. This period is defined in seconds. None Table 68. xtrim.user.allowpwdsaving xtrim.user.allowpwdsaving Specify whether the user s account login and password can be saved in the database. Select true to allow the user to check the Use account login in the MAA settings instead of entering the login and password for each MAA backend. Select false to disable the property. The user must enter and update each login manually. True EMC Documentum Federated Search Services Version 6.5 Administration Guide 49

50 Servers Configuration Table 69. xtrim.user.cachedloginname xtrim.user.cachedloginname Specify the name of the guest account. This optional property is used to optimize authentication for guest account. None 50 EMC Documentum Federated Search Services Version 6.5 Administration Guide

51 Table 70. JDBC Database static properties 51 Property name McKoi Oracle MySQL SQLServer 2005 xtrim.user.useoracle No Yes No No xtrim.user.usedb Still available? Yes Yes Yes xtrim.user.usermijdbc No No No No xtrim.user.jdbcclass com.mckoi.jdbcdriver oracle.jdbc.driver. OracleDriver org.gjt.mm.mysql.driver xtrim.user.usexopen No No Yes Yes xtrim.user. primarykeylabel xtrim.user. primarykeycreateindex com.microsoft.sqlserver. jdbc.sqlserverdriver PRIMARY KEY PRIMARY KEY PRIMARY KEY PRIMARY KEY No Yes No No xtrim.user.uniquelabel UNIQUE N/A N/A N/A xtrim.user. longtypelabel xtrim.user. binarytypelabel BIGINT NUMBER(38) BIGINT NUMERIC(28) LONGVARBINARY BLOB LONGBLOB IMAGE xtrim.user.varcharlabel LONGVARCHAR VARCHAR2(1024) BLOB VARCHAR(1024) xtrim.user. nocachelabel xtrim.user. duplicatetupleerror N/A N/A N/A N/A Immediate primary Key constraint violation ORA S1009 (Mode XOpen) Duplicate entry (Mode Text) Servers Configuration

52 Servers Configuration Table 71. JDBC Database xtrim.user.jdbcurl property Database McKoi Oracle MySQL SQL Server 2005 Value description jdbc:mckoi://<database_hostname>:<database_port>/ For example: jdbc:mckoi://fraovolagd1d:3006/ For example: aobase jdbc:mysql://<database_hostname>:<database_port>/<database_name> For example: jdbc:mysql://chichet:1972/aotest jdbc:sqlserver://<database_hostname>:<database_port>;databasename=<database_ name>;instancename=<instance_name>;servername=<server_host> For example: jdbc:sqlserver://aravis:1433;databasename=ecis;instancename= DCTM;servername=aravis Note that the instancename and servername parameters are optional. SSL CA Certificate settings The following tables describe the properties for the SSL CA Certificate settings. Table 72. xtrim.ssl.truststore xtrim.ssl.truststore Specify the path to the trusted certificates store. <FS2 installation directory> /www/docs/conf/trustedcerts.cer. Table 73. xtrim.ssl.truststoretype xtrim.ssl.truststoretype Specify the type of the truststore. jks Table 74. xtrim.ssl.truststorepassword xtrim.ssl.truststorepassword Specify the password of the truststore. changeit 52 EMC Documentum Federated Search Services Version 6.5 Administration Guide

53 Servers Configuration Table 75. xtrim.ssl.keystore xtrim.ssl.keystore Specify the path to the local certificates stores. None Table 76. xtrim.ssl.keystoretype xtrim.ssl.keystoretype Specify the type of the keystore. jks Table 77. xtrim.ssl.keystorepassword xtrim.ssl.keystorepassword Specify the password of the keystore. changeit Diagnose settings You can use logs for troubleshooting and to help you understand and diagnose misconfigurations and runtime problems. The following tables describe the properties for the Diagnose settings. Table 78. xtrim.log.mode xtrim.log.mode Specify whether to use log files (file option) or standard out (screen) to display server messages. file EMC Documentum Federated Search Services Version 6.5 Administration Guide 53

54 Servers Configuration Table 79. xtrim.log.singletrace xtrim.log.singletrace Specify on to have a single log file with all the messages (in chronological order) or off to have one file per type of event. off Table 80. xtrim.log.access xtrim.log.access If the xtrim.log.mode property is defined to a file, this property defines the storage location of the access log file. To avoid creating the file, leave the property empty. /../logs/access.log Table 81. xtrim.log.error xtrim.log.error If the xtrim.log.mode property is defined to a file, this property defines the storage location of the access log file. To avoid creating the file, leave the property empty. /../logs/error.log Table 82. xtrim.log.trace xtrim.log.trace If the xtrim.log.mode property is defined to a file, this property defines the storage location of the access log file. To avoid creating the file, leave the property empty. xtrim.log.trace path is <FS2 installation directory>/www/docs If the path is incorrect, the log file prints in the current directory. /../logs/trace.log 54 EMC Documentum Federated Search Services Version 6.5 Administration Guide

55 Servers Configuration Table 83. xtrim.wrapperdebug xtrim.wrapperdebug Use this property to keep the HTML documents in xtrim. wrapperdebugpath, if a parse error occurs (useful for debugging parsers). No Table 84. xtrim.wrapperdebugpath xtrim.wrapperdebugpath Use this property to store HTML documents. For example, C:/Temp. If the path is incorrect, the log file prints in the current directory. /../logs Server UI settings The following tables describe the properties for the Server UI settings. Table 85. xtrim.servergui.icon xtrim.servergui.icon Specify the path of the search server icon relative to <FS2 installation directory>/www/docs. None Table 86. xtrim.servergui.logo xtrim.servergui.logo Specify the path of the small search server logo relative to <FS2 installation directory>/www/docs. None EMC Documentum Federated Search Services Version 6.5 Administration Guide 55

56 Servers Configuration Table 87. xtrim.servergui.aboutlogo xtrim.servergui.aboutlogo Specify the path of the search server logo relative to <FS2 installation directory>/www/docs. None Table 88. xtrim.servergui.showsearches xtrim.servergui.showsearches Use this property to display search terms in the server console (monitor activity and suggest additional information sources to better support users). No, for privacy considerations, only display backends. Table 89. xtrim.servergui.shutdownwait 10 xtrim.servergui.shutdownwait Specify the number of seconds the server should wait to shut down. Increase this value if the shutdown is not completed (in seconds). Table 90. xtrim.server.multiservermode xtrim.server.multiservermode Use this property to control the system, which is configured to use multiple servers with load balancing settings. False Table 91. xtrim.defaultwrapperupdateurl xtrim.defaultwrapperupdateurl Specify the default URL for the adapter updater containing updated adapters. None 56 EMC Documentum Federated Search Services Version 6.5 Administration Guide

57 Servers Configuration Client configuration This section describes the appearance and default behavior of the Integration Server clients. In this part of the Servers Configuration page, you can configure the following: Results settings, page 57 Localization settings, page 58 Alert settings, page 58 Clustering settings, page 59 Security settings, page 61 Personalized Relevance Ranking settings, page 62 Query Service settings, page 62 Query Service Location settings, page 63 Query Service Proposal settings, page 63 Query Service Language Resource settings, page 64 Query Service Resource settings, page 64 The client configuration settings are stored in the file www/docs/conf/client.conf. Results settings The following tables describe the properties for the Results settings. Table 92. xtrim.clientvisibleproperties xtrim.clientvisibleproperties This is a list of attributes that are transmitted to the clients. You should not change or edit this property as the system uses it internally. None Table 93. xtrim.query.refineresults xtrim.query.refineresults Specify whether each query started should reuse the results from the previous search and filter them against the new constraint, or whether all the results should be cleared automatically between searches. Select No to always clear results between two searches with the same query. Yes (Refine the query by reusing previous results still matching) EMC Documentum Federated Search Services Version 6.5 Administration Guide 57

58 Servers Configuration Localization settings The following tables describe the properties for the Localization settings. Table 94. xtrim.extralocales xtrim.extralocales This property lists the additional supported locales by the system. This is used on the server side to prepare the properties for the clients in each supported locale. The format of the locale should be according to the ISO Language Code lowercase two letter abbreviation defined by ISO 639; at least en is required. The complete list is en, fr, de, it, ja, ko, and es. None Alert settings The following tables describe the properties for the Alert settings. Table 95. xtrim.reporttemplates xtrim.reporttemplates Use this property to specify the list of available reports to use to generate alerts for scheduled queries. Standard reports are MailReport, ShortReport, and LongReport. Additionally, a localized report is available in each language pack: FrenchReport, GermanReport, ItalianReport, JapaneseReport, KoreanReport, and SpanishReport. For example, xtrim.reporttemplates = MailReport,ShortReport,LongReport None Table 96. xtrim.report.mailreport xtrim.report.mailreport This property specifies the standard English report. The path to this file is relative to <FS2 installation directory>/www/docs/conf. For example, xtrim.report.mailreport = MailerReport_en.rtl None 58 EMC Documentum Federated Search Services Version 6.5 Administration Guide

59 Servers Configuration Table 97. xtrim.report.shortreport xtrim.report.shortreport This property specifies the standard English short report. The path to this file is relative to <FS2 installation directory>/www/docs/conf. For example, xtrim.report.shortreport = MailerReportShort_en.rtl None Table 98. xtrim.report.longreport xtrim.report.longreport This property specifies the standard English complete report. The path to this file is relative to <FS2 installation directory>/www/docs/conf. For example, xtrim.report.longreport = MailerReportLong_en.rtl None The following property is available for Chinese, French, German, Italian, Japanese, Korean and Spanish languages. Table 99. xtrim.report.<language>report xtrim.report.<language>report This property specifies the report in the chosen language available with the corresponding language pack. The path to this file is relative to <FS2 installation directory>/www/docs/conf. For example, xtrim.report.frenchreport = MailerReport_fr.rtl xtrim.report.japanesereport = MailerReport_ja.rtl None The section Appendix B, Report Generator describes how to customize your reports. Clustering settings The following tables describe the properties for the Clustering settings. Table 100. xtrim.cluster.issupported xtrim.cluster.issupported Use this property to activate the clustering feature. True EMC Documentum Federated Search Services Version 6.5 Administration Guide 59

60 Servers Configuration Table 101. xtrim.cluster.clusterthreshold 5 xtrim.cluster.clusterthreshold Specify the minimum number of results to compute the clusters. Minimum value = 1. Table 102. xtrim.cluster.subclusterthreshold 5 xtrim.cluster.subclusterthreshold Specify the minimum number of results in a clusters to compute the subclusters. Minimum value = 1. Table 103. xtrim.cluster.minimaldelay 0 xtrim.cluster.minimaldelay Specify the minimum time to wait for enough results before computing the first set of clusters (in seconds). Note: For the search server standard interface, set this value to 0, or the cluster frame may not be refreshed until the end of the query. Table 104. xtrim.cluster.defaultrelevantattributes xtrim.cluster.defaultrelevantattributes Specify the attributes to consider while computing clusters by Topics. At least one attribute is required. title, abstract, body, collection Table 105. xtrim.cluster.notrelevantattributes xtrim.cluster.notrelevantattributes Specify the attributes, that should not be considered while computing clusters. None 60 EMC Documentum Federated Search Services Version 6.5 Administration Guide

61 Servers Configuration Table 106. xtrim.cluster.suffixnotrelevantattributes xtrim.cluster.suffixnotrelevantattributes Specify the suffix attributes, that should not be considered while computing clusters. None Table 107. xtrim.cluster.prefixnotrelevantattributes xtrim.cluster.prefixnotrelevantattributes Specify the prefix attributes, that should not be considered while computing clusters. None Security settings The following tables describe the properties for the Security settings. Table 108. xtrim.server.allowauthcookie xtrim.server.allowauthcookie Use this property to specify whether clients can bypass login and password authentication by using an automatic login mechanism using a permanent cookie. The client and the server share this property. True Table 109. xtrim.server.checkipforcookie xtrim.server.checkipforcookie If the client uses an authentication cookie to log in to the Integration Server (xtrim.server.allowauthcookie), this property indicates whether the client must check the IP of the user corresponding to the IP address used while logging in the first time. The user can log in from different machine/browser, but the cookie on each of these browsers will be specific to the IP address of its machine. The client and the server share this property. True EMC Documentum Federated Search Services Version 6.5 Administration Guide 61

62 Servers Configuration Personalized Relevance Ranking settings The following tables describe the properties for the Personalized Relevance Ranking settings. Table 110. xtrim.profile.issupported xtrim.profile.issupported Use this property to activate the relevance ranking feature. True Table 111. xtrim.profile.relevantattributes xtrim.profile.relevantattributes This property lists all the attributes used for computing the personalized relevance ranking on results. For example, xtrim.profile.relevantattributes = title, body, abstract, collection, description All attributes Query Service settings The following tables describe the properties for the Query Service settings. Table 112. xtrim.queryservice.issupported xtrim.queryservice.issupported Use this property to enable or disable the query service settings. No Table 113. xtrim.queryservice.serviceavailable xtrim.queryservice.serviceavailable Specify all the available services. The first service in the list is the default service. To disable this property, remove all the available services. For example, xtrim.queryservice.serviceavailable = spellchecker, termino, sqlet, collection, authors None 62 EMC Documentum Federated Search Services Version 6.5 Administration Guide

63 Servers Configuration Table 114. xtrim.queryservice.languagesservice xtrim.queryservice.languagesservice Specify all the available languages for services. The standard language is English. Additionally, each language pack provides a language for services. The list is: french, german, italian, spanish. None Query Service Location settings Use the properties of the Query Service Location settings to specify the locations of query services. To add a service, type the service name in the xtrim.queryservice.class. field with the corresponding location value and click Add. The predefined query service locations are: xtrim.queryservice.class.authors = xtrim.services.query.queryservicewrapper xtrim.queryservice.class.collection = xtrim.services.query.queryservicewrapper xtrim.queryservice.class.spellchecker = xtrim.services.query.spellchecker. QueryServiceSpellChecker xtrim.queryservice.class.termino = xtrim.services.query.eurodicautom. QueryServiceEurodicautom To delete a service, click Delete in the row corresponding to this service. Query Service Proposal settings Use the properties of the Query Service Location settings to check the service proposals before posting them. To add a property, type the property name in the xtrim.queryservice.checkproposals. field with the corresponding value and click Add. The predefined query service proposals are: xtrim.queryservice.checkproposals.authors = No xtrim.queryservice.checkproposals.collection = No xtrim.queryservice.checkproposals.spellchecker = Yes xtrim.queryservice.checkproposals.termino = No To delete a property, click Delete in the row corresponding to this property. EMC Documentum Federated Search Services Version 6.5 Administration Guide 63

64 Servers Configuration Query Service Language Resource settings Use the properties of the Query Service Language Resource settings to set up of dictionaries used by language services. These are the paths to the dictionaries the spell checker uses. These paths are relative to <FS2 installation directory>/www/tomcat/webapps/ao/. The following tables describe the properties for the Query Service Language Resource settings. Table 115. xtrim.queryservice.dictionary.default xtrim.queryservice.dictionary.default This is the default dictionary used if the client locale is not supported. For example, xtrim.queryservice.dictionary.default = dictionary/default.dic None The following property is available for the English, French, German, Italian, and Spanish languages. Table 116. xtrim.queryservice.dictionary.<language> xtrim.queryservice.dictionary.<language> This is the standard dictionary for the chosen language. For example, xtrim.queryservice.dictionary.english = dictionary/english.dic None Query Service Resource settings Use the properties of the Query Service Resource settings to specify miscellaneous properties for query services. To add a property, type the property name in the xtrim.queryservice. field with the corresponding value and click Add. To delete a property, click Delete in the row corresponding to this property. The predefined properties for query services are: 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 64 EMC Documentum Federated Search Services Version 6.5 Administration Guide

65 Servers Configuration 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 Attribute configuration This section describes the English attributes and English attributes translation available in the file www/docs/conf/attributes_en.properties. In this part of the Servers Configuration page, you can add or delete an English attribute with the description/translation. For each attribute, you can define the following: Attribute description, page 65 Attribute translation, page 65 Attribute description This property describes the English attributes. To add an attribute and its description, type the attribute name and its description in the respective fields and click Add. To delete an attribute, click Delete in the row corresponding to this attribute. Some of the predefined attributes descriptions are: Attribute.URL = URL contains an hyper text link or Internet address where to find the resource Attribute._internal banner URL = Link to the banner Attribute._internal banner image URL = Link to the banner image Attribute._internal banner text body = Body of the banner Attribute translation Use this property to describe English attribute translation. To add the translation of an attribute, type the translation in the field and click Add. To delete an translation, click Delete in the row corresponding to this translation. Some of the predefined attributes translations are: AttributeTranslation.URL = URL AttributeTranslation._internal banner URL = banner URL AttributeTranslation._internal banner image URL = banner_image URL AttributeTranslation._internal banner text body = banner_body EMC Documentum Federated Search Services Version 6.5 Administration Guide 65

66 Servers Configuration Web Server This section of the Servers Configuration describes the following: Web Server configuration, page 66 Configuration of the Web Server with the Integration Server, page 68 Web Server configuration You can specify the Web Server address and Web Server debug parameters. The Web Server configuration settings are stored in the file www/tomcat/conf/server.xml. The following tables describe the properties for the Web Server configuration. Table 117. Port Port Specify the port of a web front end. For example, Port = 3000 None Table 118. Shutdown port Shutdown port Specify the shutdown port of a web front end. For example, Shutdown port = 3001 None Table 119. maxsparethreads maxsparethreads Specify the maximum number of the unused request processing threads to allow until the thread pool stops the unnecessary threads. For example, maxspare Threads = 75 None 66 EMC Documentum Federated Search Services Version 6.5 Administration Guide

67 Servers Configuration Table 120. maxthreads maxthreads Specify the maximum number of request processing threads to be created by this connector; this value determines the maximum number of simultaneous requests that can be handled. For example, maxthreads = 150 None Table 121. minsparethreads minsparethreads Specify the number of request processing threads that are created when this connector is first started. The connector also makes sure it has the specified number of idle processing threads available. Set this property to a value smaller than that of maxthreads. For example, minspare Threads = 25 None Table 122. acceptcount acceptcount Specify the maximum queue length for incoming connection requests when all possible request processing threads are in use. Any requests received when the queue is full will be refused. For example, acceptcount = 100 None Table 123. Debug setting Debug setting Use this property to set up of the Web Server trace level. For example, Debug setting = 0 None EMC Documentum Federated Search Services Version 6.5 Administration Guide 67

68 Servers Configuration Configuration of the Web Server with the Integration Server This section describes the configuration of the Web Server with the Integration server. The settings are stored in the file www/tomcat/webapps/ao/web INF/web.xml. This section consists of the following parts: Proxy settings, page 68 Proxy Authentication settings, page 69 RMI settings, page 70 Default Account, page 71 Domains settings, page 72 Domains Icon settings, page 72 Results settings, page 73 Export settings, page 74 Diagnose Settings, page 76 Proxy settings The following tables describe the properties for the Proxy settings. Table 124. ASKONCE_PROXY_SET ASKONCE_PROXY_SET Select an attribute true or false to use a proxy to go outside the firewall. None Table 125. ASKONCE_PROXY_HOST ASKONCE_PROXY_HOST Specify the hostname or the IP address of the proxy. For example, ASKONCE_PROXY_HOST = broker.documentum.fr None 68 EMC Documentum Federated Search Services Version 6.5 Administration Guide

69 Servers Configuration Table 126. ASKONCE_PROXY_PORT ASKONCE_PROXY_PORT Specify the TCP/IP port the proxy listens to. For example, ASKONCE_PROXY_PORT = 8000 None Proxy Authentication settings The following tables describe the properties for the Proxy Authentication settings. Table 127. ASKONCE_PROXY_AUTHENTICATION ASKONCE_PROXY_AUTHENTICATION Use this property to activate the HTTP authentication between the Web Server and the proxy server. None Table 128. ASKONCE_PROXY_USER_ ASKONCE_PROXY_USER_ Specify the user to use when the HTTP proxy authentication mode is activated. None Table 129. ASKONCE_PROXY_USER_PWD ASKONCE_PROXY_USER_PWD Specify the user password to use when the HTTP proxy authentication mode is activated. None EMC Documentum Federated Search Services Version 6.5 Administration Guide 69

70 Servers Configuration RMI settings The following tables describe the properties for the RMI settings. Table 130. ASKONCE_RMI_NAME ASKONCE_RMI_NAME Specify the name of the integration server RMI module. For example, ASKONCE_RMI_NAME = xtrim.rmiapi None Table 131. RMI_REGISTRY_HOST RMI_REGISTRY_HOST Specify the name of the machine that hosts the RMI registry. For example, RMI_REGISTRY_HOST = genepi None Table 132. RMI_REGISTRY_PORT RMI_REGISTRY_PORT Specify the port number of the RMI registry. For example, RMI_REGISTRY_PORT = 3005 None Table 133. RMI_SSL_ENABLED RMI_SSL_ENABLED Use this property to enable the encryption (using SSL) of the responses from the server to the client (results and content) trough the RMI communication. False 70 EMC Documentum Federated Search Services Version 6.5 Administration Guide

71 Servers Configuration Table 134. RMI_SSL_KEYSTORE RMI_SSL_KEYSTORE Specify the location of the keystore to use to store keys and trusted certificates for RMI Communication with the Federated Search server. The default JVM keystore Table 135. RMI_SSL_KEYSTORE_PASSWORD RMI_SSL_KEYSTORE_PASSWORD Specify the password for the keystore. The default JVM keystore password Default Account The following tables describe the properties for the Default Account. Table 136. DEFAULT_LOGIN_NAME DEFAULT_LOGIN_NAME Specify the default login to use when no personal login is defined. For example, DEFAULT_LOGIN_NAME = guest None Table 137. DEFAULT_LOGIN_PASSWORD DEFAULT_LOGIN_PASSWORD Specify the default password of the default login. For example, DEFAULT_LOGIN_PASSWORD = askonce None EMC Documentum Federated Search Services Version 6.5 Administration Guide 71

72 Servers Configuration Domains settings The following tables describe the properties for the Domains settings. Table 138. MAX_NUMBER_OF_SELECTED_DOMAINS MAX_NUMBER_OF_SELECTED_DOMAINS Specify the maximum number of domains to display in the JSP search page. For example, MAX_NUMBER_OF_SELECTED_DOMAINS = 10 None Table 139. JSP_DOMAIN JSP_DOMAIN Specify the domain name for the JSP client to look for in the All domain. For example, JSP_DOMAIN = JSP None Table 140. MAX_DOMAIN_NAME_LENGTH MAX_DOMAIN_NAME_LENGTH Specify the maximum number of letters to display for the domain name in the search panel. For example, MAX_DOMAIN_NAME_LENGTH = 15 None Domains Icon settings Use this property to set the icons used to display the domains. For each domain, the client uses two icons on/off, for example, the Business domain is represented by icons/dom06on.gif and icons/dom06of.gif. To add an icon setting, type the icon name and its domain name in the respective fields and click Add. To delete an icon setting, click Delete. 72 EMC Documentum Federated Search Services Version 6.5 Administration Guide

73 Servers Configuration Results settings The following tables describe the properties for the Results settings. Table 141. MAX_BODY_LENGTH MAX_BODY_LENGTH Specify the maximum body length in the overview view column of the result panel. For example, MAX_BODY_LENGTH = 150,300 None Table 142. MAX_DISPLAYED_RESULT MAX_DISPLAYED_RESULT Specify the maximum number of results to display in the result page and consult page in order to avoid browser crash. For example, MAX_DISPLAYED_RESULT = (minimum accepted = 5) Table 143. NB_RESULTS_PAGE_LIST NB_RESULTS_PAGE_LIST Specify the possible number of results to display in the result panel (per page) as a comma separated list of positive values. Every value is presented as an option in the Preferences panel. For example, NB_RESULTS_PAGE_LIST = 100,200,300,400,500 The default one is the first one. Table 144. TOOLTIP_LENGTH_LIST TOOLTIP_LENGTH_LIST Specify the possible maximum tooltip body length of the result panel as a comma separated list of positive values. The first two values are presented as options in the Preferences panel. For example, TOOLTIP_LENGTH_LIST = 500,1000 The default one is the first one. EMC Documentum Federated Search Services Version 6.5 Administration Guide 73

74 Servers Configuration Table 145. SORTABLE_ATTRIBUTES SORTABLE_ATTRIBUTES Specify defines the list of attributes available for sorting in the expand view. The attribute name is defined in the internal language English. For example, SORTABLE_ATTRIBUTES = title,author,collection,date,selection,source,score None Table 146. MAIN_CONTROLLER MAIN_CONTROLLER Specify defines the name of the mail integration server controller. The name you enter appears in the integration server URL. This name must match the URL mapping for the servlet ECIS, but without the leading /. For example, MAIN_CONTROLLER = ecis.jsp None Export settings The following tables describe the properties for the Export settings. The Export settings define the available export formats for the reports. Table 147. exportlist exportlist Specify the available export formats For example, exportlist=html,xml,xls,pdf None For each format listed as a value of the exportlist property, an entry specifies the report jsp for this format. For example, html=htmlreport.html (Default = None) pdf=pdfreport.pdf (Default = None) xls=xlsreport.xls (Default = None) xml=xmlreport.xml (Default = None) The HTML, XML, XLS and PDF formats are predefined. You can define a custom format. However, before defining another report format, you must modify and compile the custom report servlet CustomReportController.java. The Federated Search Services Development Guide provides more information about custom reports. 74 EMC Documentum Federated Search Services Version 6.5 Administration Guide

75 Servers Configuration Table 148. MAX_QUERY_VIEW_RANGE 5 MAX_QUERY_VIEW_RANGE Specifies the maximun number of visible queries allowed in the user interface for a persistent account. Null or negative value is not allowed. Table 149. JSP_DEBUG JSP_DEBUG Allows to set up the web server traces level. False Table 150. Session timeout 30 Session timeout Specifies the timeout in minutes for shared account session. This time is multiplied by six for persistent accounts. Table 151. RESULTS_TIMEOUT 0 RESULTS_TIMEOUT Define the timeout in milliseconds when waiting for the results and query completion from the integration server. This is not a global timeout for the whole query, it is a timeout for any response from the integration server, while fetching results. A value lower than or equals to 0 means no timeout. By default, the value is set to 0 and the timeout of the integration server adapter is used. The RESULTS_TIMEOUT is completely independent of the adapter timeout in case of buggy sources. EMC Documentum Federated Search Services Version 6.5 Administration Guide 75

76 Servers Configuration Diagnose Settings Use the Diagnose settings to create logs related to the integration server action URL. In the logs, POST parameters are displayed as GET parameters. Session s are also logged, so that you can extract a user session from the log file. The log file name will be <prefix><date><suffix> where the date format is yyyy mm dd. Table 152. suffix suffix Suffix for the log file, for example, suffix=.txt. None Table 153. prefix prefix Prefix for the log file, for example, prefix=ao_access_log. None Table 154. directory directory Directory for the log file, relative to the web server root, for example, directory=logs. By default, on Windows, the web server root is C:\Program Files\Documentum\fs2\www\tomcat\. None Table 155. accesslogfilter accesslogfilter Filter class mapping. None 76 EMC Documentum Federated Search Services Version 6.5 Administration Guide

77 Chapter 6 Indexing management In addition to searches on websites, on intranets, or on your desktop, you also have the possibility to run searches on shared resources such as network drives and on local drives. However, before running a search on documents located on shared or local drives, you need to index these documents. The indexing of drives is possible using the Federated Search Services Indexing functionality. Federated Search Services integrates two Open Source projects: Lucene API for the indexing and Nutch engine to fetch and search the documents. To run queries and receive results, FS2 server communicates with the Indexing server (or Indexer) through a specific adapter. To enable the Indexing functionality, you need to install at least one Indexer. You should install the Indexer separately from Federated Search Services, but the FS2 Admin Center should already be up and running. Documents are fetched as collections. A collection is made of one or several set(s) of documents; each set can be identified by a directory path. Collections are public by default, but the administrator can also define secure collections that control users credentials. An index is created for each collection. This chapter describes the following: Overview of the FS2 Indexing functionality, page 77 Administering the Indexing, page 81 Overview of the FS2 Indexing functionality Once the Indexer is installed, the end user can search the shared or local drives by selecting the corresponding sources in Discovery Manager or in Webtop Advanced Search panel. The end users access public files with access rights for everyone and protected files for which they have enough access rights once they have provided their own credentials. Protected files are not visible to end users that do not have enough rights, who did not provide credentials, or who provided wrong credentials. You can launch the indexing on a regular basis by defining a schedule for each Indexer. When the Indexer processes an already indexed collection, only new or modified documents are indexed. Users can use the Search functionality while the Indexer is indexing files. However, the queries will run against previously created indexes for the selected collections. Once a collection is fully indexed, the index is updated and available for search. EMC Documentum Federated Search Services Version 6.5 Administration Guide 77

78 Indexing management Prerequisites and initial configuration Installing the Indexer The Indexer requires Federated Search Services and must be installed on a Microsoft Windows host. Once you installed Federated Search Services, and while Admin Center is running, you can install the Indexer as described in the Federated Search Services Installation Guide. If Admin Center is not running when you install the Indexer, you have to register the Indexing server manually as described in To register an Indexing server:, page 81. By default, the Indexer is installed in C:\Program Files\Documentum\fs2\Indexer\. In this documentation, this directory will be referenced as <Indexer installation directory>. Configuring the Indexing for the first time Using Admin Center, configure the Indexing server and create the collections as described in Configuring the Indexing, page 81. The first time you create the collections, to validate the connection with the FS2 server, we recommend to select small sets of documents and index them immediately. Then configure an adapter backend and test it as soon as the indexing is complete. The IndexingOption adapter is installed during Federated Search Services installation, use it to create your own backends. Each backend is dedicated to one collection only, so you can have several backends for the same Indexing server. When the tests are successful, you can schedule the indexing of the collections. There is only one schedule by indexer. Since the indexing process can be resource consuming, in particular when the collections are indexed for the first time, we recommend to install the Indexer on a different machine from Federated Search Services. However, installing Federated Search Services and the Indexer on the same machine is supported. Supported environments This section describes the supported file systems and supported file formats. Supported file systems The Indexer only supports Microsoft Windows shared or local drives. The file protocol is used for public collections but for secured collection, only the Server Message Block (SMB) network protocol is supported, using the Windows NTLM authentication mechanism. The file protocol allows to index local files or files on mapped network drives. The SMB protocol allows to index remote shared drives, in this case, you must provide credentials for the indexing server to access and index the documents content. 78 EMC Documentum Federated Search Services Version 6.5 Administration Guide

79 Indexing management Depending on the IT policies in your company, you may need to update regularly the credentials required for the secure collections. To change passwords:, page 83, describes how to update the credentials. Supported file formats The following formats can be indexed: HTML files (*.htm, *.html, *.xhtml) Text (*.asc, *txt) XML (*.xml) Microsoft Office (Word, Excel, and PowerPoint), from MS Office 97 to MS Office 2007 (*.doc, *.docx, *.xls, *.xlsx, *.ppt, *.pptx) PDF (*.pdf) You can add an extension for an existing parser. For example, the text parser can parse text files with a *.log or *.ini file extension. To add a file extension to an existing parser:, page 84, describes how to manually add file extensions. Note: Files in supported format but with no extension are not indexed. Collections Collections are sets of documents located in shared or local drives. Each set is defined by its location path in URL format. The location path is defined by the protocol you chose, the host, and the directory path (including the drive name). By default, collections are considered to be public and can be accessed by users without providing credentials. It is your responsibility to define a collection as a secure collection. In this case, you must use the SMB protocol and provide credentials with enough rights or privileges to access and index the documents content for this collection. Configuration possibilities and limitations The Windows domain on which Federated Search Services is installed can be different from the domain on which the Indexer is hosted. Similarly, you can install various Indexers hosted on various domains. It is recommended to create collections on drives on the same domain as the Indexer. If you create collections on drives on a different domain, the users credentials cannot be controlled and only public documents will be returned. Access to the results Once the search has return results, users can access the content of any result. Results can be accessed as embedded objects. This mechanism allows to check the credentials. In Discovery Manager, the EMC Documentum Federated Search Services Version 6.5 Administration Guide 79

80 Indexing management properties cache URL or URL are displayed for information only and cannot be used to access the results content. In Webtop, users have the possibility to save the documents to the repository. Security User credentials are checked at search and access time. If the credentials provided are not valid, users only get as results documents from public collections or documents that can be read by everybody. It is your responsibility to decide if a collection is public or requires authentication. Running the Indexing as a Windows Service When installing the Indexer, you can choose to install it as a Windows Service by selecting the corresponding checkbox during the installation process. Once installed as a Windows service, the Indexing server starts automatically when the machine boots. If you did not select the Install as a Windows service option, you can install the Indexer as a Windows service by executing the following command (assuming you installed the Indexer in the default location): C:\Program Files\Documentum\FS2\Indexer\bin\FS2IndexerService.bat install The output of this command is as follows: %> The service 'FS2Indexer' has been installed. The EMC Documentum FS2 Indexer Service is created. You can uninstall the Indexer service using the remove parameter. Limitation: When you create the collections, you can only use the SMB protocol when using the Indexing as a Windows service. Prerequisites Before running the indexing, make sure no other process is locking (or could lock) the files during the indexing. If a file is locked by a process, such as an antivirus application or a defragmenter application, the indexing skips the collection and logs an error. The initial status of the collection is restored and the collection will be indexed by the next indexing. The error logged is the following: [ :05:51,862 ERROR ERROR IN PROCESS INSTANCE:test5] java.io.ioexception: Unable to modify the crawl database. Some files are probably locked by another process. Please check folder <Indexing data directory>/indexlist/<collection_identifier>/crawldb Where <Indexing data directory> is, by default, C:\Documentum\fs2Indexes. <collection_identifier> is a randomly generated number. 80 EMC Documentum Federated Search Services Version 6.5 Administration Guide

81 Indexing management Sizing guidelines In order to optimize the indexing, here are some recommendations on your hardware resource requirements: Estimate the size of the data to index and consider having at least the same disk space available for the creation of the indexes. The size of the created indexes depends on the formats of files indexed. Plain text files generate indexes slightly bigger than the collection. Other formats, such as Office or PDF files, generate indexes much smaller than the collection (20% of original size). The default JVM memory size is 1GB, Optimizing the indexing performance, page 85, describes how and when you can modify it. For a better performance, consider having at least a dual core processor on the indexer machine. Collections can be queried as soon as they are indexed. To make them available rapidly, create collections of less than or equal to documents. The average indexing time observed is 2 GB per hour. Administering the Indexing During the Indexer installation, you specified the host and port for the Admin Center. This allows the Indexer to automatically register itself and a link is created in the Admin Center s Indexing Servers page. If Admin Center was not running when you installed the Indexer then you need to add it manually as described in To register an Indexing server:, page 81. To register an Indexing server: 1. Click Indexing Management in the Home page of Admin Center. The Indexing Servers page appears. 2. In the first row, set the host and port of the Indexing server. 3. Click Add to add this new Indexing server. By default the credentials are the same as for the Admin Center. A new Indexing server is added to the server list. 4. Click on the Indexing server name to access to the administration page for this server. On your first access, the web browser may indicate certificate errors, accept the certificate. Configuring the Indexing Once the Indexer is registered and running, you can configure it to index the drives on which you want to run queries. To configure the Indexing functionality: Prerequisite: an Indexing server is registered. 1. Create a collection: Create at least one collection for the Indexing server. EMC Documentum Federated Search Services Version 6.5 Administration Guide 81

82 Indexing management a. Click on the Indexing server name in the server list section of the Indexing Servers page. The Indexing Management page appears where you can manage the collections of the Indexing server. b. Click Add to create a collection. The Edit collection page appears. c. Type the name and description of the collection. 2. Add URLs for the directories to index: Add a new URL to the collection. You can add several URLs in one collection; each URL points to a directory located on a drive and that you want to index. a. In the Protocol list, select the protocol to access the drive. If you use the file protocol, you can only create a public index. To create a protected index, use the smb protocol. b. If you select the SMB protocol, type the hostname. If you select the file protocol, skip this step. If credentials are available for this host, they are used and a message indicates Using credentials: <login_name>. If no credentials are found, provide valid credentials. Next to the message Missing Credentials, click Edit. In the Credentials Settings for host: <host_name> popup window, type the login, password and Windows domain required to access the host. The credentials used must have enough rights or privileges to access the documents content for this collection. c. Type the directory path including the drive name, not the driver letter. d. Click Add to add the URL to the collection. You can repeat this procedure to add as many URLs as you need. 3. Define a schedule for the indexing You can do one of the following: Create a new schedule as described in To create or modify the schedule:, page 83. Launch the indexing immediately by clicking Start. The index list displays all indexes available with the corresponding information. For each index, you can know: The description of the index. The URL(s) that define(s) the index. The status of a selected collection, that indicates: The total number of documents in the collection. The number of documents that will be parsed, that is, indexed. The number of documents that have been parsed. The number of documents that cannot be accessed (this may be an access rights issue). The current status when an indexing is in progress. In the Indexing Management page, click More Details to get the indexing status for every document. To delete an existing collection: 1. Assuming you are in the Indexing Management page of Admin Center, select the collection in the Collections list. 82 EMC Documentum Federated Search Services Version 6.5 Administration Guide

83 Indexing management 2. Click Delete. This deletes the collection information and the corresponding index, if available. To clean all collections: 1. Open the Indexing Management page of Admin Center. 2. In the Indexing Process pane, click Clean. Unlike the delete action, the collection information (including the list of URLs) is kept and all the indexes are deleted. Note: When you remove a URL from a collection, the indexing must be restarted or you have to wait for the next indexing to take the changes into account To create or modify the schedule: 1. In the Indexing Process pane, click Schedule. If the indexing is in progress, click Stop to stop the indexing and enable the Schedule button. The Scheduling settings page appears 2. Define the start time and frequency of the indexing runs. It is not possible to define time ranges or fixed dates. The frequency of the schedule can be set on a daily, weekly, or monthly basis. To disable the schedule, select None. All the URLs that are not already fetched are indexed according to the schedule. The various steps of the indexing process are displayed in real time. By default, no schedule is created, so remember to create a schedule to index your directories regularly. To change passwords: The credentials are shared between collections for the same host. You only have to change the password once and it is automatically updated for all collections. 1. In the Collections pane, click Passwords. The Update passwords page appears. The page displays the list of known hosts: these hosts have already been used for some collections URLs. 2. In the Host list, select the host for which you want to change the password. 3. In the right pane, enter the login, the password, and the Windows domain. You can either use an existing login and update the password, or you can enter a new login. In this case, the new credentials override the previous credentials for this host. 4. Click Apply to validate the password update. 5. To modify passwords for other hosts, repeat the procedure from Step 2 to Step Click Close to exit. Configuring adapter backends A specific adapter is used for the indexed collections. The installation and configuration of the adapter are described in the Federated Search Services Adapter Installation Guide. You must create all needed backends, one for each collection. EMC Documentum Federated Search Services Version 6.5 Administration Guide 83

84 Indexing management When you configure a backend, you must specify the Indexing server to use by defining the host, port, and protocol (by default, https) properties and specify the collection for this backend. Advanced configuration This section provides some procedures to help you better configure the indexing. All the procedures correspond to manual configuration to perform on the Indexer host machine. When you install the Indexer, two web applications are installed in a Tomcat instance, one for the indexing, the other to handle searches. The two webapps are located at <Indexer installation directory>/webapps/. In addition to the Admin center, some configuration files are available for these webapps and allow to fine tune the Indexing configuration. To add a file extension to an existing parser: To index a file, it is necessary to have a parser that can read the file depending on its format. Each format requires a specific parser. The supported formats are identified by the MIME type and by file extensions. Some file extensions may not be currently supported by the Indexing functionality, but if a parser already exists for their MIME type, then you can map them to this parser. For example, if you want to index *.ini files that are in text format, you can map them to the text parser. 1. Open the mime types.xml configuration file located at: <Indexer installation directory>\webapps\admin\admin\web INF\classes\ 2. The formats are identified by their MIME type. Locate the <mime type> element corresponding to the format that is compatible with the file extension you want to add. For example: <mime type name="text/plain" description="text File"> <ext>asc</ext> <ext>txt</ext> </mime type> 3. Add an <ext> element inside the <mime type> element. 4. Write the file extension as the value of the new element: <mime type name="text/plain" description="text File"> <ext>asc</ext> <ext>txt</ext> <ext>ini</ext> </mime type> 5. Open the crawl urlfilter.txt configuration file located at: <Indexer installation directory>\webapps\admin\admin\web INF\classes\ 6. Add a regular expression to include the URLs that start with file or smb and end with ini, Ini or INI: +(file smb):.*.[ii][nn][ii]$ To allow queries from another FS2 server: When you install the Indexer, you specify a FS2 server host. To run queries on the indexer from another FS2 server host, you must enable the second FS2 server for the Indexer. 84 EMC Documentum Federated Search Services Version 6.5 Administration Guide

85 Indexing management 1. Open the context.xml configuration file located at: <Indexer installation directory>\conf\ 2. Add the following line: <Parameter name="admincenter_host_x" value="<host_name>" override="false"/> Where x is a number that you increment for each additional host, <host_name> is a valid DNS name or an IP address. An alternative procedure is to disable the host verification. To do so, in the context.xml configuration file, set the DESACTIVATE_REMOTE_HOST_VERIFICATION parameter to true. In this case, queries can be run from any host without any restriction (credentials are not required). To change the credentials for the Indexing management: The same credentials are used for the Admin Center and the Indexing management. If you modify the Admin Center credentials, you must also modify the credentials for the Indexing management. 1. Launch the encryptpassword.bat script located at: <Indexer installation directory>\webapps\admin\admin\web INF\classes\ 2. Type the new password. 3. Copy the encrypted value returned by the script. 4. Open the context.xml configuration file located at: <Indexer installation directory>\conf\ 5. To set a new login, specify the value of the ADMIN_LOGIN parameter. 6. To modify the password value, paste the encrypted password as the value of the ADMIN_PASSWORD parameter. To always prompt users for their credentials: You can disable the public access to search results by always prompting users for their credentials. 1. Open the web.xml configuration file located at: <Indexer installation directory>\webapps\search\search\web INF\ 2. Set the FORCE_LOGIN parameter to true. Optimizing the indexing performance The indexing performance depends on the memory of the machine and the size and format of the files indexed. By default, the memory required by the Indexing functionality is 1 GB. You may want to increase the memory size of the JVM, in particular on 64 bit operating systems. On 32 bit Windows systems, the maximum heap size is limited to around 1.6G. Note also that indexing documents with large file size consume more memory. For this reason, the maximal file size is set to 100 MB by default. If you know that you will only process small files, you can reduce the maximum file size. Indexing some formats (such as PDF) is more resource consuming than indexing other formats (such as plain text). EMC Documentum Federated Search Services Version 6.5 Administration Guide 85

86 Indexing management To modify the maximum file size: 1. Open the nutch site.xml configuration file located at: <Indexer installation directory>\webapps\admin\admin\web INF\classes\ 2. Locate the <property> element named file.content.limit and corresponding to the maximum file size for the file protocol: <property> <name>file.content.limit</name> <value> </value> <description>... </property> 3. Modify the content of the <value> element. 4. Repeat Step 2 and Step 3 for the SMB protocol: <property> <name>smb.content.limit</name> <value> </value> <description>... </property> To modify the memory size (standard mode): 1. Locate the catalina.bat file corresponding to the Tomcat instance of the Indexing: <Indexer installation directory>\bin\ 2. Edit the file with a text editor and modify the following line: set JAVA_OPTS=%JAVA_OPTS% Xmx1024m XX:MaxPermSize=92m To modify the memory size (before installing the Indexing as a Windows service): You can apply the following steps before installing the Indexing as a Windows service, or, if the service is already installed, after uninstalling it. 1. Locate the file used to install the Indexing as a Windows service and edit it with a text editor: <Indexer installation directory>\bin\fs2indexerservice.bat 2. Look for the line starting with: "%EXECUTABLE%" //US//%SERVICE_NAME% ++JvmOptions and ending with: JvmMs 256 JvmMx Modify the value of the parameter JvmMx, that is the maximum memory (maximum memory pool size in MB). (JvmMs indicates the initial memory pool size in MB.) 4. (Re)install the Indexing as a Windows service. To modify the memory size (when the Indexing is installed as a Windows service) : 1. Locate the following file: <Indexer installation directory>\bin\fs2indexer.exe 2. Launch the file. The FS2 Indexer Properties window appears. 3. Open the Java thumbnail. 4. Modify the value of the Maximum memory pool parameter. 86 EMC Documentum Federated Search Services Version 6.5 Administration Guide

87 Indexing management To exclude files or directories from being indexed: Note: This procedure should only be used by people familiar with Nutch administration and regular expressions. 1. Open the crawl urlfilter.txt configuration file located at: <Indexer installation directory>\webapps\admin\admin\web INF\classes\ 2. Add a regular expression prefixed by a minus sign to define the files or directories you want to exclude. Troubleshooting Use any of the following tools to diagnose any communication problem: FS2 server log files, as described in Chapter 7, Logs Reporting. Log files for the webapps, as described below in Webapps log files, page 87 Adapter debug mode, as described in Federated Search Services Adapter Development Guide. Webapps log files Several log files are available for the two webapps, in <Indexer installation directory>\logs: indexeradmin.log contains the logs of the admin webapp. indexersearch.log contains the logs of the search webapp. indexerparsing.log contains the parsing logs. These log files are renamed everyday at midnight with the date of the previous day. You can customize the log files by modifying their log4j configuration files located at: <Indexer installation directory>\webapps\admin\admin\web INF\classes\log4j.xml for the admin webapp <Indexer installation directory>\webapps\search\search\web INF\classes\log4j.xml for the search webapp Note: Do not create a common log file for the two webapps or it will preclude the automatic daily renaming. Backup copies You may need to create backup copies of the collections you defined or of the indexes that were generated. Collections and their corresponding indexes are generated in the destination directory you chose during the installation of the Indexer. By default, this directory is C:\Documentum\fs2Indexes In the C:\Documentum\fs2Indexes\indexList directory, each collection that is, the collection definition and the corresponding index, if any is stored in a specific directory. For each collection, a EMC Documentum Federated Search Services Version 6.5 Administration Guide 87

88 Indexing management configuration file, info.xml, provides the name and description of the collection, as well as the list of URLs for the collection. To create a backup copy of the collection definitions and their indexes, make a copy of the fs2indexes directory. Make sure to keep the original directory structure when you restore the backup files. 88 EMC Documentum Federated Search Services Version 6.5 Administration Guide

89 Logs Reporting Chapter 7 This chapter helps you to understand and diagnose misconfigurations and runtime problems. The chapter consists of the following sections: Integration Server, page 89 Web Server, page 91 Admin Center Server, page 92 In Admin Center, click View to see the content of the various log files. Click Back to return to the list of log files. For the Web Server and Admin Center Server, select the log file to view from the drop down list then click View. By default, the syntax for the log filenames is the following:<type of log>_log.<date in ISO format>.txt, such as ao_access_log txt. Integration Server This section describes the three types of log files for the Integration Server: 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 system interaction. A sample of the log details is shown in the following example: ActionTimer: exiting... [Jan 17, :42:12 PM] Broker (3): BaseBroker shutting down [Jan 17, :42:12 PM] Broker (4): BaseBroker shutting down [Jan 17, :42:12 PM] Broker (5): BaseBroker shutting down [Jan 17, :42:12 PM] Broker (6): BaseBroker shutting down [Jan 17, :42:12 PM] Broker (7): BaseBroker shutting down [Jan 17, :42:12 PM] Broker (8): BaseBroker shutting down [Jan 17, :42:12 PM] EMC Documentum Federated Search Services Version 6.5 Administration Guide 89

90 Logs Reporting Tracing encountered errors The error.log file www/logs/error.log is used to trace errors, such as errors encountered during source wrapping. A sample of the log details is shown in the following example: xtrim.adapter.adapterexception: Adapter [computer/microsoft] raised error of type [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, 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:1 custom.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/Computer Insite, 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 Mu sic, library/bl Old, library/bl Books, library/bl Journals, library/bl Conf, library/loc, Documentum/TechLib, Documentum/NutsLib, bsb/bsbopac}] at level:1 custom.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 on client access to the Federated Search server. A sample of the log details is shown in the following example: RmiSurrogate (Client Id: 1 From: state: connected) [Jan 17, :41:30 PM] "CONNECT 1 HTTP/1.0" RmiSurrogate (Client Id: 1 From: state: connected) [Jan 17, :41:34 PM] "QUERY Query/ from account: 1, name:query 1, definition:{'full text' CONTAINS 'test tool'} => {Google, OpenDirectory} HTTP/1.0" Query/ general/opendirectory:processing [Jan 17, :41:37 PM] "FOUND general/opendirectory returned 20 results in 1968ms XTRIM/1.5" Query/ general/google:processing [Jan 17, :41:39 PM] "FOUND general/google returned 30 results in 3797ms XTRIM/1.5" Query/ general/opendirectory:processing [Jan 17, :41:41 PM] "FOUND general/opendirectory returned 20 results in 4016ms XTRIM/1.5" Query/ general/opendirectory:processing [Jan 17, :41:43 PM] "FOUND general/opendirectory returned 20 results in 2219ms XTRIM/1.5" Query/ general/opendirectory:processing [Jan 17, :41:46 PM] "FOUND general/opendirectory returned 20 results in 2672ms XTRIM/1.5" RmiSurrogate (Client Id: 1 From: state: connected) [Jan 17, :42:12 PM] "SHUTDOWN 1 HTTP/1.0" RmiSurrogate (Client Id: 1 From: state: disconnected) [Jan 17, :42:12 PM] "DISCONNECT 1 HTTP/1.0" EMC Documentum Federated Search Services Version 6.5 Administration Guide

91 Logs Reporting Note: Additional files that have adapter names can reside in this directory. They are generally HTML files, stored when parsing errors occur. They are very useful to adapter developers who can use the information contained in these files to modify the parser grammar specifications. You should send these files to the developer so that appropriate corrections can be made. Web Server The Web Server section of the page enables you to view the contents of log files in the www/tomcat/logs directory. This section 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 log This section describes the first two items in the previous list and provides 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 date of these requests. For example, A A40655A [17/Jan/2006:14:35: ] "GET /ecis.jsp HTTP/1.1" A A40655A [17/Jan/2006:14:36: ] "POST /ECIS.jsp?action=search&stringDomains=General&queryId= 0&expression=test tool&actionid= HTTP/1.1" E B8D7A412C3 [17/Jan/2006:14:38: ] "GET /ECIS.jsp HTTP/1.1" E B8D7A412C3 [17/Jan/2006:14:38: ] "POST /ECIS.jsp?action=search&stringDomains=General&queryId= 0&expression=Monde&actionId= HTTP/1.1" E B8D7A412C3 [17/Jan/2006:14:38: ] "POST /ECIS.jsp?action=search&stringDomains=General&queryId= &expression=News&actionId= HTTP/1.1" E B8D7A412C3 [17/Jan/2006:14:38: ] "GET /ECIS.jsp?action=selectCluster&current=15&actionId= HTTP/1.1" E B8D7A412C3 [17/Jan/2006:14:39: ] "GET /ECIS.jsp?action=selectClusterStrategy&actionId= HTTP/1.1" E B8D7A412C3 [17/Jan/2006:14:39: ] "POST /ECIS.jsp?action=applyClusterStrategy&selected_strategy= title&actionid= HTTP/1.1" EMC Documentum Federated Search Services Version 6.5 Administration Guide 91

92 Logs Reporting Tracing system interactions and exceptions This is used by developers to trace system interactions and exceptions. For example, :09:38 Root cause xtrim.client.i: No session Id valid and no session, you need to login again at 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 Server The Admin Center Server portion of the page enables you to view the contents of log files in the admin/logs/ directory. This portion allows you to trace system interactions and exceptions and to view the following: Web server jsp/servlets log Web server access log Web server internal log 92 EMC Documentum Federated Search Services Version 6.5 Administration Guide

93 Chapter 8 Accounts Management This chapter enables you to monitor and create accounts. Federated Search Services supports two kinds of accounts Shared and Individual Accounts. A shared account can be used for demonstration purposes or by a group of users, while an individual account is associated with a single person. Settings for individual accounts remain intact from session to session. Federated Search Services automatically saves and restores queries and results, as well as the display setup. When you create a new account, you must provide a default password. Registered users might later change the password. This chapter consists of four sections: Monitoring accounts, page 93 Creating accounts, page 95 Changing passwords, page 95 Deleting account, page 95 Accounts can also be managed using the aoaccountmanager utility script. However, if you want to use the aoaccountmanager script, note the following limitations: The aoaccountmanager script does not indicate when an account is locked; therefore, do not use the aoaccountmanager script when users are connected. The aoaccountmanager script does not hide passwords when editing, use Admin Center instead. Monitoring accounts Figure 4, page 94 shows the page that appears when you click the Account Management link in the Home page. It lists the following account details:, Name, LDAP, Queries, and Locked reasons. Theses details are described in Table 156, page 94. EMC Documentum Federated Search Services Version 6.5 Administration Guide 93

94 Accounts Management Figure 4. Account Management page Table 156. Account parameters Name LDAP Queries Locked reasons This column lists the s of the accounts created. These s are auto generated. If you created the account as shared, a minus( ) sign appears beside the. This column lists the names of the accounts created. This column lists the existing user accounts and the LDAP information. The system automatically identifies the existing user accounts listed from the LDAP directory and displays them. LDAP is a compliant directory service. Each user account registered with this directory service is automatically identified within the Federated Search Services. For organizations with a large number of user accounts, Federated Search Services can be connected to an LDAP compliant directory service as this enables you to collect the FS2 user accounts automatically from the internal directory service. This column lists the number of queries. 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. 94 EMC Documentum Federated Search Services Version 6.5 Administration Guide

95 Accounts Management Creating accounts To create an account 1. Click Create. The Create an account page opens. 2. Type the name and password in the respective fields. 3. If you want the account to be shared by many users at the same time, then select the Shared option. However, the queries run by shared accounts are neither saved nor restored between sessions. 4. Click Create. Changing passwords To change the password of the user of an account 1. In the Accounts Monitoring table, click the Change the Pwd link corresponding to the user account. The New Password screen appears. 2. Type the new password. 3. Click Submit. Deleting account To delete an account 1. In the Accounts Monitoring table, click the Delete link corresponding to the user account. A message box appears asking you to confirm that you really want to delete the selected account. 2. Click OK. EMC Documentum Federated Search Services Version 6.5 Administration Guide 95

96 Accounts Management 96 EMC Documentum Federated Search Services Version 6.5 Administration Guide

97 Chapter 9 Servers Operation This chapter gives you information to start and stop the Federated Search server. The Servers Operation page allows you to stop or restart the server. You can stop or restart the server by clicking the required link: Restart FS2 with a graphic user interface Restart FS2 without graphic user interface Stop FS2 Note: If Federated Search Services is running as a Windows services, do not use the stop, start, or restart features. EMC Documentum Federated Search Services Version 6.5 Administration Guide 97

98 Servers Operation 98 EMC Documentum Federated Search Services Version 6.5 Administration Guide

99 Uploading Chapter 10 This chapter describes the tasks you can perform from the Upload page. This page allows you to upload information sources, libraries, and images. Figure 5. Uploading page The upload procedure is the same whatever the uploaded item. To upload items: 1. Click Browse to select the appropriate file to upload. Table 157, page 100 lists the file types. 2. Select the target directory from the list. Table 157, page 100 lists the directories. 3. Select the Overwrite option to overwrite the file in the directory. 4. Click Upload. EMC Documentum Federated Search Services Version 6.5 Administration Guide 99

100 Uploading Table 157. Uploading files Source to upload File to upload Target directory Bundle information source JAR file www/wrappers/ New backend information source CONF or PROPERTIES file Integration server library JAR or ZIP file lib/jars www/wrappers/ Information source library JAR or ZIP file lib/wrapper Image of a bundle information source GIF file www/tomcat/webapps/ao/ data/sources Domain image GIF file www/tomcat/webapps/ao/ icons 100 EMC Documentum Federated Search Services Version 6.5 Administration Guide

101 Chapter 11 Configuring Admin Center The Admin Center is your primary means for administering Federated Search Services. However, you can also configure Admin Center through individual files: the web.xml, page 101 and the admin.xml, page 103 files. web.xml The web.xml file is located in <FS2 installation directory>/admin/webapps/webbasedadmin/web INF/. You can modify the following attributes in the web.xml file: Login and password, page 101 Upload feature, page 102 Size of the uploaded file, page 102 Maximum size of the visible part of log files, page 102 Command to launch servers, page 103 Login and password At Federated Search Services installation, default values are set for the login and the password. Configuration of the login and password parameters in the web.xml, page 101 shows a sample login and password configuration. Example Configuration 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> In this example, you can change the values admin (for the ADMIN_LOGIN) and ecis (for the ADMIN_PASSWORD). EMC Documentum Federated Search Services Version 6.5 Administration Guide 101

102 Configuring Admin Center Upload feature By default, you can upload files in the admin repository using Admin Center. Configuration of the upload feature in the web.xml, page 102 shows how to configure the upload feature. Example Configuration of the upload feature in the web.xml <context param> <param name>enable_upload</param name> <param value>true</param value> </context param> If you want to disable this feature for security reasons, change the value to false. Size of the uploaded file You can limit the size of the uploaded file by setting the MAX_FILE_SIZE_UPLOAD parameter. Set this parameter to 1 if you do not want any limitation. The unit is KB. Configuration of the uploaded file size feature in the web.xml, page 102 shows how to configure the size of the uploaded file. Example Configuration 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 files Log files may become big and it will be time consuming to view them. MAX_LOGPAGE_SIZE defines the maximum number for the visible part of the log. Configuration of MAX_LOGPAGE_SIZE in the web.xml, page 102 shows how to configure the maximum size of the log page. Example Configuration of MAX_LOGPAGE_SIZE in the web.xml <context param> <param name>max_logpage_size</param name> <param value>50000</param value> </context param> 102 EMC Documentum Federated Search Services Version 6.5 Administration Guide

103 Configuring Admin Center Command to launch servers This section applies only to Solaris and Linux systems. Uncomment LAUNCH_SERVERS_CMD if you want to define the complete path of the executable to launch servers on Solaris and Linux. By default, the OPENWINHOME system property and xterm are used. Configuration of the LAUNCH_SERVERS_CMD in the web.xml, page 103 shows how to configure the command to launch servers. Example Configuration 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 file is located in <FS2 installation directory>/admin/webapps/webbasedadmin/conf/. It lets you define: Reference to integration server and web server configuration files, such as server.conf and web.xml, that you want to configure through Admin Center. Reference to integration server and web server log files that you want to view through Admin Center. File types that can be uploaded. You can also specify the admin repository. Configuration files By default, a Module is defined for the integration server and another one for the web server. You must provide a localized description for each of them. Each Module contains severals s. An defines the name and location of a configuration file and its localized description. You can remove an if you do not want to edit its configuration file. It is not possible to add a new. Example Integration and web server configuration files setup in 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 EMC Documentum Federated Search Services Version 6.5 Administration Guide 103

104 Configuring Admin Center Log files The log file structure in admin.xml is similar to that of configuration files but applied to log files. You can remove/add an depending whether you want to view its log file. The following example shows the integration and web server log files configuration. Example Integration and web server log files configuration in 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 files The uploaded file structure in admin.xml is similar to that of configuration files but applied to file types that can be uploaded. You can remove or add an depending whether you want to enable the upload a file type. The Uploaded files section of web.xml configuration provides details on disabling this feature. Example Uploaded files configuration 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 104 EMC Documentum Federated Search Services Version 6.5 Administration Guide

105 Chapter 12 Customization This chapter describes the following: Customizing Admin Center, page 105 Customizing Discovery Manager, page 106 Customizing Admin Center You can customize the interface with the colors and text font in the data style sheets and the home, logo, and login pages. You can do one of the following: Customization without editing JSP pages, page 105 Customization using JSP pages, page 105 Customization without editing JSP pages You can customize the interface by changing styles for the logo and colors of pictures defined in the style sheet and in a JavaScript file. The style.css file is located in <FS2 installation directory>/admin/webapps/webbasedadmin/data/ and contains almost all styles. The tooltip.script file is located in <FS2 installation directory>/admin/webapps/webbasedadmin/data/ xml/xsl/, contains only the definition of tooltip background colors. Pictures such as logo, buttons, are located in <FS2 installation directory>/admin/webapps/ WebBasedAdmin/data/ When you change a color in style.css, do not forget to update the colors of pictures included the standard JSP client. Customization using JSP pages JSP source pages provide home, logo and login pages. They can be easily customized. They are located in <FS2 installation directory>/admin/webapps/webbasedadmin/. EMC Documentum Federated Search Services Version 6.5 Administration Guide 105

106 Customization When using JSP pages, you must comply to the following requirements: JSP pages must be compiled by Tomcat as soon as you modify them. You must stop and restart Tomcat for your changes to take effect. You need to have a Java Development Kit (JDK). To enable Tomcat to compile JSP pages 1. Add tools.jar (from a JDK) in the classpath of aoadmin scripts. Note: You can also copy the tools.jar library in the <FS2 installation directory>/admin/lib repository. 2. Edit web.xml in <FS2 installation directory>/admin/webapps/webbasedadmin/web INF/ to comment the definition of compiled jsp pages and the servlet URL mapping for these three JSP. 3. Restart aoadmin. Tomcat compiles the jsp pages. The Java and compiled versions are located in the directory <FS2 installation directory>/admin/work/ Customizing Discovery Manager You can customize the look and feel of Federated Search Services main client, Discovery Manager. For example, you might change the home page. This page appears for guest end users when no search has been performed. The home page is located in <FS2 installation directory>/www/tomcat/webapps/ao/. Its name is intro_en.html for the English version and intro_fr.html for the French version. The data stylesheet used is style2.css located in <FS2 installation directory>/www/tomcat/webapps/ao/data/. You can make any changes to this page, except you must retain the final line with the corresponding links: Copyright Documentum, a division of EMC. All Rights Reserved. For the aodirect interface, the home page is named aointro_en.html for the English version and aointro_fr.html for the French version. These files are located in the same directory as the intro_en.html. However, aointro must not contain any HTML header or footer as they are generated by the aodisplay JSP file. The search and results of look and feel can also be configured in web.xml to change the default behavior. This file is located in <FS2 installation directory>/www/tomcat/webapps/ao/web_inf/. For the search panel, you can change the number of domains to display with the property MAX_NUMBER_OF_SELECTED_DOMAINS. The property MAX_DOMAIN_NAME_LENGTH sets the maximum number of letters allowed for the domain name in the search panel. Example Search panel configuration with domains display <! Domains parameters > <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> 106 EMC Documentum Federated Search Services Version 6.5 Administration Guide

107 Customization 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 list ofattributes available to make a sort is contained in SORTABLE_ATTRIBUTES. The list must contain FS2 internal attribute names (that is, no localized value). Example Results and expand view panels configuration <! Results parameters > <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. By default, the BODY is built from the result attributes body and abstract. To change or add further attributes, the following property should be added in the adapter configuration file. The Federated Search Services Adapter Installation Guide provides more details. Table 158. client.overview Default value Mandatory Visible on client A comma separated list of attributes that constitutes the overview field in the HTML interface (for example, abstract, body) abstract, body No Yes For the login panel, custom text can be displayed above the login form to add details or explanation. The text is editable in the localization file (that is, jsp_en.properties for the English version and jsp_fr.properties for the French). These files are located in <FS2 installation directory>/www/tomcat/webapps/ao/data/i18n/. Change or specify the property AdditionalLoginMsg. Example Login panel configuration in the localization file (jsp_en.properties for the English version) # Enter text to display a message in the login panel (above the login form) AdditionalLoginMsg=Enter your NT login name EMC Documentum Federated Search Services Version 6.5 Administration Guide 107

108 Customization 108 EMC Documentum Federated Search Services Version 6.5 Administration Guide

109 Installing and Configuring CA SiteMinder 6.0 Appendix A This appendix provides information on installing and configuring the Computer Associates (CA) SiteMinder plug in for Federated Search Services. In addition, it provides information on how Federated Search Services integrates with CA SiteMinder. It includes the following topics: CA SiteMinder integration, page 109 CA SiteMinder plug in configuration, page 109 Troubleshooting CA SiteMinder, page 115 CA SiteMinder integration Federated Search Services supports the standard CA SiteMinder web agent. Therefore, it benefits from any existing customization of SiteMinder authentication screens. A SiteMinder web agent is installed on an HTTP server, which needs to be installed as a front end of the Federated Search Services client. The supported HTTP Server is Apache 2. After configuring Federated Search Services, when a user accesses the FS2interface, the following events occur: 1. The SiteMinder web agent authenticates the user. 2. The Federated Search Services client sends the authentication token to the Federated Search server. 3. The Federated Search server revalidates the token and starts a user session. 4. When a query is performed, the Federated Search server provides the token to the appropriate adapter. Note: Not all adapters support CA SiteMinder. CA SiteMinder plug in configuration This section does not provide detailed information on the policy server configuration. Therefore, you need to have fair understanding of the CA SiteMinder installation and configuration. Before performing the steps mentioned in this section, make sure that a SiteMinder policy server is already set up. EMC Documentum Federated Search Services Version 6.5 Administration Guide 109

110 Installing and Configuring CA SiteMinder 6.0 To install a SiteMinder web agent, you must set up policy server for this new agent. 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. This section describes the following: Installing the web front end, page 110 Installing and configuring Federated Search Services, page 110 Configuring the FS2SiteMinder plug in, page 113 Installing the web front end To install the web front end, complete the following steps: 1. Install Apache HTTPD on a Federated Search Services machine. You can install it on another machine if your deployment requires it. The latest stable version of Apache is available at The Apache documentation describes how to compile Apache on your machine and use the provided binary versions available from the website, 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 later. You may want to configure policy server objects to protect resource / and subdirectory on this Apache instance (directory, domain, realm, and rule). Note: You should authorize GET and POST methods because Federated Search Services uses both. 3. Test the connection between Apache and policy server by accessing port>/. Installing and configuring Federated Search Services This section provides information on connecting Apache to FS2Tomcat. If Federated Search Services is not installed, then you need to install it. You can install Federated Search Services on the same machine as the Apache HTTPS server or on another machine. The procedure to connect the Apache HTTP server to FS2Tomcat is similar to the load balancing setup described in the Federated Search Services Administration Guide. The Apache HTTP server should be able to communicate with the Tomcat JSP engine that hosts the FS2 JSP standard search client. This is done by plugging in a Tomcat module to Apache. This module is called mod_jk. In addition to Apache, it supports most HTTP servers such as iplanet and Microsoft IIS. You can obtain mod_jk from connectors/jk/binaries/. Verify the current version of Tomcat shipped with Federated Search Services to ensure that the mod_jk you install is compatible with the version of Tomcat you use. 110 EMC Documentum Federated Search Services Version 6.5 Administration Guide

111 Installing and Configuring CA SiteMinder 6.0 Binary executable versions of mod_jk are available for some platforms (currently Win32, Linux, and NetWare). The Tomcat documentation provides more information on configuring different web servers for Tomcat. The Apache standard httpd.conf file is configured for the local installation and includes a configuration file specific to Tomcat. The Apache documentation provides more information on configuring Apache. The httpd.conf file is configured so that mod_jk gets loaded by Apache and handles some of the incoming HTTP requests. In this context, mod_jk handles all the incoming requests. Therefore, the incoming request are dispatched to the FS2 Tomcat JSP front ends. The Tomcat Apache documentation provides more information on configuring Tomcat to run on Apache. To complete the Federated Search 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 ( ) # #Listen :80 Listen 3000 Below ʺ# LoadModule foo_module modules/mod_foo.soʺ, insert the following lines: #Load mod_jk LoadModule jk_module modules/mod_jk.so #Indicate to mod_jk its configuration file and error log file for #diagnosis JkWorkersFile conf/workers.properties JkLogFile logs/mod_jk.log JkLogLevel error Below the ʺDocumentRootʺ line, insert the following lines: #Specify which HTTP requests are handled by mod_jk and which worker #will process those JkMount /*.jsp server1 JkMount /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 ( ) # ServerName <your hostname>: Verify the mod_jk configuration in the workers.properties file. # The workers.properties file defines a set of workers, that handles incoming HTTP requests. It is located in the folder containing the httpd.conf file. # workers.properties # # In Unix, we use forward slashes: ps=/ # list the workers by name EMC Documentum Federated Search Services Version 6.5 Administration Guide 111

112 Installing and Configuring CA SiteMinder 6.0 worker.list=server1 # # First Tomcat server # worker.server1.port=8009 worker.server1.host=<your hostname> 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 ends located on server1 through the AJP13 protocol. The ports specified in this file correspond to the ports in the FS2Tomcat server.xml file. 3. To configure the Tomcat JSP front ends, perform the following changes to the www/tomcat/conf/server.xml configuration file in the Federated Search Services installation: Uncomment the directives to support the AJP13 protocol. <! Define a Coyote/JK2 AJP 1.3 Connector on port 8009 > <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 FS2Tomcat. 5. Start Apache HTTP server and Federated Search Services, and access Note: SiteMinder authentication is not linked to the FS2authentication. In other words, even after logging in to SiteMinder, you will be considered a guest user to Federated Search Services. 112 EMC Documentum Federated Search Services Version 6.5 Administration Guide

113 Installing and Configuring CA SiteMinder 6.0 Configuring the FS2SiteMinder plug in The following sections describes the two types of configuration: Configuring the Federated Search Services client, page 113 Configuring the Federated Search server, page 113 Configuring the Federated Search Services client To configure the Federated Search Services client, complete the following steps: 1. In <FS2 installation directory>/www/tomcat/webapps/ao/web INF/web.xml, set LOGIN_PAGE_LINK to false. 2. Uncomment filter definition SSOFilter. <! ================= > <! SSO configuration > <! ================= > <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> Configuring the Federated Search server To configure the Federated Search server, complete the following steps: 1. In Admin Center, change the server configuration property xtrim.security. providers to the following: xtrim.securityapi.siteminder.server. SiteminderAuthenticationProvider.jdbc 2. Configure SiteMinder plug in in <FS2 installation directory>/www/docs/conf/siteminder.conf. This file contains the configuration of the custom SiteMinder agent running in Federated Search server. POLICY_SERVER_IP=<policy server IP address> EMC Documentum Federated Search Services Version 6.5 Administration Guide 113

114 Installing and Configuring CA SiteMinder 6.0 AGENT_NAME=<agent object name> AGENT_IP=<Federated Search 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 SiteMinder policy server. This agent can be different from the web agent installed. AGENT_IP should contain the IP address of the Federated Search server. AGENT_SECRET should contain the shared secret defined in the agent object configuration. Note: This requires a specific configuration of the agent, where the policy server administrator manually specifies the secret. 3. Install the SiteMinder libraries. You should install the SiteMinder SDK (available from the CA support site) based on your platform. 4. From the SiteMinder SDK installation directory, copy the following file to <FS2 installation directory>/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.jar This completes the Federated Search server configuration. 5. Start the FS2and Apache servers. Note: If you encounter any problem, look for the error messages in the Federated Search Services console or in the Federated Search server log. 114 EMC Documentum Federated Search Services Version 6.5 Administration Guide

115 Installing and Configuring CA SiteMinder 6.0 Troubleshooting CA SiteMinder Table 159, page 115 lists the problems that you may encounter while working with CA SiteMinder. The table describes the cause of the problem and suggests ways to correct or avoid it. Table 159. Troubleshooting CA SiteMinder Problem Cause Action FATAL ERROR: Exception from System.loadLibrary(smjavaagentapi) java.lang.unsatisfiedlinkerror: C:\Program Files\netegrity\sdk\bin\smjavaagentapi.dll: The specified procedure could not be found FATAL ERROR: Exception from AgentAPI.initialize() java.lang.unsatisfiedlinkerror : initialize Apache displays a 405 HTTP error after waiting for 10 seconds after you click a FS2 button. javax.servlet.servletexception: Siteminder plug in is misconfigured, no cookie named SMSESSION found in the request. Incorrect Siteminder DLL is used. Web agent version is older than 6 QMR2. Web agent may be disabled. Ensure that you copy the correct DLL from CA. You may have to copy the Siteminder DLL from the web agent folder instead of the SDK folder. Update the web agent to version 6 QMR2 or later. Before the installation, stop all servers (Apache and FS2) that use the agent. Verify that the web agent is enabled. Check the EnableWebAgent variable in the WebAgent.conf file (normally located in <Apache installation directory>/conf). EMC Documentum Federated Search Services Version 6.5 Administration Guide 115

116 Installing and Configuring CA SiteMinder EMC Documentum Federated Search Services Version 6.5 Administration Guide

117 Appendix B Report Generator Federated Search Services uses the report generator to notify users through an message when new results are found by scheduled queries. The default report template is MailerReport. System administrators also use it to create specific report templates. This appendix describes the following: Using RTL to create a report template, page 117 Making a new template available, page 121 Testing a report template, page 122 Using the report generator, page 122 The section Alert settings, page 58 describes the configuration of the reports in Admin Center. Table 160. Definition of terms Term RTL EBNF HTML Template descriptor tree Explanation Report Template Language. Extension of Backus Naur Form. (A language, that describes grammar.) Hypertext Markup Language. A tree that describes the structure of the report template. The report generator can display reports in HTML table format or HTML list format. Using RTL to create a report template The FS2 Report Template Language (RTL) enables you to generate reports. This section describes the RTL that is used to create report templates. The goal of the RTL is to allow you to easily build customized reports. The reports will appear in the user s mailer, and the order of the results in the report will be the same as the order on the screen. By referring to List of the results titles, page 119, you can see that a single declaration for a result in the report template controls the display of all results in the generated report. EMC Documentum Federated Search Services Version 6.5 Administration Guide 117

118 Report Generator This section describes the following: Main characteristics of RTL, page 118 Template structure, page 118 Header and footer description, page 119 Results description, page 119 Grammar, page 120 Main characteristics of RTL The RTL syntax is similar to that of HTML. For people familiar with XML/XSLT, RTL serves a similar purpose by being specifically tailored to the generation of mail reports. The report file, which is generated, is called the target file. The file written in RTL is called the source file. HTML is used to display the report. If the generated HTML contains a link to a picture then an offline visualization of the report will not display this picture. In the source file, everything that is not specified in the RTL language is considered as plain HTML and is directly copied into the target file. Template structure A template report has four parts: Header description Results description Separator description Footer description Table 161, page 118 shows the tags that separate the different parts of a program written in RTL. The Source file column gives a summary of an RTL source file, while the Part of the file column lists the parts of the program in which they can be found. Table 161. Template structure Part of the file Header description Results description Separator description Footer description Source file [ ] <LOOP_RES> [ ] </LOOP_RES> <SEPARATOR> [ ] </SEPARATOR> The separator description is pure HTML. In other words, the interpreter will copy this part of the source file to the report file without changing anything. [ ] 118 EMC Documentum Federated Search Services Version 6.5 Administration Guide

119 Report Generator 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 the RTL file that 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 display the name, the number of results and the definition of the query: <QUERY NAME>, <QUERY NB_RESULTS>, <QUERY DEFINITION>, <QUERY DATE>, <LOCALE>. Results description The results description is the part of the RTL file that begins with <LOOP_RES> and ends with </LOOP_RES>. Between these two tags, the presentation of all results is defined. The description is repeated for all results. There are several methods of displaying unknown and known attributes. This section describes the following methods: Displaying an attribute by using its name, page 119 Displaying a message only if a predefined attribute has a value, page 119 Displaying an attribute without using its name, page 120 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 name > Example B 1. List of the results titles <LOOP_RES> <B> The TITLE is: <ATTR_VALUE NAME= title > </B> <BR> </LOOP_RES> This example will display the title of each result and each title will be preceded by: The TITLE is. Displaying a message only if a predefined attribute has a value Everything between the tags <IF_ATTR_DEF NAME= Attribute name > and </IF_ATTR_DEF> will be generated in the report if 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: without having a title written after it. <IF_ATTR_DEF NAME= title > EMC Documentum Federated Search Services Version 6.5 Administration Guide 119

120 Report Generator <CENTER> The Title is: <ATTR_VALUE NAME= title > </IF_ATTR_DEF> Displaying an attribute without using its name The RTL enables you to display attributes without using their names. You can choose 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 the current result. In this part of the template, it is possible to access the name and the value of the current attribute using <CURRENT_ATTR NAME> and <CURRENT_ATTR VALUE>. Furthermore, if the value of an attribute is a URL, the behavior of the generator will change. For example, if the attribute value is the generated text will not be when <CURRENT_ATTR VALUE> is encountered. Instead, it will be <A HREF= > </A>. In other words, when a URL is encountered, a link is automatically built. Two additional ways of using the tag LOOP_ATTR are provided. To exclude some attributes from the list, use the syntax: <LOOP_ATTR EXCLUDE = name1, name2, > </LOOP_ATTR> 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 is centered, bold and in a large point size. All the other attributes are shown as a list and the keyword attribute is never shown. <LOOP_RES> <CENTER><FONT size = 5> <B> TITLE: <ATTR_VALUE NAME= title > </B> </CENTER></FONT> <BR> <LOOP_ATTR EXCLUDE = title,keyword > <B> <CURRENT_ATTR NAME> </B> <CURRENT_ATTR VALUE> <BR> </LOOP_ATTR> </LOOP_RES> Grammar This section describes the full definition of the RTL using EBNF grammar. The syntax is not case sensitive. templatereport := header theresults [sepresults] 120 EMC Documentum Federated Search Services Version 6.5 Administration Guide

121 Report Generator footer header footer := General := General General := html <QUERY NAME> <QUERY NB_RESULTS> <QUERY DEFINITION> <QUERY DATE> <LOCALE = "localename"> <WEBHOST> <WEBPORT> sepresults theresults result := <SEPARATOR> [html] </SEPARATOR> := <LOOP_RES> result </LOOP_RES> := (definedpart ifdef)* [theattributes] (definedpart ifdef)* definedpart := (html attrvalue ) ifdef attrvalue := <IF_ATTR_DEF NAME= nameattr > definedpart </IF_ATTR_DEF> := <ATTRVALUE NAME= nameattr > theattributes := loopattr defaultattr+ </LOOP_ATTR> loopattr := <LOOP_ATTR> <LOOP_ATTR EXCLUDE = exclude > <LOOP_ATTR REMAINING > defaultattr exclude endlist nameattr localename html := ( html <CURRENT_ATTR_NAME> <CURRENT_ATTR_VALUE> ) := nameattr (endlist)* :=, nameattr := name of the attribute to display := name of the ISO locale, e.g., fr := some html Making a new template available Report templates, for example, MailerReport_en.rtl, are stored in the directory <FS2 installation directory>\www\docs\conf. The default report template is MailerReport and is configured in <FS2 installation directory>\www\docs\conf\server.conf: EMC Documentum Federated Search Services Version 6.5 Administration Guide 121

122 Report Generator 4# xtrim.scheduledqueryreport: The name of the default report template ## used for notification when scheduled queries are updated. ## The real filename will be obtained using the alert properties ## listed in the file client.conf: xtrim.reporttemplates xtrim.scheduledqueryreport=mailreport Additional reports that will be available to the end users are listed in the file: <FS2 installation directory>\www\docs\conf\client.conf. Each report is designed using a unique symbolic name. Each report is associated with an actual file that also defines its locale. ## xtrim.reporttemplates: specifies the list of available reports that ## can be used to generate 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,frenchreport xtrim.report.mailreport=mailerreport_en.rtl xtrim.report.frenchreport=mailerreport_fr.rtl xtrim.report.shortreport=mailerreportshort_en.rtl xtrim.report.longreport=mailerreportlong_en.rtl Provide a localized description of each report in the file: <FS2 installation directory>\www\tomcat\webapps\ao\data\i18n\jsp_en.properties. Report.MailReport=Default mail alert Report.ShortReport=Watch report with changes Report.LongReport=Detailed watch report Report.FrenchReport=Default mail alert in French Testing a report template You can use a script in <FS2 installation directory>/bin named aortltester (for Solaris) or aortltester.bat (for PC) to test the added report template in order to check the customization. Example B 2. List of options available for the report template tester named aortltester RTLTester requires f filename to be given usage: RTLTester d domain f filename [ o outputfile] [ s query string] [ a attribute] [ q pattern] [ dump] domain : the domain of your adapter filename : the rtl file to parse outputfile: 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 follows: Example B 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 Using the report generator This section describes how to use the report generator. 122 EMC Documentum Federated Search Services Version 6.5 Administration Guide

123 Report Generator The following example describes the TableForm template, which is used to generate the report. Example B 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 WTH='100%' CELLPADDING=0 CELLSPACING=0> <TR><TD><IMG SRC='/images/source.gif' WTH='100' HEIGHT='88'></TD> <TD ALIGN=left> <FONT SIZE=6 FACE='Arial, Helvetica'><B><FONT COLOR='red'>K</FONT> N O W L E D G E<BR><FONT COLOR='red'>B</FONT> R O K E R</B></FONT> </TD><TD ALIGN=right VALIGN=bottom> <FONT SIZE=4 FACE='Arial, Helvetica'><B><FONT COLOR='red'>X</FONT>erox<BR> <FONT COLOR='red'>R</FONT>esearch <FONT COLOR='red'>C</FONT>entre <FONT COLOR='red'>E</FONT>urope </B></FONT></TD> </TR></TABLE> <HR noshade> <BR> <CENTER> <TABLE WTH=75%> <TR><TD COLSPAN=2></TD> </TR> <TR><TD COLSPAN=2 BGCOLOR='red'><FONT SIZE=4><b>Query</b><query name> </FONT></TD></TR> <TR><TD><EM>Definition :</EM></TD><TD><query definition></td></tr> <TR><TD><EM>Performed :</EM></TD><TD><query date></td></tr> <TR><TD><EM>Nb results :</EM></TD><TD><query nb_results></td></tr> </TABLE> <table width=80% border = 3> <tr><td><b><center> TITLE </CENTER></B></td> <td VALIGN=TOP><b><CENTER>SOURCE</CENTER></B> </td> <td VALIGN=TOP><b><CENTER>REF</CENTER></B></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> <BR> <table width=100%> <tr><td COLSPAN=3><hr noshade></td></tr> <tr><td COLSPAN=3>Generated by: <var>ecis</var><br></td></tr> <tr><td COLSPAN=3> Copyright Documentum Inc. All rights reserved.</td></tr> </body></html> </table> EMC Documentum Federated Search Services Version 6.5 Administration Guide 123

124 Report Generator 124 EMC Documentum Federated Search Services Version 6.5 Administration Guide

125 Configuring External Databases Appendix C This appendix assumes that a database has been installed somewhere in the company network. You may want to define a specific user for this database, but this is out of the scope of this appendix. For each type of database, there is a static set of properties and a configurable set of properties. You should not modify the static properties since they are part of an internal configuration that specifies the type of database used. This appendix describes the following: Downloading the driver for SQL Server, page 125 Initialize accounts tables, page 125 Migrate account from one database to another, page 126 Downloading the driver for SQL Server Due to licensing restrictions, SQL Server JDBC drivers are not distributed with Federated Search Services. To use SQL Server, you must obtain the driver from Microsoft and the libraries available in your Federated Search Services installation. To download the driver for SQL Server: 1. Download the driver Microsoft SQL Server 2005 JDBC Driver 1.2 from Microsoft Download Center website: 3b d 81e1ec91c1ba&DisplayLang=en (Review the license before installing the driver). 2. Install the driver. (Depending on the platform chosen, an.exe file must be launched or a.tar.gz file must be uncompressed.) 3. Once the driver is installed, three libraries are available in the driver directory: lib/mssqlserver.jar, lib/msutil.jar, and lib/msbase.jar. Copy these libraries in the FS2 installation lib/jars directory. Initialize accounts tables Before starting Federated Search server, you will need to initialize the accounts tables in the external database and create default accounts. EMC Documentum Federated Search Services Version 6.5 Administration Guide 125

126 Configuring External Databases To initialize accounts tables 1. Use the command aoaccountmanager to initialize the accounts tables in the external database. %> aoaccountmanager initialize ECIS: progress report mode is on Warning: 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. Federated Search server is now using this updated data. 2. Create default accounts: %> bin/aoaccountmanager create guest shared 3. Type the password askonce for guest account: Account successfully created: Id: 1 name:guest Migrate account from one database to another The database shipped with Federated Search Services McKoi is not adapted to manage many accounts. For best performance, it is recommended that you use an external database when more than 100 accounts are stored. To migrate user accounts from a database to another 1. Define the new server.conf for the database to migrate to. The first section in this appendix explains how to define specific target databases. Keep the previous server.conf until the migration is completed. In the example in this section, the new server.conf is named server mysql.conf. 2. The target and source database must be running. If this is not the case and one of these databases is McKoi, restart it using aodatabase script. 3. Launch aoaccountmanager using the migrate option. The first parameter is the source database server.conf and the second parameter is the target database server.conf. %> aoaccountmanager migrate../www/docs/conf/server.conf../www/docs/conf/server mysql.conf Database 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 126 EMC Documentum Federated Search Services Version 6.5 Administration Guide

127 Configuring External Databases 4. Replace the old server.conf with the new configuration file (server mysql.conf in our example). 5. Restart Federated Search server for the new database to take effect. The target and source database can be any database among McKoi, My SQL, SQL Server, and Oracle. Using McKoi as both target and source database, it is possible to compact the database (however, you must launch two aodatabase scripts in two different environments). EMC Documentum Federated Search Services Version 6.5 Administration Guide 127

128 Configuring External Databases 128 EMC Documentum Federated Search Services Version 6.5 Administration Guide

129 Appendix D Troubleshooting This appendix deals with the following issues: Troubleshooting with Admin Center, page 129 Testing communication with a backend, page 130 Troubleshooting adapter backend configurations, page 132 Incorrect proxy configuration, page 134 Getting status information on server internals, page 134 Handling low memory conditions, page 135 Server with an external name different from the default machine name, page 137 Managing timeouts, page 137 Troubleshooting with Admin Center This section describes how to manually configure adapters if the Admin Center service does not start. To manually add a new backend 1. Create a backend configuration file (for example, www/wrappers/acme/externaldocushare.conf) that describes the technical aspect of your information sources (network location and parameters) and that associates it with the corresponding standard adapter. For example, to add your local DocuShare document server running on the host you might create the following backend file. The Federated Search Services Adapter Installation Guide provides more information on adding other types of standard information sources. bundle=core/docushare.jar host=docushare.acme.com # Geographical location: Rochester, NY, USA Lat, Lon: , # Note: thanks to UIUC ( bin/slamm/ip2ll/) # for the IP address to Latitude/Longitude service location=38, Edit the www/docs/conf/domains.conf file and check the adapter backend as follows: xtrim.domains=jsp xtrim.domain.jsp=acme,general,press,tech,international xtrim.domain.acme=acme/marketingdocushare, acme/financedocushare, acme/externaldocushare [ ] EMC Documentum Federated Search Services Version 6.5 Administration Guide 129

130 Troubleshooting 3. Create a backend description file to describe the information source and how to use it. For example, create a file named www/wrappers/acme/docushare_en.properties with the following contents: description=docushare repository for ACME headquarter based in Grenoble, France 4. Update the domain_en.properties file with a description for the newly created acme domain: Domain.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, you can use your favorite image editor to create a 50*25 pixels image. You can change this size but the ratio between height and width should be kept under two for best display. Then, save your image into the Tomcat application directory www/tomcat/webapps/ao/data/sources, with the name source <your_backendname>.gif if the property image of the backend was left unchanged. Otherwise, define this property to the name of your modified image. 6. Restart your Federated Search server. The next client to connect automatically sees the updated information source hierarchy. Testing communication with a backend You can test the network connection with a backend using the command aowrappertester: aowrappertester n <backend> [ a <attribute> q <pattern>] [ s <query string>] [ login <backendlogin> <>] [ p <home path>] [ silent] [ empty] [ loadingtrace] [ CLIRSourceLanguage <sourcelanguage>] where n <backend> is the fully qualified name of the backend, for example, general/altavista. a <attribute> is the attribute to search against, for example, title, body, ʺfull textʺ. q <pattern> is a boolean expression the search attribute should match, for example, ʺknowledge and sharingʺ. s <query string> is a complex search expression combining multiple attributes, for example, ʺ{title,contains, billy }{keyword,equals, novel }{date,after, }{price,<, 29 }ʺ. login <backendlogin> <backendpassword> name and password to use during login step (simulate search with access control). valid is used to validate the property for the client side. loadingtrace shows all the properties found in the configuration file of your backend. CLIRSourceLanguage <sourcelanguage> enables 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] where p <home path> is the root directory containing the configuration files, for example, C:\fs2\www\docs. 130 EMC Documentum Federated Search Services Version 6.5 Administration Guide

131 Troubleshooting local tests the first level of the results using a sample HTML file available locally. fetch collects a sample HTML file (to be used with option local). localarchive tests the results response using a set of sample HTML files organized by level. fetcharchive collects a set of sample HTML files (to be used with localarchive) and organized them by level. f <filename> is the name of the file used to load or store the search results, for example, test/knowledge.html (option local), test/sharing.zip (option localarchive). silent does not print performance information. empty specifies that no results are expected from this test search. loadingtrace prints loading information of bundles and backends. tokenarchive <token> z <zipname> collects a set of sample token files (to be used with embeddedarchive) and organized them by result number. embeddedarchive z <zipname> d <dirname> tests the adapter using a set of sample embedded tokens organized by result number, for example, <zipname>=test/tokens1.zip. z <zipname> is the name of the archive file used to load or store the embedded tokens, for example, test/tokens1.zip (options tokenarchive, embeddedarchive). d <dirname> is the name of the file used to store the embedded objects, for example, test/embeddedobject (option embeddedarchive). emptytoken specifies that no tokens are expected from this test embedded object response. iterate <number> executes several time the search sequence allow to see whether clean up is well performed. stopafter <number> stops the current executed adapter after <number> milliseconds allow to test if the adapter really stop. 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 appear: acme/docushare: search results = 1: [source = Doc XRCE] [title = Meeting Minutes February 16th, 1999] [summary = ] [abstract = ] [keywords = KB Xtrim] [owner_href = 42] [author = conan] [owner = conan] [date = ] [last_modified_date = ] [site = docushare.acme.com] [href = File 2245/WeeklyMeeting.htm] [type = text/html] [size = 6K] [collection_href = 527] [collection = Internal Meeting Minutes] 2: [source = Doc XRCE] [title = Meeting Minutes January 12th 1999] [summary =] [abstract = ] [keywords = KB Annual Plans] [owner_href = 42] [author = conan] [owner = conan] [date = ] [last_modified_date = ] [site = docushare.acme.com] [href = 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 EMC Documentum Federated Search Services Version 6.5 Administration Guide 131

132 Troubleshooting (PS version)] [summary = ] [abstract = ] [keywords = adapter service ranking summarization query language sumbsumption] [owner_href = 42] [author = conan] [owner = conan] [date = ] [last_modified_date = ] [site = docushare.acme.com] [href = File 1954/WS.ps] [type = application/postscript] [size = 996K] [collection_href = 524] [collection = Adapter Service] Note: The aowrappertester tool displays the number of discarded results (usually because they were returned by the source but were filtered not matching the query constraints), but not the content of those results. In some cases, it might be interesting to know why those results were discarded. In such cases, use the filter property in the adapter backend configuration file to temporarily disable the filtering on the source. Then, all results are displayed. By comparing the list of results when filtering is enabled or disabled, you can deduce which results where discarded. For web sources, it is possible to get a trace of the HTTP protocol using the second command aoverbosewrappertester. aoverbosewrappertester n acme/acmedocushare a author q conan ECIS: progress report mode is on ECIS: debug adapter mode is on [C:\ECIS\www\logs] ECIS: redirect logs to console Conn: Creating Socket: docushare.acme.com:80 Demux: Initializing Stream Demultiplexor ( ) Demux: Timeout Thread[SocketTimeout ,10,main] starting ( ) Conn: Sending Request: POST /ApplySearch HTTP/1.1 Host: docushare.acme.com Connection: Keep Alive, TE TE: gzip, deflate, compress, chunked User Agent: ECIS (Documentum Research Centre Europe; Java 1.1.6; October 1997) RPT HTTP Client/0.3 Accept Encoding: gzip, deflate, compress Content type: application/x www form urlencoded Content length: 400 Demux: Opening stream (Thread[main,5,main]) Conn: Request sent Resp: Reading Response headers (Thread[main,5,main]) Demux: Setting timeout to ms Resp: Parsing Response headers from Request "POST /ApplySearch": ( )(Thread[main,5,main]) Troubleshooting adapter backend configurations Some configuration mistakes in adapter backends might be subtle (such as a typing mistake in a filename). Therefore the FS2 adapter testing tool provides a diagnosis mode that will help you detect such mistakes. To troubleshoot with invalid adapter bundle configuration using the aowrappertester command, use the loadingtrace as follows: aowrappertester n acme/acmedocushare loadingtrace 132 EMC Documentum Federated Search Services Version 6.5 Administration Guide

133 Troubleshooting This displays the following traces that shows the files that were loaded in the order in which they were loaded. 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 > EMC Documentum Federated Search Services Version 6.5 Administration Guide 133

134 Troubleshooting 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 configuration If your server relies on an HTTP proxy to cross a corporate firewall, and the proxy is not available. The following error appears: 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] raised error of type [NETWORK] with message [failed to get data from [ bin/query], [/cgi bin/query] To resolve this issue, make sure you are using the correct hostname and port number. Getting status information on server internals The File/List thread menu of Federated Search server can help troubleshooting by displaying server internal status on the server text console, as the following example shows. This can provide the exact list of connected clients and he list of active and stopping adapters. Example D 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] 134 EMC Documentum Federated Search Services Version 6.5 Administration Guide

135 Troubleshooting [ ] 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: ),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 conditions In some cases, a low memory condition might occur when Federated Search server cannot obtain enough memory to handle its processing. The following message appears on the server console and in logs when this condition occurs: Low memory error condition detected. Please check the logs to verify normal behavior of the system. If this error reproduces, please get the list of active adapters and report it to your adapter provider and Documentum support. Check the troubleshooting section in the ECIS Administrator s guide for more details. The following table summarizes the causes, diagnosis, and actions to take when encountering low memory conditions. EMC Documentum Federated Search Services Version 6.5 Administration Guide 135

136 Troubleshooting Table 162. Low memory error troubleshooting diagnostic Cause How to diagnose How to fix the problem The number of concurrent threads (called brokers and HTTP workers) was set to a very large number. The number of adapters is higher than default configuration (for example, 100 different adapters). An adapter needs an unusual amount of memory to work properly. An adapter has a flaw, causing it to consume a lot of memory. Check the server configuration file (server.conf) properties xtrim.http.workers and xtrim.brokers for values much higher than default values (x3 or x4). Check the number of backends in the domains.conf configuration file. Check the error log files for errors with that adapter. Increase memory for the server and check that the problem disappears. If this does not solve the problem, contact the adapter provider for complete diagnosis. The adapter cannot be stopped: it always appears in the list of active threads and takes a long time to return or never stops properly. Increase the maximum memory allocated to the server process or reduce the values of those properties. Increase the maximum memory allocated to the server process or reduce the number of adapters. Increase the maximum memory allocated to the server process. Contact the adapter provider. To allocate more memory to Federated Search server, you must manually edit aoserver.bat (aoserver on Solaris and Linux). The mx option controls the maximum amount of memory that Federated Search server can request to the system as the following example shows. The default value (mx256m) specifies that Federated Search Services can consume up to 256 MB of RAM on the host system. Change this option to a higher value to increase memory allocated to Federated Search Services. Example D 2. Extract from aoserver.bat startup file :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 allocated to Federated Search Services must be smaller than the amount of physical memory of the host machine. While not dangerous for the system stability, swapping can cause performances to drop and Federated Search server response time to be unusually high. 136 EMC Documentum Federated Search Services Version 6.5 Administration Guide

137 Troubleshooting Configuration of Tomcat server To obtain more information about Tomcat server, modify the file <FS2 installation directory>/www/tomcat/conf/server.xml. Set debug to 9 instead of 0 as the following example shows. Then, restart aotomcat. More information is available on the Tomcat console and log files (located in /www/tomcat/logs). The following are the default parameters in server.xml: <Context path="" docbase="ao" debug="0" reloadable="true"> </Context> The following are the server.xml parameter values to use for debugging: <Context path="" docbase="ao" debug="9" reloadable="true"> </Context> Server with an external name different from the default machine name If the server on which Federated Search Services is installed has an external name (e.g., demo.askonce.com) different from its internal name (e.g., python), some of the links in the HTML pages might not work. To overcome this problem, you must modify the following two configuration files: server.conf Edit the parameter xtrim.server.rmi.registryhost (for example, xtrim.server.rmi.registryhost=demo.askonce.com). web.xml Edit the parameter RMI_REGISTRY_HOST (for example, <param name>rmi_ REGISTRY_HOST</param name><param value>python</param value>). Managing timeouts To efficiently manage sessions and communications between the Federated Search Services client, Federated Search server and sources, there are several timeouts that you can configure. Figure 6, page 138 shows an asterisk beside each step for which a timeout has been implemented. EMC Documentum Federated Search Services Version 6.5 Administration Guide 137

138 Troubleshooting Figure 6. Timeouts in Federated Search Services The following are the main timeout parameters implemented in Federated Search Services: Session timeout The first timeout is on the user session. If the user is a guest user (shared accounts), the default timeout is 10 minutes. For persistent users, the timeout is 6 times the timeout for guest users, therefore by default, it is 6*10=60 minutes. To modify this parameter, in Admin Center, edit the www/tomcat/webapps/ao/web INF/web.xml file, locate the property Session timeout and update its value. Connexion timeout for HTTP client This timeout is not configurable;, it applies when the source does not reply or send any error message. For example, it can occur when a firewall is active and the required ports have not been opened. By default, the timeout is set to 5 minutes. Query timeout and repeated attempts When the source replies, even if it is an error message, two parameters apply to the query sent by the Federated Search server. First, a 180 second timeout applies: you can modify this default timeout in the configuration file (.conf) of each adapter if the adapter has been developed to take it into account. The expirationtime parameter is the expiration time of the adapter until it should abort its execution. The second parameter is the number of successive trials when the source returns a network error. By default, the server will try five times to send the query. It will wait 4 seconds before the second attempt, and then the delay will be doubled between each attempt, 8 seconds before the third attempt, 16 seconds before the fourth attempt and finally 32 seconds before the fifth attempt. To modify this parameter, in Admin Center, edit the www/docs/conf/server.conf file, locate the property xtrim.maxactionfailure in the Adapters settings section and update its value. Results timeout The last timeout implemented lets you define the period of time to wait for the results to be retrieved. The default value is 0, which means that no timeout applies, assuming there is already a timeout defined specifically for each adapter in the adapter s configuration. This timeout is expressed in milliseconds and can be configured in Admin Center. Edit the www/tomcat/webapps/ao/web INF/web.xml file, locate the property RESULTS_TIMEOUT and update its value. It is not a global timeout for the whole query but applies to any response from the Federated Search server, while fetching results. 138 EMC Documentum Federated Search Services Version 6.5 Administration Guide