56
EMC ® Documentum ® Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide P/N 300-008-368–A04 EMC Corporation Corporate Headquarters: Hopkinton, MA 01748-9103 1-508-435-1000 www.EMC.com

EMC Documentum ContentServerOEMEdition Documentum® ContentServerOEMEdition Version6.5SP2 InstallationandConfigurationGuide P/N300-008-368–A04 EMCCorporation CorporateHeadquarters:

Embed Size (px)

Citation preview

EMC® Documentum®

Content Server OEM EditionVersion 6.5 SP2

Installation and Configuration Guide

P/N 300-008-368–A04

EMC CorporationCorporate Headquarters:

Hopkinton, MA 01748-91031-508-435-1000www.EMC.com

Copyright© 1994 - 2009 EMC Corporation. All rights reserved.

Published September 2009

EMC believes the information in this publication is accurate as of its publication date. The information is subject to changewithout notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONSOR WARRANTIES OF ANY KINDWITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLYDISCLAIMS 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.

Table of Contents

Preface ................................................................................................................................. 7

Chapter 1 Preparing for the Installation ........................................................................ 9Installation and configuration worksheet ........................................................... 10Prepare the host machines................................................................................. 11Deployment options ..................................................................................... 12Ports ............................................................................................................ 12Documentum directories............................................................................... 12

Prepare the database and repository .................................................................. 13Repository and global registry....................................................................... 13Connecting to an existing database ................................................................ 14Connecting to a Microsoft SQL Server database ............................................. 14Connecting to an Oracle database .................................................................. 15Entries in tnsnames.ora file........................................................................ 15

Chapter 2 Installing Content Server OEM Edition ........................................................ 17Installing Content Server OEM Edition with the GUI .......................................... 17Reinstalling Content Server OEM Edition from the GUI ...................................... 26Installing Content Server OEM Edition from the command line ........................... 26Updating the configuration file...................................................................... 26Running the command line installation .......................................................... 27

Reinstalling Content Server OEM Edition from the command line ....................... 28Reviewing the installation logs .......................................................................... 29Starting or stopping Content Server OEM Edition............................................... 30Developing custom Documentum applications................................................... 31Uninstalling Content Server OEM Edition .......................................................... 32

Chapter 3 Creating a Custom Installation Package ...................................................... 35Replacing the Welcome page ............................................................................. 35Creating an installation package for the command-line installation ...................... 35Creating the Content Server OEM Edition configuration file ................................ 36Configuration file format and parameters....................................................... 37

Removing Components from Content Server OEM Edition ................................. 39Removing sample data ..................................................................................... 40

Chapter 4 Understanding the Content Server OEM Edition Repository ...................... 41Configuring the repository ................................................................................ 41Operating configuration................................................................................ 41Global registry ............................................................................................. 42Administration jobs ...................................................................................... 42

Runtime log files .............................................................................................. 42

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 3

Table of Contents

Creating users and groups ................................................................................ 42Adding users to the repository ...................................................................... 43Using an LDAP directory server .................................................................... 43Required and recommended attributes for users......................................... 43

Required and optional attributes for groups ................................................... 44Configuring jobs............................................................................................... 45Setting job schedules..................................................................................... 45Activating and deactivating jobs .................................................................... 46

Chapter 5 Understanding Full-Text Indexing ............................................................... 47Understanding indexing and the indexing software ............................................ 47Words that are not indexed ............................................................................... 48Punctuation ..................................................................................................... 48Indexing numeric values ................................................................................... 48Indexing NULL values...................................................................................... 48Supported formats............................................................................................ 49Supported languages ........................................................................................ 49Supported querying.......................................................................................... 49Comparing Lucene and FAST full-text indexing systems ..................................... 49Internationalization .......................................................................................... 50Object type schema changes and full-text indexing ............................................. 50Optimizing the index ........................................................................................ 51Tuning the result set batch size .......................................................................... 52Objects and attributes supporting full-text indexing............................................ 52Indexing failures .............................................................................................. 53Log files and logging ........................................................................................ 53

4 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Table of Contents

List of Tables

Table 1. Installation and configuration worksheet ............................................................... 10Table 2. Content Server OEM Edition configuration file parameters ..................................... 38Table 3. Web applications installed as part of Content Server OEM Edition ........................... 39Table 4. Required and recommended user attributes ........................................................... 44Table 5. Required and optional group attributes.................................................................. 45Table 6. Full-text indexing server comparison — Lucene and FAST ...................................... 49

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 5

Table of Contents

6 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Preface

EMC Documentum Content Server OEM Edition provides an infrastructure for developingapplications that incorporate content management functionality. These applications are thendeployed as part of a custom installation program. Content Server OEM Edition is an integratedplatform that includes Content Server, development tools, administrative tools and applications. Italso includes a relational database management system, and a full-text index system. It includes thecore technology, content-related services, and the developer resources for building content-richapplications. Installing Content Server OEM Edition automatically deploys all components andconfigures a content repository. You can choose to install Content Server OEM Edition by using thegraphical user interface (GUI) installation program or by using the command line (also known as"silent” installation).

Note: Compared to Content Server Enterprise Edition, Content Server OEM Edition has limitationsin terms of scalability and performance. If you find that Content Server OEM Edition does notmeet your scalability and performance requirements, you might want to consider implementingContent Server Enterprise Edition.

This manual describes how to install and configure Content Server OEM Edition, and how toincorporate it into an application.

Intended audienceThis manual is intended for individuals developing applications that embed Content Server OEMEdition to provide an internal content repository.

Revision historyThe following revisions have been made to this document:

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 7

Preface

Revision History

Date Description

June 2009 Initial publication

September 2009 Revised publication

8 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Chapter 1Preparing for the Installation

This chapter describes how to prepare for the installation of Content Server OEM Edition into yourdevelopment environment. It consists of these major sections:

• Installation and configuration worksheet, page 10

• Prepare the host machines, page 11

• Prepare the database and repository, page 13

As you work your way through the installation steps, use the Installation and configurationworksheet, page 10, to record the information you need to collect in order to install Content ServerOEM Edition.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 9

Preparing for the Installation

Installation and configuration worksheetUse the following worksheet to record information you will be prompted for during the installationprocedure. All parameters are required unless otherwise noted.

Table 1. Installation and configuration worksheet

Parameter Resource

On Microsoft Windows only: MicrosoftWindows username and password

______________________

On Linux only: root password

______________________

Your login information for the host.

Documentum program directory:

______________________

Documentum user directory:

______________________

Prepare the host machines, page 11.

Application server port (optionalparameter)

______________________

Prepare the host machines, page 11.The default port is 9080. The GUI installation programonly asks for this information if you ask to see customoptions. You may also omit this parameter during thecommand-line installation, and instead the use thedefault value.

For Oracle databases only: the databaseconnection identifier______________________

Entries in tnsnames.ora file, page 15, and Oracledatabase documentation.

Microsoft Server only: ODBC datasource name:

______________________

Required only when connecting to an existing MicrosoftSQL Server database.Prepare the database and repository, page 13.

Database administrator name:

______________________

Database administrator password:

______________________

Required only when connecting to an existing MicrosoftSQL Server database or an existing Oracle database.Prepare the database and repository, page 13.The database administrator name is automatically setto "sa” when you choose to use the bundled MicrosoftSQL Server

Database server instance name (in ALLCAPS):

______________________

Required only for installation from the command line.Required only when Content Server OEM Editioncreates a new database.Prepare the database and repository, page 13.

10 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Preparing for the Installation

Parameter Resource

Global registry password:

______________________

Repository owner password:

______________________

Required only when connecting to an existing MicrosoftSQL Server database or an existing Oracle database.Prepare the database and repository, page 13.The repository owner password is optional with theGUI installation program. You will only be asked toenter it if you choose to specify custom options. It isrequired for an installation from the command line.

Full path for the oemConfig.xml file(full_path_of_config_file)

Required only for installation from the command line.

SMTP server name Applies only to installations from the command lineand is an optional parameter.

Administrator email Applies only to installations from the command lineand is an optional parameter.

Prepare the host machinesBefore you begin installing Content Server OEM Edition, ensure that the host machine meets thehardware and software requirements detailed in the EMC Documentum Content Server OEM EditionRelease Notes. The host on which you install Content Server OEM Edition must not have any existingEMC Documentum products installed on it. The host name must use only ASCII characters.

To install Content Server OEM Edition, including Content Server, the database, the connectionbroker, and the indexing system, you must have a minimum 15 GB of free disk space and 3 GBfree temporary space.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 11

Preparing for the Installation

Deployment options

You can deploy Content Server OEM Edition in one of two ways:• Single host: all components including application and database are on a single host. Thisconfiguration is typically used with embeddedMicrosoft SQL Express for development or proof ofconcept purposes. You can also use this configuration with Sybase in a production environment.

• Multiple hosts: A multiple host configuration is typically used in a production environmentin either one of the following configurations:

— All Documentum components and applications are installed on one host. The database ison a different host.

— All Documentum components are installed on one host. Applications and the database areinstalled on the same or different hosts.

Ports

The application server and connection broker installed with Content Server OEM Edition useports on the host machine. Before installing the software, you must identify open ports for thesecomponents to use.

The default port for the embedded application server is 9080. The application server requires a blockof 20 consecutive open ports starting at this number.

The default connection broker port is 1489. The connection broker also uses the next port number, soensure that the next port number (1490) is also open.

Documentum directories

The Content Server OEM Edition installation program installs files into two directories, referred toas the program directory and the user directory.• The program directory is the directory where Documentum products are installed. The typicallocation is C:\Program Files\Documentum (Windows) or userHomeDirectory/dctm (Linux).

• The user directory is the directory where Documentum data is stored. The typical location isC:\Documentum (Windows) or userHomeDirectory/dctm/shared. The user directory must nothave any spaces in the path.

You must identify these two directories when you run the Content Server OEM Edition installationprogram. The installation program will create the directories if they do not already exist.

Record the paths to the program directory and user directory on the Installation and configurationworksheet, page 10.

12 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Preparing for the Installation

Prepare the database and repositoryContent Server OEM Edition uses a relational database to store metadata about the content inthe repository. Content Server OEM Edition supports Microsoft SQL Server, Sybase, and Oracledatabases. For the supported database versions see the EMC Documentum Content Server OEMEdition Release Notes.

Note: The Microsoft SQL Server 2005 Express database is provided as a courtesy only. ContactMicrosoft for assistance. EMC is not responsible for supporting it.

If you are using a Microsoft SQL Server database, by default, Content Server OEM Edition createsthe database as part of the installation process. Alternatively, you have the option to connect to anexisting database. If you choose to use an existing Microsoft SQL Server database, you use MicrosoftSQL Server tools to create the database; the Content Server OEM Edition installation program createsthe necessary tables for the repository.

Content Server OEM Edition also supports a bundled Sybase database, where the database is createdas part of the installation process.

If you are using an Oracle database, you will connect to an external Oracle database.

Record a name for the database server instance on the Installation and configuration worksheet,page 10. For the command-line installation when using the bundled database, the database serverinstance name must use all capital letters. For the bundled Microsoft SQL Server or Sybase database,the installation program will create a database server instance whose name is a combination of theserver host name and the specified instance name, and, for Microsoft Windows only, create an ODBCdata source with the instance name.

Caution: The Microsoft bug described in KB article 968749 (http://support.microsoft.com/kb/968749) can cause an installation error ("DiPADbInstall failed!”) if you are using Microsoft SQLServer Express. This error occurs with XML Core Services 6.0 SP2, which is installed whenyou upgrade to Windows XP SP3.

Follow the instructions in the Microsoft KB article cited above to correct your XML Core Servicesbefore attempting to install the product again.

The repository has a name, which is the name users see when connecting to the repository and whichis also used in the name of the underlying database. The repository name needs to be unique on thenetwork. The name can have up to 32 characters, and must consist of ASCII letters, numbers, orunderscores (_), with no spaces. The repository name "docu” is reserved by EMC Documentum.

Record the repository name on the Installation and configuration worksheet, page 10.

Repository and global registry

The repository is created as a global registry. The global registry is a repository like any otherrepository except that it is capable of managing installation-wide elements that would be accessed ifother repositories where a part of the installation. Content Server OEM Edition supports the creationof one repository per Content Server OEM Edition installation. Therefore, the repository functions asboth a content repository and a global registry. For more information about global registries, refer tothe EMC Documentum Content Server Installation Guide.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 13

Preparing for the Installation

Record a global registry password and a global registry owner password on the Installation andconfiguration worksheet, page 10.

Connecting to an existing database

You can choose to connect to an existing Microsoft SQL Server or Oracle database. For informationabout supported databases, refer to the EMC Documentum Content Server OEM Edition Release Notes.

Connecting to a Microsoft SQL Server database

Refer to the Microsoft SQL Server documentation for information about installing Microsoft SQLServer. You can choose to install the Microsoft SQL Server Express database delivered with ContentServer OEM Edition, or connect to an existing Microsoft SQL Server database. If you choose to use toan existing database, you can connect to a local database on the same host machine as Content ServerOEM Edition or a remote database on a separate host. In a production environment, the databaseis almost always on a separate host for performance reasons. If you use an existing Microsoft SQLServer installation, ensure that it has the correct values for the required configuration options. Therequired configuration options are as follows:

• Select the security mode value of Mixed Mode (Microsoft SQL Server authentication andWindows authentication).

• Select a collation that uses Dictionary sort order and is case-sensitive. Install the database incase-sensitive mode.

If the database and Content Server OEM Edition are on the same host machine, ensure that thedatabase service is set to start automatically.

If the database is on a different host machine from the Content Server OEM Edition, you also needto install Microsoft SQL Server client software on the Content Server OEM Edition machine. Youneed to install both the Microsoft SQL Server client and Microsoft SQL tools; see the MicrosoftSQL Server documentation for details.

On the Content Server OEM Edition machine, create a System DSN that uses the MicrosoftSQL Server driver. When prompted for a name of the data source, use the name of the ContentServer OEM Edition host machine. When prompted for the Microsoft SQL Server name, enterhostname/instancename if you have two Microsoft SQL Server instances on the same host.

When creating the ODBC data source, you can choose either Windows authentication or MicrosoftSQL Server authentication as an authentication method.• If you choose Windows authentication for creating the ODBC data source, the repository ownermust have a Windows account and the installation owner must have System Administratorprivileges in Microsoft SQL Server.

• If you choose Microsoft SQL Server authentication, the repository owner does not have to have aMicrosoft Windows account.

14 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Preparing for the Installation

The appropriate network library for the driver depends on whether the database is on the samehost machine as Content Server OEM Edition:• If Microsoft SQL Server is on a different host from Content Server OEM Edition, select TCP.

• If Microsoft SQL Server is on the same host as Content Server OEM Edition, select Named Pipes.

If you are connecting to an existing Microsoft SQL Server database, record the name and passwordfor the database administrator and the name of the ODBC data source on the Installation andconfiguration worksheet, page 10.

Connecting to an Oracle database

Refer to the Oracle documentation for information about installing the RDBMS. If you choose to useto an existing database, you can connect to a local database on the same host machine as ContentServer OEM Edition or a remote database on a separate host. In a production environment, thedatabase is almost always on a separate host for performance reasons. Use the Custom installationoption so that you can set the configuration options that Content Server OEM Edition requires. Therequired configuration options are as follows:

• Retention Services require UTF-8 code page.

• Set up the networking parameters required by Oracle as follows:

— In the init.ora or spfile, use the following settings:optimizer_index_cost_adj=5

optimizer_index_caching=95

• Ensure that the Oracle Listener is running on the Oracle host.

Entries in tnsnames.ora file

Oracle database aliases (TNS aliases) are defined by entries in the tnsnames.ora file. You cannotconnect to an Oracle database without an alias. Configure the tnsnames.ora file on the Content ServerOEM Edition host. Use the Oracle SQL*Net configuration tool to create a database alias referring tothe database instance you plan to use for Content Server OEM Edition. After you create the alias, testthe alias by connecting to the Oracle database.

Entries in the tnsnames.ora file for the Oracle HTTP service and data expo service do not containparameters for HOST, SID, and SERVICE. If the first entry in the tnsnames.ora file is for one of theseservices, the Content Server OEM Edition installation program is unable to parse the tnsnames.ora

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 15

Preparing for the Installation

file and cannot connect to the database. Make sure that the first entry in the tnsnames.ora file is notfor the Oracle HTTP service or data expo service.

16 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Chapter 2Installing Content Server OEM Edition

You can install Content Server OEM Edition by using one of two methods:• Running a graphical user interface (GUI) installation program

• Updating a configuration file and running the installation program from the command line

Installing Content Server OEM Edition with theGUIYou install Content Server OEM Edition by running the documentumSetup.exe installation programon Microsoft Windows or the documentumSetup.bin installation program on Linux. The installationprogram creates the repository and installs all Documentum components.

You can install Content Server OEM Edition in one of the following configurations:• On a Microsoft Windows operating system and connecting to a Microsoft SQL Server database

• On a Microsoft Windows operating system and connecting to an Oracle database

• On a Microsoft Windows operating system and connecting to a Sybase database

• On a Linux operating system and connecting to an Oracle database

• On a Linux operating system and connecting to a Sybase database

Note: For optimal performance during installation, turn off any virus checking on the host machine.

To install Content Server OEM Edition on a Microsoft Windows operating system andto connect to a Microsoft SQL Server database:

Note: Java 1.5, update 12 does not support Windows Server 2008. Therefore, if you want to runContent Server OEM Edition on the Windows Server 2008 operating system, you need to upgradeto Java 1.5, update 19 after the installation. See the EMC Documentum Content Server OEM EditionRelease Notes for information on how to upgrade.

Note: Before you can install Content Server OEM Edition on a Windows Server 2008 platform, youmust disable user account control (UAC). See the EMC Documentum Content Server OEM EditionRelease Notes for information on how to disable UAC.

1. Log in to the host system using your Microsoft Windows login.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 17

Installing Content Server OEM Edition

Note: Microsoft Windows user accounts are not case-sensitive, but Content Server OEM Editioninstallation fails if you connect to the host by using the incorrect case in the username. Forexample, if the account is set up as JPSmith and you connect as jpsmith, you can log in to thehost, but installation fails.

2. Download the Content Server OEM Edition software.You can find the location of the software and instructions for downloading it in the email youreceived regarding the EMC download site.

3. Unzip the distribution file.Uncompress the distribution file in any directory whose name does not contain spaces in thepath. The installation files are uncompressed to that directory.

4. Run the installation program from the directory into which you expanded the files bydouble-clicking documentumSetup.exe.The installation program starts and a dialog box appears that lists all system requirements.

5. Ensure that your system meets all requirements listed and click Next. The software licenseagreement appears.

6. Read the license agreement.To continue with the installation, click I accept the terms of the license agreement and clickNext.If you do not accept the license agreement terms, the Next button becomes unavailable, and youcannot continue with the installation.

7. You can accept the default directory for Content Server OEM Edition and data (C:\Documentum)or click Browse to select a different installation directory. The name of the directory in whichContent Server OEM Edition is installed must contain only ASCII characters and must not includespaces. Do not use any of these characters in pathnames: ! \ / : * ? " < > | .You can accept the default directory for shared Documentum programs (C:\ProgramFiles\Documentum) or click Browse to select a different directory.Click Next.

8. Type the installation owner username and password, which is typically the login for the hoston which you are performing the installation, and click Next.

9. Choose from the following options:• Install the Microsoft SQL Server Express database delivered with the Content Server OEMEdition software package or connect to an existing database.

• Custom options, which enable you to set ports and additional passwords.

To install the Microsoft SQL Server Express database delivered with the Content Server OEMEdition software package, click Yes, install a Microsoft SQL Server Express database for me. Youmust choose this option if you do not already have an Microsoft SQL Server database installed.To connect to an existing Microsoft SQL Server database, click No, I want to use my existingMicrosoft SQL Server database. You must choose this option if you already have an MicrosoftSQL Server database installed. In the dialog that appears next, enter the data source name, andthe database administrator name and password. Click Next.To see custom options, click Yes under custom options. The Custom Options dialog appearswhere you enter the required information:• Type the application server port. The selected port must not be used by another application.The default port number is 9080. A total of 20 ports starting at the port number you select are

18 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Installing Content Server OEM Edition

reserved for this application server instance, and all of them must be available. The installerwill create an application server instance to host Webtop, the ACS methods server, and otherapplications. Enter the port number that you want the application server to bind to. This portnumber will appear in the URLs for the applications.

• Type the repository name. If you choose to use the bundled SQL Server, this field does notappear and "documentum” will be used as the repository name.

• Type the database administrator password. This field only appears if you have chosen touse the bundled SQL Server database. Enter the value that you want to set as the databaseadministrator password. The default value is "documentum-1.”

• Type the global registry password. This is the password to set for the dm_bof_registry user.Typically you would want to set the global registry password to a different value than theother passwords because you will need to share this password with most DFC clients. Thedefault value is "documentum-1.”

• Type the repository owner password. The repository owner is the database user that owns allrepository metadata. The repository uses this database user to connect to the database. Theinstallation program will create this user automatically. Enter the value that you want to set asthe repository owner password. The default value is "documentum-1.”

Click Next after having chosen your options and entered the required values. A dialog appearsthat shows a list of packages included in this installation.

10. Click Next. After clicking Next, the installation begins. If you have chosen to install the bundledSQL Server, the installation will take about 20 minutes. If you have chosen to connect to anexisting database, the installation might take up to two hours. A dialog appears that indicates thesuccessful installation of Content Server OEM Edition.

11. Click Finish.This will launch the Content Server OEM Edition welcome page that provides information onhow to launch its component applications. You can access the welcome page any time after theinstallation by navigating to Start>Programs>Documentum>Welcome.

To install Content Server OEM Edition on a Microsoft Windows operating systemand to connect to a Sybase database:

1. Log in to the host system using your Microsoft Windows login.

Note: Microsoft Windows user accounts are not case-sensitive, but Content Server OEM Editioninstallation fails if you connect to the host by using the incorrect case in the username. Forexample, if the account is set up as JPSmith and you connect as jpsmith, you can log in to thehost, but installation fails.

2. Download the Content Server OEM Edition software.You can find the location of the software and instructions for downloading it in the email youreceived regarding the EMC download site.

3. Unzip the distribution file.Uncompress the distribution file in any directory whose name does not contain spaces in thepath. The installation files are uncompressed to that directory.

4. Run the installation program from the directory into which you expanded the files bydouble-clicking documentumSetup.exe.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 19

Installing Content Server OEM Edition

The installation program starts and a dialog box appears that lists all system requirements.

5. Ensure that your system meets all requirements listed and click Next. The software licenseagreement appears.

6. Read the license agreement.To continue with the installation, click I accept the terms of the license agreement and clickNext.If you do not accept the license agreement terms, the Next button becomes unavailable, and youcannot continue with the installation.

7. You can accept the default directory for Content Server OEM Edition and data (C:\Documentum)or click Browse to select a different installation directory. The name of the directory in whichContent Server OEM Edition is installed must contain only ASCII characters and must not includespaces. Do not use any of these characters in pathnames: ! \ / : * ? " < > | .You can accept the default directory for shared Documentum programs (C:\ProgramFiles\Documentum) or click Browse to select a different directory.Click Next.

8. Type the installation owner username and password, which is typically the login for the hoston which you are performing the installation, and click Next.

9. The custom options dialog enables you to set ports and additional passwords:• Type the application server port. The selected port must not be used by another application.The default port number is 9080. A total of 20 ports starting at the port number you select arereserved for this application server instance, and all of them must be available. The installerwill create an application server instance to host Webtop, the ACS methods server, and otherapplications. Enter the port number that you want the application server to bind to. This portnumber will appear in the URLs for the applications.

• "documentum” will be used as the repository name.

• Type the database administrator password. Enter the value that you want to set as thedatabase administrator password. The default value is "documentum-1.”

• Type the repository service name. This value must match the repository service value that youadded to etc/services.

• Type the global registry password. This is the password to set for the dm_bof_registry user.Typically you would want to set the global registry password to a different value than theother passwords because you will need to share this password with most DFC clients. Thedefault value is "documentum-1.”

• Type the repository owner password. The repository owner is the database user that owns allrepository metadata. The repository uses this database user to connect to the database. Theinstallation program will create this user automatically. Enter the value that you want to set asthe repository owner password. The default value is "documentum-1.”

Click Next after having chosen your options and entered the required values. A dialog appearsthat shows a list of packages included in this installation.

10. Click Next. After clicking Next, the installation begins. The installation will take about 20minutes. A dialog appears that indicates the successful installation of Content Server OEMEdition.

11. Click Finish.

20 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Installing Content Server OEM Edition

This will launch the Content Server OEM Edition welcome page that provides information onhow to launch its component applications. You can access the welcome page any time after theinstallation by navigating to Start>Programs>Documentum>Welcome.

To install Content Server OEM Edition on a Microsoft Windows operating systemand to connect to an Oracle database:

1. Log in to the host system using your Microsoft Windows login.

Note: Microsoft Windows user accounts are not case-sensitive, but Content Server OEM Editioninstallation fails if you connect to the host by using the incorrect case in the username. Forexample, if the account is set up as JPSmith and you connect as jpsmith, you can log in to thehost, but installation fails.

2. Download the Content Server OEM Edition software.You can find the location of the software and instructions for downloading it in the email youreceived regarding the EMC download site.

3. Unzip the distribution file.Uncompress the distribution file in any directory whose name does not contain spaces in thepath. The installation files are uncompressed to that directory.

4. Run the installation program from the directory into which you expanded the files bydouble-clicking documentumSetup.exe.The installation program starts and a dialog box appears that lists all system requirements.

5. Ensure that your system meets all requirements listed and click Next. The software licenseagreement appears.

6. Read the license agreement.To continue with the installation, click I accept the terms of the license agreement and clickNext.If you do not accept the license agreement terms, the Next button becomes unavailable, and youcannot continue with the installation.

7. You can accept the default directory for Content Server OEM Edition and data (C:\Documentum)or click Browse to select a different installation directory. The name of the directory in whichContent Server OEM Edition is installed must contain only ASCII characters and must not includespaces. Do not use any of these characters in pathnames: ! \ / : * ? " < > | .You can accept the default directory for shared Documentum programs (C:\ProgramFiles\Documentum) or click Browse to select a different directory.Click Next.

8. Type the installation owner username and password, which is typically the login for the hoston which you are performing the installation, and click Next. The database connection dialogappears.

9. In the database connection dialog, type the following values:• Database connection identifier

• Database administrator name

• Database administrator password

Click Next. The custom options dialog appears.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 21

Installing Content Server OEM Edition

10. Choose from the following database options:• Connect to your existing Oracle database.

• Custom options, which enable you to set ports and additional passwords.

To connect to an existing Oracle database, click No, I want to use my existing Oracle database.You must choose this option if you already have an Oracle database installed. In the dialog thatappears next, enter the data source name, and the database administrator name and password.Click Next.To see custom options, click Yes under custom options. The Custom Options dialog appearswhere you enter the required information:• Type the application server port. The selected port must not be used by another application.The default port number is 9080. A total of 20 ports starting at the port number you select arereserved for this application server instance, and all of them must be available. The installerwill create an application server instance to host Webtop, the ACS methods server, and otherapplications. Enter the port number that you want the application server to bind to. This portnumber will appear in the URLs for the applications.

• Type the repository name. If you choose to use the bundled SQL Server, this field does notappear and "documentum” will be used as the repository name.

• Type the database administrator password. This field only appears if you have chosen touse the bundled SQL Server database. Enter the value that you want to set as the databaseadministrator password. The default value is "documentum-1.”

• Type the global registry password. This is the password to set for the dm_bof_registry user.Typically you would want to set the global registry password to a different value than theother passwords because you will need to share this password with most DFC clients. Thedefault value is "documentum-1.”

• Type the repository owner password. The repository owner is the database user that owns allrepository metadata. The repository uses this database user to connect to the database. Theinstallation program will create this user automatically. Enter the value that you want to set asthe repository owner password. The default value is "documentum-1.”

Click Next. A dialog appears that shows a list of packages included in this installation.

11. Click Next. A dialog appears that indicates the successful installation of Content Server OEMEdition.

12. Click Finish.This will launch the Content Server OEM Edition welcome page that provides information onhow to launch its component applications. You can access the welcome page any time after theinstallation by navigating to Start>Programs>Documentum>Welcome.

To install Content Server OEM Edition on the Linux operating system and to connectto an Oracle database:

1. Log in to the host system using your host system login.

2. Download the Content Server OEM Edition software.You can find the location of the software and instructions for downloading it in the email youreceived regarding the EMC download site.

3. Uncompress the distribution file.

22 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Installing Content Server OEM Edition

Uncompress the distribution file in any directory whose name does not contain spaces in thepath. The installation files are uncompressed to that directory.

4. Run the installation program from the directory into which you expanded the files bydouble-clicking documentumSetup.bin.The installation program starts and a dialog box appears that lists all system requirements.

5. Ensure that your system meets all requirements listed and click Next. The software licenseagreement appears.

6. Read the license agreement.To continue with the installation, click I accept the terms of the license agreement and clickNext.If you do not accept the license agreement terms, the Next button becomes unavailable, and youcannot continue with the installation.

7. You can accept the default directory for Content Server OEM Edition and data(userHomeDirectory/dctm) or click Browse to select a different installation directory. The nameof the directory in which Content Server OEM Edition is installed must contain only ASCIIcharacters and must not include spaces. Do not use any of these characters in pathnames: ! \/ : * ? " < > | .You can accept the default directory for shared Documentum programs (userHomeDirectory/dctm/shared) or click Browse to select a different directory.Click Next.

8. Type the root password, which is typically the login for the host on which you are performing theinstallation, and click Next. The custom options dialog appears.

9. Choose whether to specify custom options. If you choose to specify custom options, the customoptions dialog appear in which you can specify ports and additional passwords. If you do notchoose to specify custom options, the database connection panel appears.

10. If you chose to specify custom options:• Type the application server port. The selected port must not be used by another application.The default port number is 9080. A total of 20 ports starting at the port number you select arereserved for this application server instance, and all of them must be available. The installerwill create an application server instance to host Webtop, the ACS methods server, and otherapplications. Enter the port number that you want the application server to bind to. This portnumber will appear in the URLs for the applications.

• Type the repository name. If you choose to use the bundled SQL Server, this field does notappear and "documentum” will be used as the repository name.

• Type the repository service name. This value must match the repository service value thatyou added to /etc/services.

• Type the global registry password. This is the password to set for the dm_bof_registry user.Typically you would want to set the global registry password to a different value than theother passwords because you will need to share this password with most DFC clients. Thedefault value is "documentum-1.”

• Type the repository owner password. The repository owner is the database user that owns allrepository metadata. The repository uses this database user to connect to the database. Theinstallation program will create this user automatically. Enter the value that you want to set asthe repository owner password. The default value is "documentum-1.”

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 23

Installing Content Server OEM Edition

Click Next. The database connection dialog appears.

11. In the database connection dialog, type the following values:• Database connection identifier

• Database administrator name

• Database administrator password

Click Next. A dialog appears that shows a list of packages included in this installation.

12. Click Next to begin the installation. The installation might take up to two hours. After theinstallation has completed, a dialog appears that indicates the successful installation of ContentServer OEM Edition.

13. Click Finish.This will launch the a dialog that displays the path to where Content Server OEM Editionwelcome page resides that provides information on how to launch its component applications.

To install Content Server OEM Edition on the Linux operating system and to connectto a Sybase database:

Note: Sybase ASE 15.0.3 ESD#1 requires the Microsoft Visual C++ 2005 SP1 Redistributed Package.Otherwise, the installation might fail, and you might see the message: "Sybase installation has failed.It is likely the Microsoft Visual C++ 2005 SP1 Redistributed Package has not been installed. For detailson how to install that package, see the release notes.” Ensure that this package is installed beforeyou begin installing Content Server OEM Edition with a Sybase database. You can download andinstall this package from the Microsoft web site.

1. Log in to the host system using your host system login.

2. Download the Content Server OEM Edition software.You can find the location of the software and instructions for downloading it in the email youreceived regarding the EMC download site.

3. Uncompress the distribution file.Uncompress the distribution file in any directory whose name does not contain spaces in thepath. The installation files are uncompressed to that directory.

4. Run the installation program from the directory into which you expanded the files bydouble-clicking documentumSetup.bin.The installation program starts and a dialog box appears that lists all system requirements.

5. Ensure that your system meets all requirements listed and click Next. The software licenseagreement appears.

6. Read the license agreement.To continue with the installation, click I accept the terms of the license agreement and clickNext.If you do not accept the license agreement terms, the Next button becomes unavailable, and youcannot continue with the installation.

7. You can accept the default directory for Content Server OEM Edition and data(userHomeDirectory/dctm) or click Browse to select a different installation directory. The nameof the directory in which Content Server OEM Edition is installed must contain only ASCIIcharacters and must not include spaces. Do not use any of these characters in pathnames: ! \/ : * ? " < > | .

24 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Installing Content Server OEM Edition

You can accept the default directory for shared Documentum programs (userHomeDirectory/dctm/shared) or click Browse to select a different directory.Click Next.

8. Type the root password, which is typically the login for the host on which you are performing theinstallation, and click Next. The custom options dialog appears.

9. Choose whether to specify custom options. If you choose to specify custom options, the customoptions dialog appear in which you can specify ports and additional passwords. If you do notchoose to specify custom options, the database connection panel appears.

10. If you chose to specify custom options:• Type the application server port. The selected port must not be used by another application.The default port number is 9080. A total of 20 ports starting at the port number you select arereserved for this application server instance, and all of them must be available. The installerwill create an application server instance to host Webtop, the ACS methods server, and otherapplications. Enter the port number that you want the application server to bind to. This portnumber will appear in the URLs for the applications.

• For the bundled Sybase database, "documentum” will be used as the repository name.

• Type the repository service name. This value must match the repository service value thatyou added to /etc/services.

• Type the global registry password. This is the password to set for the dm_bof_registry user.Typically you would want to set the global registry password to a different value than theother passwords because you will need to share this password with most DFC clients. Thedefault value is "documentum-1.”

• Type the repository owner password. The repository owner is the database user that owns allrepository metadata. The repository uses this database user to connect to the database. Theinstallation program will create this user automatically. Enter the value that you want to set asthe repository owner password. The default value is "documentum-1.”

Click Next. The database connection dialog appears.

11. In the database connection dialog, type the following values:• Database connection identifier

• Database administrator name

• Database administrator password

Click Next. A dialog appears that shows a list of packages included in this installation.

12. Click Next to begin the installation. The installation might take up to two hours. After theinstallation has completed, a dialog appears that indicates the successful installation of ContentServer OEM Edition.

13. Click Finish.This will launch the a dialog that displays the path to where Content Server OEM Editionwelcome page resides that provides information on how to launch its component applications.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 25

Installing Content Server OEM Edition

Reinstalling Content Server OEM Edition fromthe GUIIf an error occurs during installation, first diagnose and fix the problem that caused the failure, thenreinstall Content Server OEM Edition. On a Microsoft Windows platform:• Run the uninstall wizard from the Start>Documentum>Uninstallmenu.

• If you are reinstalling on Windows, reboot the machine when prompted to do so.

• Run the installation program again.

On a Linux platform, uninstall Content Server OEM Edition from the command line as described inReinstalling Content Server OEM Edition from the command line, page 28, then install Content ServerOEM Edition on a Linux platform following GUI installation procedure described in this guide.

Installing Content Server OEM Edition from thecommand lineYou install Content Server OEM Edition by running a command on the command line. Theinstallation program creates the repository and installs all of the Documentum components.

Updating the configuration file

When the Content Server OEM Edition installation program runs, it refers to an XML configurationfile to retrieve values for configuration settings. The configuration file is used to pass parameters tothe installation program, including names for database and for the repository.

Note: The following procedure describes how to create a basic configuration file with all requiredelements. For details about optional configuration parameters, refer to Creating the Content ServerOEM Edition configuration file, page 36.

To create a configuration file:

1. Download the Content Server OEM Edition software.You can find the location of the software and instructions for downloading it in the email youreceived regarding the EMC download site.

2. Unzip the distribution file.Uncompress the distribution file in any directory whose name does not contain spaces in thepath. The installation files are uncompressed to that directory.

3. Use a text editor to open the file oemConfig.xml in the directory into which you expanded thefiles.

4. Update the XML text as shown below, with values from the Installation and configurationworksheet, page 10 in place of the italicized items.• If you are allowing the Content Server OEM Edition installation program to create a database:

26 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Installing Content Server OEM Edition

<dctmOemInstall version="1.0"><database connectionIdentifier=”db_server_name"databaseAdminName="sa" useExistingServer="false" /><docbase name="repository_name" />

</dctmOemInstall>

If the value for useExistingServer is false, the value you choose for the repository nameis ignored and your repository is named "documentum.”

• If you are connecting to an existing database:<dctmOemInstall version="1.0"><database connectionIdentifier=”ODBC_name_for_SQL_Server”

or oracle_connection_stringdatabaseAdminName="db_admin_user" useExistingServer="true" /><docbase name="repository_name" />

</dctmOemInstall>

5. To use nondefault ports for the application server or connection broker, add these elements justbefore the </dctmOemInstall> closing tag.• To use a port other than 9080 for the application server:

<javaMethodServer httpPort="application_server_port" />

• To use a port other than 1489 for the connection broker:<docbroker port="connection_broker_port" />

6. Save the configuration file.

Running the command line installation

After you have updated the configuration file, you can start the command-line installation.

To install Content Server OEM Edition:

1. Log in to the host system using your Microsoft Windows user name and password.

Note: Microsoft Windows user accounts are not case-sensitive, but Content Server OEM Editioninstallation fails if you connect to the host by using the incorrect case in the username. Forexample, if the account is set up as JPSmith and you connect as jpsmith, you can log in to thehost, but installation fails.

2. Run the installation program from the directory into which you expanded the files.The format of the command line for Microsoft Windows is:documentumSetup.exe -silent-target programDir="program_directory"

userDir="user_directory"-passwords databaseAdmin=database_admin_password

docbaseOwner=passwordwindowsInstallOwner=username_and_passwordglobalRegistryUser=password

-oemConfig file="full_path_of_config_file"

The format of the command line for Linux is:documentumSetup.bin -silent-target programDir="program_directory"

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 27

Installing Content Server OEM Edition

userDir="user_directory"-passwords databaseAdmin=sa_password

docbaseOwner=repository_owner_passwordunixRoot=root_passwordglobalRegistryUser=password

-oemConfig file="full_path_of_config_file"

Use quotation marks to enclose any parameter values containing one or more spaces.The Installation and configuration worksheet, page 10 contains the values for program_directory,user_directory, username_and_password, and full_path_of_config_file.If you are connecting to an existing database, the database_admin_passwordmust be the passwordfor the user identified in the configuration file as the databaseAdminName. If the ContentServer OEM Edition installation program is creating a new database, it will set the password forthe user "sa” to the password you enter. The installation program sets the passwords for thedocbaseOwner and globalRegistryUser to the values you enter on the command line.Valid passwords must conform to these requirements:• They must be composed entirely of alphanumeric characters (letters and the digits between0–9 only)

• They must contain at least six characters.

• They must contain at least one digit.

• They must contain at least two letters.

For example, for a new Microsoft Windows installation:documentumSetup.exe -silent-target programDir="c:\Program Files\Documentum"

userDir="c:\Documentum"-passwords databaseAdmin=dbapassword

docbaseOwner=ownerPasswordwindowsInstallOwner=install_owner_passwordglobalRegistryUser=globalregpassword

-oemConfig file="c:\temp\oemConfig.xml"

The Content Server OEM Edition installation program installs and configures the database first,then installs the Content Server OEM Edition software and configures a connection broker andrepository. If the installation program fails at any point, it returns a nonzero return code. To check thereturn code on Microsoft Windows, enter echo %errorlevel% immediately after the installationcommand returns. To check the return code on Linux in a Bourne shell, enter echo $?.

Reinstalling Content Server OEM Edition fromthe command lineIf an error occurs during installation and the repository failed to install successfully, run the Uninstallprogram to remove all of the components, then rerun the installation program. See UninstallingContent Server OEM Edition, page 32. Reboot the host machine after removing the software andbefore reinstalling it.

28 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Installing Content Server OEM Edition

Reviewing the installation logsIf the installation fails, check the file setupError.log in the directory from which you ran theinstallation program. The log gives specific information about what failed. You can start theinstallation program again after correcting the cause of the error. See Reinstalling Content ServerOEM Edition from the command line, page 28.

If any of the values from the command line or the oemConfig.xml file are incorrect, the error messagebegins with text similar to:(timestamp), Setup.product.install, com.documentum.install.shared.common.error.DiException, err, An exception occured in:DiWAOemValidateInputData, beanID: validateInputData

The remainder of the line tells you which value is invalid and why it is invalid. For example, if youspecify a userDir that does not have enough disk space, the error message would be:(timestamp), Setup.product.install, com.documentum.install.shared.common.error.DiException, err, An exception occured in: DiWAOemValidateInputData, beanID:validateInputData - The file system, C:\, should have 3GB but it has 1GB only.

For non-validation errors, the error message indicates which portion of the installationprocess failed. Refer to the log file for that component for more details. For example,if the message mentions launchServerConfigurationProgram.bat, check the log files inthe directory user_dir\product\6.5\install for more details. If the message mentionslaunchFTConfigurationProgram.bat, check the log files in the directory program_dir\IndexAgentsfor more details.

The log files created during installation are listed below. install_dir is the directory in which you runthe installation program; program_dir is the Documentum program directory, and user_dir is theDocumentum user directory.

• install_dir\install_owner.ServerInstaller.log (Content Server OEM Edition installation log)

• install_dir\setupError.log (Installation errors)

• install_dir\install.log (Server installation log)

• program_dir\IndexAgents\install.log (Index agent configuration log)

• program_dir\IndexAgents\setupError.log (Index agent configuration errors)

• user_dir\dba\config\repository_name/*.out (Repository script log)

• user_dir\oem\log\DmServerOemService.log (Documentum Content Server OEM Edition servicelog)

• user_dir\dba\log\DocBroker.Docbroker.log (Connection broker startup log)

• user_dir\dba\log\repository_name.log (Repository startup log)

• user_dir\product\6.5\install\install_owner.ServerConfigurator.log (Content Server OEM Editionconfiguration log)

• user_dir\product\6.5\install\setupError.log (Content Server OEM Edition configuration errors)

• Program Files\Microsoft SQL Server\90\Setup Bootstrap\LOG\summary.txt(Microsoft SQL Serversummary log)

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 29

Installing Content Server OEM Edition

• Program Files\Microsoft SQL Server\90\Setup Bootstrap\LOG\Files(Microsoft SQL Server log files)

• userDir/sybase/log.txt (Sybase installation log)

Starting or stopping Content Server OEMEditionThis section describes how to start and log into Content Server OEM Edition components.

To start or stop Content Server OEM Edition on Windows:

1. Start Content Server OEM Edition by starting the service named "Documentum Master Service.”The log for the service is named dctmServerOem.log and located in the user_directory\oemdirectory.

Note: The Documentum Master Service replaces the Documentum services created for theenterprise edition of Content Server, such as the Documentum Java Method Server service. Usethe Documentum Master Service to start and stop the software.

To start or stop Content Server OEM Edition on Linux:

1. To start Content Server OEM Edition, run the dctmStartFullServer.sh script

2. To stop Content Server OEM Edition, run the dctmStopFullServer.sh script.Both scripts are located in the user_directory\dba directory.

To log in to Documentum Administrator or Retention Policy Services Administratorfrom another machine:

1. Start a web browser on a client machine.

2. Connect to the following URL, where host is the name of the host machine where Content ServerOEM Edition is installed and appserver_port is the application server port on that host:http://host:portnumber/da/

orhttp://host:portnumber/rpsa/

3. Type your login name and password.If you have not yet used Documentum Administrator to add users and groups to the repository,you must log in as the installation owner, using the installation owner’s user name and password.

4. Click Login.

To log in to Documentum Administrator from the Windows Start menu:

1. From the Microsoft Windows Start menu, navigate toPrograms>Documentum>Administration>Documentum Administrator.

2. Type your Content Server OEM installation owner username and password.

3. Click Login.

30 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Installing Content Server OEM Edition

To log in to Retention Policy Services Administrator from the Windows Start menu:

1. From the Microsoft Windows Start menu, navigate toPrograms>Documentum>Administration>Retention Policy Services Admin.

2. Type your Content Server OEM installation owner username and password.

3. Click Login.

To start Documentum Composer from the Windows Start menu:

1. From the Microsoft Windows Start menu, select Documentum > Documentum Composer.

Note: Documentum Composer is supported on Microsoft Windows only.

To log in to Webtop:

1. From the Windows Start menu, navigate to Programs>Documentum>Applications>Webtop.

2. Type the username and password provided on the welcome page.

3. Click Login.

Developing custom Documentum applicationsContent Server OEM Edition includes development tools for customizing and creating Documentumapplications. The key developer-oriented products are:

• Documentum Composer, a design tool for creating application elements and deploying them intocontent repositories. Documentum Composer is supported on Microsoft Windows only.

• Documentum Foundation Classes (DFC), the application programming interface forcommunicating with Content Server OEM Edition.

• Documentum Foundation Services (DFS), a web-service interface that developers can use toaccess Documentum functionality.

• Documentum Foundation Services (DFS) software development kit (SDK), which you can useto develop Documentum functionality. The SDK package provides libraries and samples fordeveloping DFS clients that use the optional .NET or Java client productivity layer, and it providestools for generating custom services from Java and .NET source files.

The DFS SDK package is delivered as a .zip file (emc-dfs-sdk-6.5.zip). The file is available in thedirectory into which you uncompressed the installation package. For more information on how toinstall and use the DFS SDK package refer to the DFS documentation set.

• Retention Policy Services (RPS) software development kit, which you can use to developDocumentum functionality for retention policies.

The RPS SDK package is delivered as .zip file (emc-rps-sdk-6.5.zip). The file is available in thedirectory into which you uncompressed the installation package. For more information on how toinstall and use the RPS SDK package refer to the RPS documentation set.

• Web Development Kit (WDK), the development environment for customizing web-basedDocumentum applications.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 31

Installing Content Server OEM Edition

This set of products enables you to develop custom functionality at any layer of the architecture:

• To customize the presentation layer (the user interface), use WDK. You canuse WDK to customize Webtop, or use its library of web components to createnew web applications. The web components are installed into the directoryuser_directory\jboss4.2.0\server\DctmServer_MethodServer\deploy\webtop.war; thecomponents are in the wdk and webcomponent subdirectories. See theWeb Development KitDevelopment Guide for information.

Caution: This directory is part of a deployed application. Do not move or delete thatdirectory

• To customize the business logic, use the DFC business object framework to define the processinglogic and DFS to expose the logic by means of web services. See the EMC Documentum FoundationClasses Development Guide and the EMC Documentum Foundation Services Development Guide. TheEnterprise Content Services Reference provides a list of the available standard web services.

• To customize the data layer in the repository, use Composer to create repository objects and customobject types. You can also use Composer to create application DAR files that package your customartifacts for installation into a new repository. See the EMC Documentum Composer User Guide.

Uninstalling Content Server OEM EditionYou can use one of two methods to uninstall Content Server OEM Edition:• Uninstall with the GUI.

• Uninstall from the command line. This method is optional.

To uninstall Content Server OEM Edition by using the GUI:

Note: If you uninstall Content Server OEM Edition from the command line, it will preserve metadata,content files, and full-text indexing by default. If you uninstall by using the Uninstall wizard fromthe Start>Documentummenu, everything, including metadata, content files, and full-text indexingwill be deleted.

1. From the Microsoft Windows Start menu, navigate to Programs>Documentum>Uninstall andclick Uninstall to launch the uninstallation program. The uninstallation wizard starts.

2. Click Next.

3. On Microsoft Windows only, type the Windows password and click Next.At the end of the uninstallation process a dialog appears that indicates the successfuluninstallation of the software.

4. Click Next.

5. On Microsoft Windows only, restart your system when prompted.

6. If Content Server OEM Edition is connected to an existing database, use Microsoft SQL Servertools to execute these SQL commands:For a Microsoft SQL Server database:

32 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Installing Content Server OEM Edition

USE masterDROP SCHEMA repository_nameDROP DATABASE db_repository_nameDROP USER repository_name

For an Oracle database:DROP TABLESPACE dm_repository_name_docbase includingcontents;DROP TABLESPACE dm_repository_name_index including contents;DROP USER repository_name;

To uninstall Content Server OEM Edition from the command line:

Note: If you uninstall Content Server OEM Edition from the command line, it will preserve metadata,content files, and full-text indexing by default. If you uninstall by using the Uninstall wizard fromthe Start>Documentummenu, everything, including metadata, content files, and full-text indexingwill be deleted.

1. Navigate to the directory program_dir\_uninst\_suite\, where program_dir is the programdirectory you specified on the command line during installation.

2. For Microsoft Windows, enter this command line:uninstall.exe -passwords windowsInstallOwner=password[-deleteMetadata] [-deleteContentFiles][-deleteFullTextIndex] [-silent]

The three optional arguments behave as follows:• -deleteMetadata deletes metadata from the database tables, the database tables, the databasefiles. If the Content Server OEM Edition installation program created the database, it removesthe database and the Microsoft SQL Server Express software as well.

Note: If there are metadata tables left behind by a previous uninstallation procedure, runningthe uninstallation program with this option will not remove those leftover tables, nor willit remove the RDBMS binaries or DFC. In such cases, if you want to remove the leftovermetadata tables, you must do so manually. To remove the binaries, you must first removethe leftover metadata tables manually, then run the uninstallation program again with the-deleteMetadata option.

• -deleteContentFiles removes the content files from the repository’s file stores.

If you use the -deleteContentFiles argument, the repository must be running when theuninstallation program is invoked.

• -deleteFullTextIndex removes the full-text index from the file system.

For Linux, enter this command line:uninstall.sh [-deleteMetadata] [-deleteContentFiles][-deleteFullTextIndex][-silent]

The three optional arguments behave as follows:• -deleteMetadata deletes metadata from the database tables, the database tables, the databasefiles. If the Content Server OEM Edition installation program created the database, it removesthe database and the Microsoft SQL Server Express software as well.

Note: If there are metadata tables left behind by a previous uninstallation procedure, runningthe uninstallation program with this option will not remove those leftover tables, nor will

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 33

Installing Content Server OEM Edition

it remove the RDBMS binaries or DFC. In such cases, if you want to remove the leftovermetadata tables, you must do so manually. To remove the binaries, you must first removethe leftover metadata tables manually, then run the uninstallation program again with the-deleteMetadata option.

• -deleteContentFiles removes the content files from the repository’s file stores.

If you use the -deleteContentFiles argument, the repository must be running when theuninstallation program is invoked.

• -deleteFullTextIndex removes the full-text index from the file system.

If the uninstallation program fails, a nonzero code is returned.

3. If Content Server OEM Edition is connected to an existing database, use Microsoft SQL Servertools to execute these SQL commands:For a Microsoft SQL Server database:USE masterDROP SCHEMA repository_nameDROP DATABASE db_repository_nameDROP USER repository_name

In these commands, repository_name is the repository name from the <docbase> element inthe oemConfig.xml file.For an Oracle database:DROP TABLESPACE dm_repositoryName_docbase including contents;DROP TABLESPACE dm_repositoryName_index including contents;DROP USER repositoryName;

4. On Microsoft Windows, reboot the host machine.If you do not reboot, the uninstallation process will be incomplete. Any reinstallation will fail.

34 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Chapter 3Creating a Custom Installation Package

A key purpose of Content Server OEM Edition is to enable you to install a repository "behindthe scenes” as part of a custom application. This chapter discusses how to create an applicationinstallation package that includes Content Server OEM Edition. It contains the following topics:• Replacing the Welcome page, page 35

• Creating an installation package for the command-line installation, page 35

• Creating the Content Server OEM Edition configuration file, page 36

• Removing Components from Content Server OEM Edition, page 39

• Removing sample data , page 40

Replacing the Welcome pageThe Content Server OEM Edition installation package for GUI installation comes with a sampleWelcome page that you need to replace with your own before you install Content Server OEMEdition. The Welcome page launches after successful installation.

To repackage the Content Server OEM Edition installation sample Welcome pagewith your own welcome page:

1. In the directory to which you installed the Content Server OEM Edition package, locate theWelcomePage_files.zip file.

2. Unzip the WelcomePage_files.zip file and replace it with your own version ofWelcomePage.htm. Your file must be named WelcomePage.htm, and it must be locatedin the same directory as the sample file was.

Creating an installation package for thecommand-line installationFor the command-line installation, the installation program does not display a user interface forentering the necessary configuration parameters. Instead, the installation program retrieves thenecessary parameters from a configuration file and from values passed on its command line.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 35

Creating a Custom Installation Package

To install Content Server OEM Edition as part of your application, you create an installation programthat installs your application and invokes the Content Server OEM Edition installation program,passing to it the necessary configuration parameters.

To create an application installation package that installs Content Server OEM Edition:

1. Edit the Content Server OEM Edition configuration file and set values for the parameters withpre-established values.When you install Content Server OEM Edition as part of your application, the installationprogram retrieves its configuration parameters from a configuration file. You can edit theconfiguration file to hard-code the values for parameters that will be the same for all installationsof your application. For example, add any DocApps or DAR files required by your application.SeeCreating the Content Server OEM Edition configuration file, page 36, for information aboutthe required parameters and Configuration file format and parameters, page 37, for details aboutthe file format and about the available optional configuration parameters.

2. Create the installation program for your application.You can write the application installation program in the programming language of your choiceor you can use a package such as InstallShield.The application installation program needs to accomplish these tasks:• Validate that the host on which the application is being installed meets the requirements foryour application and for Content Server OEM Edition; see Prepare the host machines, page 11.

• Capture values for any Content Server OEM Edition configuration parameters that arenot preset in the configuration file. It can ask the user to enter the values or derive themprogrammatically. Update the oemConfig.xml file with the values.

• Invoke the Content Server OEM Edition installation program, as described in InstallingContent Server OEM Edition from the command line, page 26.

• Uninstall any of the Documentum web applications that you do not want to include as partof your application package; see Removing Components from Content Server OEM Edition,page 39.

• Deploy any custom applications. The JBoss deployment directory is atuserDir/jboss4.2.0/server/DctmServer_MethodServer/deploy and hot deployment is turnedon. Copy an EAR or WAR file to that directory, and it gets deployed automatically. Refer tothe JBoss 4.2.0 documentation for instructions on how to package your application. Refer tothe EMC Documentum Web Development Kit and Webtop Deployment Guide for information onhow to deploy WDK and Webtop applications.

• Run any tasks required by your application, such as running scripts or jobs.

3. Package the application installation program for delivery to customers.

Creating the Content Server OEM Editionconfiguration fileWhen the Content Server OEM Edition installation program runs, it refers to an XML configurationfile to retrieve values for a variety of configuration settings. The values in the configuration file

36 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Creating a Custom Installation Package

configure Content Server OEM Edition, the index agent, the Java method server, and the repository.You can optionally install DocApps and DAR files in the repository by identifying the DocApps inthe configuration file. When you do so, the installer "silently” invokes Documentum ApplicationInstaller (DAI) to deploy DocApps and Documentum Composer to deploy DAR files. Refer to theDocumentum Application Builder and Documentum Composer documentation for informationabout DocApps and DAR files.

You can edit the configuration file using a text editor and package it with the application installationprogram. Alternatively, the application installation program can capture the parameter values andcreate the file dynamically. In either case, the file must exist when the application installationprogram invokes the Content Server OEM Edition installation program.

Configuration file format and parameters

The names of the elements in this configuration file are case sensitive; you must specify themcapitalized as shown in the format below.

The configuration file is used to pass some parameters to the installation program. It may also beused to pass information about DocApps and DAR files to the installation program, to enable theinstaller to deploy those DocApps and DAR files.

The format of the file with only the required parameters is:<dctmOemInstall version="1.0">

<database connectionIdentifier=”db_server_or_DSN_name”databaseAdminName="db_admin_name" useExistingServer="true_or_false /><docbase name="repository_name"></docbase>

</dctmOemInstall>

The format with optional parameters is:<dctmOemInstall version=”1.0”>

<database connectionIdentifier=”db_server_or_DSN_name”databaseAdminName="db_admin_name" useExistingServer="true_or_false />

<docbroker port=”connection_broker_port” /><docbase id="repository_id" name="repository_name"

enableCollaborationServices="TRUE" collaborationServicesLicense=license_codeenableRm="TRUE" rmLicense=license_codeenableFrs="TRUE" frsLicense=license_codeenablePrm="TRUE" prmLicense=license_code<emailNotification smtpHost=”host_name”

installOwnerEmail=”install_owner_email"/></docbase><javaMethodServer httpPort=”JSM_http_port” /><docApps>

<docApp name="DocAppName"><description>DocAppDescription</description><archiveDir>PathtoArchive</archiveDir><logDir>PathtoLogDirectory</logDir>

</docApp></docApps><dars>

<dar name="DARFileName"><description>DARFileDescription</description><darFile>PathtoDARFile</darFile>

</dar></dars>

</dctmOemInstall>

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 37

Creating a Custom Installation Package

Table 2. Content Server OEM Edition configuration file parameters

Parameter Description Default

databaseconnectionIdentifier

The database server instance name (for a newdatabase) or the ODBC data source name (foran existing Microsoft SQL Server database)or the database connection identifier from thetnsnames.ora file (for an existing Oracle database).The database server instance name for a newdatabase must be all capital letters.

databasedatabaseAdminName

The user name of the database administrator. If theinstallation program is creating the database, thedatabaseAdminName must be set to "sa”.

databaseuseExistingServer

Boolean specifying whether to use an existingdatabase rather than creating one as part of theinstallation.

False. Theinstallation createsa new database

docbroker port The port on which the connection broker listens 1489

docbase id A unique repository identification number.The value can be any number from 1 to 16777215,without a leading zero (0).

Automaticallygenerated ID.

docbase name The repository name.The name must be no longer than 32 characters. Itmust consist of letters, numbers, and underscores(_), and the first character must be a letter.The repository name cannot include spaces ornonalphanumeric characters and all letters andnumbers in the name must be ASCII characters.The repository name "docu” is reserved by EMCDocumentum.

None. Thisattribute isrequired.

docbase enable{product_code}="TRUE”{product_code}License

Activates the software license for the correspondingoptional component. The licenses are activeby default. For each component you want todeactivate, set the enable{product_code} attributeto "TRUE” and provide the license key forthat component (received from EMC) with thecorresponding {product_code}License attribute. Theoptional components are:

The softwarelicenses areinactive.

• RM (Records Manager)

• FRS (Federation Records Services)

• PRM (Physical Records Manager)

emailNotificationsmtpHost

The name of the host where an SMTP server isrunning. Content Server OEM Edition uses thisSMTP server to send email notifications.

"localhost"

38 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Creating a Custom Installation Package

Parameter Description Default

emailNotificationinstallOwnerEmail

The address to which Content Server OEM Editionsends email notifications about system issues. Thevalue is the installation owner’s email address.

javaMethodServerhttpPort

The port on which the Java Method Server listens 9080

docApp Include a <docApp>...</docApp> section for eachDocApp you want to deploy.

docApp name The name of a DocApp that the installationprogram installs in the repository

description The description the DocApp

archiveDir The directory on the host where the DocApp islocated

logDir The directory on the host where the log forDocApp installation is located. You can identifyany existing directory where the installation ownerhas write permission. The name of the log file isdocAppName_installLog.html.

The default isthe value of the<archiveDir>element.

dar Include a <dar>...</dar> section for each DAR fileyou want to deploy.

dar name The name of a DAR file that the installationprogram installs in the repository

description The description the DAR file

darfile The directory on the host where the DAR file islocated

Removing Components from Content ServerOEM EditionThe Content Server OEM Edition installation program installs several web applications, shown in thetable below. If you do not want to include one or more of these web applications when you installyour application, you can remove them after running the Content Server OEM Edition installationprogram.

Table 3. Web applications installed as part of Content Server OEM Edition

Web application file Component

da.war Documentum Administrator

rpsa.war Retention Policy Services Administrator

rps.war Web services interfaces for Retention PolicyServices

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 39

Creating a Custom Installation Package

Web application file Component

webtop.war Webtop

dfs.ear Documentum Foundation Services

IndexAgent1.war Index agent (for full-text indexing)

acs.ear Accelerated Content Services server

ServerApps.ear Method server

To remove one or more web applications:

1. Stop the Content Server OEM Edition server.

2. Navigate to the directory user_directory/jboss4.2.0/server/DctmServer_MethodServer/deploy.

3. Delete the directory corresponding to the web application you want to remove.

4. Restart the Content Server OEM Edition server.

Removing sample dataWhen you install Content Server OEM Edition, the package includes sample data, such as sampleuser accounts, custom object types, and sample documents that you can use in your developmentenvironment. If you will not use the included sample data, you can remove them with DocumentumAdministrator.

Before you can remove sample data, you need user Documentum Administrator to make the sampleusers named barthur and bwhite inactive:

To change a user form active to inactive:

1. Navigate to Administration > User Management > Users.

2. Select the user and then select View > Properties to access the User Properties - Info page.

3. Make the active user inactive by selecting Inactive from the State dropdown list.

4. Click OK.

40 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Chapter 4Understanding the Content Server OEMEdition Repository

Installing Content Server OEM Edition installs a content repository. This chapter describes the initialconfiguration of the repository. It also includes information about the basic administration tasks thatyou can perform. The chapter includes the following topics:• Configuring the repository, page 41

• Runtime log files, page 42

• Creating users and groups, page 42

• Configuring jobs, page 45

Configuring the repositoryThis section describes the basic configuration of the repository and associated Content Server OEMEdition after the installation.

Operating configuration

The repository is typically configured with the following operating values:• A maximum of concurrent users it can accept. The number of users depends on the type ofdatabase to which the repository connects.

• A maximum of a specified size of objects per hour it can index. This value depends on the typeof database to which the repository connects.

• A maximum of a specified size of objects it can store. This value depends on the type of databaseto which the repository connects.

• Uses the ACL associated with a user as the default ACL for objects created by the user(dm_server_config.default_acl=3)

• Enforces folder security (dm_docbase_config.folder_security = true)

For an example of sizing and scaling values, refer to the DOCUMENTUM OEM EDITION WEBTOP6.5SP1 WITH 25 ACTIVE USERS ON SQL SERVER EXPRESS 2005 white paper on the Powerlinkweb site ((http://powerlink.EMC.com).

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 41

Understanding the Content Server OEM Edition Repository

After installation, it is possible to change the allowed number of concurrent users by setting theconcurrent_session key in the Content Server’s server.ini file. Resetting that key requires restartingthe server after the change to make the change effective.

You cannot change the tuned values for indexing ingestion or maximum object storage in therepository.

Global registry

The repository is created as a global registry. For information about global registries, refer to the EMCDocumentum Content Server Installation Guide and Repository and global registry, page 13.

Administration jobs

Configuring a repository installs the basic suite of administration jobs. The jobs are installed withdefault schedules. Some are installed in the active state and some in the inactive state. All the jobsthat delete objects or files from the repository are installed in the inactive state. For instructions onresetting job schedules and activating or deactivating jobs, refer to Configuring jobs, page 45.

Runtime log filesThe log files generated by Content Server OEM Edition at runtime are in the same location as thosecreated by a Content Server Enterprise Edition. Refer to the standard Content Server documentationsuite for full details.

Creating users and groupsAfter a repository is configured, it has a default set of users and groups. Those users and groupsprovide access for the installation owner, the repository owner, and for internal processes such as theIndex Agent. Before other individuals within an enterprise can access the repository, the individualsmust be added as users to the repository. Additionally, if the site wants to use groups to controlaccess to objects, those groups must also be added to the repository.

If a customer is planning to use an LDAP directory server to manage users and groups and foruser authentication, they must create LDAP entries for each user and group, rather than creatingthe users and groups directly in the repository. An internal job, dm_LDAPSynchronization, willautomatically propagate the user and group entries to the repository, and set the user_source andgroup_source attributes.

42 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Understanding the Content Server OEM Edition Repository

Adding users to the repository

You add users and groups to the repository using Documentum Administrator.

To create a user account:

1. Start a web browser on a client machine.

2. Connect to the following URL, where host is the name of the host machine where Content ServerOEM Edition is installed and appserver_port is the application server port on that host:http://host:portnumber/da/

orhttp://host:portnumber/rpsa/

3. Type your login name and password.If you have not yet used Documentum Administrator to add users and groups to the repository,you must log in as the installation owner, using the installation owner’s Windows user nameand password.

4. Click Login.

5. Navigate to Administration > User Management > Users.

6. Select File > New > User.The system displays the New User - Info page.

7. Click the ? in the upper right corner to display the online help for creating a new user.

Using an LDAP directory server

To use an LDAP directory server for authentication, the customer must create an ldap config object inthe repository for the directory server. Typically, ldap config objects are created using DocumentumAdministrator. The user must have Superuser privileges in the repository to create an ldap configobject. For information ldap config objects and their attributes, refer to the EMC Documentum ObjectReference Manual. For information about implementing use of an LDAP directory server, refer to theEMC Documentum Content Server Administration Guide.

The user and group entries in the LDAP directory server must include LDAP attribute values thatmap to the required attributes of users and groups. The mappings between LDAP attributes anduser or group attributes are defined in the ldap config object that represents an LDAP directoryserver in the repository.

Required and recommended attributes for users

Table 4, page 44, lists the attributes that are required and those that are recommended for users.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 43

Understanding the Content Server OEM Edition Repository

Table 4. Required and recommended user attributes

Attribute Description Required or recommended

user_name Content Server OEM Editionuser name. This can be anindividual user or a groupname. It must be uniqueamong the user and groupnames in the repository.

The name must consist ofcharacters compatible withthe server_os_codepage of theContent Server OEM Edition.

Required

user_login_name Name used to authenticate theuser.

The combination ofuser_login_name anduser_login_domain mustbe unique in the repository.

Required

user_address User’s electronic mail address. Required

user_source Indicates how the user isauthenticated

This is not required. However,the default is OS.

If the user is authenticatedthrough LDAP, the attribute isset automatically to LDAP bythe dm_LDAP ynchronizationjob.

default_cabinet Identifies the user’s defaultfolder. This is where objectscreated by the user are storedunless the user explicitlydesignates another location.

This is not required. Thedefault is Temp.

For a complete listing of user attributes, refer to the EMC Documentum Object Referencemanual.

Required and optional attributes for groups

Table 5, page 45, lists the attributes that are required and those that are recommended for groups.

44 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Understanding the Content Server OEM Edition Repository

Table 5. Required and optional group attributes

Attribute Description Required or recommended

group_name Content Server OEM Editionuser name. This can be anindividual user or a groupname. It must be uniqueamong the user and groupnames in the repository.

The name must consist ofcharacters compatible withthe server_os_codepage of theContent Server OEM Edition.

Required

group_source Identifies the source of thegroup. The only valid value isLDAP, meaning the group wascreated by importing an LDAPgroup.

This is automatically set toLDAP if the group is managedby an LDAP directory server.

Configuring jobsConfiguring a repository automatically installs a suite of administration jobs. These jobs are installedwith default schedules and many, including all those that delete objects from the repository, areinstalled in the inactive state. For list of the installed administration jobs, refer to the Tools andTracing chapter of the EMC Documentum Content Server Administration Guide. The reference materialin that chapter describes each job, its arguments, and its default settings, as well as whether it isinstalled inactive or active.

You may choose to activate or deactivate one or more jobs while installing the embedding application.You may also choose to reset a job’s schedule. Both of these operations can be performed by settingthe appropriate attributes for a job.

You may also decide to provide a way for the customer to activate and deactivate jobs and resetschedules.

Setting job schedules

Job schedules are controlled by several attributes. If you are not using Documentum Administratorto set job schedules, then you must set the attributes directly. The attributes that control a jobschedule are:• start_date

• a_next_invocation

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 45

Understanding the Content Server OEM Edition Repository

• run_mode

• run_interval

The starting date is the earliest date at which the job can be executed. The a_next_invocation propertydefines the first (or next) scheduled execution of the job. When you set the job’s schedule, setstart_date and a_next_invocation to the same value. Thereafter, when the job runs, a_next_invocationis automatically reset to the next invocation time. However, for the first run of the job, the value ina_next_invocation must match the value in start_date.

The run_mode and run_interval values work in conjunction to define how often the job is runafter its first execution. The run_mode attribute defines a unit of measure. The integer value youspecify in the run_interval attribute is interpreted according to the unit of measure you specifyin the run_mode attribute.

For example, if you set the run_mode to 2, meaning delay in Hours, and run_interval to 12, thejob is executed every 12 hours. If you set run_mode to 4, meaning day of Week, and run_intervalto 7, the job is run every 7th day of the week.

For more information about scheduling jobs, refer to the EMC Documentum Content ServerAdministration Guide. For a full list of job attributes, refer to the EMC Documentum Object Reference.

Activating and deactivating jobs

Whether a job is active or inactive is controlled by the is_inactive attribute of the dm_job object. Tochange the active state of a job, set that attribute to the value representing the desired state.

46 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Chapter 5Understanding Full-Text Indexing

This chapter discusses the Content Server OEM Edition’s implementation of the Lucene full-textindexing software. The chapter contains the following topics:• Understanding indexing and the indexing software, page 47

• Words that are not indexed, page 48

• Punctuation, page 48

• Indexing numeric values, page 48

• Indexing NULL values, page 48

• Supported formats, page 49

• Supported languages, page 49

• Supported querying, page 49

• Comparing Lucene and FAST full-text indexing systems, page 49

• Internationalization, page 50

• Object type schema changes and full-text indexing, page 50

• Optimizing the index, page 51

• Tuning the result set batch size, page 52

• Objects and attributes supporting full-text indexing, page 52

• Indexing failures, page 53

• Log files and logging, page 53

Understanding indexing and the indexingsoftwareInstalling Content Server OEM Edition installs an index agent and the Lucene full-text indexingengine and creates the full-text index. The full-text indexing process is described in the EMCDocumentum Content Server Full-text Indexing System Deployment Guide.

The Lucene software is the index server for Content Server OEM Edition. Content Server EnterpriseEdition uses a FAST index server.

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 47

Understanding Full-Text Indexing

The Lucene software consists of an indexer plug-in and a searcher servlet. The software runs in thesame application server servlet container as the index agent.

The Content Server OEM Edition’s role in indexing is the same as in Content Server EnterpriseEdition. Certain operations generate queue items that are queued to the full-text indexing user. Theindex agent reads the queue items and creates a DFTXML representation of the object to be indexed.(DFTXML is an internal format used by the indexing system.) The DFTXML representation containsthe metadata associated with the object and a pointer to the content being indexed.

Lucene extracts the indexable content from the content file, then updates the index. Lucene indexescontent synchronously. When the DFTXML representing an indexable object is submitted to Luceneby the index agent, the properties and content of the SysObject are added to the index immediately.

Lucene can index objects that have multiple associated content files. However, clients cannot specifya query against a particular content of the object. All text extracted from all of the associated contentfiles is indexed together, not discretely.

Thesaurus searching is not supported. Term-hit highlighting is not supported.

Words that are not indexedThe following stop words are not indexed:

a, an, and, are, as, at, be, but, by, for, if, in, into, is, it, no, not, of, on, s, such, t, that, the, their, then,there, these, they, this, to, was, will, with

The stop word list is not configurable.

PunctuationPunctuation marks are not included in the index. The search process analyzes queries and removespunctuation marks, so that the indexed strings and the strings for which a query searches are identical.

Indexing numeric valuesNumeric values are stored by Lucene using 16 decimal digits. Integers with a range of -21477483648to 2147483647 are indexed. Double and floating-point numeric values have five digits of precisionafter the decimal point. For doubles and floating-point integers, precision past five digits is truncated.

Indexing NULL valuesNULL values are indexed as follows by Lucene:• A NULL value for a numeric data type is stored in the index as a series of 16 zeros.

• A NULL value for a date data type is stored in the index as the date 1753-01-01 00:00:00.

48 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Understanding Full-Text Indexing

NULL values in string data types are not indexed.

Supported formatsThe supported indexable formats are listed in the EMC Documentum Content Server Full-text IndexingSystem Deployment Guide.

Supported languagesIn this release, English is the only supported language for full-text indexing of both content files andmetadata.

Supported queryingLucene supports the following queries:• The DQL SEARCH DOCUMENT CONTAINS clause

• The following DQL WHERE clauses:— String data types =, !=, like

— Boolean data types =, !=

— Integer, double, and date data types =, !=, <, >, <=, >=

— id data types =, !=

— The FOLDER clause, including DESCEND

— LIKE clauses, including wildcard support

Comparing Lucene and FAST full-text indexingsystemsThere are some differences in performance and scalability between the Lucene indexing system usedby Content Server OEM Edition and the FAST indexing system used by Content Server EnterpriseEdition, as shown in the following table:

Table 6. Full-text indexing server comparison — Lucene and FAST

Functionality Lucene index server FAST index server

Scalability 3 million documents 20 million documents per node,200 million maximum

Ingestion rate 1.3 documents/sec.‘ 14 documents/sec

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 49

Understanding Full-Text Indexing

Functionality Lucene index server FAST index server

Format support Stellent 8.1.9 Stellent 8.1.9

VQL support No Yes

XML support No Yes (VQL)

Language support English only Most languages, including CJK

Lemmatization No Yes

High availability No Active/Active, Active/Passive(IS5)

SAN/NAS support Unknown SAN, NAS in IS5

Thesaurus / synonymdictionary

No Yes

Support tools No Yes

Administrative interfaces No Yes

Platform support Windows/Linux All platforms

FAST index server and Lucene index server handle certain full-text queries differently:• In the index server, SEARCH TOPIC is deprecated syntax that is supported for backwardcompatibility. SEARCH TOPIC is not supported by Lucene. SEARCH TOPIC clauses must beremoved from queries.

• Lucene does not support zone searching.

• Lucene does not support chunked XML documents.

• Lucene wild card searches do not return matches when there is a space in the result.

For example, this query returns matches on FAST but not on Lucene because of the wild card inthe search document contains clause:SELECT object_name FROM dm_documentSEARCH DOCUMENT CONTAINS 'Installing%SCS'WHERE object_name LIKE 'FTDQL_FORMAT-12345'AND a_content_type='mif'

InternationalizationThe index is stored in the UTF-8 encoding.

Object type schema changes and full-textindexingYou do not have to reindex the repository following a change to the object type hierarchy. Objecttypes may be added or dropped and attributes added or dropped without any need to reindex.

50 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Understanding Full-Text Indexing

Optimizing the indexDocumentum provides the dm_FTOptimizeIndex job for optimizing the index. The optimizationprocess merges all existing file segments into a new segment and removes index entries that aremarked for deletion. This results in a more compact index and faster search speed. However,optimizing the index does not increase the indexing speed or reduce the disk space usage.

The time required to optimize the index varies directly with the size of the index. Optimizingregularly, for example, once a week, is useful, but you or your customers will determine the exactschedule.

During the optimization process, the disk space usage of the index approximately doubles. However,the resulting index is not twice the size of the original index, nor is it significantly smaller. Beforerunning the optimization job, ensure that there is sufficient free disk space on the drive.

The job takes standard arguments and the path to the index. For example:collection_path=C:\Documentum\data\fulltext\lucene\IndexAgent1\index

Shut down the index agent before running the job. If you run the optimization job while the indexagent is running, the index is not optimized and the job report indicates that the index agent servletwas running and must be shut down. If the job is running, the index agent servlet cannot be started.

This is a sample job report showing that the job ran successfully:FTOptimizeIndex Report For DocBase testenv.testenv As Of 2006/05/24 23:01:17

---------------------------------------FTOptimizeIndex Job Arguments:(StandardJobArgs: docbase_name=testenv.testenv userName=test1jobId=0800019f8000550d methodTraceLevel=0)collection_path=C:\Documentum\data\fulltext\lucene\IndexAgent1\index

---------------------------------------The index at C:\Documentum\data\fulltext\lucene\IndexAgent1\index wassuccessfully optimized.Report End 2006/05/24 23:01:17

This is a sample job report showing that the index agent was running:FTOptimizeIndex Report For DocBase testenv.testenv As Of 2006/05/25 16:55:25

---------------------------------------FTOptimizeIndex Job Arguments:(StandardJobArgs: docbase_name=testenv.testenv userName=test1jobId=0800019f8000550d methodTraceLevel=0)collection_path=C:\Documentum\data\fulltext\lucene\IndexAgent1\index

---------------------------------------The index at C:\Documentum\data\fulltext\lucene\IndexAgent1\indexis currently locked. Please shutdown the indexagent servlet and retry.Report End 2006/05/25 16:55:28

This is a sample job report showing that the collection_path argument was invalid or the indexdid not exist:FTOptimizeIndex Report For DocBase testenv.testenv As Of 2006/05/25 17:00:59

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 51

Understanding Full-Text Indexing

---------------------------------------FTOptimizeIndex Job Arguments:(StandardJobArgs: docbase_name=testenv.testenv userName=test1jobId=0800019f8000550d methodTraceLevel=0) collection_path=C:\Documentum\index

---------------------------------------The index does not exist at collection path C:\Documentum\index ReportEnd 2006/05/25 17:01:02

Tuning the result set batch sizeYou can tune the size of the results set returned by the searcher for queries by setting theresult_batch_size attribute in the ft engine config object. This affects all queries, both FTDQL andnon-FTDQL.

The default value for this attribute is 1000. Changing the value is desirable under some circumstances.

Increase the value if:• You expect more non-FTDQL queries than FTDQL queries, or

• You expect more queries with the NOFTDQL hint applied than queries with the FTDQL hintapplied, or

• Users are typically interested in browsing more results than the current value of the attribute.

Decrease the value if:• You expect more FTDQL-compliant queries than non-FTDQL queries, or

• You expect more queries with the FTDQL hint applied than queries with the NOFTDQL hintapplied, or

• Users are typically interested in browsing fewer results than the current value of the attribute.

Objects and attributes supporting full-textindexingThe same objects and attributes support full-text indexing in the Content Server OEM Edition as inContent Server Enterprise Edition. Note the following:• A location object named lucene refers to the directory where the dmfulltext.ini file is located.

• The dmfulltext.ini file contains the name and path of the Lucene query plugin.

• The ft engine config object representing the Lucene software is named "LUCENE Fulltext EngineConfiguration.”

• In the full-text index object, the install_loc attribute is set to the value lucene and the ft_engine_idattribute is set to the object ID of the ft engine config object.

• The fulltext_location attribute of the server config object is set to the value lucene.

• The fulltext_install_locs attribute of the docbase config object is set to the value lucene.

52 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Understanding Full-Text Indexing

Indexing failuresInformation on indexing failures is recorded in log files and in the task_state property of the queueitem. Refer to the EMC Documentum Content Server Administration Guide for information on how theindex agent handles queue items. Use Documentum Administrator to resubmit objects for indexing.

Log files and loggingThe log files for full-text indexing are located in program_directory\jboss4.2.0\server\DctmServer_MethodServer\logs. The log file name is IndexAgentN.log where N is the number corresponding tothe index agent number. (The first index agent is IndexAgent1, for example.)

The following priority levels determine how much information is recorded in the log:• fatal records errors when the index cannot be opened, the index is corrupted, or other failures arepreventing any indexing from taking place.

• error records errors when an object fails indexing, and includes the reason for the failure and theobject ID of the failed object.

This is the default logging level.

• warn records errors when a content file fails indexing but the metadata is indexed successfully.

The reasons for the content failure and the object ID are logged.

• info records all terms associated with failed object that is logged.

• debug records execution trace messages and information about indexing operations, such assegment merges.

Each logging level includes messages at its own level, plus all higher-level messages. The warnlevel also records error and fatal messages. The debug level records all possible information. Thelevels apply to both indexing and searching.

The priority level of the logged messages is determined by a setting in the program_directory\jboss4.2.0\server\DctmServer_MethodServer\deploy\IndexAgentN.war\WEB-INF\classes\log4j.propertiesfile, where N is a number corresponding to the index agent number. To change the priority level,change the following entry:#Control logging level using line below for the IndexAgent.log4j.category.com.documentum=INFO

Valid values for this entry are DEBUG, INFO, WARN, ERROR, and FATAL.

Log files are time-stamped when the application server process is restarted. The Log Purge jobcleans up old log files.

Tracing related to indexing and searching generated by the index agent and Content Server OEMEdition operates the same as for the enterprise indexing system. Tracing generated by the Lucenequery plugin is enabled by the MODIFY_TRACE administration method. The syntax is:apply,c,NULL,MODIFY_TRACE,SUBSYSTEM,S,fulltext,VALUE,S,all

To disable tracing:apply,c,NULL,MODIFY_TRACE,SUBSYSTEM,S,fulltext,VALUE,S,none

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 53

Understanding Full-Text Indexing

Trace messages are recorded in the fttrace_repositoryname.log file, where repositorynameis the name of the repository in which tracing is enabled. The log file is found in the$DOCUMENTUM/dba/log/fulltext directory. To disable tracing, turn off the MODIFY_TRACE applymethod by setting VALUE to none.

Trace messages in the log are time stamped with process ID information, and include HTTPconnection information, HTTP request and response strings, the results returned from the full-textindex, and information about how queries are translated from DQL by the query plugin.

54 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide

Index

Aadministration jobs, configuration, 42

Ccode page used by Lucene, 50command-line installation

configuration file, 26configuration file for command-line

installation, described, 26configuration file for silent installer,

described, 36Content Server

runtime log files, 42Content Server OEM Edition

Lucene software and, 47starting/stopping all components, 30

Content Server, OEM Edition. SeeDocumentum Content Server OEMEdition

Ddatabase

Oracle, 15databases

Windows requirements, 14dm_FTOptimizeIndex job, 51docbase config object

fulltext_install_locs attributesetting, 52

DocumentumContent Server OEMEdition,overviewoverview, 7

Documentum repositoryadministration jobs, 42as global registry, 42configuration, default, 41

DQL queries supported by Lucene, 49

Eembedding installer

recommendations andrequirements, 36

Ffiles

tnsnames.ora, 15ft engine config object for Lucene, 52full-text index

encoding, 50optimzing, 51

full-text indexesDQL queries, supported, 49

full-text indexingfailures, troubleshooting, 53file formats supported, 49languages supported, 49log files, 53log files, removal, 53logging levels, 53NULL values, 48numberic values, 48object type hierarchy changes and, 50overview, 47punctuation, 48query result batch size, tuning, 52term-hit highlighting, 48thesaurus searching, 48unindexed words, 48

full-text queryingdifferences from enterprise

querying, 50fulltext index object

ft_engine_id attribute setting, 52install_loc attribute setting, 52

Gglobal registry, 42

EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide 55

Index

network locations, 13SBOs, 13

groupscreating, 42LDAP Directory Server and, 43required attributes, 44

Iinstallation

update installation, 28installation owner

case-sensitivity of username, 18 to 19,21, 27

installing from command lineintroduction to, 35

installing, Sybase, 19

Jjobs

activating/deactivating, 46configuration of, 45dm_FTOptimizeIndex, 51scheduling, 45

jobs, administration, 42

LLDAP directory server, use of, 42location object lucene, 52log files

Content Server, 42Lucene

ft engine config object, 52query plugin location, 52

lucene location object, 52Lucene software

components, 48

MMicrosoft SQL Server

ODBC configuration, 14

Nnetwork location objects, 13NULL values in full-text indexes, 48numeric values in full-text indexes, 48

Oobject type hierarchy

affect of change on full-text index, 50ODBC configuration, 14Oracle

database, 15database aliases, 15TNS aliases, 15tnsnames.ora file, 15

Ppunctuation in f ull-text indexes, 48

Rrepositories

global registry, 13job activation/deactivation, 46job scheduling, 45users and groups, creating, 42

result_batch_size attribute, 52

Sserver config object

fulltext_location attribute setting, 52silent installer

configuration file, 36stop word list, 48

Tterm-hit highlighting, 48thesaurus searching, 48tnsnames.ora file, 15

Uuninstalling from command line

introduced, 32updating an installation, 28users

creating, 42LDAP Directory Server and, 43required and recommended

attributes, 43

Wwords not indexed, 48

56 EMC Documentum Content Server OEM Edition Version 6.5 SP2 Installation and Configuration Guide