EMC Documentum ContentServer - jouvinio.net

EMC® Documentum®

Content ServerVersion 6.5

Administration GuideP/N 300-007-198-A01

EMC CorporationCorporate Headquarters:

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

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

Published July 2008

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

Chapter 1 Introduction ........................................................................................... 27Essential concepts....................................................................................... 27Installation components .......................................................................... 28Configuration choices ............................................................................. 28Configuration objects.............................................................................. 29

Administration tasks .................................................................................. 29User privilege requirements for administration tasks .................................... 31Administration interfaces............................................................................ 32Starting Documentum Administrator....................................................... 32Using the Content Server Manager on Windows....................................... 32Using DQL for administrative tasks ......................................................... 33

Documentum tool suite............................................................................... 33Administration methods ............................................................................. 33The dm_error utility ................................................................................... 34Viewing connected users............................................................................. 34Where to look for more information............................................................. 34

Chapter 2 Content Repositories ............................................................................ 37Essential concepts....................................................................................... 37Repository and server connections........................................................... 38Repository configuration......................................................................... 38

Adding additional repositories .................................................................... 39Adding a repository................................................................................ 40Configuring the new repository for use with MediaTransformation Services ......................................................................... 40Contents of new repositories ................................................................... 41

Managing cabinets and folders .................................................................... 42Public and private cabinets...................................................................... 43Home cabinets........................................................................................ 43Creating folders and cabinets .................................................................. 43Changing and deleting folders and cabinets ............................................. 43

Setting the dd_locales property ................................................................... 44Manipulating type indexes.......................................................................... 44Alternate locations for object-type tables on Oracle and DB2 ......................... 45Configuring storage and handling of date values .......................................... 45Enabling a repository as a global registry ..................................................... 46Dumping and loading a repository .............................................................. 48Code page compatibility issues................................................................ 48Supporting object types........................................................................... 48Execution methods ................................................................................. 49

EMC Documentum Content Server Version 6.5 Administration Guide 3

Table of Contents

Dumping a repository............................................................................. 50Dumping objects under retention ........................................................ 50Aspects and dump operations ............................................................. 51Dumping an entire repository ............................................................. 51Dumping specific objects .................................................................... 51Setting the type property................................................................. 52Setting the predicate properties ....................................................... 53

Content files and dumping.................................................................. 54Dumping without content ............................................................... 54Including content ........................................................................... 55Compressing content ...................................................................... 55

Setting the cache size .......................................................................... 55Using non-restartable dump ............................................................... 56Using a script to create a dump file ...................................................... 56Sample script for a full repository dump with contentincluded ........................................................................................ 57Sample script for a partial repository dump ..................................... 57

If the server crashes during a dump operation ...................................... 59Moving the dump file ............................................................................. 59Loading a repository............................................................................... 59Refreshing repository objects from a dump file ..................................... 60Loading job objects ............................................................................. 60Loading registered tables .................................................................... 61Turning off save event generation during load operations ..................... 61Loading a new repository ................................................................... 61The preLoad utility ........................................................................ 62

Load procedure for new repositories.................................................... 62DocApps............................................................................................ 64

Generating dump and load trace messages............................................... 64Creating location and mount point objects.................................................... 64Location objects ...................................................................................... 65Mount point objects ................................................................................ 66Platform aliases .................................................................................. 66

Format objects ............................................................................................ 67The DOS extension property ................................................................... 68The format_class property....................................................................... 68Listing current format objects .................................................................. 68Adding format objects ............................................................................ 69Using DQL......................................................................................... 69Rich media formats............................................................................. 69

Modifying formats.................................................................................. 70Using DQL......................................................................................... 70

Deleting formats..................................................................................... 71Using DQL......................................................................................... 71

Alias sets.................................................................................................... 71Creating an alias set ................................................................................ 72Modifying or deleting an alias set ............................................................ 72

Working with object types........................................................................... 72Creating a user-defined type ................................................................... 72Using DQL......................................................................................... 73

Modifying an object type......................................................................... 73Deleting properties ............................................................................. 74Using DQL......................................................................................... 74Changing the default permissions or default storage area.................. 74Adding a property.......................................................................... 74Deleting a property......................................................................... 75Lengthening a string property ......................................................... 75

4 EMC Documentum Content Server Version 6.5 Administration Guide

Table of Contents

Deleting a type ....................................................................................... 76Cleaning up repositories ............................................................................. 76Maintaining query performance .................................................................. 79Using Update Statistics ........................................................................... 79Setting the DM_GROUP_LIST_LIMIT environment variable ..................... 79

Configuring repository-level package name control ...................................... 80

Chapter 3 Servers .................................................................................................. 83Overview of servers .................................................................................... 84Server threads (Windows) ....................................................................... 84Parent servers and session servers (UNIX)................................................ 84Configuration......................................................................................... 84Multiple servers ..................................................................................... 85Servers, connection brokers, and clients ................................................... 85The agent exec process ............................................................................ 85ACS servers ........................................................................................... 86JBoss application server .......................................................................... 86

Internationalization .................................................................................... 87The dm_start_repositoryname script (UNIX)................................................... 88The server.ini file ........................................................................................ 88SERVER_STARTUP section ..................................................................... 89DOCBROKER_PROJECTION_TARGET sections ...................................... 93FUNCTION_SPECIFIC_STORAGE and TYPE_SPECIFIC_STORAGE sections ................................................................................. 94FUNCTION_EXTENT_SIZE and TYPE_EXTENT_SIZE sections ................ 95Keys set during installation ..................................................................... 96docbase_id ......................................................................................... 96docbase_name .................................................................................... 96database_owner ................................................................................. 96database_conn.................................................................................... 96Oracle database_conn value ........................................................... 96Sybase database_conn value ........................................................... 97MS SQLServer database_conn value ................................................ 97DB2 database_conn value................................................................ 97

database_name................................................................................... 97Sybase database_name value ........................................................... 97MS SQL Server database_name value............................................... 97

service ............................................................................................... 98host ................................................................................................... 98

Optional keys ......................................................................................... 98acl_update_threshold.......................................................................... 98check_user_interval ............................................................................ 99commit_read_operations..................................................................... 99data_store and index_store ................................................................. 99gethostbyaddr .................................................................................. 100history_sessions and history_cutoff ................................................... 100max_ftacl_cache_size ........................................................................ 100max_nqa_string................................................................................ 101max_sessions_heap_size ................................................................... 101owner_xpermit_default..................................................................... 101saveasnew_retain_source_group ....................................................... 101umask (UNIX only) .......................................................................... 101upd_last_chg_time_from_db ............................................................. 102use_group_address........................................................................... 102validate_database_user ..................................................................... 102

Default keys ......................................................................................... 103


Table of Contents

client_session_timeout ...................................................................... 103concurrent_sessions .......................................................................... 103database_refresh_interval ................................................................. 104distinct_query_results ...................................................................... 104enforce_four_digit_year .................................................................... 104ignore_client_domain (Windows only)............................................... 104mail_notification .............................................................................. 105max_storage_info_count ................................................................... 105method_server_enabled .................................................................... 105method_server_threads..................................................................... 105preserve_existing_types .................................................................... 106rdbms_connect_retry_timeout ........................................................... 106server_config_name.......................................................................... 106server_startup_sleep_time................................................................. 106start_index_agents............................................................................ 107ticket_multiplier ............................................................................... 107deferred_update_queue_size............................................................. 107update_access_date .......................................................................... 107user_auth_case ................................................................................. 108user_auth_target (Windows only) ...................................................... 108use_estimate_search ......................................................................... 108wait_for_connect_timeout ................................................................. 108

Moving the server executable (UNIX only) ................................................. 109Changing default operating system permits on directories andfiles (UNIX only) ...................................................................................... 109Changing a server’s configuration.............................................................. 109Modifying the server.ini file .................................................................. 110Modifying the server config object ......................................................... 110

Setting the secure connection mode ........................................................... 110Restarting a server .................................................................................... 111Starting additional servers......................................................................... 112Configuration requirements .................................................................. 112Creating a shut-down script (UNIX only) ............................................... 113

Communicating with connection brokers ................................................... 114Defining connection broker projection targets......................................... 114Definitions in the server config object................................................. 115Definitions in the server.ini file .......................................................... 116

Setting the checkpoint interval............................................................... 116Setting the keep entry interval ............................................................... 116Defining server proximity ..................................................................... 117

Specifying queue size for incoming connection requests(Windows only)........................................................................................ 118Shutting down a server ............................................................................. 118Using the dm_shutdown_repository script (UNIX only) ........................... 119Using the Documentum Content Server Manager (Windowsonly) .................................................................................................... 119Using the Windows user interface (Windows only)................................. 119Using the shutdown method ................................................................. 120

Stopping a session server .......................................................................... 120Server log files.......................................................................................... 121Server load balancing and failover ............................................................. 121Clearing the server common area............................................................... 122Adding additional servlets to the Java method server.................................. 123


Table of Contents

Configuring the workflow agent................................................................ 123Changing the number of worker sessions ............................................... 124Changing the sleep interval ................................................................... 124Disabling the workflow agent................................................................ 124Tracing the workflow agent................................................................... 124

Recovering automatic activity work items on Content Server failure ............ 125Managing the JBoss application server ....................................................... 125Location of binaries .............................................................................. 126Starting and stopping the JBoss application server .................................. 126

Chapter 4 Methods and Jobs ............................................................................... 129Introducing methods ................................................................................ 129Execution agents ...................................................................................... 130The dmbasic method server................................................................... 130Java method server ............................................................................... 131Content Server ..................................................................................... 131

Choosing the execution agent .................................................................... 132Performance considerations................................................................... 132Security considerations ......................................................................... 133

Tracing options for methods ...................................................................... 133Defining the java.ini file (UNIX only) ......................................................... 134java_library_path.................................................................................. 134java_version ......................................................................................... 134java_classpath ...................................................................................... 135java_alias_file ....................................................................................... 135java_disabled ....................................................................................... 135

Enabling the dmbasic method server ......................................................... 135Configuring the worker threads in the dmbasic method server .................... 136Implementing a method............................................................................ 136Creating a method to be executed by Content Server or thedmbasic method server ......................................................................... 136Limitation on argument length for Docbasic....................................... 137General guideline for the script or program........................................ 137Script or program return values for workflow methods ....................... 137Calling Java or DFC in a Docbasic script............................................. 137User account (UNIX only) ............................................................. 137dmbasic executables (UNIX only) .................................................. 138Locating the java.ini file (UNIX only) ............................................. 138Sample code ................................................................................. 138

Recording the output ........................................................................ 140Setting method object properties for Content Server execution............. 140Setting method object properties for dmbasic method serverexecution ......................................................................................... 140

Creating a method to be executed by the Java method server................... 141General guideline for the script or program........................................ 141Guidelines for a Java method to be deployed as a BOF module ............ 141Script or program return values for workflow methods ....................... 141Recording the output ........................................................................ 142Storing Java methods ........................................................................ 143Setting method object properties for Java method serverexecution ......................................................................................... 143

Creating a method object....................................................................... 143Using DQL....................................................................................... 144Defining success return codes and success status ................................ 144

Executing a method on demand ................................................................ 145


Table of Contents

Creating jobs and job sequences................................................................. 145Introducing jobs ................................................................................... 146Introducing job sequences ..................................................................... 146Repository implementation ............................................................... 147Job sequence execution ..................................................................... 147Determining success for invoked jobs ............................................ 148

The repository connection file............................................................ 148The agent exec process .......................................................................... 148Creating a job ....................................................................................... 149Using DQL to create a job.................................................................. 149

Creating a job sequence......................................................................... 150Scheduling jobs .................................................................................... 150Defining a job schedule ..................................................................... 151

Passing arguments................................................................................ 151The run_now property.......................................................................... 152

Managing jobs.......................................................................................... 153Activating or inactivating a job .............................................................. 153Disabling all jobs .................................................................................. 153Modifying agent exec behavior.............................................................. 154Setting the polling interval ................................................................ 154Setting the number of jobs in a polling cycle ....................................... 154Turning on tracing for the agent exec process ..................................... 155

Creating and maintaining a repository connection file for jobsequences............................................................................................. 155Specifying the server connect string ................................................... 155Commas and backslashes in the entries .............................................. 156The dcf_edit utility ........................................................................... 156

Recovering from a job sequence failure .................................................. 158Interpreting a job sequence status report ................................................ 158Executing dm_run_dependent_jobs independently................................. 159

Chapter 5 Managing Repository Sessions ........................................................... 161Terminology............................................................................................. 162The dfc.properties file ............................................................................... 162Key format ........................................................................................... 162Setting dfc.properties entries ................................................................. 163

Defining connection brokers for connection requests................................... 163Specifying connection brokers ............................................................... 163

Failover and load balancing....................................................................... 164Requesting a specific server connection...................................................... 165Requesting a server by name ................................................................. 165Requesting a server on a specific host .................................................... 165Requesting a server by name on a specific host ....................................... 165

Turning off trusted login ........................................................................... 166Defining the secure connection default for connection requests.................... 166Configuring the number of connection attempts and the retryinterval .................................................................................................... 167Specifying the maximum number of sessions ............................................. 167Limiting which clients can access a repository ............................................ 168Configuring privileged DFC use ................................................................ 168Creating client rights objects.................................................................. 168Configuring a repository to accept only authenticated DFCinstances .............................................................................................. 169Enabling privileged DFC....................................................................... 169


Table of Contents

Disabling privileged DFC...................................................................... 170Modifying the Java security policy ........................................................ 170Managing the keystore file .................................................................... 171Changing the location and name of the keystore file ........................... 171Changing the passwords used with keytool........................................ 171Configuring a shared keystore file ..................................................... 172

Configuring connection pooling ................................................................ 172Enabling connection pooling ................................................................. 172

Configuring login tickets........................................................................... 173Setting ticket validity period.................................................................. 173Setting the ticket cache size for Content Server ....................................... 173Configuring login tickets for backwards compatibility ............................ 173

Changing a session’s configuration ............................................................ 174Changing the assigned default operating system permissions(UNIX only) ............................................................................................. 175Defining short date formats....................................................................... 175Changing the client local area directory location ......................................... 176Setting disk space limits for the client local area ......................................... 176Removing content from client local areas ................................................... 176Manual clean up................................................................................... 177

Managing persistent client caches .............................................................. 177Enabling and disabling persistent client caching ..................................... 178For a repository ............................................................................... 178For client sessions ............................................................................. 178

Creating cache config objects ................................................................. 179Defining the cached data set .............................................................. 179Defining the server check interval ...................................................... 180Defining the client check interval ....................................................... 181

Manually forcing refreshes ................................................................... 181Flushing a persistent cache................................................................ 181Setting the client_pcaching_change property ...................................... 182

Automating cache config data validation ............................................... 182Overriding consistency checking rules ................................................... 183Defining the persistent cache write interval ............................................ 183Troubleshooting persistent caching ........................................................ 184

Chapter 6 Connection Brokers ............................................................................ 187An overview of connection brokers............................................................ 187How many connection brokers are there?............................................... 188What information does a connection broker have? .................................. 188How does a connection broker get information? ..................................... 188Locating connection brokers.................................................................. 189Connection broker configuration options ............................................... 189

Servers and connection brokers ................................................................. 189Clients and connection brokers.................................................................. 190Failover for connection brokers ................................................................. 191Load balancing for connection brokers....................................................... 191Configuring a connection broker ............................................................... 191Connection broker initialization file ....................................................... 192Invoking the initialization file ............................................................... 193Configuring shutdown security (UNIX only).......................................... 193Restricting server access........................................................................ 193Translating IP addresses........................................................................ 194


Table of Contents

Restarting a connection broker .................................................................. 195Windows platforms .............................................................................. 195UNIX platforms.................................................................................... 195

Starting additional connection brokers ....................................................... 196Shutting down a connection broker ........................................................... 197Windows platforms .............................................................................. 197UNIX platforms.................................................................................... 198Multiple connection brokers on UNIX.................................................... 199

Obtaining information from a connection broker ........................................ 199The getServerMap method .................................................................... 200The getDocbaseMap method ................................................................. 200

Obtaining information about connection brokers ........................................ 200Using the getDocbrokerMap method ..................................................... 201Querying the client config object............................................................ 201

Deleting server information....................................................................... 201

Chapter 7 Content Management .......................................................................... 203Storage area options ................................................................................. 204File store storage areas .......................................................................... 205Public and private file store areas ...................................................... 205Content encryption ........................................................................... 206Content compression ........................................................................ 206Content compression characterization............................................ 207

Content duplication checking and prevention..................................... 209How checking and prevention work .............................................. 209Supporting properties................................................................... 209content_hash_mode and content_dupl_pref ............................... 210r_content_hash ........................................................................ 210

Tracing duplication checking and prevention ................................. 211Digital shredding ............................................................................. 211

EMC Centera storage ............................................................................ 212Configuration options....................................................................... 212Default retention values ................................................................ 213Compression ................................................................................ 213Whether to link or embed the content in the C-clip ......................... 214The C-clip buffer size .................................................................... 214Write retries ................................................................................. 214Override of the Centera storage strategy configuration ................... 215Maximum number of socket connections used by theCentera SDK ................................................................................ 215Use of the memory map interface for writes to the storagearea ............................................................................................. 215

NetApp SnapLock storage .................................................................... 215Configuration options....................................................................... 216Default retention values ................................................................ 216Compression ................................................................................ 217

Blob store storage areas......................................................................... 217Turbo storage ....................................................................................... 218Distributed storage areas....................................................................... 218External storage areas ........................................................................... 219Use constraints ................................................................................. 219Types of external storage areas .......................................................... 219Plug-in objects for external storage .................................................... 220

Linked store storage areas ..................................................................... 221Summary of storage area configuration options .......................................... 222Content and full-text indexes..................................................................... 223


Table of Contents

How objects, contents, and storage are connected ....................................... 223Allocating content to storage areas ............................................................ 224Using content assignment policies ......................................................... 225What content assignment policies are................................................. 225Creating content assignment policies ................................................. 225Enforcement of assignment policies ................................................... 226Behavior on encountering a rule error ................................................ 227DFC assignment policy information cache.......................................... 227Architectural implementation of assignment policies .......................... 227Algorithm used by the DFC policy engine .......................................... 228Assignment policy administration ..................................................... 229

Using the default storage algorithm ....................................................... 229Primary content algorithm ................................................................ 229Rendition algorithm.......................................................................... 231

Content Retention..................................................................................... 231System-defined storage areas .................................................................... 232File paths and URLs for content files in storage........................................... 233Path specifications for content in file stores............................................. 233URL specifications for content files ........................................................ 234

Setting up storage..................................................................................... 235Distributed storage setup ...................................................................... 236Setting up blob storage ......................................................................... 236Using DQL to set up blob storage ...................................................... 236

Setting up file store storage areas........................................................... 237File extensions and the use_extensions property ................................. 237Setting the base URL......................................................................... 238Defining file store storage areas as public (Windows only) ................. 238Using DQL to set up file storage ........................................................ 238Linked store setup ............................................................................ 239Using DQL to set up linked storage ............................................... 240

Setting up external storage .................................................................... 242An example of importing documents stored on a CD-ROM ................. 242Using the Mount method ............................................................. 243

External URL storage setup ............................................................... 244Setting up external free storage ......................................................... 244Configuring for optimal performance on retrieval............................... 245

Setting up EMC Centera storage areas.................................................... 245Setup procedure ............................................................................... 246Defining storage area retention requirements ..................................... 247Defining the connection string .......................................................... 248Required privileges for connection strings...................................... 249Defining a connection string supporting EMC Centeraclusters ........................................................................................ 249Example of use ......................................................................... 250

Configuring embedded blob use........................................................ 251Setting the C-clip buffer size.............................................................. 252Configuring write attempts in EMC Centera storage areas .................. 253Overriding the Centera single-instancing configuration ...................... 253Resetting the maximum socket connections allowed ........................... 254Configuring use of a memory map for write operations ...................... 254Setting clocks and time zones for Centera hosts and ContentServer hosts...................................................................................... 255

Setting up NetApp SnapLock storage areas ............................................ 255Setup procedure ............................................................................... 256Enabling content compression ........................................................... 256Defining SnapLock storage area retention requirements ...................... 256

Setting up turbo storage ........................................................................ 257


Table of Contents

Providing automatic file extensions ........................................................... 258Moving content files ................................................................................. 259MIGRATE_CONTENT administration method....................................... 259Content migration policies ................................................................... 260Configurable arguments ................................................................... 261Generated log files............................................................................ 262

Records migration jobs.......................................................................... 262Auditing content movement.................................................................. 263

Maintenance operations for storage areas ................................................... 263Changing the state of a storage area ....................................................... 263Determining the state of a storage area................................................... 264Moving file store storage areas .............................................................. 264Enabling forced deletion in EMC Centera storage areas........................... 265Removing orphaned content objects and files ......................................... 266Using dmclean ................................................................................. 267Including content in retention type storage areas ............................ 268Running dmclean using an EXECUTE statement ............................ 268Running dmclean from the operating system prompt ..................... 269Executing the dmclean script......................................................... 269

Using dmfilescan.............................................................................. 270dmfilescan arguments .................................................................. 270Identifying the subdirectories of the scanned storage areas.............. 271Using the -no_index_creation argument ......................................... 272Using the -force_delete argument .................................................. 272Running dmfilescan using an EXECUTE statement......................... 273Running dmfilescan from the operating system prompt .................. 273The generated script ..................................................................... 273Executing the dmfilescan script ..................................................... 274

Replacing a full distributed storage component ...................................... 274Resolving a compromised file store key ................................................. 275

Administering content assignment policies ................................................ 275Logging policy use ............................................................................... 275Enabling and disabling assignment policies............................................ 276Turning off the policy engine................................................................. 276Configuring behavior on encountering a rule error ................................. 276Configuring the update interval for the policy information cache............. 277

Archiving and restoring documents........................................................... 277How the process works ......................................................................... 277The archive and restore methods ....................................................... 280The Archive tool ............................................................................... 280Archiving..................................................................................... 280Restoring ..................................................................................... 281

Moving dump files on and off line .................................................... 282Archiving content used in multiple documents....................................... 283Options for archiving ........................................................................... 283Scheduling archiving ........................................................................ 283Types of requests .............................................................................. 284The repository operator .................................................................... 284Moving the dump file in and out of the archive directory .................... 284

Choosing an archive directory .............................................................. 285Implementing archiving........................................................................ 285Starting the Archive tool ................................................................... 286

Restoring documents ............................................................................ 286Archiving restored documents .......................................................... 286Custom restoration ........................................................................... 287

Chapter 8 Users and Groups ............................................................................... 289


Table of Contents

User names .............................................................................................. 290User privilege levels ................................................................................. 291Basic user privileges ............................................................................. 291Extended user privileges ....................................................................... 293

Privileged groups ..................................................................................... 294Adding users ........................................................................................... 295Setting user properties .......................................................................... 296User privileges ................................................................................. 297Defining the default ACL .................................................................. 297Setting user_db_name....................................................................... 298Setting default_folder ....................................................................... 298Setting accessible folders ................................................................... 298Setting client capability ..................................................................... 299

Creating a new user with DQL .............................................................. 299Adding multiple users in a single operation ........................................... 299LDIF file contents ............................................................................. 300Setting up the file ............................................................................. 300Extended characters in the file ........................................................... 301

Granting and revoking user privileges ....................................................... 301Superuser privileges and the admingroup group .................................... 302Granting and revoking privileges using DQL ......................................... 302Granting and revoking privileges using DFC.......................................... 303

Modifying users ....................................................................................... 303Using DQL........................................................................................... 304

Renaming users........................................................................................ 304Deleting users .......................................................................................... 304Using DQL........................................................................................... 305

Deactivating, locking, and reactivating users .............................................. 305Deactivating or locking users................................................................. 305Reactivating users................................................................................. 306Using DQL to change a user’s login state................................................ 306

Adding groups ......................................................................................... 307Using DQL........................................................................................... 308

Modifying groups..................................................................................... 309Using DQL........................................................................................... 309

Deleting groups........................................................................................ 309Using DQL........................................................................................... 310

Changing the membership setting of a dynamic group................................ 310Querying groups ...................................................................................... 311Obtaining a list of members in a group................................................... 311Obtaining a list of groups with a count of the members in each................ 311

Chapter 9 Managing User Authentication ............................................................ 313Authentication options ............................................................................. 313Default mechanism............................................................................... 314Custom password checking program ..................................................... 314LDAP directory server .......................................................................... 314Authentication plug-in.......................................................................... 314In-line password................................................................................... 315

The assume user and change password programs....................................... 315Assume user ........................................................................................ 315Change Password ................................................................................. 316

Using the default authentication mechanism .............................................. 316


Table of Contents

UNIX platforms.................................................................................... 316Windows platforms .............................................................................. 317Authenticating in domains .................................................................... 317No-domain required mode................................................................ 318Domain-required mode..................................................................... 318Determining the repository’s authentication mode .............................. 318Converting to domain-required mode................................................ 319

Using a custom external password checking program ................................. 319Basic steps............................................................................................ 319Writing the program ............................................................................. 320

Using Windows domain authentication for UNIX users .............................. 320Modifying the dm_check_password program......................................... 321Setting auth_protocol........................................................................ 322Setting up the domain controller map ................................................ 322Setting the user_source property ....................................................... 323

Using an LDAP directory server ................................................................ 323Benefits ............................................................................................... 324Constraints .......................................................................................... 324Integrating an LDAP directory server with a repository .......................... 324Using multiple LDAP directory servers.................................................. 325User and group synchronization............................................................ 325Synchronization and federations ....................................................... 325dm_LDAPSynchronization job .......................................................... 325How the synchronization job determines which LDAPservers to use ................................................................................... 327Attributes set by the dm_LDAPSynchronization job ........................... 327On-demand user synchronization...................................................... 328

User authentication .............................................................................. 328Authentication and federations ......................................................... 328How Content Server determines which server to use forauthentication .................................................................................. 329LDAP authentication options ............................................................ 330Connection retry attempts ................................................................. 330Authentication failover ..................................................................... 330Failover for extra directory LDAP servers ...................................... 331Tracing failover ............................................................................ 332

Implementing an LDAP directory server ................................................ 332Defining the set-up values................................................................. 333Distinguished name and bind type ................................................ 334Search bases and filters ................................................................. 334The secure connection properties ................................................... 335

Mapping LDAP attributes to repository user or groupproperties ........................................................................................ 335Required mappings ...................................................................... 336Defining mapping rules ................................................................ 336Mapping guidelines...................................................................... 337Repository storage of mappings .................................................... 337Mapping examples ....................................................................... 338

Downloading certutil and the certificate authorities ............................ 340Installing the certificate database and CA certificates .......................... 340Activating the dm_LDAPSynchronization job .................................... 341Building and installing an LDAP-enabled passwordchecking program (UNIX only) ......................................................... 341Note on using Active Directory ......................................................... 342Note on using LDAP directory servers with multipleContent Servers ................................................................................ 342

Deleting an LDAP directory server from a repository.............................. 342Setting the retry_interval property for user authentication....................... 343


Table of Contents

How the environment variables are used ........................................... 343How to set the environment variables ................................................ 344

Enabling first-time synchronization rules ............................................... 344Binding LDAP users to a different directory server ................................. 344Listing certificates in the certificate database .......................................... 345Troubleshooting the synchronization job ................................................ 345

Using authentication plug-ins.................................................................... 346Plug-in scope ....................................................................................... 346Identifying a plug-in for use .................................................................. 347Defining a plug-in identifier .............................................................. 347

Using the RSA plug-in .......................................................................... 348Using the CA SiteMinder plug-in........................................................... 348Implementing a custom authentication plug-in....................................... 349Writing the authentication plug-in ..................................................... 350Internationalization ...................................................................... 350

Tracing authentication plug-in operations .............................................. 351Using an in-line password......................................................................... 351Trusted logins .......................................................................................... 351Unified logins .......................................................................................... 351Managing encrypted passwords ................................................................ 352Using encryptPassword ....................................................................... 353If you do not want to use encrypted passwords ...................................... 353Changing an encrypted password.......................................................... 354

Limiting authentication attempts ............................................................... 356

Chapter 10 Protecting Repository Objects ............................................................ 359Overview of repository security................................................................. 359ACLs ................................................................................................... 360Additional security options ................................................................... 360Application-level control of SysObjects ............................................. 361Dynamic groups ............................................................................... 361Folder security ................................................................................. 362User privileges ................................................................................. 362Table permits ................................................................................... 362

Turning repository security on and off ....................................................... 362Turning folder security on and off ............................................................. 363Changing folder security....................................................................... 364

Setting the default permission level for application-level controlof SysObjects ............................................................................................ 364Object-level permissions ........................................................................... 364Basic permissions ................................................................................ 365Note on the Relate permit level.......................................................... 366

Extended permissions .......................................................................... 366Viewing extended permissions ......................................................... 367

Managing ACLs ....................................................................................... 368The ACL object type ............................................................................. 369Access control entries........................................................................ 369AccessPermission and ExtendedPermission entries ......................... 370AccessRestriction and ExtendedRestriction entries.......................... 370AccessRestriction entries ........................................................... 370ExtendedRestriction entries....................................................... 371Storage in the ACL ................................................................... 371

ApplicationPermission entries ....................................................... 371ApplicationRestriction entries ....................................................... 372


Table of Contents

RequiredGroup entries ................................................................. 372RequiredGroupSet entries ............................................................. 373

How ACL entries are evaluated ............................................................. 374Evaluation for non-owners and non-superusers ................................. 374How access is evaluated for object owners and Superusers .................. 374Access evaluation for an object’s owner .......................................... 375Evaluating a Superuser’s permissions ............................................ 376

Resolving multiple entries for a user .................................................. 376Disabling ACL restrictive entries ........................................................... 377External and internal ACLs ................................................................... 378ACL names ...................................................................................... 379

System, public, and private ACLs .......................................................... 379Template ACLs..................................................................................... 379Creating ACLs ..................................................................................... 380How ACLs and objects are connected .................................................... 380The default ACLs ................................................................................. 381Creating default ACLs ...................................................................... 383Assigning a default ACL to an object ................................................. 383Identifying the default ACL for use ................................................... 383

Modifying an ACL................................................................................ 384Adding entries ................................................................................. 384Removing entries.............................................................................. 384

Destroying an ACL ............................................................................... 385Removing unreferenced external ACLs .............................................. 385Removing unreferenced internal ACLs .............................................. 385

Table permits ........................................................................................... 386Setting table permits ............................................................................. 386Table permits and object-level permissions ............................................. 387Table permits and dump and load operations ......................................... 387

Auditing .................................................................................................. 387What events are auditable ..................................................................... 388Audit trails........................................................................................... 388Auditing properties .............................................................................. 388If audit_old_values is T ..................................................................... 389If audit_old_values is F ..................................................................... 390

Default auditing .................................................................................. 391Turning off default auditing .............................................................. 392Modifying the default auditing.......................................................... 393

Auditing system events......................................................................... 393Auditing application events .................................................................. 393Signing audit trail entries ...................................................................... 394Conflicting registration resolution ......................................................... 395Stopping auditing................................................................................. 396Viewing audit trails .............................................................................. 396Querying and retrieving audit trail entries ............................................. 397Interpreting audit trails of DFC method, workflow, andlifecycle events ..................................................................................... 397Audit trail properties with a common purpose ................................... 397Properties available for varied purposes............................................. 397Use in audit trails for events generated by non-workflowor lifecycle methods ...................................................................... 398Use in lifecycle audit trails ............................................................ 404Use in workflow audit trails .......................................................... 405

Interpreting ACL and group audit trails................................................. 413Verifying signed audit trail entries ......................................................... 415Removing audit trail entries .................................................................. 416Auditing in a distributed environment................................................... 416

Implementing signature support ............................................................... 417


Table of Contents

Customizing electronic signatures ......................................................... 417Customizing the default functionality ................................................ 418Adding or removing properties on the page ................................... 420Changing the property delimiters .................................................. 421Configuring the appearance of the page ......................................... 422Defining separate templates for different document types ............... 423Configuring the number of allowed signatures andsignature positioning .................................................................... 424

Creating custom signature creation methods and associatedsignature page templates .................................................................. 425Creating custom signature-creation methods.................................. 425Creating custom signature page templates ..................................... 427

Tracing electronic signature operations .............................................. 427Supporting digital signatures ................................................................ 427Customizing simple signoffs ................................................................. 428Customizing the signature validation program ................................... 428Registering for notification ................................................................ 429Querying the audit trail for signoffs ................................................... 429

Managing the encryption keys................................................................... 429The AEK .............................................................................................. 430Sharing the AEK or passphrase ......................................................... 430The AEK and distributed sites ........................................................... 431Backing up the AEK.......................................................................... 431

Repository encryption keys ................................................................... 431Encryption utilities ............................................................................... 432Using dm_crypto_boot ......................................................................... 432Troubleshooting with dm_crypto_create ................................................ 433Changing a passphrase ......................................................................... 434

Managing the login ticket key.................................................................... 436Exporting and importing a login ticket key............................................. 436Resetting a login ticket key .................................................................... 436

Configuring a repository’s trusted repositories ........................................... 437Configuring login ticket use ...................................................................... 437Configuring the default login ticket timeout ........................................... 437Restricting a Superuser’s use of global tickets ......................................... 438Revoking tickets for a specific repository................................................ 438Troubleshooting a login ticket ............................................................... 438

Configuring application access control token use ........................................ 439Enabling AAC token use by a server ...................................................... 439Enabling machine-only AAC tokens .................................................. 439

Enabling token retrieval by the client library .......................................... 440Generating tokens for storage................................................................ 441Naming the output file...................................................................... 443

Storing tokens generated by dmtkgen .................................................... 443Troubleshooting an application access control token ................................... 444

Chapter 11 Administration Tools ........................................................................... 445Essential tool concepts .............................................................................. 446How tools are implemented .................................................................. 449Standard arguments ............................................................................. 449The QUEUEPERSON argument............................................................. 450The window interval............................................................................. 450Reports and trace log files ..................................................................... 451Reports ............................................................................................ 451Storage ........................................................................................ 451

Trace log files ................................................................................... 452


Table of Contents

Storage ........................................................................................ 452Email messages .................................................................................... 452

Activating and scheduling administration tools .......................................... 453Activation ............................................................................................ 453Defining job schedules .......................................................................... 453

Running administration jobs on demand.................................................... 454Archive ................................................................................................... 454Audit Management .................................................................................. 456Consistency Checker................................................................................. 459Running the job from a command line ................................................... 460

Content Replication .................................................................................. 465Content Warning ..................................................................................... 468Create Full-Text Events ............................................................................. 470Arguments........................................................................................... 471Report sample ...................................................................................... 474

Data Dictionary Publisher ......................................................................... 475Database Space Warning .......................................................................... 476Dm_LDAPSynchronization ....................................................................... 479Executing dm_LDAPSynchronization manually ..................................... 482Explicitly specifying LDAP servers in -source_directory ......................... 482

Dmclean ................................................................................................. 482Dmfilescan .............................................................................................. 487File Report .............................................................................................. 493Group Rename ......................................................................................... 498Index Agent Startup ................................................................................. 498Log Purge ............................................................................................... 499Queue Management ................................................................................. 503Remove expired retention objects .............................................................. 506Rendition Manager .................................................................................. 509State of the Repository Report .................................................................. 514Swap Info ................................................................................................ 518ToolSetup................................................................................................. 519Update Statistics ...................................................................................... 519User Chg Home Db .................................................................................. 522User Rename............................................................................................ 523Version Management ............................................................................... 525Tool maintenance and troubleshooting....................................................... 529Changing the default settings ................................................................ 529Using DQL....................................................................................... 529

Using the tool trace log files .................................................................. 530Viewing the tool reports........................................................................ 530

Chapter 12 Logging and Tracing Facilities ............................................................ 531Introduction ............................................................................................. 531Content Server logging and tracing............................................................ 531Starting and stopping Content Server tracing operations ......................... 532Starting and stopping tracing from the startup command line ............. 532Using setServerTraceLevel ................................................................ 533


Table of Contents

Using SET_OPTIONS ....................................................................... 535Examples of server tracing .................................................................... 535Determining which tracing options are turned on ................................... 536

DFC logging............................................................................................. 536DFC tracing.............................................................................................. 536The logger and logging appender .......................................................... 537Enabling tracing ................................................................................... 537Configuring the logging appender ......................................................... 537Trace file names.................................................................................... 539Defining file creation mode ................................................................... 539Defining the timestamp format.............................................................. 540Defining a date format ...................................................................... 542

Defining what is traced ......................................................................... 542Configuring method tracing .............................................................. 542Defining maximum stack depth to trace ........................................ 542Specifying method entry and exit tracing ...................................... 543Identifying which packages, classes, and methods to trace .............. 543

Tracing users by name ...................................................................... 544Tracing threads by name ................................................................... 545Including the session ID.................................................................... 545Tracing RPC calls ............................................................................. 546Including stack trace for exceptions ................................................... 546Setting verbosity .............................................................................. 546

Directing categories to the trace file ....................................................... 547Interactions of tracing specifications ...................................................... 548Log file entry format ............................................................................. 548Trace file examples ............................................................................... 549

Appendix A Consistency Checks ............................................................................ 551User and group checks.............................................................................. 552ACL checks .............................................................................................. 553SysObject checks ...................................................................................... 554Folder and cabinet checks ......................................................................... 555Document checks ..................................................................................... 556Content object checks................................................................................ 557Workflow checks ...................................................................................... 557Object type checks .................................................................................... 558Data dictionary checks .............................................................................. 559Lifecycle checks ........................................................................................ 560Object type index checks ........................................................................... 561Method object consistency checks .............................................................. 561

Appendix B IDQL and IAPI ...................................................................................... 563Using IDQL.............................................................................................. 563Starting IDQL....................................................................................... 563The IDQL commands............................................................................ 566Entering queries ................................................................................... 567Clearing the buffer................................................................................ 567Entering comments............................................................................... 567Stopping IDQL ..................................................................................... 568

Using IAPI ............................................................................................... 568Starting IAPI ........................................................................................ 568IAPI commands.................................................................................... 571


Table of Contents

Entering method calls ........................................................................... 572Entering comments............................................................................... 573Quitting an IAPI session ....................................................................... 573

Appendix C Archiving scripts ................................................................................. 575The dql Script........................................................................................... 575The dm_archive_start script ...................................................................... 576The post_archive script ............................................................................. 577The pre_restore script ............................................................................... 581The post_restore script .............................................................................. 585

Appendix D High-Availability Support Scripts ........................................................ 589Monitoring scripts .................................................................................... 589Processes not requiring a script ................................................................. 591

Appendix E Populating and Publishing the Data Dictionary ................................... 593Populating the data dictionary................................................................... 593Data dictionary population script .............................................................. 594The initialization file ............................................................................. 594The data files........................................................................................ 595File structure .................................................................................... 595Summary of settable data dictionary properties .................................. 597Setting foreign keys .......................................................................... 601Examples of data file entries .............................................................. 602

Executing the script .............................................................................. 605Populating a Japanese locale on a Korean host or a Koreanlocale on a Japanese host ....................................................................... 605Default files provided by EMC Documentum ......................................... 606Using DQL statements .......................................................................... 606

Publishing the data dictionary information ................................................ 606The data dictionary publisher job .......................................................... 607The publishDataDictionary method ....................................................... 607The PUBLISH key phrase ...................................................................... 608

Appendix F System Events .................................................................................... 609dm_default_set event................................................................................ 609DFC events .............................................................................................. 610Workflow events ...................................................................................... 615Lifecycle events ........................................................................................ 618Events sent to the fulltext user ................................................................... 619

Appendix G Plug-in Library Functions for External Stores .................................... 621General recommendations ........................................................................ 621dm_close_all ............................................................................................ 622dm_close_content ..................................................................................... 622dm_deinit_content.................................................................................... 622dm_init_content ....................................................................................... 623dm_open_content ..................................................................................... 623dm_plugin_version................................................................................... 625dm_read_content...................................................................................... 625


Table of Contents

List of Figures

Figure 1. Small file compression percentages................................................................ 207Figure 2. Medium file compression percentages ........................................................... 208Figure 3. Large file compression percentages................................................................ 208Figure 4. Relationship of content assignment policies and object types .......................... 228Figure 5. Relationship between a file store object and a location..................................... 237Figure 6. The objects that define a linked store storage area .......................................... 240Figure 7. Content Server and EMC Centera cluster configuration in

single-repository distributed environment ................................................. 251Figure 8. The archive and restore process .................................................................... 279Figure 9. Default signature template ............................................................................ 418


Table of Contents

List of Tables

Table 1. Users created during repository configuration.................................................. 41Table 2. Groups created during repository configuration ............................................... 41Table 3. Permissions required to modify or delete cabinets and folders ........................... 44Table 4. Example of date handling behavior for combinations of property

values and release versions ......................................................................... 46Table 5. security_type property settings for location objects ........................................... 65Table 6. Interaction of properties that determine package control behavior ..................... 81Table 7. Locale-based configuration settings by host machine locale ............................... 87Table 8. Server.ini SERVER_STARTUP section keys....................................................... 89Table 9. Server.ini DOCBROKER_PROJECTION_TARGET keys .................................... 94Table 10. Server.ini FUNCTION_SPECIFIC_STORAGE keys ........................................... 94Table 11. Server.ini TYPE_SPECIFIC_STORAGE keys ..................................................... 95Table 12. Server.ini FUNCTION_EXTENT_SIZE keys ..................................................... 95Table 13. Server.ini TYPE_EXTENT_SIZE keys ............................................................... 95Table 14. Standard arguments passed to jobs ............................................................... 152Table 15. dcf_edit utility arguments ............................................................................. 156Table 16. Entries in a job sequence statusreport............................................................. 158Table 17. dm_run_dependent_jobs arguments .............................................................. 159Table 18. Summary of storage area configuration options .............................................. 222Table 19. Availability of retention functionality............................................................. 232Table 20. Examples of URLS and formats ..................................................................... 244Table 21. dmclean arguments ...................................................................................... 267Table 22. Arguments to the dmfilescan utility ............................................................... 270Table 23. Basic user privileges ..................................................................................... 291Table 24. Extended user privileges .............................................................................. 293Table 25. Privileged groups ......................................................................................... 294Table 26. Security properties for new users................................................................... 297Table 27. Default values for new users ......................................................................... 300Table 28. RSA plug-in modules.................................................................................... 348Table 29. CA SiteMinder plug-in files........................................................................... 349Table 30. Password files encrypted by default............................................................... 352Table 31. Repository security settings........................................................................... 362Table 32. Object-level permissions ............................................................................... 365Table 33. Permitted operations for object-level permissions ........................................... 365Table 34. Extended object-level permissions ................................................................. 366Table 35. The extended permission computed properties .............................................. 367Table 36. Table permits ............................................................................................... 386


Table of Contents

Table 37. Behaviors for audit properties combinations .................................................. 389Table 38. Events audited by the dm_default_event........................................................ 392Table 39. Usage of generic properties by API events...................................................... 398Table 40. Usage of generic properties by lifecycle events ............................................... 404Table 41. Usage of generic properties by workflow events ............................................. 405Table 42. System-defined document properties for the signature page template.............. 419Table 43. System-defined signature properties for the signature page template .............. 420Table 44. Parameters passed by addESignature to the signature-creation method ............ 425Table 45. Interaction of dm_crypto_change_passphrase arguments................................ 435Table 46. dmtkgen utility arguments............................................................................ 441Table 47. EMC Documentum tool suite ........................................................................ 446Table 48. Standard arguments passed to jobs ............................................................... 449Table 49. Archive arguments ....................................................................................... 454Table 50. Audit Management arguments ..................................................................... 457Table 51. Content Replication arguments ..................................................................... 467Table 52. Content Warning arguments ......................................................................... 469Table 53. Create Full-Text Events arguments................................................................. 471Table 54. Data Dictionary Publisher argument ............................................................. 475Table 55. Database Space Warning arguments .............................................................. 477Table 56. dm_LDAPSynchronization arguments ........................................................... 480Table 57. Dmclean arguments...................................................................................... 483Table 58. Dmfilescan arguments .................................................................................. 488Table 59. File Report arguments................................................................................... 495Table 60. Files deleted by the Log Purge tool ................................................................ 499Table 61. Log Purge arguments.................................................................................... 500Table 62. Queue Management arguments..................................................................... 504Table 63. Remove Expired Retention Objects arguments................................................ 507Table 64. Rendition Management arguments ................................................................ 509Table 65. State of the Repository arguments ................................................................. 514Table 66. Swap Info arguments .................................................................................... 518Table 67. Update Statistics arguments .......................................................................... 521Table 68. Version Management arguments ................................................................... 526Table 69. Server start-up trace options.......................................................................... 533Table 70. Trace level severity values ............................................................................. 534Table 71. Valid facilities for setServerTraceLevel ........................................................... 534Table 72. Logging appender configuration options ....................................................... 537Table 73. Valid values for dfc.tracing.file_creation_mode............................................... 540Table 74. Valid values for dfc.tracing.timing_style......................................................... 541Table 75. Log entry components .................................................................................. 548Table 76. Consistency checks for users and groups........................................................ 552Table 77. Consistency checks for ACLs ........................................................................ 553Table 78. Consistency checks for SysObjects ................................................................ 554Table 79. Consistency checks for folders and cabinets ................................................... 555


Table of Contents

Table 80. Consistency checks for documents................................................................. 556Table 81. Consistency checks for content objects ........................................................... 557Table 82. Consistency checks for workflows ................................................................ 557Table 83. Consistency checks for object types ............................................................... 558Table 84. Consistency checks for the data dictionary .................................................... 559Table 85. Consistency checks for lifecycles.................................................................... 560Table 86. Consistency checks for object type indexes .................................................... 561Table 87. Consistency checks for method objects ........................................................... 562Table 88. IDQL command line arguments..................................................................... 564Table 89. IDQL commands .......................................................................................... 566Table 90. IAPI command line arguments ...................................................................... 569Table 91. IAPI commands............................................................................................ 571Table 92. Monitoring Scripts........................................................................................ 589Table 93. Codepages for the data dictionary files provided with Content Server ............. 596Table 94. Settable data dictionary properties using population script ............................. 597Table 95. Events represented by the dm_default_set event............................................. 609Table 96. Events arising from DFC methods ................................................................. 610Table 97. Workflow events .......................................................................................... 615Table 98. LIfecycle events ........................................................................................... 618Table 99. dm_close_all arguments................................................................................ 622Table 100. dm_close_content arguments ........................................................................ 622Table 101. dm_init_content arguments........................................................................... 623Table 102. dm_open_content arguments ........................................................................ 623Table 103. dm_plugin_verson arguments ....................................................................... 625Table 104. dm_read_content arguments ......................................................................... 625


Preface

This manual contains information, instructions, and procedures for the normal system administrationtasks of a Documentum installation. It provides an overview of the system and guidelines tocustomize the configuration. It provides instructions for changing the configurations of repositories,Content Servers, clients, and sessions as well as instructions for routine maintenance. It also describesconnection brokers, full-text indexing administration, managing content storage area, and repositorysecurity.

Intended audienceThis manual is written for system and repository administrators. The systemadministrator is the person who generally installs and owns the Documentuminstallation. Repository administrators are the users who own and are responsiblefor one or more repositories. Readers should be familiar with the general principlesof client-server architecture and networking. In addition, they should know andunderstand the Windows and UNIX operating systems.

ConventionsThis manual uses the following conventions in the syntax descriptions and examples.

Syntax conventions

Convention Identifies

italics A variable for which you must provide a value.

[ ] square brackets An optional argument that may be included onlyonce.

{ } curly braces An optional argument that may be included multipletimes.


Preface

Revision historyThe following changes have been made to this document.

Revision history

Revision Description

July 2008 Initial publication of Documentum Content ServerAdministration Guide 6.5


Chapter 1Introduction

This chapter includes the following topics:• Essential concepts, page 27• Administration tasks, page 29• User privilege requirements for administration tasks, page 31• Administration interfaces, page 32• Documentum tool suite, page 33• Administration methods, page 33• The dm_error utility, page 34• Viewing connected users, page 34• Where to look for more information, page 34The Content Server administration guide contains information and procedures for administrationtasks that apply to individual repositories and nondistributed storage areas. Administration tasksassociated with distributed configurations are described in the Documentum Distributed ConfigurationGuide.

Essential conceptsAn EMC Documentum installation has many aspects that you can arrange to suit yourrequirements. For instance, you can choose how many repositories to create, how manyservers for each repository, where to put the content storage areas, whether to haveseparate tablespaces or segments for type indexes, and so forth. Most of these decisionscan also be modified later.

Keep your initial installation simple to ensure best results. After you are familiar withEMC Documentum, you can modify the installation if necessary.


Introduction

Installation components

In a general sense, a Documentum installation consists of one or more repositories, theservers that access the repositories, and the clients that access the repositories throughthe servers. However, from the viewpoint of a system administrator, the installation alsoincludes its supporting parts: the machines, the networking software, the file-sharingsoftware, the relational database, and so forth. The requirements for these parts—forexample, which machines, operating systems, and databases EMC Documentum can runon—are found in the Content Server Release Notes. This chapter provides some guidelinesto decide the type of configuration for your installation.

Conguration choices

You have a number of choices for your installation, which fall into these broad categories:• Overall system architecture

For example, before you install Documentum, you must decide if you want to putContent Server and the relational database management system (RDBMS) on thesame machine or different machines and where to locate the full-text indexingsoftware. You should also determine how many servers you want for any particularrepository. Repositories that are accessed more frequently or by users at differentgeographical sites generally have multiple servers. The Content Server InstallationGuide, Content Server Full-Text Indexing System Installation and Administration Guide,and Distributed Configuration Guide contain information on system architecture.Chapter 3, Servers and Chapter 2, Content Repositories contain information onconfiguring servers and repositories.

• Server configuration

Servers can vary widely in their configuration. When you start a Content Server, itsconfiguration is taken from parameters set in its server.ini file (an initialization file)and from the values in its server config object. For example, through the serverconfig object, you can control the number of concurrent sessions a server accepts,the server and client cache sizes, what user-defined object types the server cacheson startup, and which storage areas it can use. The server.ini file lets you define theserver’s proximity to connection brokers (and consequently, to clients). Chapter 3,Servers contains more details about your choices when configuring a server.

• Repository configuration

There are various configuration choices for a repository, including what types ofstorage areas will you use and how user connection attempts are handled. Chapter2, Content Repositories contains information on the choices available to you whenconfiguring a repository.


Introduction

• Client configuration

From the client side, there are many configuration choices. For example, youcan determine how a particular client shares files with the server, how to displaydates, and which connection broker to use. Chapter 5, Managing RepositorySessions contains information on client configuration.

If you choose to use the basic installation that is in place after you install Content Server,you only have to decide where to put the installation. If you modify the basic installation,then the number and scope of your decisions will depend on what modifications youwant to make.

Conguration objects

In each repository, there are a variety of objects that, taken together, define yourconfiguration. For example, the objects include:• Server config object• Docbase config object• Location objects• Mount point objects• Storage objects• Format objects• Method objectsAs you make choices about how to configure your installation and repositories, you willmodify these objects or add new ones to implement your decisions.

Administration tasksAfter Content Server is installed and running, typical system administration tasks for arepository or installation include:• Modifying the configuration of the server, connection broker, or client sessions

Chapter 2, Content Repositories, Chapter 3, Servers and Chapter 5, ManagingRepository Sessions contain information on these tasks. The Distributed ConfigurationGuide contains instructions on creating distributed configurations and federations.


Introduction

• Creating new repositories

Installation of the Content Server creates one repository, one server, and oneconnection broker. Your organization may want additional repositories. Instructionsfor creating new repositories are found in the Content Server Installation Guide, withsome guidelines also in Chapter 2, Content Repositories.

• Maintaining content repositories

Organizations grow and change continuously. This is reflected in changingrepository requirements. Repository maintenance tasks keep repositoriessynchronized with business needs by adding objects as needed and removingunwanted or unneeded objects. These tasks include:

— Creating new object types, new format objects, and new alias set objects.

These objects typically support repository users and applications that access therepository. Chapter 2, Content Repositories describes how to create these objects.

— Creating new method objects, new jobs, and new configuration objects suchas locations and mount point objects.

Method objects and jobs typically support system administrators by allowingadministrators to automate some administration tasks. They can also be usedto automate some business processes, such as report generation. Location andmount point objects support the repository architecture. Chapter 4, Methodsand Jobs describes how to create method and job objects. Chapter 2, ContentRepositories describes how to create location and mount point objects.

— Cleaning up repositories

Some user operations leave orphaned objects in the repository. For example,when users delete documents, the associated content files are orphaned inthe storage areas. Cleaning up orphaned objects is an important systemadministration task. Chapter 2, Content Repositories describes how to cleanup a repository.

— Maintaining repository consistency

The Consistency Checker administration tool provides important informationon repository consistency. Appendix A, Consistency Checks describes eachcheck run by the tool.

• Configuring, starting, and shutting down servers

The Content Server Installation Guide and Chapter 3, Servers contain procedures forserver administration.

• Changing session configurations

Chapter 5, Managing Repository Sessions includes procedures for changing sessionconfigurations and managing local areas.


Introduction

• Maintaining connection brokers

The connection broker is an EMC | Documentum name server. It providesContent Server connection information to client sessions. Chapter 6, ConnectionBrokers describes how to configure the connection broker behavior and how to stopand start a connection broker.

• Managing content storage areas and content files

The basic installation has one storage area for content files. Typically, you will addmore storage areas immediately after installation or later, as the repository grows.Chapter 7, Content Management describes the types of content storage areas you canuse and includes procedures for setting up and maintaining them. The chapter alsoincludes instructions for archiving and restoring content files.

• Administering full-text indexes

The Content Server Full-Text Indexing System Installation and Administration Guidedescribes full-text indexes and includes procedures for setting up and maintainingfull-text indexes.

• Managing users and groups

Chapter 8, Users and Groups contains procedures for adding, changing, andremoving local users and groups.

• Managing security

Documentum security features include object-level permissions (implemented asACLs), table permits, user privilege levels, and auditing and tracing capabilities.

Chapter 10, Protecting Repository Objects describes the Documentumimplementation of object-level permissions and table permits. The chapter alsodescribes the auditing capabilities. It includes procedures for creating andmaintaining ACLs (which enforce object-level permissions), setting table permits,and for turning auditing on and off.

User authentication is described in Chapter 9, Managing User Authentication.

User privileges are described in Chapter 8, Users and Groups.

Tracing capabilities are described in Chapter 12, Logging and Tracing Facilities.

User privilege requirements for administrationtasks

Most of the system administration tasks in this manual require at least the Sysadmin userprivilege. Some tasks, such as deleting audit trail entries, require one of the extendedprivileges. The instructions for a particular procedure inform you what level of userprivileges is required.


Introduction

When you connect to a repository to perform an administrative task, log in as a user withat least the minimum required level of user privileges needed for the procedure.

Administration interfacesThe primary user interface for administration tasks is Documentum Administrator.Documentum Administrator is a web-based interface that lets you monitor, administer,configure, and maintain Documentum repositories throughout the enterprise (both localand federated) from any system running a web browser. Documentum Administratoralso provides easy access to the Documentum System Administration Tool suite and theadministration methods.

Documentum Administrator is sold separately. It is not included with Content Server.For instructions on starting Documentum Administrator and connecting to a repository,refer to Starting Documentum Administrator, page 32. (Instructions for installingDocumentum Administrator are found in the Documentum Administrator DeploymentGuide.) Documentum Administrator includes an extensive online Help system.

You can also use Document Query Language (DQL) directly to perform someadministrative tasks. To use DQL, you can enter DQL statements through DocumentumAdministrator or use the IDQL utility. Appendix B, IDQL and IAPI, describes how touse the utility.

Starting Documentum Administrator

You can start Documentum Administrator from Internet Explorer or NetscapeCommunicator. Use the URL provided by your system or repository administrator toaccess Documentum Administrator.

Documentum Administrator allows you to change the connection broker in use. You canalso identify a particular server as the target of your repository connection request. Ifyou need help to identify a different connection broker or to connect to a repository, referto Documentum Administrator online help.

Using the Content Server Manager on Windows

The Content Server Manager is an administration tool added during server installation.You can use the Content Server Manager to:• Change your server configuration by editing the server.ini file


Introduction

• Uninstall a repository• Start the IDQL utility• Change how you start a connection broker• Display connection broker log files• Invoke the Setup program to install or uninstall additional server components• Invoke the Microsoft Performance Monitor tool• Create a configuration summary report for troubleshooting

Using DQL for administrative tasks

You can use DQL statements to perform some administration tasks. There are two waysto issue DQL statements:• Documentum Administrator• IDQL utilityTo use DocumentumAdministrator, refer to the DocumentumAdministrator online help.

The IDQL utility is a command-line interface that lets you connect to a repository andexecute DQL statements. The utility is provided with Content Server. Using IDQL, page563 provides information about using IDQL.

Documentum tool suiteDocumentum provides a suite of administration tools with Content Server. These toolsautomate such tasks as:• Removing unwanted renditions, content files, and log files• Monitoring space in the storage areas and database tables• Managing full-text indexesThe tools are implemented as jobs and most are installed in the inactive state. For adescription of each tool, refer to Chapter 11, Administration Tools. The chapter alsocontains instructions for activating the tools, resetting their schedules, and viewingtheir reports and log files.

Administration methodsDocumentum provides a variety of administration methods that you can use to performmany administration tasks, such as managing full-text indexes, managing content files,


Introduction

or monitoring sessions. You can run the methods from Documentum Administrator orusing a DFC apply( ) method or the DQL EXECUTE statement. For complete informationabout these methods, refer to the Content Server DQL Reference Manual.

The dm_error utilityThe dm_error utility is a utility that returns information about a specified Content Servererror. The utility is run from the operating system prompt. The command line is:dm_error <error_code>

The error_code is the abbreviated text that describes the error. For example,DM_SERVER_E_NO_MTHDSVR_BINARY.

The output of the utility lists the error and a description of its cause and actions to take.Here is a sample of the output:[DM_SERVER_E_NO_MTHDSVR_BINARY]"%s: Method server binary is not accessible."

CAUSE: The method server binary "mthdsvr" is not under$DM_HOME/bin or it does not have the proper permission.

ACTION: Make sure method server binary "mthdsvr" is under$DM_HOME/bin and set execution permission for it.

Viewing connected usersBefore you begin a system administration procedure, you may want to determinewhether any users are currently logged in to the system. Use the Sessions page inDocumentum Administrator to obtain this information. For further instructions, refer tothe Documentum Administrator online help.

For more information about clients and sessions, refer to Chapter 5, ManagingRepository Sessions.

Where to look for more informationThis guide provides instructions for tasks that affect a single repository. Information andinstructions for tasks that affect federations or distributed storage areas are found in theDocumentum Distributed Configuration Guide.

For information about installing the Content Server, refer to Content Server InstallationGuide.


Introduction

For detailed information about Documentum objects and DQL statements, refer to thereference manuals:• Documentum System Object Reference• Content Server DQL ReferenceContent Server Fundamentals describes the basic features of the Content Server and therepository. It explains the data model, session and transaction management, contentmanagement, and the behavior and implementation of features such as workflows andlifecycles.

The Content Server Full-Text Indexing System Installation and Administration Guide describesthe possible full-text configurations and how to install and maintain them.


Introduction


Chapter 2Content Repositories

This chapter contains the following information about repositories:• Essential concepts, page 37• Adding additional repositories, page 39• Managing cabinets and folders, page 42• Setting the dd_locales property, page 44• Manipulating type indexes, page 44• Alternate locations for object-type tables on Oracle and DB2, page 45• Configuring storage and handling of date values, page 45• Enabling a repository as a global registry, page 46• Dumping and loading a repository, page 48• Creating location and mount point objects, page 64• Format objects, page 67• Alias sets, page 71• Working with object types, page 72• Cleaning up repositories, page 76• Maintaining query performance, page 79• Configuring repository-level package name control, page 80.

Essential conceptsRepositories are comprised of object type tables, type indexes, and content files. The typetables and type indexes are tables in an underlying relational database. The content filesare typically stored in directories on disks in your installation. However, content filescan also be stored in the database, in a retention storage system such as EMC Centera orNetApp SnapLock, or on external storage devices.


Content Repositories

A full-text index is associated with a particular repository or, in a consolidateddeployment, with all repositories indexed by a particular index server installation.Full-text indexes enable rapid searching for designated values or strings in contentfiles and property values.

Users access repositories through Content Servers. The Content Servers receive queriesfrom clients in the form of DFC methods or DQL statements and make the actual callto the underlying RDBMS or the file directories. Every repository must have at leastone active Content Server. If a repository does not have an active server, users cannotaccess that repository.

Repository and server connections

Information that you provide about the repository when you create it is used to build aserver startup file. The startup file is executed whenever you start the repository’s server.The information in that file binds the Content Server to the repository.

The default installation starts one Content Server for a repository. However, you canstart multiple servers for the same repository. Refer to Starting additional servers, page112 for instructions. If a repository is very active, serving many users, or its users arewidely spread geographically, multiple servers can provide load balancing and enhanceperformance. Multiple servers also enables you to dedicate one server to a particularapplication or group of users and have other servers available to everyone.

Repository conguration

A repository’s operating configuration is defined by its docbase config object, whichresides in the repository. This object is created when you create the repository. Theproperties in the docbase config object record information such as:• Name of the underlying RDBMS• Security level for the repository• Whether folder security is turned on• Macintosh access protocolThe repository’s structural configuration, that is, where its content and index files are,what file formats it recognizes, and so forth, is defined in the repository itself by objects.The following objects define the repository structurally:• Location objects

A location object defines the location of a particular file or directory for the ContentServer.



• Storage objects

Storage objects define content storage areas. There are several types of storageareas, each represented by a different storage object type. A storage area object ispaired with a location object to define content storage areas in a repository. Formore information about the types of storage areas, refer to Chapter 7, ContentManagement.

• Mount point objects

If a number of locations reside under one upper-level directory, and all the locationsmust be visible to the clients, use a mount point object to define the location of theupper-level directory. The use of mount point objects alleviates the need to mountmultiple directories on clients.

• Format objects

Format objects define file formats. A server recognizes a file format only if the formathas a format object in the repository.

• Fulltext index objects

Fulltext index objects represent full-text indexes. If you index some or all of thecontent files in your repository, you have a fulltext index object in the repository.The basic installation is configured for full-text indexing. For information aboutmanaging full-text indexes and directories, refer to the Content Server FulltextIndexing System Installation and Administration Guide.

You must have Sysadmin or Superuser user privileges to change a repository’s docbaseconfig object.

Adding additional repositoriesThis procedure describes the basic steps for adding another repository to an existinginstallation. If you are setting up the initial Documentum Content Server installation,refer to the Content Server Installation Guide for instructions.

When you create a new repository, the installation wizard:• Asks several questions about the new repository, such as its ID and name, and uses

the answers to build the Content Server startup files.

Note: A repository name must consist of ASCII characters and be less than or equalto 32 characters in length. The name docu is reserved by Documentum.

• Creates the database account for the new repository if you wish.

Note: For DB2, a database account is not needed. However, you must grant anexisting account certain authorities or privileges to access the database. For example,the installation owner must have DBADM authority. Refer to the installation manualfor more information.



• Runs the Content Server startup files to start Content Server.• Executes the headstart.ebs file to populate your repository with a basic set of

configuration-related objects, such as the basic location objects, format objects, andmethod objects.

You must be logged in as the installation owner to create a new repository. However,you can designate any user as the repository owner.

Many sites place the storage areas, the share directory, or both on disks that are separatefrom the disk that holds the Documentum installation executables (the product and dbadirectories). If your site has done this, you must edit entries in headstart.ebs script topoint to the correct directories before executing the script.

Adding a repository

This procedure outlines the basic steps to add a repository to an existing Documentuminstallation.

To create an additional repository:1. Read the information in Content Server Installation Guide concerning repository

configuration and the prerequisite decisions and actions.

2. Log in as the installation owner.

3. Change to the $DOCUMENTUM/product/version/install directory.

4. Follow the procedure for Configuring the Repository in the Content Server InstallationGuide.

Conguring the new repository for use with MediaTransformation Services

If your site has Documentum Media Transformation Services installed and you intendto store rich media documents in the new repository, install (or reinstall) MediaTransformation Services on the Content Server host machine.

Each repository must have a dedicated Media Server, and the base_url property for therich media storage areas in the repository must be properly set. A Thumbnail Server canservice multiple repositories. However, if you rerun the Thumbnail Server installationprocedure, it automatically sets the base_url property correctly for the new repository.

Note: The new repository must be running before you rerun the Thumbnail Serverinstall.



Refer toMedia Transformation Services Installation Guide for instructions on installingMedia Servers and Thumbnail Servers.

Contents of new repositories

A new repository is not actually empty. The installation program and the scripts thatrun during repository configuration automatically create a variety of objects, such ascabinets, configuration objects, users, and groups.

Table 1, page 41, lists the users that were created during repository configuration and theprivileges each has by default.

Table 1. Users created during repository conguration

User User privileges Extended user privileges

repository_owner 16 (Superuser) None

installation_owner 16 (Superuser) None

global registry user

A default user nameis suggested duringinstallation, but a differentname may be chosen.

0 (None) None

dm_bpm_inbound_user 0 (None) None

dm_autorender_win31 8 (Sysadmin) None

dm_autorender_mac 8 (Sysadmin) None

dm_mediaserver 8 (Sysadmin) None

dm_fulltext_index_user 16 (Superuser) None

Configuring a repository also creates a number of groups. Table 2, page 41, lists thebasic groups. In addition, a set of privileged groups are also created. For a listing of theprivileged groups, refer to Chapter 8, Users and Groups.

Table 2. Groups created during repository conguration

Group Members

admingroup repository ownerinstallation owner



Group Members

docu repository ownerinstallation ownerdm_autorender_win32dm_autorender_macdm_mediaserver

queue_admin None

This is a role group supporting the queue managementfeature of Documentum Process Builder.

queue_manager queue_admin group


queue_processor queue_manager group


process_report_admin queue_admin


Managing cabinets and foldersThe objects in a repository are organized by using cabinets and folders. Cabinets providethe highest level of organization. Every document and folder must reside in a cabinet.There is no limit to the number of cabinets in a repository or the number of objects ina cabinet.

Folders can be placed inside cabinets or other folders. Documents and other objectsare stored inside folders or directly inside cabinets. Placing related documents withinfolders and related folders within cabinets helps organize them so that you or someoneelse can find them later. For example, you can easily organize a repository’s cabinets orfolders by project or department.

Users place objects into folders and cabinets by using one of the Documentumclients designed for that purpose or a customized client interface. DocumentumAdministrator also allows you to link objects to a folder or cabinet. Applications use anIDfSysObject.link method to perform these operations.



Public and private cabinets

A cabinet’s is_private property indicates whether the cabinet is private or public. If set toTRUE, the cabinet is private. If set to FALSE, the cabinet is public. The default is FALSE.This property is not used by Content Server for security or any other use. It is intendedfor use by client applications. For example, Documentum Desktop Client keeps privatecabinets invisible to all but their owners.

Home cabinets

Typically, every user has a home cabinet. The home cabinet is where users storepersonal documents, folders, and Smart Lists. A user may have a home cabinet in everyrepository. If your repositories are federated, global users typically have only one homecabinet, which is found in their home repository. Home cabinets and home repositoriesare defined in the user object.

Creating folders and cabinets

Any user can create folders. Creating cabinets requires the Sysadmin, Superuser, orCreate Cabinet privileges.

You can create folders and cabinets by using Documentum Administrator or anotherDocumentum client, such as Webtop. (If you need instructions, refer to the online helpsystem for the client you use.) You can also use DQL.

To create a cabinet or folder by using DQL, use the CREATE...OBJECT method.

For a complete list of cabinet and folder properties, refer to the Documentum SystemObject Reference Manual.

Changing and deleting folders and cabinets

You can modify or delete cabinets and folders by using Documentum Administrator,another Documentum client (such as Webtop), or DQL. Using DocumentumAdministrator allows you to:• View and edit cabinet and folder properties• Add or remove links to a folder• Delete a cabinet or folderIf you use DQL, use an UPDATE...OBJECT or DELETE...OBJECT statement.



Table 3. Permissions required to modify or delete cabinets and folders

Action Permission required

Changing a cabinet orfolder’s properties

Minimum of Write permission on the object.

Adding or removinglinks for a folder

Minimum of Write permission on the folder.

Deleting a folder Delete permission for the folder.

Deleting a cabinet Superuser, Sysadmin, or Create Cabinet privilege.

Setting the dd_locales propertyThe dd_locales property in the docbase config object records the data dictionary localesrecognized by the Content Server. This property is set automatically when you add alocale to the data dictionary using the dd_populate.ebs script. Refer to Populating thedata dictionary, page 593 for information about the script.

You must have Superuser privileges to set this property manually, and you mustreinitialize the server after setting the property to make the change visible to the server.

The locale value is stored in the property in its preferred format. For example, if you setthe value to fr_ca for French Canadian, the value is stored as fr_CA.

Manipulating type indexesIndexes on the object type tables in the RDBMS enhance the performance of repositoryqueries. When a repository is configured, the system creates a variety of objecttype indexes. You can also create type indexes for your special needs by using theMAKE_INDEX function.

By default, type tables and indexes are stored in the same tablespace or segment.However, you can create a repository with separate tablespaces or segments for eachor you can move the indexes later, using the MOVE_INDEX function. Indexes that youcreate can be placed in any directory. The Content Server Installation Guide providesinstructions to create a repository with separate tablespaces or segments.

To remove a user-defined index, use the DROP_INDEX administration method. It isstrongly recommended that you do not remove any of the system-defined indexes.

The MAKE_INDEX, MOVE_INDEX, and DROP_INDEX administration methods aredescribed in detail in the Content Server DQL Reference Manual. Each can be executed



through Documentum Administrator, an apply method, or the DQL EXECUTEstatement.

Alternate locations for object-type tables onOracle and DB2

If you use Oracle or DB2, to improve performance and increase the throughput of thesystem, you can control where repository information is stored. For example, you canstore frequently used data on disks different than those used for less-frequently useddata. Defining database parameters to store data in different tablespaces also partitionsdata into smaller, more manageable pieces.

When a repository is created, the system automatically creates object-type tables andindexes in the underlying RDBMS. (The object-type tables and indexes are describedin Content Server Fundamentals.)

By default, Content Server creates all object-type tables and indexes in the sametablespace. The size and number of the extents allotted for each table are determinedby default configuration parameters. You can edit the server.ini file to change thedefault database configuration parameters when the repository is created, before youstart the server.

For complete instructions, refer to the Content Server Installation Guide.

Conguring storage and handling of datevalues

By default, date values are stored as follows:• As UTC (Coordinated Universal Time) time in new repositories (Documentum 6

and later).• As the Content Server’s local time in repositories that are upgraded from before

version 6.

The r_normal_tz property in the docbase config object controls how Content Server storesdates in the repository. If set to 0, all dates are stored in UTC time. If set to an offset value,dates are normalized using the offset value before being stored in the repository. If set toan offset value, the property must be set to a time zone offset from UTC time, expressedas seconds. For example, if the offset represents the Pacific Standard Time zone, theoffset value is -8*60*60, or -28800 seconds. When the property is set to an offset value,Content Server stores all date values based on the time identified by the time zone offset.



For example, suppose a client application in the Pacific Standard Time zone sends thedate 10/14/2006 1:00:00 p.m. to a Content Server in the Eastern Standard time zone. Table4, page 46, summarizes how Content Server handles the date on reception depending onwhether the client is a Version 6 client or an earlier client.

Table 4. Example of date handling behavior for combinations of property values and releaseversions

Version 6 (or later) Content Server in Eastern Standard Time zonereceives 10/14/2006 1:00:00 p.m. from:

Property settings Version 6 (or later) client inPacific Standard time zone

Verson 5.3 or earlier client inPacific Standard time zone

r_normal_tz= 0 Content Server converts thereceived date (10/14/2006 1p.m.) into server local time,which is 10/14/2006 4 p.m.Then, it converts that serverlocal time into UTC time(10/14/2006 9 p.m.) and savesthat into the repository.

Because the client applicationis earlier than version 6,Content Server assumes that thereceived date (10/14/2006 1 p.m.)represents server local time.

Content Server converts10/14/2006 1 p.m. to UTCtime (10/14/2006 6 p.m.) andsaves it into the repository.

r_normal_tz =-18000 (-5*60*60)

Content Server converts thereceived date (10/14/2006 1p.m.) into server local time,which is 10/14/2006 4 p.m.

Content Server saves 10/14/20064 p.m. in the repository becausethe server local time is the timezone identified by the offset.

Because the client applicationis earlier than version 6,Content Server assumes that thereceived date (10/14/2006 1 p.m.)represents server local time.

Content Server saves 10/14/20061 p.m. in the repository becausethe server local time is the timezone identified by the offset.

In a new Documentum 6 or later repository, r_normal_tz is set to 0. In a repositoryupgraded from a release earlier than version 6, r_normal_tz is set to the offset thatrepresents Content Server local time and cannot be changed.

Enabling a repository as a global registryTo enable a repository as a global registry after configuration, you must activate thedm_bof_registry user.



To enable a repository as a global registry:1. Access Documentum Administrator in a browser and connect to the repository.

2. Navigate to Administration > User Management > Users.

3. Locate the user named dm_bof_registry and select View > Properties > Info to accessthe User Properties - Info page.

4. Verify that the username attribute is set to dm_bof_registry.The value dm_bof_registry is required.

5. Optionally, change the user login name to a new value.

6. Change the user’s password.

7. Set the dm_bof_registry user’s status to Active.

8. Click OK to save the user.

9. During DFC installation on client machines, such as the Webtop or DocumentumAdministrator hosts, provide the user login name and password.This updates the dfc.properties file and enables that DFC installation to contactthe global registry as required.

10. To manually modify the dfc.properties file to designate a global registry repositoryand user credentials:

a. On the DFC host, navigate to $DOCUMENTUM/config (UNIX or Linux) or%DOCUMENTUM%\config (Windows).

b. From a command prompt, execute the following command to generate theencrypted form of the global registry user’s password:java -cp dfc.jar com.documentum.fc.tools.RegistryPasswordUtilspassword_of_userwhere password_of_user is the global registry user’s clear-text password. In stepd, enter the encrypted form of this password in the dfc.properties file.

c. Open the dfc.properties file in a text editor.

d. Modify the following attributes:dfc.globalregistry.repository=global_registry_repository_namedfc.globalregistry.username=user_login_namedfc.globalregistry.password=encryped_password_of_userwhere encryped_password_of_user is the encrypted password you generated instep b.

e. Save the dfc.properties file.



Dumping and loading a repositoryYou must have Superuser privileges to perform a dump or load operation. You usedump and load operations to:• Move a repository from one location to another.• Duplicate a repository.

Use dump and load operations if the duplicated repository must have a name orrepository ID different from the source repository. If the duplicated repository isfor testing purposes and can have the same name and ID as the source repository,you can use the instructions for creating a repository copy in the Content ServerInstallation Guide.

Note: A repository copied using the procedure in the Content Server InstallationGuide cannot be moved into a server installation that already contains repositoriesbecause the aek.key file used by the new copy is not identical to the aek.key file usedin the target server installation.

• Duplicate or move some portion of a repository.A dump operation creates a binary file of objects dumped from a repository. If a dumpedobject has associated content files, the content files are either referenced by full path orincluded directly in the dump file. The load operation loads the objects and content filesinto another repository.

Dump and load operations are not supported in repositories where Web Publisher isinstalled.

Code page compatibility issues

Dump files are created by using the session code page. For example, if the session inwhich the dump file was created was using UTF-8, the dump file is a UTF-8 dump file.The repository into which you load a dump file must use the same code page as thatin use when the dump file was created.

The dump file header does not indicate the session code page in which the dump filewas created. If you do not know the session code page in use when a dump file wascreated, do not load the dump file.

Supporting object types

Dump and load operations are supported by four object types:



• Dump Record (dm_dump_record)

A dump record object contains information about a specific dump execution. It hasa property that contains the name of the file with the dumped information andproperties whose values tell Content Server which objects to copy into the specifiedfile.

• Dump Object Record (dmi_dump_object_record)

A dump object record object contains information about one specific object that iscopied out to the dump file. Dump object record objects are used internally.

• Load Record (dm_load_record)

A load record object contains information about a specific load operation. Itsproperties are used by Content Server to manage the loading process. It also has twoproperties that contain the starting and ending times of the load operation.

• Load Object Record (dmi_load_object_record)

A load object record object contains information about one specific object that isloaded from the dump file into a repository. Load object record objects are usedinternally.

For information about the properties of these object types, refer to the DocumentumSystem Object Reference Manual.

For information about setting up and using the dump operation, refer to Dumping arepository, page 50.

For information about setting up and using the load operations, refer to Loading arepository, page 59.

For information about moving the dump file, refer to Moving the dump file, page 59.

For information about trace messages related to dump and load procedures, refer toGenerating dump and load trace messages, page 64.

Execution methods

To perform dump and load operations manually, you can use either IAPI, Docbasicscripts, or DFC. The DFC interfaces are IDfDumpRecord and IDfLoadRecord. Thisdocumentation illustrates how to use dump and load by using method statements thatwould be executed through IAPI. For help with the DFC interfaces, refer to the Javadocsfor the interfaces.



Dumping a repository

To avoid dumping unwanted objects, run dmclean before dumping a repository.

To dump a repository, create and save a dump record object. The act of saving the objectstarts the actual dump operation. The properties that you set in the dump record objectdetermine:• What set of objects are dumped

You can dump all or part of a repository. Refer to Dumping an entire repository,page 51 or to Dumping specific objects, page 51 for instructions.

• Whether content is included directly or referenced in the dump file, and if directlyincluded, whether it is compressed

By default, if a dumped object has associated content, the operation places a referenceto the content in the dump file. This is described in Dumping without content, page54. You can set up the dump operation to include the actual content file in the dumpfile. Including content, page 55 contains information about including content.

Note: If you are dumping a repository with an encrypted storage area, you mustinclude the content files in the dump file. The content copied into the dump inclear text. It is not encrypted.

• The cache size used for the operation

Refer to Setting the cache size, page 55 for information about defining the cache size.• Whether the operation is restartable

Refer to Using non-restartable dump , page 56for information about this option.

Dumping objects under retention

The information in this section only applies to dump and loads that are performed byusing the dump and load methods in scripts or on the command line. The informationdoes not apply to dump and loads that are used to execute object replication jobs.

If a dumped SysObject is associated with a retainer, the dump operation also dumps theretainer. Retainers record retention policy definitions.

If you dump a retainer object directly, the object identified in the retainer’sretainer_root_id property is also dumped. That object may be a single SysObject ora container such as a folder. If it is a container, the objects in that container are notdumped, only the container itself is dumped.



Aspects and dump operations

A dump operation does not dump aspects associated with a dumped object. If you haveaspects associated with specific instances of an object type, you must create those aspectsin the target repository. Similarly, if you have default aspects defined for an object typeand you dump instances of that type, the default aspects must be manually createdin the target repository. The aspects must be created in the target repository beforeperforming the load operation.

Dumping an entire repository

To dump the contents of an entire repository, set the dump_operation property of thedump record object to full_docbase_dump.

By default, a full repository dump includes content files by reference. To include themdirectly, refer to Including content, page 55 for instructions.

A full repository dump does not include any DocApps installed in the repository. Afteryou load the dump file into the new repository, you must reinstall the DocApps.

If you set dump_operation to full_docbase_dump, Content Server ignores:• The restartable argument in dump_parameter

A full repository dump is always restartable.• The cache_size argument in dump_parameter

Refer to Setting the cache size, page 55 for information about the cache.• The type, predicate, and predicate2 properties

Dumping specic objects

To dump only specific objects in a repository, set the type, predicate, and predicate2repeating properties of the dump record object. The type property identifies the typeof object you want to dump and the predicate and predicate2 properties define aqualification that determines which objects of that type are dumped. The DocumentumSystem Object Reference Manual contains a full description of a dump record object’sproperties.

However, when you dump an object, the server includes any objects referenced by thedumped object. This process is recursive, so the resulting dump file can contain manymore objects than the object specified in the type, predicate, and predicate2 repeatingproperties of the dump record object.



When dumping a type that has a null supertype, the server also dump all the objectswhose r_object_ids are listed in the ID field of the type.

The ACL associated with a dumped object is also dumped.

Setting the type property

The type property is a repeating property. The object type specified at each indexposition is associated with the WHERE clause qualification defined in the predicateat the corresponding position.

The dump operation dumps objects of the specified type and any of its subtypes thatmeet the qualification specified in the predicate. Consequently, it is not necessary tospecify each type by name in the type property. For example, if you specify the SysObjecttype, then Content Server dumps objects of any SysObject or SysObject subtype thatmeets the qualification.

Use the following guidelines when specifying object types and predicates:• The object type must be identified by using its internal name, such as dm_document

or dmr_containment.

Object type definitions are only dumped if objects of that type are dumped or ifobjects that are a subtype of the type are dumped.

This means that if a subtype of a specified type has no objects in the repositoryor if no objects of the subtype are dumped, the dump process does not dump thesubtype’s definition. For example, suppose you have a subtype of documents calledproposal, but there are no objects of that type in the repository yet. If you dump therepository and specify dm_document as a type to dump, the type definition of theproposal subtype is not dumped.

This behavior is important to remember if you have user-defined subtypes in therepository and want to ensure that their definitions are loaded into the targetrepository.

• To dump subtype definitions for types that have no objects instances in the repositoryor whose objects are not dumped, you must explicitly specify the subtype in thedump script.

• If you have created user-defined types that have no supertype, be sure to explicitlyinclude them in the dump script if you want to dump objects of those types. Forexample, the following commands will include all instances of your_type_name:append,c,l,typeyour_type_nameappend,c,l,predicate1=1



• If you have system or private ACLs that are not currently associated with an object,they are not dumped unless you specify dm_acl as a type in the dump script. Forexample, include the following lines in a dump script to dump all ACLs in therepository (including orphan ACLs):append,c,l,typedm_aclappend,c,l,predicate1=1

You may want to specify a qualification in the predicate to exclude orphanedinternal ACLs.

• By default, storage area definitions are only included if content associated with thestorage is dumped. If you want to dump the definitions of all storage areas, eventhough you may not dump content from some, include the storage type (file store,linked, and distributed) explicitly in the dump script.

• When you dump the dm_registered object type, Content Server dumps only theobject (dm_registered) that corresponds to the registered table. The underlyingRDBMS table is not dumped. Use the dump facilities of the underlying RDBMSto dump the underlying table.

Setting the predicate properties

You must supply a predicate for each object type you define in the type property. If youfail to supply a predicate for a specified type, then no objects of that type are dumped.

To dump all instances of the type, specify a predicate that is true for all instances of thetype, such as 1=1.

To dump a subset of the instances of the object type, define a WHERE clause qualificationin the predicate properties. The qualification is imposed on the object type specified atthe corresponding index level in the type property. That is, the qualification definedin predicate[0] is imposed on the type defined in type[0], the qualification defined inpredicate[1] is imposed on the type defined in type[1], and so forth.

For example, if the value of type[1] is dm_document and the value of predicate[1] isobject_name = ’foo’, then only documents or document subtypes that have an objectname of foo are dumped. The qualification can be any valid WHERE clause qualification.The Content Server DQL Reference Manual contains the description of a valid WHEREclause qualification.

The predicate property accepts a maximum of 255 characters. If the qualificationexceeds 255 characters, place the remaining characters in the predicate2 property atthe corresponding index level. For example, if the qualification defined for type[0] is300 characters, you put the first 255 characters in predicate[0] and the remaining 45 inpredicate2[0]. When the dump is executed, Content Server concatenates predicate[0] andpredicate2[0]. The predicate2 property accepts a maximum of 255 characters also.



Important: If you use the predicate2 property at any index position, you must alsoset the predicate2 property at all index positions before the desired position. ContentServer does not allow you to skip index positions when setting repeating properties. Forexample, if you set predicate2[2] and predicate2[4], you must also set predicate2[0],predicate2[1], and predicate2[3]. It is valid to set the values for these intervening indexpositions to a single blank.

Content les and dumping

How the dump operation handles content depends on where the content is stored andhow the include_content parameter is set in the dump_parameter argument of thedump object.

By default, if the content is stored in a file store, EMC Centera storage area, or NetAppSnapLock storage area, the content is not included in the dump file. You can set theinclude_content parameter to include such content. If you are dumping a repository thathas encrypted file store storage areas, you must include the content in the dump file.Content Server decrypts the content before placing it into the dump file.

Dumping without content, page 54 describes the default behavior and requirementsfor handling dump files without content. Including content, page 55 describes how toinclude content and the requirements for dump files with content.

If the content is stored in a blob or turbo storage area, the content is automaticallyincluded in the dump file because the content is stored in the repository.

Content stored in external storage cannot be included in a dump file.

Dumping without content

By default, a dump operation on content in file stores, EMC Centera stores, or NetAppSnapLock stores does not include content. Instead, when an object with content isdumped, the operation places a reference to the content in the dump file. If the contentis stored in a file system, the reference is a file system path. If the object is stored in aretention storage system, the reference is the content’s address.

When the dump file is loaded into the target repository, any file systems referenced forcontent must be visible to the server at the target site. For content in retention storage,the ca_store object at the target site must have an identical definition as the ca_storeobject at the source repository and must point to the same storage system used by thesource repository.

In the target repository, the storage objects for the newly loaded content must havethe same name as the storage objects in the source repository but the filepaths for thestorage locations must be different.



The owner of the target repository must have Read permission in the content storageareas of the dumped repository when the load operation is executed. The load operationuses the target repository owner’s account to read the files in the source repositoryand copy them into the target repository.

Including content

To include content in a dump file, set the include_content property to T (TRUE) in thedump record object. If the property is true, when Content Server dumps an object withcontent, the content is copied into the dump file also. The content must be stored in afile store, EMC Centera store, or NetApp SnapLock storage area. Content Server cannotcopy content from external storage into a dump file.

In the target repository, the storage objects for the newly loaded content must have thesame names as those in the source repository, but the actual directory location, or IPaddress for a retention store, can be different or the same.

Always include content if you are dumping a repository to make a backup copy, toarchive a repository, or to move the content or if the repository includes an encryptedstorage area.

Compressing content

When you include content, you can create a compressed dump file to save space.To compress the content in the dump file, set the dump_parameter property tocompress_content = T.

Content Server automatically decompresses a compressed dump file during a loadoperation.

Setting the cache size

Content Server uses an in-memory cache to store the object IDs of dumped objects.Before dumping an object, Content Server checks the cache to see if the object hasalready been dumped.

You can improve the performance of a large dump operation by setting a larger cachesize. If you do not specify a cache size, the server uses a default size of 1 MB, whichcan hold up to 43,690 object IDs.

To increase the cache size, set the cache_size argument of the dump_parameter propertyto a value between 1 and 100. The value is interpreted as megabytes and defines the



maximum cache size. The memory used for the cache is allocated dynamically as thenumber of dumped objects increases.

Content Server ignores the cache setting when doing a full repository dump.

Using non-restartable dump

You can also improve the performance of a dump operation by creating a non-restartabledump. However, if a non-restartable dump operation fails, you will not be able to restartthe dump from the failure point. Instead, you must create a new dump record object tostart the dump operation from the beginning.

A dump operation can only be non-restartable if it is a partial repository dump. Fullrepository dump operations are always restartable.

To create a non-restartable dump, set the dump_parameter property to restartable=F.

Using a script to create a dump le

For dump operations that you execute regularly, we recommend that you write a scriptthat creates and saves the dump object and checks for errors after the execution. Using ascript avoids re-creating the dump object manually each time you want to performthe task.

To use a script:1. Write a script that creates the dump object, sets its properties, saves the object, and

checks for errors.If you do not set the file_name property to a full path, Content Server assumes thepath is relative to the root directory of the server. The filename must be uniquewithin its directory. This means that after a successful load operation that uses thedump file, you must move the dump file to archival storage or destroy it so youcan successfully execute the script later.

2. Use IAPI to execute the script. Use the following command line syntax:iapi source_db -Uusername -Ppassword < script_filename

where:• source_db is the name of the repository that you want to dump.• username is the user name of the user who is executing the operation.• password is the user’s password.• script_filename is the name of the file you created in Step 1.



3. If the dump was successful, destroy the dump object. If the Save on the dumpoperation did not return OK, the dump was not successful.Destruction of the dump object cleans up the repository and removes the dumpobject records and state information that are no longer needed.

Sample script for a full repository dump with content included

The following script dumps an entire repository by setting the dump_operation propertyof the dump record object to full_docbase_dump, includes the content directly in thedump file, and compresses the content:create,c,dm_dump_recordset,c,l,file_name/tmp/dumpfile.outset,c,l,dump_operationfull_docbase_dumpset,c,l,include_contentTappend,c,l,dump_parametercompress_content=Tsave,c,lgetmessage,c #Check for dump errors

Sample script for a partial repository dumpNote: There is a template for a sample script in %DM_HOME%\install\DBA\dump_template.bat ($DM_HOME/install/DBA/dump_template.api ).

The script below has the following characteristics:• It does not copy content files into the dump file.• It only dumps ACLs associated with a dumped object.• It does not dump subtype definitions if there are no objects of that subtype.• It does not dump storage area definitions if the dump does not include any content

associated with the storage area.• It does not dump user-defined subtypes that have no supertype.• It does not dump job objects.• It is not restartable.The script assumes that you want to dump all instances of the types, not just a subset.Consequently, the predicates are set as 1=1 (you cannot leave them blank). If you wantto dump only some subset of objects or want to include all ACLs, type definitions, orstorage area definitions, modify the script accordingly.

Here is the script:create,c,dm_dump_recordset,c,l,file_name



dump file name# Supply your own file name.# This must be a new fileappend,c,l,typedm_sysobjectappend,c,l,predicate1=1append,c,l,typedm_assemblyappend,c,l,predicate1=1append,c,l,typedm_formatappend,c,l,predicate1=1append,c,l,typedm_userappend,c,l,predicate1=1append,c,l,typedm_groupappend,c,l,predicate1=1append,c,l,typedmi_queue_itemappend,c,l,predicate1=1append,c,l,typedmi_registryappend,c,l,predicate1=1append,c,l,typedm_relationappend,c,l,predicate1=1append,c,l,typedm_relation_typeappend,c,l,predicate1=1append,c,l,typedmr_containmentappend,c,l,predicate1=1append,c,l,typedmr_contentappend,c,l,predicate1=1append,c,l,dump_parametercache_size=60 #set cache sizeappend,c,l,dump_parameterrestartable=F #non-restartable dumpappend,c,l,predicate1=1save,c,lgetmessage,c

Notes:• In the append command line, the l is the lowercase letter L.



• If you do not set the file_name property to a full path, Content Server assumes thepath is relative to the root directory of the server. The filename must be uniquewithin its directory. This means that after a successful load operation using thedump file, you must move the dump file to archival storage or destroy it so that youcan successfully execute the script later.

• To dump user-defined types that have no supertype, add Append methods for eachto the script:append,c,l,typeyour_type_nameappend,c,l,predicate1=1

If the server crashes during a dump operation

If Content Server crashes during a dump operation, there are two alternatives:• Destroy the dump file ( target file named in the script) if it exists and then re-execute

the script.

If the specified file already exists when you try to save a new dump record object, thesave will fail. Re-executing the script creates a new dump record object.

• If the dump operation is restartable, fetch the existing dump object from the sourcerepository and save it again. Saving the object starts the dump operation. ContentServer will begin where it left off when the crash occurred.

Moving the dump le

The dump file is a binary file. If you move a dump file from one machine to anotherelectronically, be sure to use a binary transfer protocol.

If your operating system is configured to allow files larger than 2 GB, the dump file canexceed 2 GB in size. If you create a dump file larger than 2 GB, you cannot load it on amachine that does not support large file sizes or large file systems.

Loading a repository

Loading a repository puts the objects stored in a dump file into the repository.

If the dump file does not include the actual content files associated with the objectsyou are loading, the operation reads the content from the storage areas of the dumpedrepository. This means that the owner of the repository that you are loading must



have Read privileges at the operating system level for the storage areas in the sourcerepository.

The load operation generates a dmi_queue_item for the dm_save event for each object oftype SysObject or a subtype that is loaded into the target repository. The event is queuedto the dm_fulltext_index_user user account. This ensures that the objects are added tothe target repository’s index. You can turn off this behavior. For instructions, refer toTurning off save event generation during load operations, page 61.

Loading a repository is accomplished by creating and saving a load record object. Theact of saving the object starts the operation.

Note: The load operation performs periodic commits to the repository. Consequently,you cannot load a repository if you are in an explicit transaction. The Content Serverwill not allow you to save a load record object if you are in an explicit transaction.Similarly, you cannot perform a revert or destroy operation on a load record object ifyou are in an explicit transaction.

Refreshing repository objects from a dump le

Generally, when you load objects into a repository, the operation does not overwrite anyexisting objects in the repository. However, in two situations overwriting an existingobject is the desired behavior. These situations are:• When you are replicating content between distributed storage areas• When you are restoring archived contentIn both situations, the content object that you are loading into the repository may alreadyexist. To accommodate these instances, the load record object has a relocate property.The relocate property is a Boolean property that controls whether the load operationassigns new object IDs to the objects it is loading.

The type and predicate properties are for internal use and cannot be used to loaddocuments of a certain type.

Loading job objects

If you dump and load job objects, the load operation automatically sets the job to inactivein the new repository. This ensures that the job is not unintentionally started before theload process is finished and it allows you the opportunity to modify the job object ifneeded. For example, you may want to adjust the scheduling to coordinate with otherjobs in the new repository.

The load operation sets jobs to inactive (is_inactive=TRUE) when it loads the jobs, andsets the jobs’ run_now property to FALSE.



If the load operation finds an existing job in the target repository that has the same nameas a job it is trying to load, it does not load the job from the dump file.

Loading registered tables

When you load a registered table, the table permits defined for that table are carried overto the target repository.

Turning off save event generation during load operations

During a load operation, every object of type SysObject or SysObject subtypeloaded into the target repository generates a save event. The event is queued to thedm_fulltext_index_user. This behavior ensures that the object is added to the targetrepository’s index.

The behavior is controlled by the load parameter called generate_event. The parameteris T by default. If you do not want the load operation to queue save events to thedm_fulltext_index_user, set the parameter to F for the operation. The parameter is set inthe load_parameter property as:generate_event=F

Loading a new repository

New repositories are not empty. They contain a variety of cabinets and folders createdby the installation process, such as:• A user object for the repository owner• A cabinet for the repository owner• The docu group• The System cabinet, which contains a number of subfolders• The Temp cabinetWhen you load a dump file into a new repository, these objects are not replaced by theircounterparts in the dump file because they already exist in the new repository.

However, if you have changed any of these objects in the source repository (the source ofthe dump file), the changes are lost because these objects are not loaded. For example,if you have added any users to the docu group or if you have altered permissions onthe System cabinet, those changes are lost.



To ensure that any changes you have made are not lost, fetch from the source repositoryany of the system objects that you have altered and then use the Dump method to get arecord of the changes. For example, if the repository owner’s cabinet was modified, usethe following command sequence to obtain a listing of its property values:fetch,c,cabinet_iddump,c,l

After the load operation, you can fetch and dump the objects from the new repository,compare the new dump results with the previous dump results, and make any necessarychanges.

The preLoad utility

Documentum provides a utility that you can run on a dump file to tell you what objectsthat you must create in the new repository before you load the dump file. The utility canalso create a DQL script that you can edit and then run to create the needed objects. Thesyntax for the preload utility is:preload repository [-Uusername] -Ppassword -dump_file filename[-script_file name]

• repository is the name of the repository into which you are loading the dump file.• filename is the name of the dump file.• name defines a name for the output DQL script.If you do not include a username, the current user is assumed.

Note: This utility does not report all storage areas in the source repository, but only thosethat have been copied into the dump file.

Load procedure for new repositories

Use the following procedure to load a dump file into a new repository.

Note: You cannot perform this procedure in an explicit transaction because the loadoperation performs periodic commits to the repository. Content Server does not allowyou to save the load record object to start the load operation if you are in an explicittransaction.

To load a dump le into a new repository:1. Create the new repository.

Notes:• If the new repository shares any directories with the source repository, you must

assign the new repository an ID that differs from that of the source repository.



• If the old and new repositories have different owners, ensure that the newrepository’s owner has Read privileges in the storage areas used by the oldrepository if the old repository was not dumped with the include_contentproperty set to TRUE.

2. Create the necessary storage objects and associated location objects in your newrepository.Each storage object in your source repository must have a storage object with thesame name in the new repository. The filestore objects in the new repository mustreference location objects that point to actual directories that differ from thosereferenced by the location objects in the source repository.For example, suppose you have a file store object with the name storage_1 inyour source repository that points to the location object named engr_store, whichreferences the d:\documentum\data\engr (/u04/home/installation_owner/data/engr)directory. In the new repository, you must create a file store object with the namestorage_1 that references a location object that points to a different directory.

Note: The location objects can be named with different names or they can have thesame name. Either option is acceptable.

3. If your storage areas in the source repository had associated full-text indexes, createcorresponding fulltext index objects and their location objects in the new repository.Note that these have the same naming requirements as the new storage objectsdescribed in Step 2.

4. Create and save the following script:create,c,dm_load_recordset,c,l,file_namefull_path_of_dump filesave,c,lgetmessage,c

5. Log in as the owner of the installation and use IAPI to execute the script.When you start IAPI, connect to the new repository as a user who has Sysadminprivileges in the repository.

6. After the load completes successfully, you can destroy the load object:destroy,c,load_object_id

Notes:• Destroying the load object cleans the load object record objects that are generated

by the loading process and old state information.• If you created the dump file by using a script, move the dump file to archival

storage or destroy it after you successfully load the file. You will not be able tosuccessfully execute the script again if you leave the dump file in the locationwhere the script created it. Content Server will not overwrite an existing dumpfile with another dump file of the same name.



• If Content Server crashes during a load, you can fetch the Load Object and saveit again, to restart the process. Content Server will begin where it left off whenthe crash occurred.

DocApps

DocApps are not dumped when you dump a repository. Consequently, after you loada new repository, install and run the DocApp installer to reinstall the DocApps in thenewly loaded repository.

Generating dump and load trace messages

You can activate tracing during dump and load operations to generate trace messages inthe Content Server session log.

To activate tracing, use a setServerTraceLevel method.

The trace information includes:• Whether Content Server fails to dump or load an object• The query used to search for matching objects for a dump or load operation• The current progress and status of a dump or load operation

Creating location and mount point objectsThe directories that a Content Server accesses are defined for the server by locationobjects. A location object can represent the location of a file or a directory.

A mount point object represents a directory that is mounted by a client. It is a useful wayto aggregate multiple locations that must be mounted.

Note: A UNIX client can only mount a Windows Content Server disk if the Windowsmachine has an NFS package installed that exports the disk.

Both locations and mount point objects reside in the repository in the File System folderin the System cabinet.



Location objects

You can create a location object by using Documentum Administrator or a DQLCREATE...OBJECT statement. For help with the procedure using DocumentumAdministrator, refer to the Documentum Administrator online help. Using DQL allowsyou to create the object and set its properties in one step.

For example, the following DQL statement creates a location object, sets it properties,and saves the object when the statement completes successfully. The location object isnamed storage_5 and references a directory on a Windows host:CREATE "dm_location" OBJECTSET "object_name" = 'storage_5',SET "file_system_path" = ‘d:\documentum\data\storage_5',SET "path_type" = 'file',SET "security" = 'private'

Here is the same example illustrated for a UNIX host:CREATE "dm_location" OBJECTSET "object_name" = 'storage_5',SET "file_system_path" = 'u16/home/installation_owner/data/storage_5',SET "path_type" = 'file',SET "security" = 'private'

Saving the location object automatically creates only the final leaf of the directorypath referenced by the location. For example, if you issue the statement above, thesystem only creates the storage_5 directory. If the containing directory structured:\documentum\data (u16/home/installation_owner/data) did not already exist, theoperation would fail.

When you create a location object, you must set the following properties:• object_name• file_system_path

The value in file_system_path must consist of ASCII characters.• path_typeYou may also wish to set the optional security_type property. If the location object isassociated with a storage area, the setting in the property is applied to files stored in theassociated storage area. There are three possible values for the security_type property.Table 5, page 65, lists the values and the file permissions associated with each.

Table 5. security_type property settings for location objects

Security setting Owner Group World

public Read and write Read Read

public_open Read and write Read and write Read and write

private Read and write None None



The default setting for security_type is private.

The remaining properties are optional and the server will provide default values ifthey are not set. Refer to the Documentum System Object Reference Manual for a completelisting of the type’s properties.

If the location represents a directory or file that users will be sharing through diskmounting, consider placing it under one upper level directory that can be represented bya mount point object. If all shared files and directories are put under one mount point,system administration tasks are simplified and system resources are conserved.

Mount point objects

Mount point objects represent shared (mounted) directories. You can create mount pointobjects by using Documentum Administrator or the DQL CREATE...OBJECT statement.You must have Sysadmin or Superuser user privileges to create a mount point object.Using Documentum Administrator or DQL allows you to create the mount point object,set its properties and save it in one operation.

When you create a mount point, you must set the following properties:• object_name• file_system_path• host_nameAdditionally, the three properties that record alias values for the shared (mounted) diskare typically set. Refer to the Documentum System Object Reference Manual for a completelist of the mount point object’s properties.

Note: A UNIX client can only mount a Windows Content Server disk if the Windowsmachine has an NFS package installed that exports the disk.

Platform aliases

When you create a shared disk or mount a disk, you typically define an alias for thatshared (mounted) disk for use by clients. A mount point object has three properties torecord the aliases for the directory represented by the mount point object. Each propertyrepresents the alias for a particular client platform.

If you use them:



• Set unix_preferred_alias to the directory name you used to mount the directory.

For example, assume you mounted the /u25 disk using the following command:mount remote_computer:/u25 /r25

You would set unix_preferred_alias to /r25.• Set win_preferred_alias to the alias drive letter you used to mount the directory.

For example, suppose you mounted the same disk on a windows machine by usingthe following command:net use f: \\remote_computer\share\ name

You would set win_preferred_alias to f:\.

Alternatively, if you are using UNC naming conventions, set win_preferred_aliasby using the following format:\\machine_name\alias_name\

For example,\\cougar\link_01

cougar is the name of a Windows host and link_01 is a shared name that points tothe file system path of the dm_location object that represents the storage area.

• Set mac_preferred_alias to the volume name chosen for the mounted directory.

The mounted directory’s volume name is set when the directory is exported throughthe file-sharing system and will appear in the Chooser for that directory.

Format objectsFormat objects define file formats. Content Server only recognizes formats for whichthere is a format object in the repository. When a user imports a document, the formatof the document must be a format recognized by Content Server. If the format is notrecognized by the server, the user cannot save the document in the repository.

The installation procedure adds a basic set of format objects to the repository. You canadd more format objects, delete some of the objects, or change the properties of anyobject. You can query the repository to obtain a list of the format objects in the repository.Refer to Listing current format objects, page 68 for a sample query.

For a complete list of properties defined for the format object type, refer to theDocumentum System Object Reference Manual.



The DOS extension property

When a user requests a file without specifying a filename for the working copy of thefile, the server names the file for the user. If the dos_extension property of the file’sassociated format object is set, the server automatically appends that extension to the filename when it copies the file to the client local area or the common area.

Similarly, if the storage object associated with the file’s storage area has theuse_extensions property set, the server appends the extension defined in dos_extensionto the file when it places the file in storage. Refer to Providing automatic file extensions,page 258 for more information about DOS extensions.

The format_class property

The format_class property of the format object may be set to values that determinewhich formats are indexed:• ftalways

All renditions in formats whose format_class property is set to ftalways are indexed.For example, if a document has renditions in Microsoft Word and PDF formatsand the format_class property for both formats is set to ftalways, both renditionsare indexed.

• ftpreferred

If a document has multiple renditions in indexable formats and one is in a formatwhose format_class property is set to ftpreferred, the rendition in that formatis indexed rather than any renditions in other formats, with the exception thatany formats whose format_class property is set to ftalways are also indexed. Ifa document has more than one rendition whose format_class property is set toftpreferred, the first rendition processed for indexing is indexed and the otherrenditions are not. It is recommended that for any document, only one rendition is ina format whose format_class property is set to ftpreferred.

If a document has renditions in four different formats, of which the format_class ofone is set to ftpreferred and the format_class of the other three is set to ftalways,all four renditions are indexed.

Listing current format objects

The formats installed by default when Content Server is installed are listed in formats.csv,which is found in %DM_HOME%\install\tools ($DM_HOME/install/tools). The



formats.csv script is run during server installation to install the default formats. You canexamine that file to see the formats installed by default and their settings.

The format objects in your repository may be different from those defined in theformats.csv file if you have customized any formats or added formats. Use the followingquery to obtain a list of the formats currently defined in a repository:SELECT "name", "description" FROM "dm_format"

To obtain more information about the format definitions in the repository, modify thequery to return other or all format property values.

Adding format objects

You can add a format object by using Documentum Administrator or DQL. Forinstructions on using Documentum Administrator, refer to the DocumentumAdministrator online help. The Documentum System Object Reference Manual lists theproperties of format objects.

Using DQL

Use the DQL CREATE...OBJECT statement to create a format object. The syntax is:CREATE "dm_format" OBJECTSET property = value {,SET property = value}

For example, the following statement (taken from the formats.ebs script), creates theformat object for the text format:CREATE "dm_format" OBJECTSET "name" = 'text',SET "can_index" = true,SET "mac_creator" = 'ttxt',SET "mac_type" = 'TEXT',SET "dos_extension" = 'txt',SET "description" = 'ASCII text'

Rich media formats

If the format you are adding is a rich media format (video, audio, and so forth), there arefour properties that you may want to set depending on the format. Set these propertiesby using DQL or Documentum Administrator. The properties are:



• richmedia_enabled

Set to TRUE to generate thumbnail files, automatic renditions, and metadata forcontent files in the new format. You must have Documentum Media TransformationServices installed.

• asset_class

Set to enable applications to identify the kind of content represented by the format.Set the property to a string value that identifies the content.

• default_storage

Set to store all content files in this format in a storage area that differs from thedefault storage area for the object type of the object containing the file. Set theproperty to the object ID of the appropriate storage area.

• filename_modifier

Set to have Site Caching Services append a modifier to renditions when exportingmultiple renditions of the file. Set the property to the modifier you want to append.

Modifying formats

Use Documentum Administrator or DQL to modify a format object.

Using DQL

Use the DQL UPDATE...OBJECT statement to change a format object. The syntax is:UPDATE type_name [(ALL)][correlation_variable]OBJECT[S] update_list[WHERE qualification]

where update_list is:set property_name = valueset property_name[[index]] = valueappend [n]property_name = valueinsert property_name[[index]] = valueremove property_name[[index]]truncate property_name[un]link 'folder path'move [to] 'folder path'

For example, here is an excerpt of an IDQL session that sets the dos_extension propertyfor a user-defined format:1>update dm_format object2>set dos_extension = 'txt'3>where name = 'myformat'4>go



For a complete description of this statement and its use, refer to the Content Server DQLReference Manual.

Deleting formats

You cannot delete a format if the repository contains content files in that format.

To delete a format, use Documentum Administrator or DQL.

Using DQL

Use the DQL DELETE...OBJECT statement to delete a format object. The syntax is:DELETE type_name [(ALL)][correlation_variable]OBJECT[S][WHERE qualification]

The qualification in the WHERE clause identifies the format to delete. For example, hereis an excerpt of an IDQL session that deletes the format named myformat:1>delete dm_format object2>where name = 'myformat'4>go

For a complete description of this statement and its use, refer to the Content Server DQLReference Manual.

Alias setsAlias sets are objects that define one or more aliases and their corresponding values.Aliases are place holders for values in:• The r_accessor_name property in template ACLs• The acl_name, acl_domain, and owner_name properties in SysObjects• The performer_name property in dm_activity objects (workflow activity definitions)• The folder path in IDfSysObject.link and IDfSysObject.unLink methodsFor a complete description of how aliases are used, refer to Documentum Content ServerFundamentals.



Creating an alias set

Any user can create an alias set. You can use Documentum Administrator or DQL tocreate an alias set.

In DQL, use a CREATE...OBJECT statement. The Documentum System Object ReferenceManual lists the properties of an alias set.

If you are creating an alias set to use in a template, it is not necessary to provide actualvalues for the aliases defined in the alias set. If the alias values are undefined, the valuesare determined when the template is used. For example, if the template is a workflowtemplate, the person starting the workflow is prompted for the alias values when theworkflow is started.

Modifying or deleting an alias set

To use Documentum Administrator to change or delete the alias set, you must be eitherthe alias set’s owner or a Superuser.

Working with object typesBecause every business has requirements that are particular to its environment,Documentum allows you to create object types and modify existing object types, withsome constraints.

Creating a user-dened type

You can use Documentum Administrator or DQL to create a new object type. Forinstructions on using Documentum Administrator to create a type, refer to theDocumentum Administrator online help.

To create a new type, you must have Superuser, Sysadmin, or Create Type userprivileges. You can create a subtype from any of the object types listed in CREATE TYPEstatement description in the Content Server DQL Reference Manual.

If you have Superuser privileges, you can create a subtype with no supertype.



Using DQL

In DQL, use the CREATE...TYPE statement to create a new object type. The statement’ssyntax and usage information are found in the Content Server DQL Reference Manual.

Be sure to set the acl_domain and acl_name properties to define the default ACL forthe object type if the new type is subtyped from dm_SysObject, a SysObject subtype,dm_user, or a user subtype. The ACL is not used to control access to the type. Instead, itcan be used to assign default permissions for new objects of the type.

The acl_name property is set to the object_name of the ACL you are assigning to theobject type. You can specify any ACL that you own or that is owned by the repositoryowner (or the owner’s alias, dm_dbo if your RDBMS is Oracle or Sybase). If you identifyan ACL owned by the repository owner or dm_dbo in acl_name, you must specifyacl_domain. If you specify only acl_name, the server searches only your privately ownedACLs for the ACL.

The acl_domain property is set to the name of the user who owns the ACL. Valid usernames are your name or the repository owner’s name or alias (dm_dbo).

Unless you are a Superuser, you must identify the new type’s supertype. If you area Superuser and want to create the type without a Supertype, specify NULL as thesupertype.

To illustrate the statement’s usage, here are two examples:CREATE "mytype" TYPE("name" char(64), "address" char(255), "dependents"char(32) repeating)WITH SUPERTYPE NULL

CREATE "report_doc" TYPE("monthly_total" integer repeating, "month_name"char(12) repeating)WITH SUPERTYPE "dm_document"

Modifying an object type

Use DQL or Documentum Administrator to modify system-defined object types anduser-defined object types.

You can change the default group, default ACL, or default storage area for any objecttype. However, what other changes you can make depends on whether the object type isa user-defined type or a system-defined type. For a summary of the kinds of changesthat you can make, refer to the ALTER TYPE description in the Content Server DQLReference Manual.

Any changes you make to a type are cascaded to all objects of that type, to its subtypes,and to all objects of any of its subtypes.



Deleting properties

Properties are stored as columns in a table representing the type in the underlyingRDBMS. However, not all RDBMSs allow you to drop columns from a table.Consequently, if you delete a property, the corresponding column in the tablerepresenting the type may not actually be removed. In such cases, if you later try to adda property to the type that has the same name as the deleted property, you will receivean error message.

Using DQL

Use the DQL ALTER TYPE statement to modify a user-defined type’s definition or set thedefault group, ACL, or storage area for a type. The statement has four forms, dependingon what kind of alteration you want to make.

Changing the default permissions or default storage area

To change a default ACL or storage area, use the SET clause in the ALTER TYPEstatement.

The syntax is:ALTER TYPE type_name SET set_clause

where set_clause is one of the following:DEFAULT STORAGE new storage areaDEFAULT ACL acl_name [IN acl_domain]

For example, the following statement changes the default storage area for the report_doctype to storage_12:ALTER TYPE "report_doc" SET DEFAULT STORAGE "storage_12"

If the value for acl_name or acl_domain includes a space or another character that requiresyou to enclose the string in single quotes, enclose both strings in single quotes. Forexample:ALTER TYPE "report_doc" SET DEFAULT ACL "design_state" IN "howardj"

Adding a property

You can add properties only to custom object types. You cannot add properties to objecttypes whose names begin with dm. To add a property, use the following syntax:ALTER TYPE type_name ADD property_def {,property_def}



The type_name argument must identify a user-defined type.

The property_def argument defines the new property’s name, datatype, length if it is astring datatype, and whether it is a repeating property. The format for this information is:property_name datatype [REPEATING]

For example, the following statement adds a character string property to the report_doctype:ALTER TYPE report_doc ADD department string (16)

If you want department to be a repeating property, the statement looks like this:ALTER TYPE "report_doc" ADD "department" string(16) REPEATING

The definition can also include data dictionary information for the property. Forinformation about the syntax for defining data dictionary information, refer to CREATETYPE description the Content Server DQL Reference Manual.

Deleting a property

You can delete properties only from user-defined object types. Use the following ALTERTYPE syntax:ALTER TYPE type_name DROP property_name


For example, the following statement deletes the department property from thereport_doc type:ALTER TYPE "report_doc" DROP "department"

Lengthening a string property

You can lengthen string properties only in user-defined object types. Use the followingALTER TYPE syntax:ALTER TYPE type_name MODIFY property_def {,property_def}


The property_def argument identifies both the property to change and its new length. Forexample, suppose you want to lengthen the department property for the report_doc typeto 24 characters. Here is the statement:ALTER TYPE "report_doc" MODIFY "department" char(24)

If department is a repeating property, the statement looks like this:ALTER TYPE "report_doc"MODIFY "department" char(24) REPEATING



Deleting a type

You can remove a type from the repository only if:• The type is a user-defined type.

You cannot remove system-defined types from the repository.• You are the owner of the type or a user with Superuser user privileges.• The type has no subtypes.• There are no existing objects of that type in the repository.Use either Documentum Administrator or DQL to remove a type from the repository.For instructions on using Documentum Administrator, refer to the DocumentumAdministrator online help.

To use DQL, use the DROP TYPE statement. The syntax is:DROP TYPE type_name

For example, the following statement removes the report_doc type:DROP TYPE "report_doc"

Cleaning up repositoriesEvery site should have a schedule for repository maintenance that includes regularrepository cleanup. Cleaning a repository involves removal of:• Orphaned content files

When users delete a document, or any object that has a content file associated with it,the system deletes the object and marks the content as an orphan. The system doesnot delete the actual content file. This must be done using the dmclean utility.

• Unwanted document versions and renditions

Depending on your business rules, you can remove older versions of a document.You can also remove renditions associated with deleted documents or unneededrenditions and annotations for current documents.

• Orphaned annotations and internal ACLs

An annotation (dm_note object) is orphaned when it is detached from all documentsor other objects to which it was attached.

An internal ACL (dm_acl object) is orphaned when it is no longer referenced by anyobject. (Internal ACLs are ACLs that are created by the server.)



• Aborted workflows

A workflow that has been stopped by the execution of an Abort method is anaborted workflow.

• Old log filesCleaning a repository regularly helps ensure that there is little or no wasted spacein your installation.

To clean a repository:1. Perform a complete backup of the repository.

2. Delete unwanted versions of documents.Based on your business rules, you can delete only versions created before a certaindate or by a certain author. Or, you can delete all but the CURRENT version fromone or more version trees. What you want to delete will determine which methodyou use.• To delete selected versions of documents, use the DELETE...OBJECT statement.

You can identify the documents to delete by their creation date, modificationdate, or some other criteria that you choose. For example, the followingstatement deletes all documents that have not been changed since January1, 2000:DELETE "dm_document" OBJECTSWHERE "r_modify_date" < DATE('01/01/2000')

Or, the next statement deletes all documents created before January 1, 1999and have the version label outdated:DELETE "dm_document" OBJECTSWHERE "r_creation_date" < DATE('01/01/1999)AND ANY "r_version_label" = 'outdated'

• To delete versions from a version tree, use a IDfSysObject.prune method.

Prune deletes all unwanted versions on a specified tree or branch of a tree. Anunwanted version is any version that has no symbolic label and that does notbelong to a virtual document. Refer to the Javadocs for the usage of the method.

If you specify the root version of the version tree in the prune method, themethod searches the entire tree for versions to prune. If you specify a node onthe tree, the method only searches the versions on that branch of the tree.

The keepSLabel argument is a flag that tells the server whether or not to keep anyversion that has a symbolic label. It is TRUE by default. If you set it to FALSE,the server removes versions with symbolic labels.

3. Delete unused renditions.



Renditions are created automatically by the server to fulfill a user’s request orexplicitly by a user. A rendition is represented in the repository by a content objectthat points to the rendition’s source document and by a content file.Over time, you may find that you want to remove document renditions that areno longer needed or wanted. To delete a rendition (without deleting its sourcedocument), you first update the content object for the rendition to remove itsreference to the source document. For example, the following UPDATE...OBJECTstatement updates all server- and user-generated renditions created before January 1,2000. The updates in the statement detaches the affected renditions from their sourcedocuments, effectively deleting them from the repository.UPDATE "dmr_content" OBJECTSSET "parent_count" = 0,TRUNCATE "parent_id",TRUNCATE "page"WHERE "rendition" != 0 AND "set_time" < DATE('01/01/2000')

The content objects for the renditions and their content files are now orphaned andyou must run dmclean to remove them (Step 6).

4. Clean the temp directory by deleting the temporary files in that location.You can determine where the temp directory is with the following query:SELECT "file_system_path" FROM "dm_location"WHERE "object_name" = 'temp'

5. Delete any unwanted dmi_queue_item objects.Every time an object is placed in a user’s inbox, a dmi_queue_item object iscreated. When the object is removed (by any means), the queue item object is notdestroyed, but it is marked in the repository as dequeued. Based on your businessrules, you may want to remove some of these queue item objects. You can use theDELETE...OBJECT statement for this. For example, the following statement removesall queue items objects representing objects that were dequeued before January 1,2000:DELETE "dmi_queue_item" OBJECTSWHERE "dequeued_date" < DATE('01/01/2000')AND "delete_flag'=true

6. Run dmclean to remove the content files left orphaned when you removedold versions and renditions, orphaned annotations and ACLs, and abortedworkflows. You can execute the Dmclean administration tool or run the dmcleanutility manually. Instructions for using the tool are found in Dmclean , page 482.Instructions for running the utility manually are found in Using dmclean, page 267.

7. Delete or archive old server logs, session logs, trace files, and old versions of theproduct.Session logs are found in %DOCUMENTUM%\dba\log\repository_id($DOCUMENTUM/dba/log/repository_id).



Content Server and connection broker log files are found in%DOCUMENTUM%\dba\log ($DOCUMENTUM/dba/log). The serverlog for the current server session is named repository_name.log. The log for thecurrent instance of the connection broker is named docbroker.docbroker_hostname.log.Older versions of these files have the extension .save and the time of their creationappended to their name.On Windows, you can use the del command or the File Manager to removeunwanted session logs, server logs, and connection broker logs. On UNIX, use therm command.

Maintaining query performanceUse the information in this section to help maintain optimal query performance in therepository.

Using Update Statistics

As users add documents and other objects to the repository, the tables in the RDBMS thatstore information about those objects will grow. This affects the performance of queries.This can be particularly noticeable for queries against documents stored in a distributedstorage area as the dmi_replica_record table grows. To ensure that queries are using thebest possible query plan, be sure to run statistics against your repository regularly.

Documentum provides a system administration tool called Update Statistics thatgenerates statistics for all the repository tables. For information about this tool, referto Update Statistics , page 519.

Alternatively, you can use run statistics by using the command available directly inthe RDBMS. For information about that, consult the documentation provided by yourRDBMS vendor.

Setting the DM_GROUP_LIST_LIMIT environmentvariable

When a query is issued, Content Server checks the user’s permissions on all returnedresults to ensure that only those results the user has permissions for are returned to thatuser. To perform the permission checking, Content Server also checks each group towhich the user belongs. If the user belongs to a large number of groups, Content Servermay use a subquery to perform the permission checking.



The number of groups that Content Server can check without resorting to a subquerydefaults to 250. If the user belongs to more than 250 groups, the server must use asubquery. For example, suppose a user who is a member of 500 groups executes thefollowing query:SELECT r_object_id FROM dm_document WHERE object_name LIKE '%dm%'When this query is translated to SQL, a subquery is needed to perform the ACL checkingbecause the default group list limit for queries is 250. The performance is slower due tothe need for the subquery. To avoid the use of the subquery, you can reset the defaultgroup list limit by setting the DM_GROUP_LIST_LIMIT environment variable.

Note: Setting the variable affects all queries. If you want to change the limit for a singlequery, or just a particular set of queries, you can use the GROUP_LIST_LIMIT DQL hintin the particular query or queries.

To set the variable on Windows, set the variable as a system variable. Use a no-signinteger as the value.

On UNIX platforms, add the following line to the dm_start_repositoryname script afterthe first line of the script:DM_GROUP_LIST_LIMIT=value export DM_GROUP_LIST_LIMIT

where value is the number to which you wish to reset the limit.

You must restart Content Server after setting the variable.

Conguring repository-level package namecontrol

When an application or user issues an addPackage or addAttachment method to add apackage or attachment to an activity or work item in a running workflow, the applicationor user has the option of providing the names of the package or attachment componentsas a method argument. By default, when the names are provided, Content Server recordsthe names in the generated package or wf attachment object. For packages, this makesthe name available for use in the message string specified in the activity’s task_subjectstring. Attachments are not supported for referencing in task subjects. However, forsecurity reasons, you can disable the ability to record the names in the package or wfattachment object by turning on package control.

Two properties control this functionality:• wf_package_control_enabled in the docbase config object• package_control in the workflow definition (a dm_process object)The wf_package_control_enabled property is set to F (FALSE) by default. This meansthat Content Server can record component names in package or wf attachment objectsif package control is not enabled in the workflow and the names are provided in



addPackage or addAttachment method. When wf_package_control_enabled is set toF, the setting of the package_control property in the workflow definition determineswhether the name is actually recorded in the package object.

The package_control property in the workflow definition (dm_process object) is set to 0by default. This setting means that package control is not enabled. This allows the serverto record package names specified in the addPackage and addAttachment methods inthe package, or the wf attachment objects that are generated for the workflow’s activitiesor work items.

Table 6, page 81 illustrates how the property settings interact to determine whetherthe server can record the names.

Note: Enabling package control at the repository level (setting wf_package_control_enabled to T) means that the server cannot record the names regardless of the workflowsetting.

Table 6. Interaction of properties that determine package control behavior

wf_package_control_enabled (docbase config setting)package_control (processsetting) T (on) F (off)

0 (off) Content Serverrecords blanks inr_component_name

Content Server recordsobject names inr_component_name ifspecified in Addpackage

1 (on) Content Serverrecords blanks inr_component_name

Content Serverrecords blanks inr_component_name

To enable package control at the repository level, set the wf_package_control_enabledproperty in the docbase config object to T (TRUE). In doing so, the server cannot recordcomponent names in the package object, regardless of the setting in the workflowdefinition.




Chapter 3Servers

This chapter contains an overview of Content Servers and the standard procedures for workingwith the servers. The topics in this chapter are:• Overview of servers, page 84• Internationalization, page 87• The dm_start_repositoryname script (UNIX), page 88• The server.ini file, page 88• Moving the server executable (UNIX only), page 109• Changing default operating system permits on directories and files (UNIX only), page 109• Changing a server’s configuration, page 109• Setting the secure connection mode, page 110• Restarting a server, page 111• Starting additional servers, page 112• Communicating with connection brokers, page 114• Specifying queue size for incoming connection requests (Windows only), page 118• Shutting down a server, page 118• Stopping a session server, page 120• Server log files, page 121• Server load balancing and failover, page 121• Clearing the server common area, page 122• Adding additional servlets to the Java method server, page 123• Configuring the workflow agent, page 123• Recovering automatic activity work items on Content Server failure, page 125• Managing the JBoss application server, page 125


Servers

Overview of serversServers are processes that provide client access to the repository. They receive queriesfrom clients in the form of DFC methods or DQL statements and make a call to theunderlying RDBMS or the file directories. Every repository must have at least oneactive server. If a repository does not have an active server, then users cannot accessthat repository.

Server threads (Windows)

When a server is started, the resulting server process contains three threads, one ofwhich is called the main thread. When a client asks for a repository connection throughthe server, a session thread is started for that client within the server process. Sessionthreads persist only for the life of the session; as soon as the session terminates, so dosession threads.

The number of session threads that can be started within the server process isconfigurable.

Parent servers and session servers (UNIX)

When a server is started, the resulting server process is called a parent server. Eachtime a client asks for a repository connection through a parent server, the parent serverspawns another server process to service that client. These spawned server processes arecalled session servers in this manual. They persist only for the life of the session. As soonas the session terminates, so do session servers.

The number of session servers that can be spawned from a parent server is configurable.

Conguration

A server configuration is defined by the server’s server.ini file and server config object.Both are created during the installation procedure for the server and called when theserver is started.

The server.ini file contains information you provide during the installation process,including the repository name and the repository ID. That information allows the serverto access the repository and contact the RDBMS server. The server.ini file also containsthe name of the server’s server config object.


Servers

The properties in the server config object give the server its operating parameters andprovide it with a map to the files and directories that it will access during the course ofits work. For example, the concurrent_sessions property tells the server how manyconcurrent users it can accept.

At startup, a Content Server always reads the CURRENT version of its server configobject.

Multiple servers

The standard, default installation process creates one repository with one server. Afteryou complete the procedure, you can add additional servers for the repository. If youare implementing a configuration that uses a distributed storage area, you will install aserver at the site of each distributed component. You may also want to start additionalservers for load balancing or to enhance performance if a repository is very active orserving many users, or if its users are spread over a wide area.

Servers, connection brokers, and clients

The connection broker is the intermediary between the client and the server when a clientwants a repository connection. If a server is not known to at least one connection broker,no clients can connect to the repository associated with the server.

Each server regularly projects connection information to at least one connection broker.When a client requests a connection to a repository, the connection broker sends theclient the connection information for each server associated with the repository. Theclient can then choose which server to use. Refer to Chapter 6, Connection Brokers, formore information about connection brokers. Clients and client sessions are the subject ofChapter 5, Managing Repository Sessions.

You can configure the server to project information to multiple connection brokers. Youcan also configure how often the server projects information.

The agent exec process

The agent exec process is the process that oversees the execution of jobs Jobs areautomated methods. For information about jobs, refer to Chapter 4, Methods and Jobs.An agent exec process is installed with each Content Server.

When you start a server, the agent exec process is automatically started by aninvocation of the agent_exec_method. The agent_exec_method method is created by the


Servers

headstart.ebs script when you configure the repository, and its name is recorded in theagent_launcher property of the server config object.

The agent exec process runs continuously, polling the repository at specified intervals forjobs to execute. The default polling interval is 60 seconds. The polling interval can bechanged.

If there are multiple jobs to execute, the process runs each job, sleeping for 30 secondsbetween the jobs. By default, the process runs up to three jobs in each polling cycle. Youcan reset the number of jobs executed in each cycle through an argument on the agentexec command line. After the jobs are executed and the polling cycle is complete, theprocess sleeps for the specified interval before polling the repository again.

You can change the agent exec’s polling interval or modify the maximum number ofjobs run in a polling cycle. However, you cannot change the 30-second sleep periodbetween jobs in a polling cycle.

For instructions on changing these configurable defaults, refer to Modifying agent execbehavior, page 154. That section also includes information about turning on tracing forthe agent exec process.

ACS servers

When the first repository is installed and configured in an installation on a host machine,the process also installs an ACS server. This server is used by WDK web-based clientapplications. For information about this server and the configurations that use it, referto the EMC Documentum Distributed Configuration Guide.

JBoss application server

When the first repository is installed and configured in an installation on a host machine,the process also installs a JBoss application server. The application server hosts the JavaMethod Server and other Java-based processes.

For information about starting and stopping the JBoss application server, refer to Startingand stopping the JBoss application server, page 126.


Servers

InternationalizationWhen you install Content Server, the procedure determines the locale of the hostmachine and, based on that locale, sets Content Server’s locale to one of the supportedlocales. The supported locales are:

• English • Swedish

• French • Korean

• Spanish • Chinese

• Italian • Japanese

• German

The procedure also uses the host machine’s locale as the basis for setting some otherconfiguration parameters that define the expected code page for clients and the hostmachine’s operating system. Table 7, page 87 lists these parameters and their defaultsettings for each locale.

Table 7. Locale-based conguration settings by host machine locale

Host machinelocale

Parameter

locale_name default_client_codepage

server_os_codepage

English en ISO-8859–1 ISO-8859–1

French fr ISO-8859–1 ISO-8859–1

Italian it ISO-8859–1 ISO-8859–1

Spanish es ISO-8859–1 ISO-8859–1

German de ISO-8859–1 ISO-8859–1

Swedish sv ISO-8859–1 ISO-8859–1

Japanese ja Shift_JIS On Windows:Shift_JIS

On UNIX: EUC-JP

Korean ko EUC-KR EUC-KR

Chinese zh MS936 MS936

The Content Server uses the UTF-8 code page. If the server_codepage key is set in theserver.ini file, it must be set to UTF-8. While Documentum requires Unicode UTF-8 for


Servers

Content Server’s internal code page, the database (RDBMS) and operating system of theserver’s host machine may use non-Unicode code pages.

On clients, the Shift_JIS code page supports the NEC extensions.

You cannot reset the server’s locale_name, and it is strongly recommended that youdo not reset the default_client_codepage or server_os_codepage. The server uses thevalue in default_client_codepage when communicating with pre-4.2 Documentum clientapplications. Resetting this parameter or server_os_codepage may cause unexpectederrors in how the server handles queries and content files.

The dm_start_repositoryname script (UNIX)Starting a server invokes the dm_start_repositoryname script. The script checks to ensurethat a log directory is defined for the installation, copies any existing log file for the serverto a new location, and then starts the server. The script has an optional argument, -oclean,that removes the files in the server common area if you include it in the command line.

To configure the server being started, the script reads the server.ini file and the serverconfig object referenced in the server.ini file.

The command line that starts the server executable specifies a relative path for the serverexecutable. The script reads the DM_HOME_CURRENT environment variable and setsthe current directory to the directory specified in that variable before executing thecommand line. (DM_HOME_CURRENT is set to $DM_HOME/bin.)

The starting command line contains an argument called -security. This argument is setduring Content Server’s installation to provide an initial security level for the repository.It is read once, the first time you start the first server for the repository. When you runthe script again to restart the server or run an altered script to start additional servers,the -security argument is ignored.

The dm_start_repositoryname script is stored in the $DOCUMENTUM/dba directory.

The server.ini leThe server.ini file contains configuration information used by the server to defineits behavior. The file is stored in %DOCUMENTUM%\dba\config\repository($DOCUMENTUM/dba/config/repository) and is called when the server is started.

The format of the file is:[SERVER_STARTUP]key=value


Servers

[DOCBROKER_PROJECTION_TARGET]key=value

[DOCBROKER_PROJECTION_TARGET_n] #n can be 0-49key=value

[FUNCTION_SPECIFIC_STORAGE] #Oracle & DB2 onlykey=value

[TYPE_SPECIFIC_STORAGE] #Oracle & DB2 onlykey=value

[FUNCTION_EXTENT_SIZE] #Oracle onlykey=value

[TYPE_EXTENT_SIZE] #Oracle onlykey=value

Only the [SERVER_STARTUP] section is required. The other sections are optional.

Changes to the server.ini file take effect only after the server is stopped and restarted.Refer to Restarting a server, page 111 for instructions on restarting the server.

Note: To receive a verbose description of the server.ini file, type the following commandat the operating system prompt:documentum -h

If you want to add a comment to the file, use a semicolon (;) as the comment character.

SERVER_STARTUP section

The keys in the [SERVER_STARTUP] section provide the information the server needs toaccess the repository and the database. When you install the server, you are promptedfor the information to set these keys. The [SERVER_STARTUP] section also contains keysthat provide default operating parameters for the server. You are not prompted for thesevalues. Some are default values and some are optional. You can change the defaults orset optional keys during installation or after the installation process is completed.

Table 8, page 89, lists the keys in the server startup section. The keys are listed inalphabetical order in the table, though they do not appear in that order in an actualserver.ini file.

Table 8. Server.ini SERVER_STARTUP section keys

Key Datatype Comments

acl_update_threshold integer None

check_user_interval integer The default is 100.


Servers


client_session_timeout integer Value is interpreted inminutes.

commit_read_operations Boolean None

concurrent_sessions integer The default is 100.

data_store string Used with DB2 only

database_conn string Required by Oracle andDB2.

Not required by Sybaseand MS SQL Server

database_name string Not required by Oracle andDB2.

Required by Sybase andMS SQL Server.

database_owner string None

database_password_file string None

deferred_update_queue_size integer Default value is 1000. Validrange is 256 to 4096. Fordetails, refer to deferred_update_queue_size, page107.

distinct_query_results Boolean None

docbase_id integer None

docbase_name string None

enforce_four_digit_year Boolean The default in a newrepository is T.

gethostbyaddr Boolean None

history_cuttoff integer None

history_sessions integer None

host string None

ignore_client_domain Boolean Used on Windowsplatforms only

index_store string Used with DB2 only

install_owner string Unused. The server configsetting is used instead.


Servers


ip_mode string Specifies whetherContent Server supportsIP addresses in IPv6format. Valid valuesare DUALSTACK andV4ONLY. The defaultvalue is DUALSTACK,meaning that ContentServer accepts both IPv4and IPv6 addresses.

listener_queue_length integer For Windows platformsonly. Refer to Specifyingqueue size for incomingconnection requests(Windows only), page118, for details.

mail_notification Boolean None

max_nqa_string integer Defines the maximumlength of a non-qualifiablestring property, in bytes.

The default is 2000.

If this is not set, the defaultis the maximum lengthallowed by the underlyingrelational database.

max_ftacl_cache_size integer Limits the numberof elements cachedper session to processFTDQL-compliant full-textqueries.

max_session_heap_size integer None

max_storage_info_count integer Defines the maximumnumber of storage areasfor which Content Servermaintains informationin shared memory. Thedefault is 100. Valid valuesare positive integers from100 to 65535.


Servers


method_server_enabled Boolean The default is T (TRUE).

method_server_threads integer The default is 5.

owner_xpermit_default string This has one valid value:acl

owner_xpermit_default,page 101, describes thekey’s use.

preserve_existing_types Boolean None

rdbms_connect_retry_timeout integer None

root_secure_validator string

saveasnew_retain_source_group Boolean Controls which group isset as default group foran object created with aSaveasnew method.

server_codepage string UTF-8 is the only allowedvalue

server_config_name string None

server_login_ticket_version integer Controls format ofgenerated login ticket, forbackwards compatibility.Refer to Configuring logintickets for backwardscompatibility, page 173, fordetails.

server_startup_sleep_time integer None

service string Service name for therepository

start_index_agents Boolean The default is T (TRUE).

thread_lock_timeout integer None

ticket_multiplier integer Refer to Setting the ticketcache size for ContentServer, page 173 forinformation about this key.


Servers


umask string(4) This is supported forUNIX platforms only.Refer to Changing defaultoperating system permitson directories and files(UNIX only), page 109 forinformation about its use.

update_access_date Boolean None

upd_last_chg_time_from_db Boolean None

use_estimate_search Boolean None

use_group_address integer Configures who receivesemail notifications whenan event is queued to agroup. For details, refer touse_group_address, page102.

user_auth_case string None

user_auth_target string Used on Windowsplatforms only

validate_database_user Boolean Controls whether ContentServer checks for a valid OSaccount for the databaseowner’s user account.

wait_for_connect_timeout integer None

DOCBROKER_PROJECTION_TARGET sections

The [DOCBROKER_PROJECTION_TARGET] and [DOCBROKER_PROJECTION_TARGET_n] sections define the connection brokers to which the server sends itsconnection information. When you install Content Server, the procedure creates one[DOCBROKER_PROJECTION_TARGET] section in the server.ini file, which containsaccess information needed for a server’s first broadcast to a connection broker. In thatfirst section, the host key is set to the connection broker name you provide during theinstallation. The proximity key is set to a default value of 1. When the server is started atthe end of the installation procedure, it projects connection information to the connectionbroker specified in the host key.


Servers

Connection broker projection targets are also defined in a set of properties in the serverconfig object. Use the server config properties to define additional projection targets,rather than the server.ini. This method enables you to change a target without restartingthe server. If the same projection target is defined in both the server config propertiesand in the server.ini file, the values for the target in the server config properties are used.

The [DOCBROKER_PROJECTION_TARGET] section defines the first projection target.To define additional targets, use [DOCBROKER_PROJECTION_TARGET_n] sections.The n can be any integer from 0 to 49. Refer to Defining connection broker projectiontargets, page 114, for instructions about defining these sections.

Table 9, page 94 lists the keys for these sections.

Table 9. Server.ini DOCBROKER_PROJECTION_TARGET keys


host string Name of connection broker host

port integer Port number used by the connection broker

proximity integer User-defined value that represents distanceof server from connection broker

FUNCTION_SPECIFIC_STORAGE and TYPE_SPECIFIC_STORAGE sections

The [FUNCTION_SPECIFIC_STORAGE] and [TYPE_SPECIFIC_STORAGE] sectionsdefine which tablespace or device will store the RDBMS tables and indexes for objecttypes. These sections are available only for Oracle and DB2 and must be defined whenContent Server is installed. For information about using these sections, refer to ContentServer Installation Guide.

Table 10, page 94 lists the keys for a FUNCTION_SPECIFIC_STORAGE section.

Table 10. Server.ini FUNCTION_SPECIFIC_STORAGE keys


database_table_large string Name of a tablespace

database_table_small string Name of a tablespace

database_index_large string Name of a tablespace

database_index_small string Name of a tablespace

Table 11, page 95 lists the keys for a TYPE_SPECIFIC_STORAGE section.


Servers

Table 11. Server.ini TYPE_SPECIFIC_STORAGE keys

Key Datatype Comnents

database_table_typename string The key is set to the name of atablespace. Replace typename withthe name of the object type.

database_index_typename string The key is set to the name of atablespace. Replace typename withthe name of the object type.

FUNCTION_EXTENT_SIZE and TYPE_EXTENT_SIZEsections

The [FUNCTION_EXTENT_SIZE] and [TYPE_EXTENT_SIZE] sections determine howmuch space is allocated in the RDBMS for the object type tables. They are available onlyfor Oracle and must be defined when the repository is installed. For information aboutusing these sections, refer to Content Server Installation Guide.

Table 12, page 95, lists the keys for the FUNCTION_EXTENT_SIZE section.

Table 12. Server.ini FUNCTION_EXTENT_SIZE keys


database_ini_ext_large integer None

database_ini_ext_small integer None

database_ini_ext_default integer None

database_next_ext_large integer None

database_next_ext_small integer None

database_next_ext_default integer None

Table 13, page 95, lists the keys for the TYPE_EXTENT_SIZE section.

Table 13. Server.ini TYPE_EXTENT_SIZE keys


database_ini_ext_typename integer Replace typename with the nameof the object type.

database_next_ext_typename integer Replace typename with the nameof the object type.


Servers

Keys set during installation

The keys described in this section derive their settings from information you provideduring the server installation procedure.

docbase_id

The docbase_id key contains the repository ID. You will find a range of valid valuesenclosed in the box with your software. Use one of the numbers in the range you havebeen assigned. If you have other repositories at your site, the number you select must beunique among all the repositories.

docbase_name

The docbase_name key contains the name you choose for your repository.

database_owner

The database_owner key contains the RDBMS login name of the repository’s owner.

database_conn

The database_conn key contains the database connection string, which is used by theserver to connect with the RDBMS server. This value is required by Oracle and DB2.

Oracle database_conn value

The database_conn value is the alias for the Oracle database. The alias is defined in a filecalled tnsnames.ora. Here is a sample entry in this file:production=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=muskox)(PORT=1232))(CONNECT_DATA=


Servers

(SID=ORC)))

The alias is the name specified on the first line. In the example above, the alias isproduction. Ask your Oracle System Administrator or DBA for the alias for the databasethat contains your repository’s tablespace.

Sybase database_conn value

The database_conn value is the name of the Sybase server.

MS SQLServer database_conn value

The database_conn value is the ODBC Data Source Name assigned to the SQLServer.This name can be found by double-clicking the ODBC Data Sources icon in the ControlPanel.

DB2 database_conn value

The database_conn value is the name of the DB2 database on which the repository isrunning.

database_name

The database_name key identifies your tablespace or database in the RDBMS. This key isrequired by Sybase and MS SQL Server. Oracle and DB2 do not use this key.

Sybase database_name value

The database_name is the name of the Sybase database corresponding to your repository.

MS SQL Server database_name value

The database_name is the name of the SQL Server database corresponding to yourrepository.


Servers

service

The service key contains the TCP/IP service name for the Content Server. The value isthe service name that appears in the server host machine’s services file. If a repositoryhas multiple servers, this name must be unique for each server.

You can specify multiple service names, but the services must be running on the samehost machine. Separate the service names with commas. (Supplying multiple names isa failover mechanism.)

host

The host key specifies an IP address on which the server will listen. Some host machineshave multiple network cards. If you want the server to use a particular network card onthe host machine, specify the card’s IP address in this key before starting the server.

Optional keys

You are not prompted for values for these keys. Some are given default values duringthe installation procedure and some are not. You can set them during the installationprocedure by modifying the server.ini file before the server is started. Some can also beset after the procedure is finished. Refer to Modifying the server.ini file, page 110, forinformation about changing a server.ini file.

acl_update_threshold

The acl_update_threshold key, if set, is used when the permission granted to dm_worldin an ACL is updated. Setting acl_update_threshold improves performance of theupdate.

Changing the dm_world permission in an ACL (or adding an entry for dm_world) maycause Content Server to set the r_is_public property for any objects using the ACL.Changes to r_is_public may require related changes to associated content objects.

If acl_update_threshold is not set, Content Server iterates through and updates the entiredmr_content object type table. If the key is set and the affected rows are fewer than thekey value, only the affected rows are updated, which improves performance. However,if the number of affected rows is larger than the threshold set, Content Server ignores thekey value and updates the entire table.


Servers

check_user_interval

The check_user_interval key defines the frequency, in seconds, with which ContentServer checks the session user’s login status for changes.

The default value is 0, meaning that the user’s status is checked only at connection time.

commit_read_operations

The commit_read_operations key controls whether an explicit commit call is performedafter each read-only repository operation is completed. Under the default setting, TRUE,a commit is issued after each read-only repository operation, with two exceptions:• When the operation is part of a multi-statement transaction

In this case, the commit must be issued by the caller.• When a collection is open

In this case, the commit is issued when the last collection is closed.FALSE means that all update operations are committed when they are complete andread operations execute under the assumption that the RDBMS will release locksautomatically at the end of the operation.

data_store and index_store

The data_store and index_store keys are used only by installations running on DB2. Thedata_store key identifies the tablespace in which the repository tables are to be stored.The index_store key identifies the tablespace in which the type index tables are to bestored.

By default, these keys are set to the default tablespace of the user performing therepository configuration. You can change the default during repository configuration ifyou use the custom configuration option to configure the repository. The behavior whenyou set these keys is as follows:• If you set data_store and do not set index_store, the system creates both the object

type tables and the index tables in the tablespace defined by data_store.• If you set index_store and do not set data_store, the system creates the indexes in

the tablespace defined by index_store and creates the object type tables in the user’sdefault tablespace.

• If you set both keys, the system creates the object type tables in the tablespacespecified in data_store and the indexes in the tablespace specified in index_store.

Note: On DB2, you cannot move indexes after the index tables are created.


Servers

If you uninstall a DB2 repository with separate tablespaces for the object type andindex tables, the procedure does not destroy the tablespaces, nor does it destroy all therepository tables. It destroys only the following repository tables:• dmi_vstamp• dmi_object• dmi_object_type

gethostbyaddr

The gethostbyaddr key determines whether the server calls the gethostbyaddr() functionto obtain the host name of the machine on which a client application resides. By default,this key is TRUE.

If a large number of your client machines do not have names, set this to FALSE to skipthe calls to gethostbyaddr during connection requests, resulting in better performancefor connection requests. The server uses client host addresses instead of names.

history_sessions and history_cutoff

The history_sessions key defines the number of maximum historical sessions (timed-outsessions) the LIST_SESSIONS function will return. Use the apply method or theEXECUTE statement to run LIST_SESSIONS. The DQL Reference Manual containsadditional information about the LIST_SESSIONS function.

The history_cutoff key specifies a cut-off time for historical sessions in minutes. Forexample, if you set history_cutoff to 15, then the server will not return any historicalsession older than 15 minutes, even if the maximum number of sessions defined inhistory_sessions has not been reached.

The default for history_cutoff is 240 minutes.

max_ftacl_cache_size

Content Server caches ACL information on objects to evaluate security on the resultsreturned by full-text queries. The max_ftacl_cache_size key defines the number ofelements cached.

The default value is -1 (no limit set). If the value is set to 0, no security information iscached. The value may be set to any integer greater than -1. It is recommended that youdo not change the default value.


Servers

max_nqa_string

The max_nqa_string key defines the maximum length of a non-qualifiable stringproperty. The value defaults to 2000 if not set. Nonqualifiable properties are stored inthe i_property_bag property of an object. For more information about nonqualifiableproperties and the property bag, refer to Content Server Fundamentals.

max_sessions_heap_size

The max_sessions_heap_size key allows you to control the size of a session’s memoryusage. This number is expressed in bytes.

The default value is -1. The heap will grow as necessary to whatever size the servermachine resources will allow, up to a server’s addressing limits of 2 GB of memory.

owner_xpermit_default

The owner_xpermit_default key controls whether object owners have all available defaultextended permissions for an object or only those explicitly assigned to the owners.

If the key is set to acl, object owners have only the extended permissions assignedexplicitly. The owners are not granted default extended permissions. If the key is not set,object owners have all extended permissions available to object owners by default.

saveasnew_retain_source_group

The saveasnew_retain_source_group key controls which default group is assigned to anew object created by a IDfSysObject.saveAsNew method. If the key is set to T (TRUE),the new object is assigned to the default group of the original (source) object. If the key isset to F (FALSE), the new object is assigned to the default group of the user who issuesthe saveAsNew method. The default is F.

umask (UNIX only)

The umask server.ini key modifies the default operating system permissions assignedto public directories and files created by Content Server in the server or repositoryinstallation. For example, this affects the storage area directories and the full text indexdirectories, as well as the files written to those directories.


Servers

Note: If umask is not set, the default operating system permissions are 777 for directoriesand 666 for files.

The umask key works similarly to the UNIX umask functionality. The value youassign to the key is subtracted from the default permissions to determine the actualpermissions assigned to a file or directory. For example, if you set umask=2, then thedefault permissions assigned to directories becomes 775 and the default permissionsfor files becomes 664. Or, if you set umask=22, then the permissions become 755 fordirectories and 644 for files.

upd_last_chg_time_from_db

The upd_last_chg_time_from_db key is used to ensure that all Content Servers in aclustered environment have timely access to all changes in group membership. Thedefault value is F (FALSE). Set upd_last_chg_time_from_db to T (TRUE) only in anenvironment where multiple servers run against a repository. In such an environment,set the key to T for all running Content Servers.

use_group_address

The use_group_address key controls who receives the email notifications when an eventis queued to a group. Valid values and their associated behaviors are:• 0, which directs the server to send email to each member of the group. This is the

default setting.• 1, which directs the server to send email to the group’s address (identified in the

group’s group_address property). If the group has no email address, the serversends notifications to each member of the group.

• 2, which directs the server to send email to each member of the group and to thegroup address, if it exists.

validate_database_user

The validate_database_user key controls whether Content Server validates that the useridentified in the database_owner key in the server.ini file has a valid operating systemuser account. The default value is T (TRUE), meaning that the existence of a OS accountfor the database owner is validated.


Servers

Default keys

During the server installation procedure, default values are assigned to the keysdescribed in this section. You are not prompted for their values. You can change thesevalues at any time.

client_session_timeout

The client_session_timeout key defines how long the server waits for a communicationfrom a client session before disconnecting the session.

The default value is 5 minutes.

concurrent_sessions

The concurrent_sessions key controls the number of connections the server can handleconcurrently. This number must take into account not only the number of users who willbe using Documentum concurrently, but also what kinds of operations those users willbe executing. Some operations require a separate connection to complete the operation.For example:• Issuing an IDfQuery.execute method with the readquery flag set to FALSE causes

an internal connection request.• Executing an apply method or an EXECUTE DQL statement starts another

connection.• When the agent exec executes a job, it generally requires two additional connections.• Issuing a full-text query requires an additional connection.The default value is 100. Consider the number of active concurrent users you expect, theoperations you think they will be performing, and the number of methods or jobs youexecute regularly, and then modify this value accordingly.

The maximum number of concurrent sessions is dependent on the operating systemof the server host machine. The limit is:• 1022 for Solaris and AIX platforms• 2046 for HP-UX• 1024 for Windows systems


Servers

database_refresh_interval

The database_refresh_interval key defines how often the main server thread (parentserver) reads the repository to refresh its global caches. You can raise this value but itcannot be lowered.

The default value is 1 minute.

distinct_query_results

The distinct_query_results key tells the server whether to return duplicate rows inqueries. FALSE tells the server to include duplicate rows in query results. TRUE tells theserver to return only distinct rows (no duplicates).

If NOFTDQL hint is specified for a query and the distinct_query_results flag is set toTRUE, only unique results are returned by the query. If the identical query is executedin FTDQL and the distinct_query_results key is set to TRUE, the setting of the key isignored and all results of the query are returned, including duplicate results.

The default value is FALSE.

enforce_four_digit_year

Set to TRUE, the enforce_four_digit_year key directs the server to set or display datesusing four digits for the year if the user does not specify a date format.

The default value is TRUE.

ignore_client_domain (Windows only)

The ignore_client_domain key indicates whether the server ignores the domain passed toit by the client during a connection request. TRUE directs the server to ignore the clientdomain and use the domain specified in user_auth_target for all user authentications.FALSE directs the server to use the client domain passed in a connection request.

The default value is FALSE.


Servers

mail_notication

The mail notification key is a Boolean key that controls whether email messages are sentwhen a work item or an event is queued. If this is set to FALSE, the email messagesare not sent to the users.


max_storage_info_count

The maximum storage information count key defines the maximum number of storageareas for which Content Server maintains information in shared memory. Valid valuesare positive integers from 100 to 65535. The value defined by the key does not limit thenumber of storage areas you can create. For example, if the key is set to 150 and youalready have 150 storage areas, you can create additional storage areas, but informationfor the additional storage areas is not maintained in memory.

In a multiserver environment, ensure that this key is set to the same value for all ContentServers.

The default value is 100.

method_server_enabled

The method_server_enabled key is a Boolean key that controls whether the methodserver or the Java method server may be used to execute dm_method objects. Thedefault value is T (TRUE), meaning that dm_method objects that are configured toexecute through the method server do so with no further configuration needed. If themethod_server_enabled is set to F (FALSE), the methods are executed through ContentServer.

Note: Enabling the method server alone does not cause dm_method objects to beexecuted by the method server or Java method server. The method objects must also beconfigured correctly. For more information, refer to Creating a method object, page 143.

method_server_threads

The method_server_threads key defines the maximum number of method server workerprocesses that are available to execute method objects. The default (and minimum)value is 5. The maximum value for this key is the value set in the concurrent_sessionsproperty of the server config object.


Servers

preserve_existing_types

When a server starts, it queries the RDBMS to determine if the object type tables arepresent for all the object types defined in the server.

The default value is TRUE, meaning the server does not dynamically destroy andre-create object type tables for types that are erroneously reported missing by theRDBMS.

If this flag is set to FALSE, the server does dynamically destroy and re-create object typetables for types that are erroneously reported missing by the RDBMS.

rdbms_connect_retry_timeout

The rdbms_connect_retry_timeout key determines how long the server tries to connectto the RDBMS. The server attempts to connect every 30 seconds until it is successfulor the time-out limit is reached.

The default time-out value is 5 minutes.

server_cong_name

The server_config_name key identifies which server config object is used to startthe server. When you install Content Server, the procedure assigns the name of therepository to the server config object generated for the server.

The default value is the name of the repository.

server_startup_sleep_time

The server_startup_sleep_time key specifies the amount of time, in seconds, thatContent Server waits before trying to connect to the RDBMS. The time delay allows theunderlying RDBMS to start before Content Server attempts to connect.



Servers

start_index_agents

The start_index_agents key indicates whether Content Server starts configured indexagent instances at Content Server startup.


ticket_multiplier

The ticket_multiplier key determines the number of login tickets with server scopeallocated in shared memory. The number of tickets allocated by the server is computedas follows:

#tickets = concurrent_sessions * ticket_multiplier


deferred_update_queue_size

The deferred_update_queue_size key controls the size of the deferred object updaterecord queue. The queue is set to 1000 by default when Content Server is installed. Thevalid range for this parameter is 256 to 4096.

If repository operations generate a large number of deferred object updates, you maywant to increase this queue size. If the queue fills up, the deferred updates are performedimmediately, which may impact performance of an application.

update_access_date

The update_access_ date key indicates whether the r_access_date property is updated inthe deferred update process. TRUE directs the server to update the property as part ofthe deferred update process. FALSE directs the server not to update the property.



Servers

user_auth_case

The user_auth_case key indicates the case (upper, lower, or unspecified) to which theserver should convert the client’s username before authenticating the user. Valid settingsare:• upper• lower• NULLThe default is NULL, which means the name is authenticated using the case in which itwas entered by the user.

user_auth_target (Windows only)

The user_auth_target key identifies the domain or default LDAP server that ContentServer uses to authenticate the client’s username and password.

The default is the domain in which the server resides.

use_estimate_search

The use_estimate_search key controls whether users can execute theESTIMATE_SEARCH administration method. The administration method is used tofine-tune SEARCH conditions for queries. FALSE means that the method will notexecute if a user tries to use the method. TRUE allows the method to execute.

The default value is T (TRUE).

wait_for_connect_timeout

The wait_for_connect_timeout key defines how long the server waits for a connectionrequest before starting to process other work, such as deferred updates.

The default value is 10 seconds.


Servers

Moving the server executable (UNIX only)The Content Server installation procedure places the server executable in the$DM_HOME/bin directory. If you move the executable to another directory, you mustmodify the DM_HOME_CURRENT variable in the dm_start_repositoryname script ormodify the command line in the script that references the executable.

The command line references the executable by using a relative path. The script sets thecurrent directory to the directory specified in DM_HOME_CURRENT before executingthe command line.

If you change DM_HOME_CURRENT to the new location of the executable, the scriptuses that location as the current directory when it executes the command line.

Alternatively, you can replace the ./ in the command line with the full pathto the executable’s new location. In this case, the script ignores the setting ofDM_HOME_CURRENT.

Changing default operating system permits ondirectories and les (UNIX only)

When Content Server creates directories and files in the server installation, it assignsdefault operating system permissions to those directories and files. The defaultpermissions assigned to directories are 777 and the default permissions assigned to filesare 666. You can change the defaults assigned to public directories and files by settingthe umask key in the server.ini file. Setting umask affects all public directories andfiles created after the key is set.

The umask value works similarly to the UNIX umask functionality. The value issubtracted from the default permissions to determine the actual permissions assignedto a file or directory. For example, if you set umask=2, then the default permissionsassigned to directories becomes 775 and the default permissions for files becomes 664.Or, if you set umask=22, then the permissions become 755 for directories and 644 for files.

Changing a server’s congurationDepending on what you are changing in the server’s configuration, modify either theserver.ini file or the server config object.


Servers

Modifying the server.ini le

To change the server.ini file, you must have appropriate access privileges for the%DOCUMENTUM%\dba\config\repository ($DOCUMENTUM/dba/config/repository)directory in which the file resides. Typically, only the installation owner can accessthis directory.

To modify the server.ini le:1. Open the server.ini file.

On UNIX, use the text editor of your choice.On Windows:

a. Navigate to Start > Programs > Documentum > Content Server Manager.

b. Select the repositories tab.

c. Select the repository associated with the server. ini file.

d. Click Edit Server.ini.

2. Make the changes.

3. Save the file.

4. Stop and restart the server to make the changes visible.

Modifying the server cong object

The server startup procedure always uses the CURRENT version of the server configobject.

To change the server config object, you must have Sysadmin or Superuser privileges.

Use Documentum Administrator to modify the server config object. For instructions onusing Documentum Administrator, refer to the Documentum Administrator online help.

Setting the secure connection modeWhen you install a Content Server, two service names and associated ports are defined.One port is a native, or unsecure port, the other is a secure port. For more informationabout the service names and their ports, refer to Content Server Installation Guide. Duringthe installation process, you are asked what connection mode you want for the server.There are three valid modes:


Servers

• Native: The server listens on an unsecure port. Connection requests from clientsthat ask for a secure connection will fail.

• Secure: The server listens only on a secure port. Connection requests from clientsthat ask for a native connection will fail.

• Native and secure: The server listens on both a native and a secure port. Connectionrequests from clients asking for either type of connection are accepted.

To change the secure connection mode for the server, reset the secure_connect_modeproperty in the server’s server config object. You can use Documentum Administratoror DQL to reset the secure_connect_mode property. You must restart the server afterresetting the secure_connect_mode property.

Note: Do not set the mode to secure if you have pre-5.2 clients connecting to therepository. The connection requests from such clients will fail.

Restarting a serverHow you restart a server depends on the repository configuration.

If a repository has other active servers, use Documentum Administrator to restart theserver. For instructions, refer to the Documentum Administrator online help.

If a repository has only one server or if all servers for a repository are shut down, use thefollowing procedure to restart a server for the repository.

Use the following procedure for servers on a Windows host.

To restart a server using Content Server Manager:1. Log into the machine where Content Server is installed as the Documentum

installation owner.

2. Navigate to Start > Programs > Documentum > Documentum Content ServerManager.

3. Select the repositories tab.

4. Click Start.Use the following procedure for servers on a UNIX host.

To restart a server using the startup script (UNIX):1. Log into the machine where Content Server is installed as the Documentum

installation owner.

2. Change to the $DOCUMENTUM/dba directory.

3. Run the dm_start_repositoryname script that references the server to start.


Servers

Starting additional serversYou can start additional servers for a repository on different machines or the samemachine. The service name for each server must be unique within the networkconnecting the machines and that service name must be referenced in the serviceproperty of the server.ini file invoked for the server.

Caution: Do not use the instructions in this section to set up servers for asingle-repository distributed configuration. Setting up a single-repositorydistributed configuration requires more than changing the configuration of theserver. Refer to the Distributed Configuration Guide for those instructions.

Servers servicing one repository must be all non-trusted servers or all trusted servers.You cannot have trusted and non-trusted servers servicing one repository.

On a Windows host, each server must have its own server config object and server.inifile. Creating a new server using Documentum Administrator automatically createsthem for you.

On a UNIX host, each server must have its own server config object and server.ini file,and start up script. You may also want a shutdown script for each server. Creating thenew server using Documentum Administrator automatically creates the server configobject, the server.ini file, and the start up script. You must manually create the shutdownscript.

A server-specific server config object is needed because each server must referencelocal copies of the assume user, check password, change password, and secure writerprograms. These programs are located by a server through location objects defined in itsserver config object. If the servers are in different geographical locations, there are alsoseveral other configuration settings you will probably change.

A server-specific server.ini file is needed because the file references the server configobject. When a server is started, the server.ini file is read and the appropriate serverconfig object must be invoked.

Conguration requirementsNote: For information about starting additional servers on existing Content Server hosts,refer to the Appendix titled “Configuring Multiple Servers in the Same Installation” inthe Content Server Installation Guide.

The following configuration requirements must be met to run multiple servers for thesame repository:


Servers

• Windows-specific requirements:

— All machines running a Content Server for a particular repository must be inthe same domain.

— The primary host’s installation account must be in the domain’s administratorsgroup.

— The program SC.EXE must be installed in %SystemRoot%\System32\SC.EXE.

SC.EXE is available on the Windows SDK CD. It is used to create and startservices for Documentum servers.

• UNIX-specific requirements:

— The primary server’s installation account must have sufficient privilege toexecute remsh commands.

— The primary host must be able to resolve target machine names through the/etc/hosts file or DNS.

— Each target machine must be able to resolve the primary host name through the/etc/hosts file or DNS.

— If you intend to use Documentum Administrator’s Server Management featureto create and start a new, remote server, there are some additional configurationrequirements. Refer to Documentum Administrator online help for details.

• General requirements for all platforms:

— The Documentum installation accounts for each site must be known to all hosts.

It is recommended that each site use the same account as the installation account.

— The servers must all be non-trusted servers or all trusted servers.

Creating a shut-down script (UNIX only)

Use the instructions in this section to create a server-specific shut-down script.

To create a dm_shutdown_repository script for a new server:1. Make a copy of an existing dm_shutdown_repository script and give the copy a new

name.dm_shutdown_repository scripts are found in $DOCUMENTUM/dba.For example:% cd $DOCUMENTUM/dba% cp dm_shutdown_engrrepository dm_shutdown_devrepository1


Servers

2. In the new copy, edit the line immediately preceding shutdown,c,T by replacingrepository namewith repository_name.server_config_name.The line you want to edit looks like this:./iapi <repository name> -U$DM_DMADMIN_USER -P -e << EOF

Use the name of the server config object that you created for the server. For example:./iapi devrepository2.server2 -U$DM_DMADMIN_USER -P -e << EOF

3. Save the file.

Communicating with connection brokersThe connection broker is the intermediary between clients and servers for all connectionrequests. Content Servers must regularly broadcast, or project, connection informationto at least one connection broker to be considered active.

Server broadcasts are called checkpoints, and the interval between the checkpoints isconfigurable. Refer to Setting the checkpoint interval, page 116 for instructions. Theconnection brokers receiving the checkpoints are called connection broker projectiontargets.

In addition to the connection information, the server sends each projection target aproximity value. This value describes the server’s proximity to the connection broker.The connection broker passes the proximity value to clients so they can decide whichserver to use.

The connection broker keeps a server’s connection information for a length of time calledthe keep entry interval. This is a configurable interval. Refer to Setting the keep entryinterval, page 116 for instructions.

Dening connection broker projection targets

Connection broker projection targets are defined in either the server config object orthe server.ini file. If you define projection targets in the server config object, you canmodify the targets, add a new target, or remove a target and implement the changes byreinitializing the server. If you define the projection targets in the server.ini file, youmust stop and restart the server to implement the changes.

Note: By default, when you install remote Content Servers, they are configured withdefault projection targets and proximity values. A Content Server at a remote site isconfigured to project to its local connection broker and the connection broker at theprimary site. Its proximity value for the local connection broker is 9001 and the valueprojected to the primary site is 9010.


Servers

If you define the same connection broker projection target in both the server config objectand the server.ini file, the definition in the server config object overrides the definition inthe server.ini file.

The Content Server installation procedure defines one connection broker projectiontarget in the server.ini file. The target is the connection broker you specify during theinstallation procedure. When the installation procedure is complete, you can move thetarget definition to the server config object.

Denitions in the server cong object

The following repeating properties in the server config object store connection brokerprojection target definitions:• projection_targets

The projection_targets property contains the name of the host machine on whichthe connection broker resides.

• projection_ports

The projection_ports property contains the port number on which the connectionbroker is listening.

• projection_proxval

The projection_proxval property contains the proximity value that the server projectsto the connection broker.

• projection_enable

The projection_enable property determines whether the server projects to theconnection broker. If it is set to TRUE, the server projects to the connection broker. Ifit is set to FALSE, the server does not project to the connection broker.

• projection_notes

The projection_notes property is a place for you to record short notes about thetarget. The property is 80 characters long.

The values at the same index positions across the properties represent the definition ofone connection broker projection target. For example, suppose you want to define asecond projection target for server_1. The target connection broker resides on bigdog,and you want to project a proximity value of 10 to the connection broker for the server.Set the properties in server_1’s server config object to the following values:projection_targets[1]=bigdogprojection_ports[1]=1489projection_proxval[1]=10projection_enable[1]=Tprojection_notes[1]=your comments


Servers

Use Documentum Administrator to modify the server config object to set the properties.For instructions, refer to the Documentum Administrator online help.

Denitions in the server.ini le

Connection broker projection targets are identified in the server.ini file in one or more[DOCBROKER_PROJECTION_TARGET] sections.

The format for the first target definition is:[DOCBROKER_PROJECTION_TARGET]host=connection broker host nameport=connection broker port numberproximity=proximity_value

The sections for additional definitions differ only in the addition of an index value to thetitle of the section:[DOCBROKER_PROJECTION_TARGET_n]...

where n is an integer from 0 to 49. You can include a maximum of 50 sections.

Setting the checkpoint interval

A checkpoint interval defines how often a server broadcasts service information toconnection brokers. Checkpoint intervals are defined in the checkpoint_intervalproperty in the server’s server config object. You can set the checkpoint interval usingDocumentum Administrator.

Use Documentum Administrator to modify the server config object to set the checkpointinterval. For instructions on using Documentum Administrator to modify the serverconfig object, refer to the Documentum Administrator online help.

Setting the keep entry interval

Each connection broker is told how long it can keep a server entry if it does notreceive checkpoint broadcasts from the server. This time limit is defined in thekeep_entry_interval property of a server’s server config object and is included in theserver’s checkpoint information. By default, the keep entry interval is set to 24 hours(expressed in minutes).


Servers

Use Documentum Administrator to modify the server config object to set the keep entryinterval. For instructions on using Documentum Administrator to modify the serverconfig object, refer to the Documentum Administrator online help.

Dening server proximity

Servers send a proximity value to each connection broker projection target. Theproximity value represents the server’s physical proximity to the connection broker.

When clients receive server information from a connection broker, by default they chooseto connect to the server with the smallest proximity value (representing the closestavailable server). For example, assume a client gets information about servers A, B, andC. The proximity value is 2 for A, 4 for B, and 5 for C. The client will attempt to connectto server A because that server has the lowest proximity value. If two or more servershave the same lowest value (for example, if both servers A and B have a value of 2) thenthe client makes a random choice between the servers.

Note: Clients and users can override this default behavior by specifying either a serveror host machine when requesting a connection.

The proximity values should reflect the topology of your installation. For example, ifyou have three servers and one connection broker, the server closest to the connectionbroker should project the lowest proximity value to the connection broker. The serverfarthest from the connection broker should project the highest proximity value to theconnection broker.

An individual server that has multiple connection broker projection targets can project adifferent proximity value to each target.

Guidelines for setting proximity values are:• Use proximity values in the range of 1 to 999 unless you are setting up content

servers for a distributed configuration.• Any server with a proximity value of 9000 to 9999 is considered a content server and

typically will only be used to handle content requests.

For information about content and data servers and how to set them up, refer to theDistributed Configuration Guide.

• If you specify a value between 1001 and 8999, the fourth digit (counting from theright) is ignored and only the first three digits are used.

For example, if you define a proximity value of 8245, clients ignore the 8 and onlyconsider 245 the proximity value.


Servers

• On Windows platforms, proximity values of 10,000 and over are considered torepresent servers in another domain.

Users who want to connect to such servers must specify them by name in theConnect command line.

Specifying queue size for incoming connectionrequests (Windows only)

Content Server creates a socket listener for incoming connection requests with amaximum backlog set to 200 by default. On Windows platforms, you can reset thatmaximum if needed. To do so, set the listener_queue_length key in the server.ini file.Set the key to a positive integer value. Content Server passes the specified value tothe Windows Sockets call listen().

Shutting down a serverOn Windows platforms, you can use Documentum Content Server Manager, theWindows user interface, or an IDfSession.shutdown method to shut down a server ifit is the only active server for a repository. On UNIX, use the dm_shutdown_repositoryscript or the shutdown method.

Caution: On Windows platforms, using an IDfSession.shutdown method, whilepossible, is not recommended. The method does not use the Windows servicemanager to shut down the server and, consequently, may not shut down all relevantprocesses. Using the DocumentumContent Server Manager or theWindows servicemanager to shut down a server on a Windows host is the recommended procedure.

On either platform, if the repository has multiple active servers, use DocumentumAdministrator to shut down one of the servers. For instructions, refer to theDocumentum Administrator online help.

You must have Sysadmin or Superuser user privileges to stop a server.

The procedures in this section shut down the main server thread (parent server). To stopa session server, refer to Stopping a session server, page 120, for instructions.


Servers

Using the dm_shutdown_repository script (UNIX only)

The dm_shutdown_repository script logs into the specified repository and issues ashutdown request. The script waits 90 seconds before exiting. If the repository shutsdown more quickly, the script exits as soon as the server is down. This script is usefulwhen you want to shut down the server as part of a program or application, withouthuman intervention.

You must run the script on the machine where the server resides. To invoke the script,issue the command:dm_shutdown_docbase [-k]

where docbase is the name of the server’s repository. The -k flag instructs the script toissue an operating-system kill command to stop the server if the shutdown request hasnot been completed in 90 seconds.

Using the Documentum Content Server Manager(Windows only)

To shut down a server using the Content Server Manager:1. Navigate to Start > Programs > Documentum > Documentum Content Server

Manager.

2. Select the Repositories tab.

3. Select the repository from the list of repositories.

4. Click Stop.

Using the Windows user interface (Windows only)

Content Server is installed as a Windows service. You can use the Windows ServiceControl Panel to stop the server.

To stop a server using the Service Control Panel:1. Double-click the Control Panel icon in the Main group.

The Control Panel window appears.

2. Double-click the Services icon in the Control Panel window.The Services window appears.

3. Select the server.


Servers

4. Click Stop.

Using the shutdown method

Using the IDfSession.shutdown method provides additional options. The method can:• Shut down the server immediately, without waiting for currently connected users

to finish.• Shut down the server after all sessions finish their current transaction.• Direct the connection broker to delete its information about the server.These options are implemented by two arguments to the shutdown method: immediateand deleteEntry.

By default, the method waits until all current transactions are finished before stoppingthe server. If you want to stop the server immediately, issue the method with theimmediate argument set to T (TRUE).

When you shut down a server by using the shutdown method, the server sends theconnection broker a message that it is shutting down. If you intend to restart theserver, you want the connection broker to retain the information it has about the server.However, if you are shutting down the server permanently, you want the connectionbroker to remove information about the server. To accomplish this, set the deleteEntryflag to T (TRUE).

Both of these arguments are FALSE by default.

Stopping a session serverUse a kill method to shut down a session server. To use kill, you must have Sysadminor Superuser privileges. You also need the session ID of the session you want to stop.You can obtain this ID using the LIST_SESSIONS or SHOW_SESSIONS administrationmethod. TheDQL Reference Manual contains more information about the LIST_SESSIONSand SHOW_SESSIONS administration methods.

You can terminate a session in one of three ways:• The default kill

The default kill provides the least disruption to the end user. The targeted sessionterminates when it has no more open transactions and no more open collections.The client remains functional.


Servers

• An After current request kill

An after current request kill provides a safe and more immediate means ofterminating a session. If the session is not currently executing a request, the sessionis terminated. Transactions may be rolled back and collections may be lost.

• An Unsafe kill

An unsafe kill provides a means for terminating a session when all other techniqueshave failed. Use this option with caution. It can result in a general server failure.

The method also lets you send a message to the session user.

Server log lesEach Content Server maintains a log file. By default, the log file is storedin %DOCUMENTUM%\dba\log ($DOCUMENTUM /dba/log) and namedserverconfig_name.log, where serverconfig_name is the name of the server config objectused by the Content Server. The default location is defined in a location object named“log” that is referenced by the log_location property in the server config object. Thelocation object is created and the property set by headstart.ebs.

You can override both the name and the location of the file by setting the -logfileparameter on the server start-up command line.

The server appends to the log file so long as the server is running. If the server is stoppedand restarted, the file is saved and another log file started. The saved log files are namedin the following format:

On Windows platforms: serverconfig_name.log.save.mm-dd-yy_hh.mi.ss

On UNIX platforms: serverconfig_name.log.save.mm.dd.yyyy.hh.mi.ss

Server load balancing and failoverWhen your installation has a large number of users or there is a lot of activity in therepository, you may want to start multiple servers to spread the load. Starting multipleservers will also allow graceful failover if a particular server stops for any reason.

The servers used for load balancing must project identical proximity values to any givenconnection broker. In that way, when a client DMCL determines the server, it willrandomly pick one of the servers. If the values are different, the DMCL will alwayschoose the server with the lowest proximity value.

If a Content Server stops and additional servers are running against the repository withproximity values less than 9000, the client library, with a few exceptions, will gracefully


Servers

reconnect any sessions that were connected to the stopped server to one of those servers.The exceptions are:• If the client application is processing a collection when the disconnection occurs,

the collection is closed and must be regenerated again when the connection isreestablished.

• If a content transfer is occurring between the client and server, the content transfermust be restarted from the beginning.

• If the client had an open explicit transaction when the disconnection occurred, thetransaction was rolled back and must be restarted from the beginning.

• If the original connection was started with a single-use login ticket or a login ticketscoped to the original server, the session cannot be reconnected to a failover serverbecause the login ticket may not be reused.

If the additional servers known to a session’s connection broker do not have the sameproximity value, the client library will choose the next closest server for failover. Sessionscannot failover to a Content Server whose proximity is 9000 or greater. Content Serverswith proximities set 9000 or higher are called content-file servers. Remote ContentServers installed at remote, distributed sites are configured as content-file servers bydefault.

Note: A client session can only fail over to servers that are known to the connectionbroker used by that session. For a proper failover, ensure that Content Servers project tothe appropriate connection brokers and with appropriate proximity values.

Clearing the server common areaUse the procedures in this section to remove files that are in the server common area.

To remove all les from the server common area:1. Stop Content Server.

2. Do one of the following:• On Windows, edit the Content Server service to add -oclean to the end of the

command line.• On UNIX, add the -oclean argument in the dm_start_repositoryname command

line.3. Restart the server.


Servers

Adding additional servlets to the Java methodserver

To use the HTTP_POST administration method, you must write and install the servletor servlets that handles those calls. Use the following procedure to implement sucha servlet.

To implement a new servlet:1. Write the servlet.

2. Install the servlet on the Java method server.

3. Update the server config object for each server from which HTTP_POST methodsmight originate.Add the new servlet’s name to the app_server_name property and the servlet’s URIto the app_server_uri property.Use Documentum Administrator to modify the server config object. TheDocumentum Administrator online help provides instructions on how to modifythe server config object.

4. Select Re-initialize.

5. Click Check In.

Conguring the workow agentThe workflow agent controls the execution of automatic activities in a workflow. Theagent is comprised of a master repository session and one or more worker sessions. Themaster session is quiescent until the workflow agent is notified by Content Server thatan activity has been created or until the sleep interval expires. At that time, the mastersession queries the repository for information about the activity or activities and assignsthe waiting activity to a free worker session.

You can change the workflow agent’s defaults by:• Changing the number of worker sessions• Changing the sleep interval• Disabling the workflow agentIn addition, you can trace workflow agent operations. Tracing the workflow agent,page 124, describes how tracing is started.


Servers

Changing the number of worker sessions

The number of worker sessions available to execute automatic activities is controlled bythe wf_agent_worker_threads property value in the server config object. By default, thisvalue is set to 3. You can reset the value to any positive number to a maximum of 1000.

Use Documentum Administrator to change the value. You must stop and restart ContentServer for your change to take effect. Reinitializing the server does not make the changeeffective.

Changing the sleep interval

The sleep interval determines how long the master session sleeps after querying therepository for activity information in the absence of a notification from Content Server. Ifthe sleep interval expires without a notification, the master session wakes up and queriesthe repository even though it has not received a notification from Content Server. Thedefault sleep interval is 5 seconds.

The sleep interval is controlled by the wf_sleep_interval property in the server configobject. The value is interpreted in seconds. Use IDQL to change the value. You must stopand restart Content Server for your change to take effect. Reinitializing the server doesnot make the change effective.

Disabling the workow agent

Disabling the workflow agent stops the execution of automatic activities. To disable theworkflow agent, set the wf_agent_worker_threads property in the server config objectto 0. Use Documentum Administrator to set the property. You must stop and restartContent Server for your change to take effect. Reinitializing the server does not makethe change effective.

Tracing the workow agent

By default, tracing for the workflow agent is turned off. You can turn it on by either:• Adding the -otrace_workflow_agent argument on the server startup command line.• Executing a SET_OPTIONS administration method with the -trace_workflow_agent

option specified.


Servers

If you add the argument to the server startup command line, you must restart the serverto start the tracing. However, workflow agent tracing is turned on automatically whenthe server starts.

If you use SET_OPTIONS, tracing starts immediately. It is not necessary to restart theserver. However, if you stop and restart the server, you must reissue the SET_OPTIONSadministration method to restart the tracing.

For instructions on adding the argument to the startup command line, refer to Startingand stopping tracing from the startup command line, page 532. For instructions on usingSET_OPTIONS, refer to the Content Server DQL Reference Manual.

The trace messages are recorded in the server log file.

Recovering automatic activity work items onContent Server failure

If a Content Server fails, the workflow agent associated with that server also stops. Insuch cases, there may be work items that were claimed by the workflow agent prior tothe failure but not yet processed. If you can restart the Content Server, the workflowagent will recognize these work items and process them after the restart. However, ifyou cannot restart the Content Server, you need to remove the workflow agent’s claim tothose work items so that another workflow agent can claim and process them.

A workflow agent claims a work item by setting that work item’s a_wq_name propertyto the r_object_id of the server config object of the Content Server with which theagent is associated. To remove a workflow agent’s claim to a work item, use theRECOVER_AUTO_TASKS administration method to reset that property. The methodresets the a_wq_name property of the work item to empty, which allows anotherworkflow agent to claim that work item. The method operates only on the work itemsclaimed by a workflow agent associated with a specified server. Other work itemsclaimed by agents associated with other servers are not affected.

Managing the JBoss application serverThis section provides instructions and information for administration of the JBossapplication server on a Content Server installation.


Servers

Location of binaries

The JBoss binary is bundled with your installation suite. The application server isinstalled into the jboss<version> subdirectory of the Content Server installation directory.The default directory, referred to as the JBoss root directory, is:• On Windows:

C:\documentum\jboss<version>• On UNIX:

$DOCUMENTUM_SHARED\jboss<version>A JBoss server instance is created in <JBossRoot>\server\<instance name>. For example,C:\documentum\jboss4.2.0\server\DctmServer_MethodServer.

Starting and stopping the JBoss application server

When you first install the Content Server installation, the JBoss application serveris started automatically. However, starting and stopping a Content Server in theinstallation does not automatically start or stop the JBoss application server.

The application server hosts one or more Java applications or processes. In a ContentServer installation, the method server hosts, for example, the Java Method Server, ACSserver, and the DmMail application.

To start the application server:1. On Windows:

a. Navigate to <JBossRoot>\server.

b. Execute startMethodServer.cmd.

c. Alternatively, start the Windows service for the server instance.For the Java method server, and the server instance hosting the Java methodserver, the service name is Documentum Java Method Server. Starting thatservice is equivalent to executing startMethodServer.cmd.

2. On UNIX:


b. Execute start MethodServer.sh.Use the following procedure to stop the application server. Stopping the server stops allapplications running within it.


Servers

To stop an instance server:1. On Windows:


b. Execute stopMethodServer.cmd.

c. Alternatively, stop the Windows service for the server instance.For the Java method server, and the server instance hosting the Java methodserver, the service name is Documentum Java Method Server. Stopping thatservice is equivalent to executing stopMethodServer.cmd.

2. On UNIX:


b. Execute stopMethodServer.sh.


Servers


Chapter 4Methods and Jobs

This chapter describes how to create and execute methods and jobs. The chapter includes thefollowing topics:• Introducing methods, page 129• Execution agents, page 130• Choosing the execution agent, page 132• Tracing options for methods, page 133• Defining the java.ini file (UNIX only), page 134• Enabling the dmbasic method server, page 135• Configuring the worker threads in the dmbasic method server, page 136• Implementing a method, page 136• Executing a method on demand, page 145• Creating jobs and job sequences, page 145• Managing jobs, page 153

Introducing methodsMethods are executable scripts or programs that are represented by method objects inthe repository. The script or program can be a Docbasic script, a Java method, or aprogram written in another programming language such as C++. The associated methodobject has properties that identify the executable and define command line arguments,and the execution parameters.

Methods are executed by issuing a DO_METHOD administration method or by using ajob. Using a DO_METHOD allows you to execute the method on demand. Using a joballows you to schedule the method for regular, automatic execution. For informationabout creating jobs, refer to Creating jobs and job sequences, page 145.

The executable invoked by the method can be stored in the file system or ascontent of the method object. If the method is to be executed by the Java method


Methods and Jobs

server, you must store the executable in %DOCUMENTUM%\dba\java_methods($DOCUMENTUM/dba/java_methods) or deploy the executable as a BOF module.

Deploying a Java-based method as a BOF module allows the method and the executableto be packaged and deployed in a DAR archive. It also allows you to take advantage ofBOF sandboxing, and to make modifications to the module without requiring you torestart the Java method server.

You can execute a method by using the dmbasic method server, the Java methodserver, or Documentum Content Server. Execution agents, page 130, describes each ofthese agents and Choosing the execution agent, page 132 provides some guidelines forchoosing which to use.

Execution agentsThe execution agents are the server processes that are capable of executing methods.There are three execution agents:• The dmbasic method server• Java method server• Documentum Content Server

The dmbasic method server

The dmbasic method server is a separate process that is installed with DocumentumContent Server and resides on the same host. It is enabled by default. After it is started,it runs continuously. If you stop Content Server, the method server is also stopped. Ifthe method server stops, Content Server restarts it automatically. For instructions onenabling and disabling the method server, refer to Enabling the dmbasic method server,page 135.

The dmbasic method server uses a method execution queue to manage methodssubmitted for execution. When you direct a method to the method server, Content Serverplaces a method execution request on the bottom of the method execution queue. Themethod server reads the queue and executes the request at the top of the queue. Themethod server has a configurable number of worker threads to execute requests. Themaximum number of requests the queue can contain is the number of threads times100. For example, if the method server is configured to use 5 threads, then the methodexecution queue can contain 250 requests. For instructions on configuring the number ofthreads, refer to Configuring the worker threads in the dmbasic method server, page 136.

The method server uses connection pooling. This is true regardless of whetherconnection pooling is enabled for the Documentum Server.


Methods and Jobs

Java method server

The Java method server is a third-party application server, installed as a component ofContent Server installation. Additionally, Documentum provides a servlet to executemethods called by DO_METHOD. During installation, the app_server_name andapp_server_uri properties are set to configure use of the Java method server. Theapp_server_name property in the server config object identifies the application serversrecognized by Content Server. The value “do_method” in that property represents theJava method server. The value in the corresponding index position in the app_server_uriproperty contains the host and port number for the server.

Refer to Documentum Content Server Installation Guide for more information about how toconfigure the Java method server and the servlet.

The Java method server resides on the same host as Content Server. The Java MethodServer is started automatically by the Content Server installation process. However,if you start or stop Content Server after installation, you must start or stop the JavaMethod Server manually, if needed. Starting and stopping Content Server does not startor stop the Java Method Server. Starting and stopping the JBoss application server, page126 provides instructions to start and stop the Java method server.

The programs launched with DO_METHODs that are sent to the Java methodserver must be Java methods stored in %DOCUMENTUM%\dba\java_methods($DOCUMENTUM/dba/java_methods) or deployed as a BOF module. When aDO_METHOD method directed to the Java method server is issued, it generates aninternal HTTP_POST request. The Java method server invokes the do_method servlet toservice the request.

Note: The Java method server can also be used to execute Java methods that are notassociated with a method object. To do this, use an HTTP_POST administration methodto send the request to the Java method server. For details about the administrationmethod, refer to the Content Server DQL Reference Manual.

Content Server

Documentum Content Server is the default execution agent for a method if you do notset the method’s use_method_server property to TRUE to direct the execution to themethod server or Java method server.


Methods and Jobs

Choosing the execution agentThe execution agent that you choose to execute a method depends on the language of themethod’s program and where the program is stored. You can:• Use the dmbasic method server to execute Docbasic scripts.• Use Content Server to execute Docbasic scripts or programs in any language.• Use a Java method server to execute Java methods that are installed on the Java

method server or deployed as BOF modules.To execute Java or DFC calls that use the dmbasic method server, the Java or DFC callsmust be called in a Docbasic program.

You cannot use the Java method server to execute Docbasic scripts or any program otherthan Java methods installed on the Java method server.

Content Server is the default execution agent for methods. If you do not specifically directa method to use the method server or the Java method server, Content Server executesthe method. Methods are directed to the method server or Java method server by settingthe method object’s use_method_server property to TRUE and setting the remainingproperties appropriately. Refer to Creating a method object, page 143 for instructions.

Performance considerations

Use of either the method server or the Java method server improves the performance ofmethod execution.

To execute a method, Content Server generates a new process to execute the method.That process opens a new session with the repository, which in turn opens anothersession with the RDBMS.

Use of the method server avoids the overhead of the additional repository session andRDBMS session. The method server runs continuously, so no new process is created toexecute the method. The first time the method server executes a method, it opens arepository session and an associated RDBMS session. Thereafter, the method server usesconnection pooling. Use of connection pooling removes the need to open new repositoryand RDBMS sessions for subsequent method executions.

Use of the Java method server provides similar performance benefits.


Methods and Jobs

Security considerations

Security is only a consideration when you are executing a method on the Java methodserver. When executing on the Java method server, there are two security issues:• Determining the origin of the generated HTTP_POST request generated by the

DO_METHOD.• Logging in without passwords.To resolve the first issue, the invoked servlet ensures that the generated request comesfrom a machine that hosts a Content Server by checking the IP address of the senderagainst a list of repositories. When the Java method server receives a request, it issuesa DFC getServerMap() call to obtain a list of all servers servicing the repository. Fromthat list, it determines whether the IP address of the machine that originated the requestis a Content Server host. If the sender’s IP address does not match the IP address ofa Content Server host, the request fails.

The second issue occurs because the Java method server runs as the Content Serverinstallation owner. Consequently, the servlet it invokes to execute DO_METHOD callsalso runs as the installation owner. A process running on the Content Server hostas installation owner can log into the repository as the installation owner without apassword. Consequently, a servlet or an invoked Java method can log into the repositorywith superuser privileges without providing a password.

If you write a method that logs in a user in that manner, you may want to ensure thatthe actual user who issues the DO_METHOD to invoke the method has the appropriateprivileges to execute the program as a superuser. To do this, send the current usernameand a login ticket to the method in the arguments. The method can use this informationto log in and check the privileges of the user before connecting as the current operatingsystem user.

Tracing options for methodsYou can trace the DO_METHOD administration method, the program execution, or both.

To trace the DO_METHOD method, set the trace_launch property of the method objector the TRACE_LAUNCH argument on the DO_METHOD command line. If both are set,the setting on the command line overrides the property setting. The trace information, upto 2047 characters, includes the command executed to invoke the method and messagesthat indicate the success or failure of the invocation. The trace information generatedby TRACE_LAUNCH is stored in the repository log file.

To trace method execution in the dmbasic method server or Content Server, set thetrace_method_server server flag. Set this flag by using the SET_OPTIONS administrationmethod or on the server startup command line. Tracing information generated by


Methods and Jobs

Content Server is stored in the server log file. Tracing information generated by themethod server is stored in the method server log file. The log file is stored in:%DOCUMENTUM%\dba\log\<repository_id>\MethodServer\MethodServer\server_config_name.log

or$DOCUMENTUM/dba/log/<repository_id>/MethodServer/MethodServer/server_config_name.log

The log file is created when the method server is started. If a method server log filecurrently exists, it is saved with a timestamp and a new log file is started.

To trace method execution on the Java method server, set the trace parameter in theweb.xml file to true. For example:<init-param>

<param-name>trace</param-name><param-value>t</param-value></init-param>

Dening the java.ini le (UNIX only)On UNIX, both Content Server and the method server require a Java initialization file toexecute Java or DFC calls in Docbasic scripts. The initialization file, java.ini, identifies thelocation of the runtime Java and shared libraries. The java.ini file is created and installedby default when you install Content Server.

The format of the file is:java_library_path=full_path_libjava.so #requiredjava_version=java_runtime_version #requiredjava_classpath=classpath_or_invoked_java_class #requiredjava_alias_file=full_path_to_dfc.aliases #optionaljava_disabled=Boolean #False by default

java_library_path

The java_library_path setting must be the full path to the java shared library, libjava.so.

java_version

The valid value for java_version is 1.3.1 or higher.


Methods and Jobs

java_classpath

All the invoked Java classes must be included in this classpath setting. If they are not,a runtime error occurs. If the Docbasic methods invoke the DFC class methods, theclasspath must include the dctm.jar file. Paths specified in classpath are separated bysemicolons (:). For example:java_classpath=<$dm_home>/classes/com/documentum/dctm.jar:/usr/java/bin/jre

java_alias_le

This specifies the full path to the dfc.aliases file installed with the DFC. This file is readand parsed by the Docbasic engine. If you include this in the java.ini file, you can declarevariables with DFC types. If not, you must declare any DFC-allocated object as “Object”.To embed DFC in Docbasic, you must include this parameter.

java_disabled

Setting this flag to TRUE disables the Java VM. When the flag is TRUE, Docbasicmethods cannot call Java. The flag is FALSE by default.

Enabling the dmbasic method serverThe method server is installed and enabled automatically when you install ContentServer.

To enable or disable the method server:1. Open the server.ini file in a text editor.

2. Do one of the following:• To enable the method server, set the method_server_enabled key to T.• To disable the method server, set the method_server_enabled key to F.

3. Save the server.ini file.

4. Restart Content Server.


Methods and Jobs

Conguring the worker threads in the dmbasicmethod server

The threads are the processes that execute the requests on the dmbasic method server’sexecution queue. By default, there are five threads. You can reset this number to amaximum equal to the number of allowed concurrent sessions on the Content Server.

To change the number of threads:1. Open the server.ini file in a text editor.

2. Reset the value in the method_server_threads key.

3. Save the server.ini file.

4. Restart the server.

Implementing a methodThere are two basic steps to implement a method:

1. Create the script or program.

2. Create the method object.

The details of each step depend on the chosen program language and the execution agentchosen to execute the method. There are three possible execution agents: Content Server,the dmbasic method server, and the Java method server.

For guidelines about creating a method for execution by Content Server or the dmbasicmethod server, refer to Creating a method to be executed by Content Server or thedmbasic method server, page 136.

For guidelines about creating a method for execution by the Java method server, refer toCreating a method to be executed by the Java method server, page 141.

Creating a method to be executed by Content Server orthe dmbasic method server

Use the following guidelines when creating a method to be executed by Content Serveror the dmbasic method server.


Methods and Jobs

Limitation on argument length for Docbasic

The total length of the arguments passed in a Docbasic method cannot exceed 4095characters.

General guideline for the script or program

If the program starts a repository session, it is recommended that the program call anexplicit disconnect when the session is finished.

Script or program return values for workow methods

The Content Server facility that executes automatic activities examines the return valuefor the executed script or program. If the return value is 0, the facility assumes thatthe execution was successful. If the return value is any value other than 0, the facilityassumes that there was an error in the execution and moves the associated work item tothe paused state and places it on the supervisor’s queue.

We strongly recommend that the script or program associated with an automatic activityreturn a value other than zero if any error occurs during the execution of the script orprogram.

Calling Java or DFC in a Docbasic script

If you want to call Java or DFC methods in a Docbasic script, use the guidelines in thissection.

User account (UNIX only)

On UNIX, the user account under which a Docbasic script calls Java or the DFC musthave $DM_HOME/bin in the account’s shared library path:• LD_LIBRARY_PATH for Linux and Solaris• LIBPATH for AIX• SHLIB_PATH for HP-UXAlso located in $DM_HOME/bin are two scripts to help set up user environments:• dm_set_server_env_sh• dm_set_server_env.csh


Methods and Jobs

dmbasic executables (UNIX only)

Content Server ships with three versions of the dmbasic executable: dmbasic,dmbasic_shr, and dmbasic_noshr.

The standard interface is dmbasic and uses the shared library version of the DMCL,which dmbasic links to dynamically.

The dmbasic_shr and dmbasic_noshr executables are copies of dmbasic. Althoughdmbasic_shr is the same as dmbasic, it is provided for backwards compatibility. Thedmbasic_noshr executable should not be used for executing Docbasic scripts that callDFC.

Locating the java.ini le (UNIX only)

The method server and Content Server use a java.ini file to find the location of the Javaruntime and the shared libraries. The method server looks for the file in the followingplaces, in the order listed:• In the $DM_JAVA_CONFIG environment variable. The value must be a full-path

specification for the file, including the file’s name.• The current directory• $DM_HOME/binThe Content Server looks first for a -j argument on the dmbasic command line. If the-j argument is not found, it uses the same algorithm as the method server to find thejava.ini file.

To include the -j argument on the dmbasic command line for a method executing on theContent Server, use the following format:-j init_file_location

where init_file_location is either a full or relative path to the java.ini file.

For example:

dmbasic -eentrypoint -j init_file_location

Sample code

Java methods are accessed in Docbasic through the Docbasic CreateObject method,specifying the object class to instantiate. After the object is created, its properties andmethods are accessed using the dot syntax (object.property=value).

Here is sample code that invokes Java:Declare Function SetupSession (ByVal db As String, ByVal ddo As String,


Methods and Jobs

ByVal pass As String) As ObjectDeclare Sub CreateDocumentDeclare Sub Disconnect

Dim session As Object

Sub Entry_Point (ByVal docbase As String, ByVal docowner As String,ByVal password As String)

On Error Goto GAFF

Dim clientx As ObjectDim client As objectDim logininfo As Object

Set session = SetupSession(docbase,docowner,password)Call CreateDocument

session.disconnectExit Sub

GAFF:Print "An error has occurred."Print "The error number is " & Err() & "."Print "The error message is: " & Error$ & "."Exit Sub

End Sub

Function SetupSession (ByVal db As String, ByVal ddo As String,ByVal pass As String) As Object

On Error Goto GAFF

Set clientx = CreateObject("java:com.documentum.com.DfClientX")Set logininfo = clientx.getLoginInfologininfo.setUser ddologininfo.setPassword passSet client = clientx.getLocalClientSet SetupSession = client.newSession(db,logininfo)Exit Function

GAFF:Print "An error has occurred."Print "The error number is " & Err() & "."Print "The error message is: " & Error$ & "."Exit Function

End Function

Sub CreateDocument

Dim dmdoc As Object

On Error Goto GAFF

Set dmdoc = session.newObject("dm_document")doc_id$ = dmdoc.getObjectId().ToString

Print Mid(doc_id,1,2)If Mid(doc_id,1,2) <> "09" Then

Print "ERROR: The docbase id " & doc_id & " is not correct."Stop

End IfPrint "Created a document."dmdoc.setObjectName "dfcdoc1"


Methods and Jobs

Print "Set the document name."content$ = ".\dfcdoc.ebs"Dim emptystr As Stringdmdoc.setContentType "text"dmdoc.setFile contentPrint "Assigned a content to the document."dmdoc.SavePrint "Saved the document."Exit Sub

GAFF:Print "An error has occurred."Print "The error number is " & Err() & "."Print "The error message is: " & Error$ & "."Exit Sub

End Sub

Recording the output

To record the output of the script or program, set the SAVE_RESULTS argument toTRUE on the DO_METHOD command line.

Setting method object properties for Content Server execution

To execute the method using Content Server, the use_method_server property mustbe set to F (FALSE). The remaining properties are set as needed. For example, if theprogram is written in Docbasic, then method_type and method_verb are set to dmbasic.The Documentum System Object Reference Manual lists the properties of a method objectand their valid settings.

Note: Setting method_type to dmbasic directs Content Server to add -f to the beginningof the file name when it executes the method and to pass all arguments specified on theDO_METHOD command line to the program. If method_type is not set correctly, themethod will not execute correctly.

For instructions on how to create a method object, refer to Creating a method object,page 143.

Setting method object properties for dmbasic method serverexecution

To execute a method using the dmbasic method server, set the method properties asfollows:


Methods and Jobs

• Set method_type property to dmbasic.• Set use_method_server property to T (TRUE).• Set run_as_server property to T (TRUE).For instructions on how to create a method object, refer to Creating a method object,page 143.

Creating a method to be executed by the Java methodserver

Use the following guidelines when creating a method to be executed by the Java methodserver.

Note: Documentum does not provide basic support for resolving problems encounteredwhen creating or executing custom Java methods or classes. For help, contact DeveloperSupport or Documentum Professional Services.

General guideline for the script or program

If the program starts a repository session, it is recommended that the program call anexplicit Disconnect when the session is finished.

Guidelines for a Java method to be deployed as a BOF module

If you intend to the deploy the method as a BOF module, observe these guidelines:• The method must implement the IDfMethod interface.• The module must be a simple module, one which implements the IDfModule

interface.• The method_verb property of the dm_method object must be set to the module’s

name, not the class name.

Script or program return values for workow methods

The Content Server facility that executes automatic activities examines the return valuefor the executed script or program. If the return value is 0, the facility assumes thatthe execution was successful. If the return value is any value other than 0, the facility


Methods and Jobs

assumes that there was an error in the execution and moves the associated work item tothe paused state and places it on the supervisor’s queue.

We strongly recommend that the script or program associated with an automatic activityreturn a value other than zero if any error occurs during the execution of the script orprogram.

Recording the output

If you are executing the DO_METHOD on the Java method server, Documentumrecommends that you include the following interface in the method’s program.Including this interface is required if you want to save the response to the repository in adocument. You can also use this interface to capture error or trace messages from theJava method or servlet.

package com.documentum.mthdservlet;import java.io.OutputStream;import java.util.Map;

/*** Interface for Java Methods that are invoked by the* Documentum Content Server.**/

public interface IDmMethod{

/*** Serves as the entry point to a Java method (installed* in application server) executed by* the Content Server DO_METHOD apply method.** @param parameters A Map containing parameter names as keys and parameter values* as map values.The keys in the parameter are of type String.* The values in the parameter map are of type String array.* (This map corresponds to the string ARGUMENTS passed by the* DO_METHOD apply call.)** @param output OutputStream to be sent back as the HTTP response content,* to be saved in the repository if SAVE_RESULTS was set to TRUE* in the DO_METHOD apply call.* NOTE: This output stream is NULL if the DO_METHOD was* launched asynchronously. Always check for a null* before writing to the OutputStream.*/

public void execute(Map parameters, OutputStream output) throws Exception;}


Methods and Jobs

Storing Java methods

The storage location of the executable methods to be executed by the Java method serverdepends on whether or not the method is deployed as a BOF module.

If the method is not deployed as a BOF module, the method must be stored in%DOCUMENTUM%\dba\java_methods ($DOCUMENTUM/dba/java_methods).

If the method is deployed as a BOF module, it is stored automatically in the defaultlocation for the module.

Setting method object properties for Java method server execution

Methods that you intend to execute on an Java method server must have the followingproperty values:• The method_type property must be set to Java.• The use_method_server property must be set to T (TRUE).• The method_verb property is set to identify the method:

— For methods stored in the java_methods directory, method_verb must be setto a fully qualified class name of a Java implementation class. For example:com.documentum.services.myAutoMethod

— For methods deployed as a BOF module, method_verb must be set to the modulename.

• The run_as_server property must be set to T (TRUE).

Note: UNIX users who are authenticated against a Windows domain cannot executemethods under their own accounts. All methods executed by such users must be runwith run_as_server set to TRUE.

For instructions on how to create a method object, refer to Creating a method object,page 143.

Creating a method object

You must have Sysadmin or Superuser privileges to create method objects. Becausemethod objects are a subtype of the SysObject object type, it is not necessary to reinitializeContent Server after you create a new method object.

Methods are typically created using Documentum Administrator. It is also possibleto create a method object using DQL. For instructions on using Documentum


Methods and Jobs

Administrator, refer to the Documentum Administrator online help. Using DQL, page144 describes how to use DQL to create a method object.

The values you set in many method properties depend on how you intend to execute themethod. For guidelines, refer to Creating a method to be executed by Content Serveror the dmbasic method server, page 136 and Creating a method to be executed by theJava method server, page 141. For a list of the properties of a method object, refer to theDocumentum System Object Reference Manual.

If you are creating a method for a job that will be executed in a job sequence, refer toDefining success return codes and success status, page 144 for information about settingthe success_return_codes and success_status properties.

Using DQL

Use a DQL CREATE...OBJECT statement to create a method object. The syntax is:CREATE dm_method OBJECTSET property_name[[index]]=value[,SETFILE filepath CONTENT_FORMAT=format_name]{,SETFILE filepath PAGE_NO=page_number}

Refer to the Documentum System Object Reference Manual for information about theproperties of a method object.

To add the content file containing the script or procedure using the SETFILE clause in theCREATE...OBJECT statement, you must have Superuser privileges. Additionally, thecontent file must be stored on the host on which Content Server is running. The ContentServer DQL Reference Manual has complete information about using the SETFILE clause.

Dening success return codes and success status

The methods executed by jobs included in a job sequence must have a defined valuefor the success_return_codes property or the success_status property or both. Thedm_run_dependent_jobs method, which invokes sequenced jobs, uses one or both ofthose properties to determine whether an invoked job completed successfully.

The dm_run_dependent_jobs method compares the values in the success_return_codesproperty and the success_status property to the values in the job’s a_last_return_codeand a_current_status. The value in a_last_return_code is compared to the value orvalues in success_return_codes, and the value in a_current_status is compared to thevalue in success_status.

If you set only success_return_codes, dm_run_dependent_jobs compares the value ina_last_return_code to the value or values in success_return_codes, and any value in


Methods and Jobs

a_current_status is ignored. If you set only success_status, dm_run_dependent_jobscompares the value in a_current_status to the value in success_status and ignoresthe value in a_last_return_code. If the values in the comparison operation match,dm_run_dependent_jobs considers the invoked job to have completed successfully.

If both success_return_codes and success_status are set, then dm_run_dependent_jobscompares each to its corresponding job property. If either comparison fails,dm_run_dependent_jobs considers the invoked job to have failed. If both comparisonssucceed, then dm_run_dependent_jobs considers the invoked job to have succeeded.

Note: The agent exec process sets the job’s a_last_return_code property. The propertyis set to the value returned by the job’s method. The job’s a_current_status propertymust be set directly by the invoked method.

Executing a method on demandTypically, methods are executed on demand through Documentum Administrator. Forinstructions, refer to the Documentum Administrator online help.

You can also use a DQL EXECUTE statement to issue a DO_METHOD call to execute amethod. The Content Server DQL Reference Manual describes how to use DO_METHODand the EXECUTE statement.

Creating jobs and job sequencesThis section contains information about jobs and job sequences, how to create them andhow to set their schedules. The following topics are included:• Introducing jobs, page 146• Introducing job sequences, page 146• The agent exec process, page 148• Creating a job, page 149• Creating a job sequence, page 150• Scheduling jobs, page 150• Passing arguments, page 151• The run_now property, page 152


Methods and Jobs

Introducing jobs

Jobs automate method execution. Jobs are stored in the repository as dm_job objects. Theproperties of a job object reference an associated method object and define an executionschedule. The methods are executed automatically on the schedule specified in the job.You can schedule jobs to be executed individually or in a job sequence.

Jobs are a useful, easy way to automate tasks that you perform regularly. Documentumprovides several system administration tools that are implemented as jobs. These toolsperform a variety of common system administration tasks, such as removing oldrenditions and providing warnings when disk space for content runs low. (Refer toChapter 11, Administration Tools, for a list and description of the tools.)

Use Documentum Administrator to create jobs. You must have Sysadmin or Superuserprivileges to create a job. Refer to Creating a job, page 149, for instructions.

Introducing job sequences

A job sequence is a set of one or more jobs that are executed in a user-defined order. Youcan put replication jobs and custom jobs of any user-defined type in a sequence. Youcannot put system-defined jobs, other than replication jobs, in a job sequence. The jobscan reside in different repositories, but all must reside in 5.3 or later repositories.

Sequences are an effective way to handle replication jobs that might overlap in theiroperations because they allow you to define the order in which the jobs must be run andno job is run until all of its predecessors complete successfully.

For example, perhaps you have two replication jobs with the same source and targetrepositories. To ensure that the two jobs do not try to load the replicas into the targetrepository at the same time, you can put both in a job sequence and they are run oneafter the other, in the order you define.

A job sequence can contain any number of jobs, and the jobs can reside in differentrepositories. However, you cannot put a job that requires multiple invocations, such as amanual transfer replication job, in a job sequence.

Execution of the job sequence is initiated by a controlling job that you define. Thecontrolling job executes the dm_run_dependent_jobs method, which is installed withContent Server.


Methods and Jobs

Repository implementation

A job sequence is stored in the repository as a set of dm_job_sequence objects. Each jobsequence object represents one job in the sequence. The information in the job sequenceproperties is used by the dm_run_dependent_jobs method (invoked by the controllingjob) to execute the job and the sequence. For example, the information identifies the jobto be executed, the job’s predecessors, and the user as whom the job runs.

The value in the object_name property of job sequence objects is the name of the sequence.All job sequence objects representing one job sequence must have the same object name.

Job sequence execution

All jobs in a job sequence must be inactive. If a job in a sequence is an active job, itgenerates an error when the sequence is executed.

Execution of the sequence is initiated on the schedule you define for the sequence’scontrolling job. When that job is started, it invokes the dm_run_dependent_jobs method.The method controls the execution of the jobs in the sequence. The method initiates ajob in the sequence by setting the job’s run_now property to T. The job is then executedby the agent exec process the next time it polls the repository. The methods invoked bythe sequenced jobs can be executed by the Java Method Server, the dmbasic methodserver, or Content Server.

The dm_run_dependent_jobs method begins by initiating all the jobs in the sequencethat have no predecessors. When a job in the sequence completes, the method initiatesany other jobs in the sequence whose predecessors have successfully completed. If a jobin the sequence fails, the method attempts to run the job up to two more times. If thejob is not successfully run in three attempts, the method considers the job to have failedand records the information in the controlling job’s a_current_status property. (You canview the current status information using Documentum Administrator.) Additionally,if a sequenced job fails, the dm_run_dependent_jobs method stops after allowing anyremaining active jobs to complete. It does not initiate any more jobs.

The dm_run_dependent_jobs method finishes when there are no jobs in the sequencethat are running and no jobs remaining to be run. The dm_run_dependent_jobs methodreturns one of two possible values on completion:• 0, meaning every job in the sequence executed successfully• 1, meaning some job or jobs in the sequence did not successfully complete, or rarely,

that the method itself failed due to some problem after all jobs completed

Note: Recovering from a job sequence failure, page 158, contains instructions onhandling this situation.


Methods and Jobs

Determining success for invoked jobs

The controlling method, dm_run_dependent_jobs, uses the values in the methodproperties called success_return_codes and success_status to determine whether aninvoked job completed successfully. For details of how this works, refer to Definingsuccess return codes and success status, page 144.

The repository connection le

The repository connection file contains connection information used by thedm_run_dependent_jobs method to connect to a repository to activate a job in thesequence. There is one repository connection file for each repository. The file is one ormore individual lines that contain a server connection string, domain name, user name,and an encrypted password.

The location of the file is provided to controlling jobs as a job argument. Whendm_run_dependent_jobs wants to initiate a job, it searches the file for an entrythat matches the values in the job_docbase_name, job_login_user_name, andjob_domain_name properties of the job’s job sequence object. If a match is found, themethod uses those values and the password in that entry to connect to the repository.

Using the file is not mandatory. If the argument identifying the file is not provided or if amatch is not found, the method uses trusted login to connect to the repository. However,to use a trusted login, the server to which the method is connecting must reside onthe same host as the controlling job. Additionally, the method must be running as theconnecting user, and generally requires the connecting user to be the installation owner.

Typically, the file is created and maintained automatically by DocumentumAdministrator when you use Documentum Administrator to create and edit jobsequences. Documentum Administrator creates the file and names it connect.dcf.It is stored in %DOCUMENTUM%\dba\config\repository_name\connect.dcf($DOCUMENTUM/dba/config/repository_name/connect.dcf). You can create and managethe file using the edit_dcf utility if you want to use another name or storage location.For instructions, refer to Creating and maintaining a repository connection file for jobsequences, page 155.

The agent exec process

All jobs are started by the agent exec process, a process that is installed with ContentServer. At regular intervals, the agent exec process examines the job objects in therepository and runs those jobs that are ready for execution. (A job is ready for execution


Methods and Jobs

if the value in its a_next_invocation property is less than the current date and time or ifits run_now property is set to T.)

There are several behavioral parameters that you can configure for the agent exec process,including how often it polls and how many jobs it executes each time. For instructionson configuring the agent exec, refer to Modifying agent exec behavior, page 154.

Creating a job

You must have Sysadmin or Superuser privileges to create a job. Creating a job is easiestif you use Documentum Administrator. However, you can also use DQL statements.For instructions on using Documentum Administrator, refer to the DocumentumAdministrator online help.

Before you create a job, you may wish to read the information about scheduling jobs.Whether you decide to run a job as an individual job or as part of a sequence, you mustset the job’s schedule. Setting the schedule appropriately when the job is created willsave steps after the job is created.

Similarly, you may wish to read the information about passing arguments before youcreate the job. Passing arguments, page 151, describes how arguments are passed tothe methods executed by jobs.

To create a job:1. Write a Docbasic script, Java method, or other program to perform the required

operations.

2. Create a method object that references the program created in Step 1.Creating a method object, page 143, describes how to create a method object.If the method is for a job that will be part of a job sequence, use the guidelines inDefining success return codes and success status, page 144, to set the success returncodes and success status fields.

3. Create a job object that points to the method.If you intend to execute the job individually, activate the job.If you intend to execute the job as part of a job sequence, inactivate the job.

Using DQL to create a job

Use the DQL CREATE...OBJECT statement to create a job object. You must set themethod_name, start_date, run_mode, run_interval, and a_next_invocation properties.You will probably also want to set the optional properties that set the job’s name


Methods and Jobs

and expiration date, pass argument values to the method, and activate the job. (TheDocumentum System Object Reference Manual has a description of job object properties.The scheduling properties are described in detail in Scheduling jobs, page 150.)

Creating a job sequence

Before you create a job sequence, determine which jobs you want to include in thesequence and the order in which you want the jobs to execute. Use DocumentumAdministrator to create the sequence. You must have Sysadmin or Superuser privilegesto create a job sequence.

Documentum Administrator only displays as choices for inclusion those jobs whoseassociated methods have a value for either or both of the following properties:success_return_codes and success_status properties. (For information about setting theseproperties, refer to Defining success return codes and success status, page 144.)

Use the following guidelines for the sequence:• All included jobs must be set to inactive.

Documentum Administrator will allow you to add active jobs to a sequence.However, you must set such jobs to inactive before running the sequence.

• The controlling job must execute the dm_run_dependent_jobs method.

Documentum Administrator enforces this guideline and does not allow you tochange the method when creating a job sequence.

• Set Pass Standard Arguments to true for the controlling job.Creating the first job sequence automatically creates the repository connection file.Creating additional sequence modifies the file if needed. (The repository connection file,page 148, describes the file and its purpose.)

Scheduling jobs

Jobs are executed on a defined schedule. If the job is executed as a standalone job (not ina job sequence), the execution schedule is controlled by property settings in the job. If thejob is in a job sequence, its schedule is determined by a controlling job that activates thesequence. However, you must set the scheduling properties of jobs in a sequence to validvalues or the jobs fail when they are invoked in the sequence.


Methods and Jobs

Dening a job schedule

Use Documentum Administrator to set job schedules. You must specify a starting dateand the interval at which to execute the job. The interval is defined in the Repeat andFrequency fields.

Defining the starting date sets the following properties:• start_date• a_next_invocationThe starting date is the earliest date at which the job can be executed. Thea_next_invocation property defines the first (or next) scheduled execution of the job. Bydefault, Documentum Administrator displays the current date and time as the defaultstarting date. Reset this to the actual date and time on which you want the job to executefor the first time. After the job executes, the a_next_invocation property is reset to thedate and time of the next invocation, computed using the interval you define.

The specific dates and times you set for a job (for example, an activation date orexpiration date), are interpreted as server time. For example, suppose you set a job’s startdate to August 1 at 9 a.m. on a client machine in New York when the server machine is inThe Hague. The tool becomes active when it is August 1, 9 a.m. in The Hague.

Defining the interval sets these underlying properties:• run_mode, set in the Repeat field• run_interval, set in the Frequency fieldThese two values work in conjunction to define how often the job is run after its firstexecution. The Repeat field defines a unit of measure. The integer value you specify inthe Frequency field is interpreted according to the unit of measure you select in theRepeat field.

For example, if Repeat (run_mode) is set to Weeks and Frequency (run_interval) is setto 1, the job repeats every week. If Repeat is set to Weeks and Frequency is set to 3, thejob repeats every three weeks.

In addition to specifying how often the job executes, you can specify how many timesyou want it to execute and when you want it to stop executing. The maximum numberof executions is recorded in the max_iterations property. The end date for the job isrecorded in the expiration_date property. When either value is met, the agent execprocess ignores the job and no longer schedules it for execution.

Passing arguments

Jobs have a property called pass_standard_arguments that determines which argumentsare passed automatically to the method associated with the job.


Methods and Jobs

If pass_standard_arguments is set to T, the server passes four standard arguments,listed in Table 14, page 152, to the method.

Table 14. Standard arguments passed to jobs

Argument Datatype Value Description

-docbase string(64) repository_name Identifies therepository

-user_name string(64) user_name The user executingthe job

-job_id ID job_object_id Object ID of the job

-method_trace_level

integer level Method trace level touse. The default is 0(no tracing).

The value forthis argument istaken from themethod_trace_levelproperty of the jobobject.

If the server passes the standard arguments, it does not pass to the method anyarguments defined in the job’s method_arguments property. The method must use thejob ID passed as a standard argument to obtain the argument values defined in thejob’s method_arguments property.

If pass_standard_arguments is set to F, the server passes the method the argumentvalues found in the job’s method_arguments property, but does not pass the standardarguments.

The default for pass_standard_arguments is F.

Note: For all the system administration jobs installed with Content Server,pass_standard_arguments is set to T. Do not reset that value to F.

The run_now property

The run_now property can be used for testing. If set to TRUE, the agent exec process runsthe job the next time the process polls the repository for jobs ready for execution. Theproperty does not affect the settings for run_mode, run_interval, or a_next_invocation.For example, if you modify a job’s associated program, you can test it immediately by


Methods and Jobs

setting run_now to TRUE and saving the job. You do not have to wait to test the jobuntil its next scheduled execution.

In Documentum Administrator, you set run_now by selecting the Run After Updatecheckbox.

Managing jobsThis section contains information and procedures for managing jobs and job sequences.Included are the following topics:• Activating or inactivating a job, page 153• Disabling all jobs, page 153• Modifying agent exec behavior, page 154• Creating and maintaining a repository connection file for job sequences, page 155• Recovering from a job sequence failure, page 158• Interpreting a job sequence status report, page 158• Executing dm_run_dependent_jobs independently, page 159

Activating or inactivating a job

When you set a job to inactive, the agent exec process ignores the job when it polls therepository and the job is never started by agent exec. When you set a job to active, theagent exec examines the job when it polls the repository and executes the job on theschedule defined in the job.

A job’s activation status is recorded in its is_inactive property. Use DocumentumAdministrator to change the status.

A job can be set to inactive automatically if you have set a maximum number ofexecutions for the job. In such cases, the job is inactivated after the specified numberof executions are completed. Similarly, if you specify an expiration date for a job, it isinactivated on that date.

Disabling all jobs

To disable all job executions, set the agent_launcher property in the server config objectto an empty string ("") and stop and restart the server. Stopping the server stops the


Methods and Jobs

current running agent exec process. When you restart the server, the agent_exec processis not launched.

Modifying agent exec behavior

The agent exec process controls the job execution. It runs continuously, polling therepository at intervals for jobs to execute. By default, only three jobs are allowed toexecute in a polling cycle and tracing for the process is turned off.

You can change these default parameters, including the polling interval. The behavior iscontrolled by command line arguments in the method_verb argument of the methodobject that invokes the agent exec process. The arguments can appear in any order on thecommand line. You must have Superuser privileges to change the agent_exec_method.

Setting the polling interval

The agent exec process runs continuously, polling the repository at specified intervalsfor jobs to execute. The default polling interval is controlled by the setting in thedatabase_refresh_interval key in the server.ini file. By default, this is set to 1 minute(60 seconds).

To change the polling interval without affecting the database refresh interval, add the-override_sleep_duration argument with the desired value to the agent_exec_methodcommand line. Use Documentum Administrator to add the argument to the commandline. For example:.\dm_agent_exec -override_sleep_duration 120

The polling interval value is expressed in seconds (120 is 2 minutes expressed asseconds). The minimum value is 1 second.

Setting the number of jobs in a polling cycle

By default, the agent exec executes up to three jobs in a polling cycle. To change themaximum number of jobs that can run in a polling cycle, add the -max_concurrent_jobsargument with the desired value to the agent_exec_method method command line.For example:.\dm_agent_exec -max_concurrent_jobs 5

Use Documentum Administrator to modify the command line.


Methods and Jobs

Turning on tracing for the agent exec process

Tracing for the agent exec process is turned off by default (trace level = 0). To turnit on, use Documentum Administrator to add the -trace_level argument to theagent_exec_method method command line. For example:.\dm_agent_exec -trace_level 1

Setting the trace level to any value except zero turns on full tracing for the process.

The log file is named agentexec.txt and is stored in the%DOCUMENTUM%\dba\log\repository_id\agentexec($DOCUMENTUM/dba/log/repository_id/agentexec) directory.

Creating and maintaining a repository connection lefor job sequences

A repository connection file contains connection information used by thedm_run_dependent_jobs method to connect to the repositories that contain the jobsin the sequence. When the dm_run_dependent_jobs method executes, it searches therepository connection file to find an entry that specifies the server connection string,user, and domain identified in the job sequence object. If such an entry is found, it usesthe password specified for that entry to make the connection to run the job.

Each entry in the file appears on a separate line and has the following format:server_connect_string,[domain],user_name,password

Using this file is optional. If the dm_run_dependent_jobs method does not find amatching entry in the file or if the file does not exist, the method attempts to use a trustedlogin to invoke the sequenced job.

The file is typically maintained by Documentum Administrator when you edit or modifya job sequence. You can, however, use the dcf_edit utility to edit the file directly. Refer toThe dcf_edit utility, page 156, for instructions.

Specifying the server connect string

The dm_run_dependent_jobs method matches the value in the server_connect_stringportion of the entry to the value in the job sequence object’s job_docbase_name propertywhen looking for a matching entry in the repository file.

The value can be any valid value used to designate a repository or server whenconnecting to a repository. For example, the following are valid formats for the values:


Methods and Jobs

repository_name

repository_name.content_server_name

repository.content_server_name@host_name

The only requirement is that the value you define for the server connection string inthe file must match the value specified in the job_docbase_property for the job in thesequence.

Commas and backslashes in the entries

You can use commas or backslashes in the values specified for the server connectionstring, domain, and user name by escaping them with a backslash. For example,“doe\,john” is interpreted as “doe, john”, and “doe\\susie” is interpreted as“doe\susie”.

You cannot use a backslash to escape any characters except commas and backslashes.

The dcf_edit utility

The dcf_edit utility allows you to add, remove, or replace entries in a repositoryconnection file. It also allows you to backup the entire file. The utility is installed withContent Server as a method implemented using a Java class. The class is:documentum.ecs.docbaseConnectionFile.DCFEdit

You can run the utility as a method from Documentum Administrator or as a Javacommand line utility. Table 15, page 156, lists the arguments accepted by the methodor on the command line.

Table 15. dcf_edit utility arguments

Argument Description

-server_configserver_config_name

Identifies the repository to which the utility will connect.

This argument is required for Add and Removeoperations, but is invalid for Backup operations.

-login_domain domain_name The domain of the user identified in the -login_userargument

This argument is optional for the Add and Removeoperations, but is invalid for Backup operations.


Methods and Jobs


-login_user user_name Identifies the user as whom to connect.

This argument is optional for the Add and Removeoperations, but is invalid for Backup operations.

-password user_password The clear-text password for the user identified in-login_user.

This argument is required for the Add operation, but isinvalid for Remove and Backup operations.

-f repository_filepath Path to the repository connection file.

This parameter is a required parameter for alloperations.

-operation operation_name Identifies the operation being performed. Include onlyone operation on each execution of the utility. Validoperation names are:• add• remove• backup

Use add to add the connection information specifiedin the server_config, user, and password argumentsto the file. If the entry already contains an entrywith a matching server config value, this informationreplaces that entry. The password is encryptedbefore being added to the file. You must include the-password argument for an add operation. Includingthe -login_user argument is optional.

Use remove to remove an entry from the file. Theutility removes the entry with a value matching the-server_config name. Including the -login_user or-password arguments for a remove operation is optional.

Use backup to create a backup of the file. The backupfile is created in the same directory as the original file.The name is the file’s name with an appended timestamp, in the format:

file_name-time_stamp

Do not include the -login_user or -password argumentsfor backup operations.


Methods and Jobs

When the utility executes an Add operation, it looks for an entry in the file that matchesthe values you provide as arguments for -server_config, -login_user, and -login_domain.If a match is not found, the utility creates a new entry. If a match is found, the utilityreplaces the existing entry with the values in the arguments.

Recovering from a job sequence failure

If the controlling job exits with a status of 1, it typically means that one or more jobsin the sequence failed to complete successfully. To recover from that situation, takethe following steps:

1. Examine the controlling job’s status report to determine which jobs failed.

Use Documentum Administrator to view the job’s status report. Interpreting a jobsequence status report, page 158, describes the entries in the report.

2. Examine the job reports of the failed jobs and the session and repository log files todetermine the cause of the failure.

3. Correct the problem.

4. Run dm_run_dependent_jobs as a method, with the -skip argument, to re-executethe failed jobs.

Executing dm_run_dependent_jobs independently, page 159, describes thearguments that you can include when you run the method independently of the job.

Interpreting a job sequence status report

The dm_run_dependent_jobs method, called by a job sequence’s controlling job,generates a status report. You can view the status report using DocumentumAdministrator. Table 16, page 158, lists the events recorded in the report and describestheir format.

Table 16. Entries in a job sequence statusreport

Event Entry Format

StartDate Time start-sequence=job_sequence_name

Start JobDate Time start job - docbase=repository_namejob=job_id attempt=1|2|3


Methods and Jobs

Event Entry Format

End JobDate Time end job - docbase=repository_namejob=job_id result=succeed|fail lastReturnCode=a_last_return_code lastDocumentID=ID_of_job_reportlastJobStatus=a_current_status

EndDate Time end - job_sequence=controlling_job_idresult=succeed|fail

ErrorDate Time error - docbase=repository_namejob=job_id msg=error_message

Executing dm_run_dependent_jobs independently

You can execute the dm_run_dependent_jobs method independently of the controllingjob. Use Documentum Administrator to run the method manually.

Table 17, page 159, lists the arguments accepted by the method. Some arguments arerequired and some are optional.

Table 17. dm_run_dependent_jobs arguments

Argument Required? Description

–docbase repository_name

Yes Identifies the repository that contains the jobsequence.

–user_nameuser_name

Yes Identifies the user executing the job sequence.

–job_sequencesequence_name

Yes Identifies the job sequence to be executed.

–method_trace_leveltrace_level

No Defines a trace level for thedm_run_dependent_jobs method. Thetwo valid values are 0 and 10. 0 recordsstatus messages only. 10 provides debuggingmessages in addition to status messages.

The default trace level is 0.


Methods and Jobs

Argument Required? Description

–skip list_of_jobs No Identifies the jobs in the sequence thatyou do not want to execute. Provide acomma-separated list of job object IDs.

–dcf See description Specifies the location of the repositoryconnection file.

This is not required if the method is usingtrusted login to connect to the repositories inwhich the jobs in the sequence reside.


Chapter 5Managing Repository Sessions

This chapter contains instructions for common administration tasks for repository sessions. Fora detailed description of sessions and how sessions behave, refer to Documentum Content ServerFundamentals. The topics in this chapter are:• Terminology, page 162• The dfc.properties file, page 162• Defining connection brokers for connection requests, page 163• Failover and load balancing, page 164• Requesting a specific server connection, page 165• Turning off trusted login, page 166• Defining the secure connection default for connection requests, page 166• Configuring the number of connection attempts and the retry interval, page 167• Specifying the maximum number of sessions, page 167• Limiting which clients can access a repository, page 168• Configuring privileged DFC use, page 168• Configuring connection pooling, page 172• Configuring login tickets, page 173• Changing a session’s configuration, page 174• Changing the assigned default operating system permissions (UNIX only), page 175• Defining short date formats, page 175• Changing the client local area directory location, page 176• Setting disk space limits for the client local area , page 176• Removing content from client local areas, page 176• Managing persistent client caches, page 177


Managing Repository Sessions

TerminologyThis chapter uses the following terms in the manner described:• A client is an end user, application, or process that uses Content Server to access

the repository.• A client platform is the machine on which the end user applications are running.

The dfc.properties leMost of the configuration parameters that configure how repository sessions are handledby DFC are contained in the dfc.properties file. For example, the file contains keys thatidentify which connection brokers are used to obtain a session, specify how manysessions are allowed for one user, and enable persistent client caching. Many keys havedefault values, but some must be explicitly set by an administrator or application.

Some of the keys in the file are dynamic; that is, changing them affects any open sessionsas soon as DFC notes the change. Other keys are not dynamic. Changing non-dynamickeys affects only future sessions. Current sessions are not affected. Dynamic changesare effective the next time DFC checks the file for changes. By default, the file ischecked for changes every 30 seconds. This interval is configurable. It is set in thedfc.config.check_interval key in the dfc.properties file.

The dfc.properties keys are described in file called dfcfull.properties, which is installedwhen you install DFC. The information in that file describes each key and its defaultand valid values, as applicable.

Key format

Each key in the dfc.properties file has the following format:category.name=value

The category identifies the functionality, feature, or facility that is configured or controlledby the key. Key categories are in the format:dfc.category_name

where category_name can be one or more words separated by periods. For example, thefollowing are key categories: dfc.data, dfc.content, dfc.tracing, and dfc.search.ecs.

The name begins after the last period in the key. If the name contains multiple words,they are separated by underscores. For example, the following are key names: dir,max_error_retries, and enable.



When you add a key to the dfc.properties file, you must specify both the category andthe name, in addition to a value. For example:dfc.data.dir= valuedfc.tracing.enable= valuedfc.search.ecs.broker_count = value

Setting dfc.properties entries

For EMC Documentum web-based products, the dfc.properties file is packaged in theapplication’s WAR file. The file is modified using a JMX-based resource agent throughDocumentum Administrator.

For desktop applications and Content Server, the file is installed on the file system duringproduct installation. On Windows hosts, it is found in the C:\Documentum\Configdirectory. On UNIX hosts, it is found in $DOCUMENTUM_SHARED/config. The filemay be edited using any text editor.

The dfc.properties file is a standard Java properties file. If the value you are specifyingfor a key has a special character, you can use a backslash (\) to escape the character. Indirectory path specifications, use a forward slash (/) to delimit directories in the path.

Dening connection brokers for connectionrequests

When a client requests a connection, the request is sent to a connection broker, whichreturns server connection information to the client. Which connection brokers canhandle a client’s connection request is defined in the client’s dfc.properties file. Theremust be at least one connection broker identified in the dfc.properties file. If multipleconnection brokers are defined in the file, the system will use the additional connectionbrokers if needed for backup or failover. Failover and load balancing, page 164, formore information.

Specifying connection brokers

The dfc.properties file used by a session must specify at least one connection broker.Including additional entries for backup is optional; however, providing additionalentries for backup can help ensure that all connection requests are successful.

To specify a connection broker in the dfc.properties file, use the following keys:



dfc.docbroker.host[n]=host_name|IP_address #requireddfc.docbroker.port[n]=port_number #optional

The [n] is a numeric index, where n is an integer starting with 1. All keys for a particularconnection broker must have the same numeric index. If there are entries for multipleconnection brokers, DFC contacts the connection brokers in ascending order based onthe numeric index by default.

The host_name is the name of the machine on which the connection broker resides. TheIP_address is the IP address of the machine.

The port is the TCP/IP port number that the connection broker is using forcommunications. The port number defaults to 1489 if it is not specified. If the connectionbroker is using a different port, you must include this key.

The following example defines two connection brokers for the client:dfc.docbroker.host[1]=bigdogdfc.docbroker.port[1]=1489

dfc.docbroker.host[2]=littlecatdfc.docbroker.port[2]=1489

In this example, lapdog is defined as the connection broker. Because lapdog is not usingthe default port number, the port number is also specified in the file:dfc.docbroker.host[1]=lapdogdfc.docbroker.port[1]=1491

Only the host specification is required. The other related keys are optional.

If you add, change, or delete a connection broker’s keys, the changes are visibleimmediately. You do not have to restart your session.

Failover and load balancingFailover and load balancing for client requests to connection brokers are controlled bysettings in the dfc.properties file. The dfc.docbroker.auto_request_forward key controlsfailover. The dfc.docbroker_search_order key controls load balancing. For informationabout setting up default failover, refer to Failover for connection brokers, page 191. Forinformation about setting up load balancing, refer to Load balancing for connectionbrokers, page 191.



Requesting a specic server connectionIf you have started multiple servers for a repository, you can be as specific as you likeabout which server you want to use for your repository connection. You can:• Let DFC choose the server for you• Choose a server by its name• Choose any server residing on a specific host machine• Choose a server by name that resides on a specific host machine

Requesting a server by name

To request a server by name, include the name of the server in the session request.

If there is no server with the specified name that accesses the specified repository, theconnection request fails.

To find out what servers are associated with a particular repository, use anIDfDocbrokerClient.getServerMap or getServerMapFromSpecificDocbroker method.Refer to the Javadocs for information about these methods.

Requesting a server on a specic host

You may want the connection broker to give you only connection information for aserver that lives on a specific host machine. To do this, specify the repository in therequest as repository@host_name in the connection request.

If there is no server on the specified host that accesses the specified repository,the connection fails. To ensure that you request a host that has at least one serverthat accesses the requested repository, use an IDfDocbrokerClient.getServerMap orgetServerMapFromSpecificDocbroker method. Refer to the Javadocs for informationabout these methods.

Requesting a server by name on a specic host

You can tell the connection broker exactly which server you want on aspecific host machine by specifying the repository in the connection request asrepository.server_name@host_name.



If the specified server does not reside on the specified host or if the server does not accessthe specified repository, the connection fails.

Turning off trusted loginBy default, applications running on the Content Server host are allowed to makerepository connections as the installation owner without presenting a password. This iscalled a trusted login. If an application, such as Documentum Administrator, that has anexplicit login dialog box is installed on a Content Server host, a user is able to login as theinstallation owner without a password using a trusted login.

If you do not wish to allow trusted logins through such applications, you can set thefollowing preference in the dfc.properties file to F:dfc.session.allow_trusted_login=F

When that key is false, a user is required to always provide a password, even whenlogging in as the installation owner.

Dening the secure connection default forconnection requests

All connections between Content Server and a client application are either secure ornative (unsecure) connections. Which option is used for a particular connection dependson how the server is configured and what sort of connection is requested by the clientapplication when it attempts to obtain a session. If the request does not specify whattype of connection is requested, the connection type specified in the dfc.properties file, inthe dfc.session.secure_connect_default key, is used.

There are four possible settings for this key:• native

native means that you want only a native connection. If DFC cannot establish anative connection, the connection attempt fails.

• secure

secure means that you want a secure connection only. If DFC cannot establish asecure connection, the connection attempt fails.



• try_secure_first

try_secure_first means that you prefer a secure connection, but will accept a native(unsecure) connection. DFC attempts to establish a secure connection first. If itcannot, it tries to establish a native connection. If that also fails, the connectionattempt fails.

• try_native_first

try_native_first means that you prefer a native connection, but will accept a secureconnection. DFC attempts to establish a native connection first. If it cannot, it tries toestablish a secure connection. If that also fails, the connection attempt fails.

The default setting for the key is try_native_first.

Specifying a connection type in the application overrides the default setting in thesecure_connect_default key. For information on how to specify it in an application,refer to the DFC Development Guide. The Javadocs for IDfLoginInfo.setSecurityModedescribe the interaction between the connection type requested by the client and theserver default setting. Setting the secure connection mode, page 110, describes howto set the server default.

Conguring the number of connection attemptsand the retry interval

Two keys in the dfc.properties file control DFC behavior regarding the number ofconnection attempts and the interval between the attempts when an application issues arequest for a session. One key controls how many attempts are made to obtain a sessionby DFC in response to the request and one controls how long DFC waits between eachattempt.

To set the number of attempts, set the dfc.session.max_connect_retries key. This key isset to 2 by default.

To set the interval between attempts, set the dfc.session.connect_retry_interval key. Thekey is set to 0 by default. Zero means that the retries are issued immediately, with nowaiting time.

Specifying the maximum number of sessionsThe dfc.session.max_count key in dfc.properties defines the maximum number ofsessions that can be opened for a particular user or application. By default, the key is setto 10. The format of the key is:dfc.max_count=n



where n is an integer value greater than zero.

Note: The maximum number of sessions possible for a client process running on a UNIXplatform is also limited by the descriptors set in the UNIX kernel. If a client processrequires more sessions than this limit permits, the UNIX system administrator mustmodify the UNIX kernel.

Limiting which clients can access a repositoryYou can enforce which EMC Documentum client versions may access a particularrepository.

Two properties of the docbase config object control client access: the oldest_client_versionproperty and the check_client_version property. The oldest_client_version property isused by DFC to determine how to store chunked XML documents. Its value must beset manually.

When check_client_version is set to TRUE, then the value of oldest_client_version is alsoused to determine the oldest Documentum client version that may access the repository.

If Retention Policy Services or Collaborative Services is enabled in the repository,the value of oldest_client_version is set to 6.0 and the value of check_client_versionis set to TRUE. If older clients must access that repository, you must manually setcheck_client_version to FALSE. However, note that the older clients can bypass therestrictions imposed by Retention Policy Services.

Conguring privileged DFC usePrivileged DFC is a standard security feature that enables DFC instances to invoke aprivileged BOF module to perform operations not otherwise permitted to the user aswhom the application is running. The procedures in this section configure the use ofthis feature.

For a detailed description of this feature, refer to Content Server Fundamentals.

Creating client rights objects

Client rights objects define the roles a particular DFC may use within a repository.After installing a DFC instance, use Documentum Administrator to create a clientrights object in each repository in which the DFC will use a privileged role or invoke aprivileged module. When you create a client rights object, Content Server also copies the



specified public key certificate from the global registry to the repository to which you areconnected. The copy is stored in a public key certificate object.

For instructions on using Documentum Administrator, refer to the online help or tothe Documentum Administrator User Guide.

Conguring a repository to accept only authenticatedDFC instances

An authenticated DFC instance is a DFC instance that has a client rights object and anassociated public key certificate object in the repository. By default, a Content Serveraccepts a connection request sent by any DFC instance. However, you can configure arepository to decline all connection requests except those coming from authenticated DFCclients. To do so, set the approved_clients_only property in the docbase config object.

Setting this to T directs a repository’s Content Server to accept connection requests onlyfrom DFC instances that have a client rights and an associated public key certificate inthe repository. If the property is F (false), the repository’s Content Server may acceptconnection requests from any DFC instance.

Use Documentum Administrator to set this property.

Enabling privileged DFC

In most installations, no manual operations are required to enable and use privilegedDFC. There are two requirements to use privileged DFC, both of which are metautomatically in most environments. These requirements are:• The dfc.privilege.enable key in the dfc.properties file must be set to T.

This is the default setting for the key.• The Java security policy file or files must be modified to give the dfc.jar file all

permissions

In installations in which the JRE environment is owned by the Documentum product,the necessary modifications are done during product installation. For example,the modifications are performed automatically when you install Content Server,Documentum Administrator, or a WDK-based application on the application server.

However, in some environments, the application does not own the JRE environment.In those instances, you must manually modify the file. For example, if you installIAPI or IDQL and a DFC instance on a workstation, you must manually modifythe Java security policy file or files. For instructions on modifying the file, refer toModifying the Java security policy , page 170.



Disabling privileged DFC

To disable a DFC instance’s use of privileged DFC, set the dfc.privilege.enable key in thedfc.properties file to false.

To disable use of privileged roles and modules:1. Add the following key to the dfc.properties file used by the DFC instance:dfc.privilege.enable=F

2. Reinitialize the DFC instance.

Modifying the Java security policy

The implementation of the privileged DFC feature assumes that the dfc.jar file has allpossible privileges in the JRE environment. To make that assumption true, the Javasecurity policy files are modified automatically during installation of Documentumproducts that also install a DFC instance. However, if you are running a DFC instancein an environment in which you do not own the JRE environment, you must makethe necessary file modifications manually if you want the DFC to run as a privilegedDFC. For example, a workstation on which IAPI is installed may require the manualmodifications.

The security policy files are referenced in the $JREHOME/lib/security/java.security file,which configures the JRE startup environment for finding the policy files. The entriesfor the default policy files are:policy.url.1=file:${java.home}/lib/security/java.policypolicy.url.2=file:${user.home}/.java.policyThe default policy files are:${java.home}/lib/security/java.policy${user.home}/.java.policyThe file found in ${java.home}/lib/security is a global file. Modifying that file affectsall instances of the JVM in $JREHOME/ on the host. The file found in ${user.home} isspecific to the user who starts the JVM. The set of permissions given to a program is theunion of the permissions contained in the global and user-specific policy files.

These files are text files. To edit the files, use the policytool utility or a text editor. Foreach instance of a dfc.jar file that may be used for privileged DFC, the policy file mustcontain an entry like this:grant codeBase "file:/C:/fully_qualified_path_to_dfc.jar"{permission com.documentum.fc.client.impl.bof.security.RolePermission

"*", "propagate";};



where fully_qualified_path_to_dfc.jar is the fully qualified path to the dfc.jar instance. Ifneeded, consult the JDK documentation for help with the syntax. A syntax guide for theentries in the

Managing the keystore le

The keystore file stores a DFC instance’s PKI credentials. By default, this file is nameddfc.keystore file and it is stored in the same directory as the dfc.properties file. Youcan change the file’s name and location.

The credentials in the file are accessed using the keytool utility provided with the JavaSDK.

Changing the location and name of the keystore le

By default, the PKI credentials for a DFC instance are stored in a file named dfc.keystorethat is stored in the same directory in which the dfc.properties file is stored. Youcan change its location, and optionally its name, by setting the following key in thedfc.properties file:dfc.security.keystore.file

The key must be set to a fully qualified file name.

Changing the passwords used with keytool

PKI credentials are composed of two parts: a public key and a private key. When youaccess a set of credentials using the keytool utility, you must provide a password toaccess either key. There are two different passwords: one for the public key and one forthe private key. Default passwords are provided for accessing each key.

The default password for the public key is “dfc”. To change that password, set thefollowing key in the dfc.properties file:dfc.security.keystore.password=newPassword

where newPassword is the password you wish to use to access the public key in thecredentials.

The default password for the private key is “!!dfc!!”. To change that password, set thefollowing key in the dfc.properties file:dfc.security.keystore.privatekey.password=newPassword



where newPassword is the password you wish to use to access the private key in thecredentials.

Conguring a shared keystore le

It is possible to configure multiple DFC instances to share the same keystore file. Todo so, you must set the name and location of the keystore file to the same name andlocation for each keystore. You must also configure an alias for each DFC instance todisambiguate the identities of the instances within the file. By default, the alias foreach DFC instance is dfc. If multiple instances are sharing the same keystore, you mustdefine unique aliases for each.

To define an alias for a DFC instance, set the following key in the dfc.properties fileused by the DFC instance:dfc.name=alias

where alias is the alias name you wish to assign the instance. The alias must be uniqueamong those DFC instances sharing the same keystore file.

Conguring connection poolingConnection pooling allows applications to reuse sessions. When a session is releasedor disconnected, the session is held in the pool to be used the next time the user ora different user requests a connection to the repository. DFC uses connection poolingby default. However, explicitly enabling connection pooling is recommended becausethe most efficient resource management is provided when pooling is explicitly enabled.For complete details of how connection pooling is implemented, refer to Content ServerFundamentals.

Enabling connection pooling

To enable connection pooling, set the dfc.session.pool.enable key in the dfc.propertiesfile to TRUE.

Setting this key affects all sessions that are opened after the key is set. Sessions that areopen when the key is set are not affected.



Conguring login ticketsLogin tickets are values that applications can use in place of a user’s password whenestablishing a repository session or authenticating a user. Login tickets are obtained byexecuting one of several methods in the IDfSession interface. For a complete descriptionof login tickets, their use and implementation, refer to Content Server Fundamentals.

You can configure the length of time for which a ticket is valid and, indirectly, the numberof tickets that a Content Server can maintain concurrently. You can also configurewhether Content Server generates login tickets for backwards compatibility.

Setting ticket validity period

To define the length of time for which a login ticket is valid, set the login_ticket_timeoutproperty in the server config object. By default, the property is set to 5 minutes.

After you set the property, you must reinitialize the server to make the change take effect.

Setting the ticket cache size for Content Server

By default, the maximum number of tickets with server scope that can be cached inContent Server is equal to 10 times the maximum number of concurrent sessions. Forexample, if the maximum number of concurrent sessions allowed is 1000, then themaximum number of tickets that can be cached is 10,000.

You can change the multiplier (10) by setting the ticket_multiplier key in the server.inifile.

The number of concurrent sessions is controlled by the concurrent_sessions key in theserver.ini file.

Conguring login tickets for backwards compatibility

In environments that have Content Servers at mixed version levels, you may wish togenerate login tickets that are compatible with the version level of the server that willreceive the login ticket. For example, if you have multiple Content Servers on onerepository, there may be a period where one or more of the servers are not yet upgradedto version 6. Or if you are using global login tickets, the Content Servers in the differentrepositories may be at different version levels.



A Version 6 Content Server can accept a login ticket generated from any Content Server,regardless of the server’s version level. However, a pre-5.3 SP4 Content Server cannotautomatically accept login tickets generated by a Content Server at version 5.3 SP4 orhigher. And, a 5.3 SP4 or 5.3 SP5 Content Server cannot automatically accept login ticketsgenerated by a Version 6 Content Server.

To ensure that login tickets generated by a Content Server are backwards compatible, setthe server_login_ticket_version key in the server.ini file:• Set the key to 1 to generate login tickets acceptable to a pre-5.3 SP4 Content Server

This setting is only valid on Version 6, 5.3 SP4, and 5.3 SP5 Content Servers.• Set the key to 2 to generate login tickets acceptable to a 5.3 SP4 or 5.3 SP5 Content

Server

This setting is only valid on Version 6 Content Servers.• Set the key to 3 to generate login tickets acceptable to Version 6 Content Servers.

This setting is only valid on Version 6 Content Servers.The key default to 3 if not set.

Changing a session’s congurationA session’s configuration, or operating behavior, is determined by the values of theproperties in its session config and connection config object and in the client configobject. The session and connection config objects are constructed when the session isstarted, using the properties of the client config object and the server’s server configobject. The values in the client config object are reflections of the values in the client’sdfc.properties file.

You can change the behavior of a session by changing any of the configuration objects orthe dfc.properties file. Changing the session config or connection config objects affectsonly the current session. Changing the dfc.properties file or the client config objectaffects all sessions using those objects.

If you change the server config object, and reinitialize the server, after you change andsave the server config object, the changes affect your current session and any subsequentsessions. Note that current sessions other than yours are not affected by the changes. Ifyou restart the server after you change and save the server config object, the changesaffect only your current session. (Future sessions are not affected until you reinitializethe server.) Restarting the server is a useful way to test changes before making themvisible to other sessions.



Changing the assigned default operatingsystem permissions (UNIX only)

When a client DFC creates directories on the client machines or writes files to directorieson the client machines, it assigns default operating system permissions to thosedirectories and files. The default permissions assigned to directories are 777 and thedefault permissions assigned to files are 666. You can change the defaults assigned topublic directories and files by setting the dfc.data.umask key in the dfc.properties file orby setting the corresponding property in the client config object.

Setting dfc.data.umask in the dfc.properties file affects all public directories and filescreated during sessions established using that file. Setting it in the client config objectaffects only directories and files created during repository sessions under that sessionmanager.

The dfc.data.umask value works similarly to the UNIX umask functionality. The value issubtracted from the default permissions to determine the actual permissions assignedto a file or directory. For example, if you set umask=2, then the default permissionsassigned to directories becomes 775 and the default permissions for files becomes 664.Or, if you set umask=22, then the permissions become 755 for directories and 644 for files.

Dening short date formatsDifferent parts of the world have different shorthand ways to write a date. Forexample, some people use mm/dd/yy and others use dd-mm-yyyy. To accommodate thesedifferences, the client platforms allow users to specify a short date format. The serverrecognizes all of these user-specified short date formats as valid formats for date input.

If a short date format is defined for a client machine, the server displays dates on thatclient using the short date format. If no short date format is defined on a client machine,the server uses mm/dd/yyyy as the default.

On Windows clients, use Control Panel > Regional and Language Options to set theshort date format.

On UNIX clients, defining the short date differs by machine:• For SunOS and HP-UX clients, there is no way to define a short date format. The

server assumes the format in these cases to be mm/dd/yy hh:mm:ss.• For Solaris and AIX, the short date format is the format defined by the machine’s

locale. (Locale is set by the setlocale command.) In most cases, this is already setto the appropriate value. However, if it is not, you can set the time and date to usethe appropriate locale with the following command:setenv LC_TIME local_code



• Refer to your UNIX System Administrator’s manual for the Solaris machine for thevalid local codes.

Changing the client local area directorylocation

To change the location of the client local area directory, you can:• Set the dfc.data.local_dir key in the dfc.properties file.

Changing the key affects the current session and all future sessions using that file.• Set the dfc.data.local_dir property in the client config object.

Changing this property affects the current session and any session established whilethe client config object persists. The object persists while the DFC remains initialized.

• Set the dfc.data.local_dir property in the session config object.

Changing this property affects only the current session.

Setting disk space limits for the client localarea

You can set the dfc.data.local_diskfull_limit key in the dfc.properties file to set a limit onthe size of the client local area. By default, this key is set to 0, which means the size of theclient local area is allowed unlimited growth.

This is an integer key. If set to a value other than zero, the value is interpreted asmegabytes and represents the maximum allowed size of the client local area. If copyinga file into the local area will fill the space beyond this limit, the server generates anerror and does not copy the file.

By default, when a client reaches the limit, the server automatically removes all thecontent files from the client’s local area that were fetched during that client’s session. Thisbehavior is controlled by the dfc.data.local_purge_on_diskfull key in the dfc.propertiesfile. It is a Boolean key and is set to TRUE by default during the installation procedure.

Removing content from client local areasWhen users terminate their sessions, the files that they requested during their sessionsare automatically removed from the client local area. If a session terminates abnormally,



for example, if the machine crashes, the local area is not cleaned up. However, bydefault, each time a session is started on a client machine, the system scans the machine’slocal area and cleans up any files not being used by an active session. This means thatthe files left behind by an abnormal session termination are removed when the nextsession is started.

The system uses the session ID in the file’s path to determine if the file is in use or not. Ifthe session is an active session, the file is not removed during the clean up. If the sessionis not an active session, the file is removed.

The default cleanup when starting a session is controlled by the dfc.data.local_clean_on_init key in the dfc.properties file. This key is true by default.

Note: Files copied to client local areas are given names in the following format:\root\docbase_id\machine_name\session_id\file_name

or, on UNIX:/root/docbase_id/machine_name/session_id/file_name

Manual clean up

If you receive an error or warning because you have exceeded the limit specified in thedfc.data.local_diskfull_limit key, you can use the IDfSession.purgeLocalFiles method toremove the files in your local area.

The method removes from the local area copies of any files that you have requestedduring your current session. It does not remove files copied into the area by other activesessions. For example, if you have sessions A and B open, executing purgeLocalFilesfrom session A only removes files copied into the area during session A. The filesrequested by session B are not touched.

Any user can use this method.

Managing persistent client cachesPersistent client caches are caches of objects and query results managed by the clientDFC and maintained across sessions. Objects and query results are placed in thecaches by specific request when an application or user issues a caching fetch or query.Typically, the cached objects and query results are objects and results that change veryinfrequently. If objects or results that change frequently are cached, the cached copiesmust be updated regularly and the benefits of caching are diminished.

Persistent client caching is enabled by default in repositories and client sessions.Documentum Webtop and Documentum Desktop take advantage of this feature



automatically. User applications can also take advantage of persistent client caching byusing the DFC methods that support object and query caching.

Cached data is checked for consistency with the repository based on consistency checkrules defined when the fetch or query is executed. Objects and query results can beconsistency checked individually or a set of data can be defined in a cache config objectand checked as a set.

For a complete description of persistent client caching and it use, refer to Content ServerFundamentals. This section contains instructions for enabling or disabling persistentclient caching and for creating cache config objects.

Enabling and disabling persistent client caching

Persistent client caching can be controlled at either the repository level or session level.

For a repository

To enable or disable persistent client caching for a repository, set theclient_pcaching_disabled property in the docbase config object. If persistent clientcaching is disabled for a repository, users cannot persistently cache objects fetched fromthe repository or the results of queries against the repository.

The default setting for the property is F (FALSE), meaning that persistent caching isenabled for the repository. Setting client_pcaching_disabled to T (TRUE) disablespersistent client caching for the repository.

For client sessions

Persistent client caching is controlled at the session level by the dfc.cache.enable_persistence key in the dfc.properties file.

The key affects both object and query caching. It is TRUE by default, allowing clientsto persistently cache both objects and query results. If you set the key to FALSE, userscannot persistently cache objects or query results.



Creating cache cong objects

Cache config objects are used to group cached objects and query results into a singleunit for purposes of consistency checking. You must be a Superuser to create a cacheconfig object.

To create a cache cong object:1. Create a dm_cache_config object.

2. Set the object_name of the cache config object to a name that is unique among thecache config objects in the repository.Although not enforced by Content Server, the object name must be unique amongthe cache config objects in the repository because the object is referenced by name inmethods. If the name is not unique, consistency checking results will be ambiguousand unpredictable.

3. Set the cache_element_queries and cache_element_types properties.These properties define the set of cached data managed by the cache config object.Refer to Defining the cached data set, page 179, for information and guidelines forsetting these properties.

4. Set the server_check_interval.This determines how often Content Server validates the cached data. Defining theserver check interval, page 180, contains guidelines for setting this property.

5. Set the client_check_interval.This determines how often a client application refreshes the cached data. Definingthe client check interval, page 181, contains information about how this property isused.

6. Save the cache config object.

Dening the cached data set

Youmust set two properties to identify the cached data managed by a cache config object:cache_element_queries and cache_element_types. Both are repeating properties. Thecache_element_queries property contains a list of DQL queries. Each index position inthe property can store one DQL SELECT statement. Each SELECT statement can returnone or more objects or a set of query results. The cache_element_types property indicateswhether the query in the corresponding index position in cache_element_queries isreturning objects or a query result set for caching.

The queries can be any legal SELECT statment.



The queries that return objects must identify the same objects that are fetched by thefetch methods that reference the cache config object. Similarly, the queries that returnquery results for caching must match the queries defined in the IDfQuery object thatreference the cache config object.

If the query is returning objects, include r_object_id and i_vstamp in the selected valueslist. This ensures that if the object is changed, the results of the query change.

If you are caching objects that are SysObjects or SysObject subtypes, you may want toinclude the ALL keyword. The ALL keyword directs Content Server to examine allversions of the objects and return any that satisfy the query. If ALL is not included, onlythe CURRENT version of an object is examined. Including ALL ensures that consistencychecking on older object versions is not skipped.

The cache_element_type property identifies what the query in the corresponding indexposition in cache_element_queries returns. Legal values are “query” and “object”. Forexample, suppose you want to cache an SOP named SOP_1216, and to do so, you setcache_element_queries[3] toSELECT "owner_name","i_vstamp","r_object_id" FROM "dm_document"WHERE "title"='SOP_1216'

To tell Content Server that the query in cache_element_queries[3] refers to an object, youmust set cache_element_types[3] to object.

The order in which query results are returned is important in consistency checking. Ifthe order of the returned results varies whenever the query is run, it appears as if theresults have changed and the client caches are assumed to be invalid. If a query definedin a cache config object is sufficiently complex that the RDBMS may periodically vary thequery plan used to execute the query, it is recommended that you include an ORDERBY clause in the query.

Dening the server check interval

The server check interval defines how much time can elapse between validations of thequeries in a cache config object. The server check interval is expressed as seconds and isdefined in the server_check_interval property.

When a CHECK_CACHE_CONFIG administration method is issued, the method sends arequest to Content Server to validate the data defined in the cache config object. ContentServer subtracts the r_last_checked_date value in the cache config object from the currenttime and date and compares the result to the value in the server_check_interval. If thesubtraction result is greater than the value in server_check_interval, the server calls thedm_CheckCacheConfig method to re-execute the queries defined in the cache configobject. The query results are hashed and the hash is stored in the i_query_result_hashproperty and the r_last_checked_date and r_last_changed_date properties are updated.



Dening the client check interval

The client check interval determines how often client applications ask Content Serverto validate the cached data defined in a cache config object. The client check interval isdefined in seconds and set in the client_check_interval property.

When a session first references a cache config object, DFC obtains informationabout that cache config object from the server and stores that information witha timestamp. Thereafter, whenever the object is referenced during the session,DFC subtracts the timestamp from the current time and compares the result to theclient_check_interval value. If the result is greater than the check interval, DFC issues aCHECK_CACHE_CONFIG administration method, to ask Content Server whether thecached results are still valid. Content Server uses the value in server_check_interval todetermine whether or not to rerun the queries in the cache config object.

Manually forcing refreshes

Although data persistently cached in the client DFC is checked for consistency andautomatically updated when needed, you may want to occasionally force a refresh. Toforce a refresh, you can:• Flush the objects you want to refresh from a cache• Reset the client_pcaching_change property in the docbase config object

Flushing a persistent cache

To flush a persistent client cache, use an IDfSession.flush method. You can flush cachedobjects or queries or both. The method only acts on the persistent caches owned by theuser who executes the method. You can remove:• All persistently cached objects and query results in a cache• Only cached objects or only cached queries from a cacheIf a persistent object cache is flushed, the next time the user who owns the cache accessesa persistently cached object, Content Server refetches the object, and it is stored in thecache again. Similarly, if cached queries are flushed, the next time the cache ownerexecutes a cached query, Content Server recomputes the results, and they are storedagain in the cache. For instructions on using flush, refer to the Javadocs.



Setting the client_pcaching_change property

The client_pcaching_change property in the docbase config object is used byDocumentum clients to determine whether to refresh all persistent client caches. Whena Documentum client application starts up, it checks the value of that property. Ifthe value has not changed since the last time the value was checked (the last time theapplication started), the caches are retained. If the value has changed, DFC throwsaway the persistent client caches.

Automating cache cong data validation

To automate validation of the cached data defined in a cache config object, create ajob to execute the dm_CheckCacheConfig method. If you automate the server-sidevalidation, when DFC asks the server if the cached data is current, the server can respondimmediately, without requiring a check at the time the request is issued.

To create a job automating cache cong validations:1. Create a script that calls the DO_METHOD administration method executing the

dm_CheckCacheConfig method.The DO_METHOD syntax is:apply,session,,DO_METHOD,METHOD,S,dm_CheckCacheConfig,ARGUMENTS,S,argument_list

The argument list must include the following arguments:• -docbase_name docbase_name• -user_name user_name• -cache_config_name cache_config_obj_nameYou can also include an argument that sets a tracing level for the method if youlike: -method_trace_level trace_level, where trace_level is a value from 0 to 10. If youinclude the method_trace_level argument, you may want to set the SAVE_RESULTSargument for the DO_METHOD to TRUE:apply,session,,DO_METHOD,METHOD,S,dm_CheckCacheConfig,ARGUMENTS,S,argument_list,SAVE_RESULTS,B,T

Doing so causes the trace results to be saved to a document rather than the serverlog. (For complete information about using DO_METHOD, refer to the ContentServer DQL Reference Manual.)

2. Create a method object and associate the script with the method object.Refer to Chapter 4, Methods and Jobs, for instructions on creating a method object.

3. Create a job to execute the method object.



Chapter 4, Methods and Jobs, contains instructions for creating jobs also.To be most beneficial, schedule the job to execute at an interval more frequent thanthe interval defined in the server_check_interval property of the cache_config_object.

For general information about creating jobs, refer to Creating jobs and job sequences,page 145.

Overriding consistency checking rules

Overriding the consistency checking rules forces DFC to use the default consistencychecking rule. The default is to always check. This means that if the cached data is anobject, the object is always checked against the object in the repository. If the cached datais a set of query results, the results are always regenerated.

To override consistency checking rules, set the dfc.force_coherency_check key in thedfc.properties file or the corresponding property in the client config object or connectionconfig object. If you set force_coherency_check to T, the consistency checking rulesdefined in a fetch method or with a query are ignored by DFC. Instead, DFC uses thedefault consistency checking rule.

Dening the persistent cache write interval

The persistent cache write interval controls how often persistently cached objects arewritten to the persistent object cache file on the user’s local disk during a repositorysession.

When objects are fetched, they are stored in an in-memory object cache in DFC. Theobjects are placed in the cache the first time they are fetched by a client. If the object isnot persistently cached, it remains in the cache only for the life of the repository session.If the object is persistently cached, at the close of the session, the object is written to afile on disk. The file is located in:root/object_caches/machine_name/docbase_id/abbreviated_user_name

When the next session is started, the objects in the file are loaded back into thein-memory cache.

During a session, persistently cached objects in memory may change. Consequently,each time the in-memory object cache is accessed, DFC determines whether the clientpersistent cache write interval has expired and if so, writes all the persistently cachedobjects from memory to the persistent object cache file.

The interval is defined by the dfc.cache.write_interval key in the user’s dfc.propertiesfile. The default interval is 3600 seconds (60 minutes). The update occurs if any cached



object types have been added or changed since the last update. If none of the objects havechanged and no new objects have been added to the cache, the update does not occur.

If an explicit transaction is open, writing cached objects to disk is delayed until after thetransaction is committed.

Troubleshooting persistent caching

There are several actions that you can take if you need to troubleshoot persistent cachingoperations:• Turn on RPC tracing and trace the fetch methods and query execution.

This tells you which queries are being satisfied using cached data. For example, if afetch method has no corresponding RPC call, the cached object was used.

• Examine the cached files directly.

The object cache files and the query result files are stored in ASCII. You can openthese files with a text editor.

• Invoke the dm_CheckCacheConfig method directly, to test its behavior or results.

Use the DO_METHOD administration method to invoke the method. Set the-method_trace_level argument to 10, to generate trace messages, and include theSAVE_RESULTS argument on the DO_METHOD command line to capture the tracemessages in a seperate document.

• Execute the CHECK_CACHE_CONFIG method with the FORCE_CHECK argumentset to T (TRUE).

This forces the server to execute the queries defined in the cache config object. Youmust be a superuser or have Execute Procedure permission on the cache configobject to use the FORCE_CHECK argument.

• Flush the caches.

Flushing a cache forces DFC to refetch the objects or re-execute the cached queriesthe next time the objects or query results are accessed. Flushing a persistent cache,page 181, contains information about how to flush a persistent cache.



• Delete or rename the cache files.

After you delete or rename the files, re-execute the fetch or query to determine if theproblem persists. If the problem persists, it is likely that the persistent cache is notsource of the problem.




Chapter 6Connection Brokers

This chapter contains information about the connection broker, Documentum’s name server. Thechapter includes the following topics:• An overview of connection brokers, page 187• Servers and connection brokers, page 189• Clients and connection brokers, page 190• Failover for connection brokers, page 191• Load balancing for connection brokers, page 191• Configuring a connection broker, page 191• Restarting a connection broker, page 195• Starting additional connection brokers, page 196• Shutting down a connection broker, page 197• Obtaining information from a connection broker, page 199• Obtaining information about connection brokers, page 200• Deleting server information, page 201

An overview of connection brokersThe Documentum connection broker is a process that provides client sessions withconnection information. To establish a connection, a client session must know where tofind a server that accesses the requested repository. When a client session is opened, theclient contacts the connection broker and requests the information it needs to connectwith a server for the requested repository. The connection brokers that can handlea client’s connection request are defined in the client’s dfc.properties file. Definingconnection brokers for connection requests, page 163, contains more information aboutdefining connection broker targets for clients.

The connection broker sends back the IP address for the host on which such a serverresides and the port number that the server is using. If there are multiple servers for the


Connection Brokers

repository, the connection broker returns connection information for all of them. Theclient session then uses that information to choose a server and open the connection.

Clients can request a connection through a particular server, any server on a particularhost, or a particular server on a specified host. Requesting a specific server connection,page 165, contains instructions.

How many connection brokers are there?

By default, each installation must have one connection broker. The first connectionbroker is started as part of the installation process. You can set up additional connectionbrokers later. Starting additional connection brokers, page 196, contains instructions.

What information does a connection broker have?

Each connection broker has information about servers and the repositories they access.Server information includes:• The server’s name• The process ID• The name of the host machine on which the server resides• The server’s status• When the connection broker last received some status information• When the connection broker expects to hear from the server againRepository information includes:• The repository name and ID• A description of the repositoryThere are methods in the DFC IDfDocbrokerClient interface that return information heldby connection brokers. For example, the getDocbaseMap method returns the informationabout repositories known to connection brokers. The getServerMap method returns theinformation for servers.

How does a connection broker get information?

Each server broadcasts information to connection brokers at regular intervals. Thebroadcast contains the information maintained by connection brokers about the serverand the repository accessed by the server. Servers and connection brokers, page 189,


Connection Brokers

contains a detailed description of the communications between servers and connectionbrokers.

Locating connection brokers

You can determine which connection brokers a client can talk to by issuing anIDfDocbrokerClient.getDocbrokerMap method call. This method returns a docbrokerlocator object. A docbroker locator object is a non-persistent object that is constructedand returned by the DFC in use by the session. It tells you which connection brokersyour session can access. For each connection broker, it tells you the host on which theconnection broker resides, what communication protocol it uses, the port number it usesfor communication, and its time-out period. Obtaining information about connectionbrokers, page 200, contains the procedure.

Alternatively, you can also examine the client’s dfc.properties file.

Connection broker conguration options

A standard connection broker works as installed and needs no additional configuration.However, you can change the configuration to:• Protect the connection broker from being shutdown by an unauthorized person• Define which servers can access the connection broker• Define a specific IP listening address for the connection broker

This is one way to run multiple connection brokers on one machine.• Enable a connection broker to service connection requests that originate outside

a firewallAll of these options are set up in the connection broker initialization file. This is anoptional file that is referenced on the command line when you start a connection broker.Configuring a connection broker, page 191, contains instructions on the format of theinitialization file, and how to configure the options.

Servers and connection brokersConnection brokers do not ask servers for information. Instead, they wait for servers tobroadcast information to them.

When you start a server, it automatically broadcasts information about itself. Eachconnection broker that receives the broadcast adds the server to its registry, or list of


Connection Brokers

known servers. The server sends the first broadcast before it is fully initialized, so theconnection broker sets the server’s status to starting. As soon as the server is fullyinitialized and ready to service clients, it broadcasts a checkpoint message. The receivingconnection brokers then update the server’s status to open.

Thereafter, the server broadcasts a checkpoint message at regular intervals. By default,the checkpoint interval is five minutes; however, you can reset it to a different value(Setting the checkpoint interval, page 116, contains instructions).

A connection broker keeps track of when it last heard from a server andwhen it expects tohear from that server next. If it does not receive a broadcast from a server at the expectedtime, it sets the server’s status to presumed down. A connection broker keeps the entryfor a non-broadcasting server for a certain number of hours. At the end of that time (thekeep entry interval), if the connection broker has not heard from the server, it removesthe server from its registry. By default, the keep entry interval is 24 hours. However, youcan change the interval (Setting the keep entry interval, page 116, contains instructions).

When a system administrator shuts down a server gracefully, the server sends out amessage telling the connection brokers that it is going down. The connection brokersthat hear that message set the server’s status to stopped. Later, when the server isrestarted, it rebroadcasts its information and the connection brokers update their entriesfor the server and reset its status.

Clients and connection brokersA client is anything requesting a connection to a server. For example, a client can beWebtop, an external application, or a user working with Documentum Administrator.In each case, at the start of a new client session, a connection must be established witha repository. To establish the initial connection, the client application first sends amessage to a connection broker asking for the service information that it needs to makethe requested connection.

Each client session has a default connection broker. Generally, to ensure continuousservice, clients also have backup connection brokers.

The default and backup connection brokers for clients are defined in the dfc.propertiesfile. Each EMC Documentum web-based client application contains a dfc.properties filepackaged with the application’s WAR file. Defining connection brokers for connectionrequests, page 163, contains information about defining connection brokers in adfc.properties file.


Connection Brokers

Failover for connection brokersFailover for connection information requests from a client is provided by identifyingmultiple connection brokers in the dfc.properties file and ensuring that thedfc.docbroker.auto_request_forward key in the dfc.properties file is set to T, whichis the default.

By default, a connection request is handled by the first connection broker listed in thefile. However, if that connection broker does not respond within 15 seconds or less ordoes not know about the requested repository, failover occurs if another connectionbroker is defined and auto_request_forward is T. The request is forwarded to the nextconnection broker in the file. If that connection broker does not respond, the request isforwarded to the next connection broker in the file. The request goes in turn to eachconnection broker listed in the file until a connection broker responds successfully oruntil all connection brokers defined in the file have been tried. If there is no successfulresponse, the connection request fails.

Load balancing for connection brokersTo ensure that connection requests do not all fall on the first connection broker identifiedin a dfc.properties file, use the dfc.docbroker.search_order key in the dfc.propertiesi file.The search_order key determines whether the request is sent first to the first connectionbroker or to a connection broker randomly selected from the list of connection brokersin the file.

Setting this key to “random” causes DFC to randomly select a connection broker fromthose specified in the dfc.properties file for a connection request. Randomly selecting aconnection broker from the list of connection brokers in the file helps prevent connectionbroker performance bottlenecks that can occur if large numbers of users are sharing thesame connection brokers.

Conguring a connection brokerYou can configure a connection broker to include the following options:• Shutdown security (UNIX only)

Configure a connection broker to require a password whenever the connectionbroker is shut down.

• Server access restrictions

Configure a connection broker to accept or reject broadcasts from specific servers.


Connection Brokers

• Specific IP listening addresses

Define specific IP listening addresses for connection brokers, which allows you torun multiple connection brokers on one machine by using a specific network card foreach connection broker. Starting additional connection brokers, page 196, containsinstructions on this option.

• IP address translation

Configure a connection broker to receive connection requests from clients outside afirewall and direct the request to the appropriate repository.

All of these features are configured in an initialization file, which is then referenced onthe connection broker’s start-up command line.

Connection broker initialization le

The connection broker initialization file is an optional file that you create and has thefollowing format:[SECURITY]password = string_valueallow_hosts=host_name_list|deny_hosts=host_name_list

[DOCBROKER_CONFIGURATION]host = host_name|IP_address_stringservice = service_nameport = port_number

[TRANSLATION]port=["]inside_firewall_port=outside_firewall_port{,inside_firewall_port=outside_firewall_port}["]host=["] inside_firewall_port=outside_firewall_port{,inside_firewall_port=outside_firewall_port}["]

Note: The password key in the security [SECURITY] section is recognized and usedonly on UNIX platforms. Connection brokers on Windows platforms are not affectedby the definition of a security password.

If a valid service name is included, the connection broker is started with the service name.Otherwise, if a valid port number is included, the connection broker is started using theport number. If neither is included, the connection broker is started on port 1489.

The file can have any valid file name. You can store the file in any location, but themost convenient place may be the same directory in which the dm_launch_docbrokerscript is stored.

The translation strings are enclosed in double quotes when multiple ports or hosts arespecified.


Connection Brokers

Invoking the initialization le

When you start a connection broker, the initialization file is not automatically invoked.To invoke the file, you must include the -init_file argument on the startup command line.

For Windows platforms, the syntax is:drive:\documentum\product\version_number\bin\dmdocbroker.exe-init_file filename

If the connection broker is running as a service, edit the service entry to include theargument on the command line. You can use the Documentum Server Manager to editthe service entry.

For UNIX platforms, the syntax is:% dm_launch_docbroker -init_file filename

If there are other arguments on the command line in addition the initialization fileargument, the -init_file argument must appear first or it is ignored.

Conguring shutdown security (UNIX only)

Defining a security password for a connection broker ensures that only a user who knowsthe password can stop the connection broker. Define a password in the [SECURITY]section with the password key:[SECURITY]password=string_value

Restricting server access

By default, a connection broker accepts broadcasts from any server. However, you canconfigure a connection broker to either:• Accept broadcasts only from specified servers• Reject broadcasts from specified serversTo define accepted servers, use the following format in the initialization file:[SECURITY]...allow_hosts=host_name_list

To define rejected servers, use the following format:[SECURITY]...deny_hosts=host_name_list


Connection Brokers

host_name_list is a list of the host machines on which the servers reside. Multiple hostnames are separated by commas. For example:[SECURITY]...deny_hosts=bigdog,fatcat,mouse

The options are mutually exclusive. For each connection broker, you can configure eitherthe accepted servers or the rejected servers, but not both.

Translating IP addresses

For security reasons, many enterprises set up firewalls to prevent outside users fromaccessing enterprise repositories and file systems. However, on occasion, users outsidethe firewall may need to access a repository inside the firewall.

To allow a user or client application to connect to a repository inside a firewall, theconnection broker initialization file includes a [TRANSLATION] section. This sectionredirects a request to a safe IP address and port name. The section has the followingformat:[TRANSLATION]port=outside_firewall_port=inside_firewall_port{,outside_firewall_port=insdie_firewall_port}host=outside_firewall_IP=inside_firewall_IP{,outside_firewall_IP=inside_firewall_IP}

outside_firewall_port and inside_firewall_port are port numbers.

outside_firewall_IP and inside_firewall_IP are IP addresses.

For example, suppose repository A is inside a firewall and that application B, outsidethe firewall, wants to connect to repository A. Also suppose the connection broker thatreceives the request has the following TRANSLATION section in its initialization file:[TRANSLATION]port=2231=4532host=2.18.13.211=172.18.23.257

When the connection broker receives the request, it translates 2231 and 2.18.13.211 to4532 and 172.18.23.257. It sends the values 4532 and 172.18.23.257 back to application B,which uses them to establish the connection.

If you specify multiple ports or hosts for translation, you must enclose the translationstring in double quotes. For example:[TRANSLATION]port="2253=6452,22254=6754"

To use a [TRANSLATION] section:1. Define the IP address translation rules in the firewall.


Connection Brokers

2. Enter the rules in the [TRANSLATION] section of the connection broker’sinitialization file.

3. Restart the connection broker, specifying the initialization file on the command line.

Restarting a connection brokerThe procedures in this section describe how to restart a connection broker that wasstopped.

Windows platforms

A connection broker running on a Windows platform may be running as a service ormay have been started from the command line.

To start a connection broker running as a service:1. Double-click Start connection broker in the Documentum group.

This launches the connection broker executable.

Note: The connection broker service name is Documentum Docbroker Serviceconnection_broker_namewhere connection_broker_name is the name of the connectionbroker. The default service name is Documentum Docbroker Service Docbroker.

To start a connection broker that is not running as a service:1. At the operating system prompt, enter the startup command line.

The syntax for the startup command is:dmdocbroker.exe [-init_file filename ] -host host_name-service service_name - port port_number

For example:d:\documentum\product\6.0\bin\dmdocbroker.exe-init_file DocBrok.ini -host engr -service engr_01

UNIX platforms

Use the following procedure to restart a connection broker that runs on a UNIX platform.


Connection Brokers

To restart a connection broker:1. Log into the machine on which to start the connection broker.

2. Change to the $DOCUMENTUM/dba directory:% cd $DOCUMENTUM/dba

3. At the operating system prompt, type the command line for thedm_launch_docbroker utility. The command line syntax is:dm_launch_docbroker [-init_file file_name] [-host host_name][-service service_name] [-port port_number]

You must include the host name and a service name or port number to identifythe connection broker unless you specify an initialization file that includes a[DOCBROKER_CONFIGURATION] section to identify the connection broker.

Starting additional connection brokersYou can run multiple connection brokers for a repository. The connection brokers canrun on separate machines or you can run them on the same machine. If you run multipleconnection brokers on the same machine, each connection broker on the machine mustuse a separate port or a separate network card.

To configure a connection broker to use a separate port, define a services file entrythat identifies the service name for the connection broker. The service name for theconnection broker must be unique among the service names. Alternatively, create aninitialization file that identifies the service. For example:[DOCBROKER_CONFIGURATION]host=host_machine_nameservice=service_name

or[DOCBROKER_CONFIGURATION]host=host_machine_nameport=port_number

where port_number is the port identified in the new service.

To configure a connection broker to use a separate network card, createan initialization file for the connection broker. The file must include a[DOCBROKER_CONFIGURATION] section to identify the IP address of the networkcard. Use the following format:[DOCBROKER_CONFIGURATION]host=IP_address_stringservice=service_nameport=port_number

IP_address_stringmust be in the dotted decimal format (for example, 143.23.125.65).


Connection Brokers

The service name is the connection broker’s service name, defined in the host machine’sservices file. The port number is the port defined in the service. Refer to Content ServerInstallation Guidefor instructions on setting up service names. If you include a servicename, the connection broker is started using that service. Otherwise, if you include aport number, the connection broker is started using that port. If you do not include aservice name or a port number, the connection broker uses port number 1489.

To start additional connection brokers:1. Start the connection broker from the operating system prompt.

• On Windows:d:\documentum\product\6.0\bin\dmdocbroker.exe[-init_file filename ]-host host_name -service service_name

• On UNIX:dm_launch_docbroker [-init_file filename]-host host_name-service service_name

You must include the host name and a service name or port number to identifythe connection broker unless you specify an initialization file that includes a[DOCBROKER_CONFIGURATION] section to identify the connection broker.

2. Modify the projection properties in the server config object to add the newconnection broker as a server projection target.

3. Optionally, modify the server.ini file to add the new connection broker as a serverprojection target.Refer to Defining connection broker projection targets, page 114, for informationabout adding the new target to the server.ini file.

4. Reinitialize the server.

Shutting down a connection brokerThe procedures in this section describe how to shut down a connection broker. If theconnection broker was configured with shutdown security, you must know the correctpassword to shut down the connection broker.

Windows platforms

A connection broker on a Windows host may have been started as a service or mayhave been started from the command line.


Connection Brokers

To stop a connection broker that is running as a service:1. Click Start > Program Files > Documentum > Server Manager

2. Select the connection broker tab.

3. Select the correct connection broker.

4. Click Stop.

To stop a connection broker started from the command line:1. Close the window in which the connection broker is running.

UNIX platforms

A connection broker started on a UNIX host is started from the command line.

To stop a connection broker started from the command line:1. Execute the dm_stop_docbroker utility. The command line for this utility is:

% dm_stop_docbroker [-Ppassword][-B[atch]][-Nport_number][-Sservice_name]

The utility stops the connection broker that is running on the host specified in thedmshutdown script. The connection broker specified in that script is set whenyou run dm_setup during the initial server installation. (It will be the connectionbroker with which your first-installed server is communicating.) If executingdm_stop_docbroker in the interactive mode (without the -B flag), the utility tells youwhich connection broker it intends to stop and prompts for a confirmation. If youinclude the -B flag, the utility does not prompt for confirmation or tell you whichconnection broker it is stopping. The default for the -B flag is FALSE.You can include the -N and -S arguments to identify a particular connection brokerto shut down if you have multiple connection brokers on one machine.The password is the password specified in the connection broker initializationfile. You must supply this password if the connection broker was started withsecurity imposed. (Configuring shutdown security (UNIX only), page 193, containsinformation about imposing security on connection brokers.)If you cannot use the dm_stop_docbroker utility, you can use the UNIX killcommand to stop the connection broker if it was started without security. (If youdo not know the process ID for the connection broker, you can obtain it using theUNIX ps command.) You cannot use the UNIX kill command to stop a connectionbroker that was started with security. Only the UNIX kill -9 command will stopa secured connection broker.


Connection Brokers

Multiple connection brokers on UNIX

If you have multiple connection brokers, you can stop two or more by editing thedm_stop_docbroker script before running the dm_stop_docbroker utility. The scriptis found in $DOCUMENTUM/dba. The final line in this script identifies the host ofthe connection broker to be stopped when the dm_stop_docbroker utility is run. Thefollowing is an example of the code line:./dmshutdown docbroker -Tlapdog -P$password $@# lapdog is the host name

To stop multiple connection brokers, modify the script by adding multiple copies of thisline, one for each host on which a connection broker resides. For example, suppose thereare connection brokers running on lapdog, fatcat, and mouse. To stop all three with oneiteration of dm_stop_docbroker, edit dm_stop_docbroker to include these three lines:./dmshutdown docbroker -Tlapdog -P$password $@#lapdog is the host name

./dmshutdown docbroker -Tfatcat -P$password $@#fatcat is the host name

./dmshutdown docbroker -Tmouse -P$password $@#mouse is the host name

The dm_stop_docbroker utility substitutes the password specified on its command linefor $password in the script. If you imposed a different password for each connectionbroker, you must explicitly put the correct password in the command line that shutsdown each connection broker:./dmshutdown docbroker -Tlapdog -P$bigbark $@#lapdog is the host name

./dmshutdown docbroker -Tfatcat -Pmeowmeow $@#fatcat is the host name

./dmshutdown docbroker -Tmouse -Psqueak $@#mouse is the host name

Obtaining information from a connectionbroker

A connection broker can provide information about the servers known to it or about therepositories the servers access. To obtain this information, a client (such as an applicationor a system administrator) must issue the getServermap or getDocbaseMap method.The getServerMap method returns server information for a particular repository, andgetDocbaseMap returns information about repositories.


Connection Brokers

The getServerMap method

Use an IDfDocbrokerClient.getServerMap method to obtain information about theservers known to a connection broker that access a particular repository.

The Getservermap method returns an IDfTypedObject object whose type name isserver_locator. This is a non-persistent object that contains the information known to theconnection broker about any server for the repository. The Documentum System ObjectReference Manual contains a description of the properties in a server locator object.

The information for a single server appears at corresponding index positions in theobject’s repeating properties. For example, the name of the host machine for the servernamed in r_server_name[0] is found in r_host_name[0], its process ID is found inr_process_id[0], and its status is found in r_last_status[0].

The getDocbaseMap method

Use an IDfDocbrokerClient.getDocbaseMap method to obtain information about therepositories that servers can access.

The method returns an IDfTypedObject object whose type name is docbase_locator.A docbase locator object is a non-persistent object that contains information aboutthe repositories associated with the servers known to the connection broker. TheDocumentum System Object Reference Manual contains a description of the properties ina docbase locator object.

The information for a single repository appears at corresponding index positionsin the repeating properties. For example, the name of the repository whose ID isin r_docbase_id[3] is found in r_docbase_name[3] and its description is found inr_docbase_description[3].

Obtaining information about connectionbrokers

To obtain information about which connection brokers a client can access, do one ofthe following:• Use the getDocbrokerMap method.• Query the client config object.


Connection Brokers

Using the getDocbrokerMap method

The getDocbrokerMap method returns an IDfTypedObject object whose type name isdocbroker_locator. This object lists, in repeating properties, all connection brokers thatare visible to the client session.

The information in the docbroker locator object’s properties is taken from thedfc.properties file that the client session is accessing. The information for a singleconnection broker appears at corresponding index positions in the repeating properties.For example, the values at network_protocol[2], host_name[2], port_number[2], andtime_out[2] describe one connection broker.

The method is also useful when you want to send a getDocbaseMap or getServerMapmethod to a particular connection broker and need to find the protocol, host name, andport number values for the connection broker.

Querying the client cong object

Each client session references a non-persistent client config object for some configurationinformation. The information in this object is taken from the dfc.properties file in use bythe session. Included in that information are the connection brokers for the session.

The information about the connection brokers in the properties file is contained in thekeys with the category dfc.docbroker. For example, a dfc.docbroker.host key identifiesa connection broker host and a dfc.docbroker.port key identifies the port in use by aconnection broker. The keys include indexes, with the information across any particularindex representing the information about one connection broker.

In the client config object, the information in these keys is found in repeating propertiesof the same name. For example, all the names of connection brokers are found in arepeating property named dfc.docbroker.host.

Deleting server informationA connection broker deletes a server from its list of known servers when either of thefollowing situations occurs:• A server sends a delete me message as a result of a manual shutdown.

This occurs when a server is shut down with instructions to broadcast a delete memessage. Using the shutdown method, page 120, contains instructions.


Connection Brokers

• A server fails to broadcast a checkpoint message within the expected keep_entryinterval.

This occurs when a server is not active as a result of a shutdown without a delete memessage, a crash, or when the network between the server and connection brokerfails.

• A server is reinitialized after a change to the projection targets in the server configobject that deletes the connection broker from the targets.


Chapter 7Content Management

Content is the text, graphics, tables, charts, and other information (except property values) that isstored with an object. Content is typically stored in documents or a document subtype. However, anySysObject or SysObject subtype except cabinets and folders accepts content. Content associated withan object is stored in a storage area defined in the repository. This chapter describes how to create,use, and manage those storage areas. The chapter covers the following topics:• Storage area options, page 204• Summary of storage area configuration options, page 222• Content and full-text indexes, page 223• How objects, contents, and storage are connected, page 223• Allocating content to storage areas , page 224• Content Retention, page 231• System-defined storage areas, page 232• File paths and URLs for content files in storage, page 233• Setting up storage, page 235• Providing automatic file extensions, page 258• Moving content files, page 259• Maintenance operations for storage areas, page 263• Administering content assignment policies, page 275• Archiving and restoring documents, page 277

Note: This chapter does not describe distributed storage areas in detail, nor how to set up or managedistributed storage areas. They are described in detail, including their setup and management, in theEMC Documentum Administrator User Guide or in the Documentum Administrator online help.


Content Management

Storage area optionsThere are a variety of storage area options supported by Content Server. Which storageoption or options you choose for a repository depends on the types of files you plan tostore in the repository, how you intend to use those files, and how you designed thestorage strategy in your installation. The storage options are:• File system directories

Storing content in file system directories is the most common choice. The file store,distributed store, and linked store storage options all use file system directories asthe underlying storage facility. File store storage areas, page 205, describes file storestorage areas in detail.

• Retention storage

Retention storage areas store content that you want to retain for a specified time.They are often used for storing massive amounts of unchanging data, such as emailarchives or check images. There are two types of retention stores:

— EMC Centera store

EMC Centera stores can store metadata values with each piece of content and aredescribed in EMC Centera storage, page 212.

— NetApp SnapLock store

NetApp SnapLock storage systems are described in NetApp SnapLock storage,page 215.

• Blob storage

Content in blob storage is stored directly in the repository, in a special table. Blobstore storage areas, page 217, describes blob storage areas.

• Turbo storage

Content in turbo storage is stored in a property in content or subcontent objects.Turbo storage, page 218, describes turbo storage areas.

• Distributed storage

Content in distributed storage areas is replicated from its primary location to allcomponent storage areas of the distributed storage area. Using distributed storageareas is beneficial if the business has sites in different geographic locations.

The components of a distributed storage area can be file store storage areas or linkedstore storage areas.

Setting up and managing a distributed storage area is described in the EMCDocumentum Distributed Configuration Guide.


Content Management

• External storage

Content in external storage is stored on external storage devices outside theDocumentum system. External storage areas, page 219, describes this option.

• Linked storage

A linked storage area points to an underlying storage area, typically a file storestorage area. Linked store storage areas, page 221, describes the use of a linkedstore storage area.

Note: Linked store storage areas are deprecated. DFC versions 6 and later do notsupport linked store storage areas.

With the exception of turbo storage, all the storage options are represented in therepository by specific object types that are subtypes of the dm_store object type. Thestore object type provides a set of properties inherited by all the storage subtypes. Thedescription of the type in the Documentum System Object Reference Manual lists thesecommon properties.

File store storage areas

File store storage areas are the basic building blocks of a storage strategy. Storage areasof this type can contain content files in all formats. In most installations, the majorityof the content files are stored in file store storage areas. A file store storage area isrepresented in the repository as an object of type dm_filestore. The Documentum SystemObject Reference Manual lists the properties defined for the file store object type.

File store storage areas offer a variety of configuration options, including:• Private or public access• Content encryption• Content compression• Duplicate-content checking and prevention• Digital shredding

Note: The compression and duplicate-content checking and prevention options require aContent Storage Services license. The encryption and digital shredding options require aTrusted Content Services license.

Public and private le store areas

You can define a file store storage area as public or private.


Content Management

If a storage area is defined as public, the server assumes that all files stored in that areaare open to the public. This means that the files, as well as the directories that containthem, must be public at the operating system level. When a client fetches a file from apublic storage area, the file is not copied to a mutually accessible area. Instead, the servergives the client access to the file directly, in the storage area.

If a storage area is defined as private, the server does not provide direct access to the filein the storage area. Instead, when a client fetches a file from a private storage area, theserver copies the file to some user-defined location that is mutually accessible to boththe server and the client.

File store storage areas are private by default. Use Documentum Administrator tochange the file store storage area to private. The public or private setting is recordedin the is_public property of the storage area’s dm_filestore object. The property is setto T (TRUE) if the storage area is a public storage area and to F (FALSE) if the storagearea is private.

Content encryption

Content encryption is a configuration option only if you have installed Content Serverwith a Trusted Content Services license. The option allows you to designate a file storestorage area as an encrypted storage area when you create the storage area. The settingfor encryption cannot be changed after the storage area is created. You cannot changean encrypted storage area to a non-encrypted storage area, nor can you change anon-encrypted storage area to an encrypted storage area.

If a storage area is configured to use content encryption, all content files stored in thatstorage area are encrypted. Content Server automatically encrypts the content whenit is saved to the storage area and decrypts the content when it is retrieved from thearea. For a complete overview of the implementation of encrypted storage areas, referto Content Server Fundamentals.

It is possible to both encrypt and compress content in a file store storage area. In suchcases, Content Server compresses the content first and then encrypts it.

Note: The encryption key is 192 bits in length and is used with the Triple DES-EDE-CBCalgorithm.

Content compression

This option requires a Content Storage Services license. Content compression is enabledwhen the storage area is created and cannot be reset later.


Content Management

The content compression option directs Content Server to compress content saved to thestorage area. If this option is enabled, Content Server automatically compresses contentwritten to the storage area and decompresses the content when retrieving the content.

A file store storage area may not use compression if that storage area will be a componentof a distributed storage area. Distributed storage areas do not support compression.

Note: If your clients are configured to use compression (dfc.content.use_compressionin the dfc.properties file is set to T), Content Server uncompresses the content receivedfrom the client and applies the compression algorithm used for the storage area if savingcontent to a storage area configured for compression.

Content compression characterization

These graphs provide information about how much a file is compressed whencompression is enabled for a storage area. The percentages are averages representing theaverage percentages by which a file was compressed. For example, a small Powerpointdocument (PPT) was compressed by approximately 42.41 %, meaning that aftercompression, the document was approximately 57.59% of its original size.

Figure 1, page 207, shows the compression percentages for small files in various formats.

Figure 1. Small le compression percentages

Figure 2, page 208, shows the compression figures for medium-size files in variousformats.


Content Management

Figure 2. Medium le compression percentages

Figure 3, page 208, shows the compression figures for large files in various formats.

Figure 3. Large le compression percentages


Content Management

Content duplication checking and prevention

This option requires a Content Storage Services license.

The content duplication checking and prevention option is used to prevent ContentServer from saving duplicate content files to a storage area. This option is particularlyuseful if you plan to store archived email or similar content in the storage area. Forexample, suppose you are storing email archives in a storage area. If your companyhas 10,000 employees and each receives the same email attachment, there is no needto store 10,000 copies of the attachment in the storage area. If the content duplicationchecking and prevention option is set for the storage area, Content Server saves one copyof the attachment to the storage area and then creates content objects for the other 9,999recipients that point to the originally saved copy.

Note: Content duplication checking and prevention is not applied, even if configured fora storage area, to Macintosh resource fork content files stored in the storage area.

A file store storage area may not use content duplication checking and prevention if thatstorage area will be a component of a distributed storage area. Distributed storage areasdo not support content duplication checking and prevention.

How checking and prevention work

If a storage area has content duplication checking and prevention configured, ContentServer generates hash values for content files stored in the storage area. The hash valuefor each content file is stored in a property of the file’s associated content object. Beforesaving a content file to the storage area, the server compares the file’s generated hashvalue to the hash values recorded for content of the same format already in the storagearea. If it finds a duplicate hash value for a content file of the same format, the servercreates a new content object for the content file but does not actually write the content tothe storage area. Instead, it points the new content object at the existing content file.

It is possible to configure a storage area so that Content Server generates the hash butdoes not perform the comparison operation. If you configure a storage area in thatmanner, Content Server writes the content to the storage area even if a copy of a contentalready exists in the storage area.

Supporting properties

Three properties support the content duplication checking and prevention functionality:• content_hash_mode• content_dupl_pref• r_content_hash


Content Management

content_hash_mode and content_dupl_pref

The content duplication checking and prevention setting for a storage area is recorded intwo properties of the storage area: content_hash_mode and content_dupl_pref. Theseproperties are defined for dm_store and inherited by dm_filestore.

The content_hash_mode property, if set to 1, causes Content Server to generate a hashvalue for a content file saved to the storage area. The hash value is stored in the contentobject in the r_content_hash property. If the property is set to 0, Content Server does notgenerate the hash values.

The content_dupl_pref property records whether Content Server checks for an existingcopy of a content file before saving the file to the storage area. If the property is set to1, Content Server checks for a duplicate hash value before saving a content file to thestorage area. When the content_dupl_pref value is 1, the content_hash_mode value mustalso be 1. If it is not, Content Server resets content_hash_mode to 1 automatically.

You can change content_hash_mode from 0 to 1 or from 1 to 0 only if content_dupl_prefis set to 0. If you change content_hash_mode from 0 to 1 (turning on hash generation),the server generates hash values for content stored in the storage area after the changebut does not generate hash values for content stored before the change. If you changethe value from 1 to 0 (turning off hash generation), the server does not generate hashvalues for content stored after the change, but does not remove hash values recordedbefore the change.

r_content_hash

The r_content_hash property is defined for the dmr_content object type. It stores thehash value for the content if a hash value is generated. The hash value is stored in thefollowing format:hash_value/{SHA1}

where hash_value is a 40–byte hexadecimal string.

For example:f64d3298b660119d5adbbf03f4eb683bca98b5a1/{SHA1}

To obtain the value, Content Server submits the content to the crypto library. The libraryreturns a 20-byte (160 bit) SHA1 hash string that the server converts to the 40-bytehexadecimal string. The conversion is performed using the algorithm in the followingcode:char * ConvertSHA1HashToHexString(unsigned char *digestedData)

{char hashString[41];

sprintf(hashString, "%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x",


Content Management

digestedData[0], digestedData[1], digestedData[2],digestedData[3], digestedData[4], digestedData[5],digestedData[6], digestedData[7], digestedData[8],digestedData[9], digestedData[10], digestedData[11],digestedData[12], digestedData[13], digestedData[14],digestedData[15], digestedData[16], digestedData[17],digestedData[18], digestedData[19]);

return hashString;}

where digestedData is the SHA1 hash string returned by the crypto library.

Tracing duplication checking and prevention

If the DM_SERVER tracing facility is turned on, messages are recorded in the log filewhenever a content file is found to be a duplicate of an existing content in a storage area.The DM_SERVER tracing facility is turned on using the setServerTraceLevel method.

Digital shredding

Digital shredding is a process that ensures that a content file is deleted in anunrecoverable way. You must have installed Content Server with a Trusted ContentServices license to enable digital shredding.

If digital shredding is enabled for a file store storage area, when a document whosecontent is stored in that storage area is deleted from the repository, Content Serverimmediately digitally shreds the content and removes the document and the associatedcontent object from the repository.

Content Server utilizes the capabilities of the underlying operating system to shredcontent files. The shredding algorithm is in compliance with DOD 5220.22–M (NISPOM,National Security Industrial Security Program Operating Manual), option d. Thisalgorithm overwrites all addressable locations with a character, then its complement,and then a random character.

You can enable digital shredding for any standalone file store area. You may also enableshredding for file store storage areas that are the targets of linked store storage areas.This feature is not supported for file store storage areas that are components of adistributed storage area.


Content Management

EMC Centera storage

Using EMC Centera storage requires a Content Services for EMC Centera license. If youinstall Content Server with that license, Content Server supports the use of the EMCCentera Storage System. (Refer to the release notes for the exact version.)

Use EMC Centera storage systems if you want to store massive amounts of unchangingdata, such as email archives or check images. In addition to the content, a Centerastorage system allows you to store up to 62 metadata values with each piece of contentin the system.

Note: You cannot store files created on a Macintosh machine in a Centera storage area.

Content in an EMC Centera storage area is located using a content address rather than afile path. The address is created and managed by the storage system and provided toContent Server. A particular content file may have multiple addresses. Some operationsgenerate new addresses for the content. For example, if you change the metadata valuesstored with the content, the system generates a new address for the content. The firstcontent address generated for a content file is stored in the content object. Additionaladdresses are stored in the i_contents property of an associated dmi_subcontent object.

Content Server communicates with the storage system through a plug-in and sharedlibrary installed with Content Server.

In the repository, a Centera storage area is defined using a ca store object. The storageobject identifies the content metadata and values that you want to store with content inthe storage system. It also defines the default retention period, if any.

For instructions on setting up a Centera storage area, refer to Setting up EMC Centerastorage areas, page 245. For information about how to save documents to a Centerastorage area, refer to Content Server Fundamentals.

Conguration options

You can set the following configuration options for an EMC Centera storage area whenyou create the storage area:• A default retention value• Content compression

Content compression is supported only if you have also installed Content Serverwith the Content Storage Services license.

• Content storage as embedded blobs• Size of the C-clip buffer• Number of retries for write attempts


Content Management

• Override of the Centera single-instance checking configuration• Maximum number of socket connections used by Centera SDK• Use of the memory map interface for writes to the storage area in certain

circumstances

If configured, the memory map interface is only used when content is movedfrom an unencrypted, uncompressed file store to the Centera storage area usingMIGRATE_CONTENT or by setting an object’s a_storage_type.

Default retention values

EMC Centera storage areas support the definition of a default retention value for contentstored in those storage areas. The default is applied to all content saved into the storagearea if a retention value is not set explicitly for the content when it is saved.

The default retention value is defined at the storage-area level and is enforced by theCentera host system. Content saved with a retention value, either explicit or defaulted,cannot be removed from the storage system until the retention expires.

You can define the default retention value as a number of days or as a hard date. If youspecify a number of days, the content is held for the specified number of days countingfrom the time the content is saved to the storage area. If you specify a hard date, thecontent is retained until that date.

Note: The retention value defined for a Centera storage area is independent of theretention policy management features supported by Content Server. However, if theSysObject that contains the content has an associated retention policy, the retention datedefined by the policy is also stored as metadata in the Centera system, and the retentiondate furthest in the future is enforced. For more information about defining retentionperiods and how retention policies and Centera store retention periods interact, refer toDefining storage area retention requirements, page 247.

Compression

Content stored in an EMC Centera storage area may be stored as compressed content ifyou have installed Content Server with a Content Storage Services license. If the storagearea is configured to store compressed content, Content Server compresses the contentwhen writing to the storage area and uncompresses the content when retrieving it.

Content compression is enabled when the storage area is created and cannot be resetlater.


Content Management

Whether to link or embed the content in the C-clip

Each piece of content stored in an EMC Centera storage area is represented in thestorage area by an object called a C-clip. The content address of the content is an XMLrepresentation of the C-clip. By default, the actual content is stored in a separate objectlinked to the C-clip. It is possible to configure a Centera storage area to store the contentin the C-clip as an embedded blob instead of creating a separate linked object for thecontent. Embedding the content reduces the number of objects in storage, providingscalability and cost-of-ownership benefits.

When you configure a Centera storage area to use embedded blobs, you define themaximum size of the content you want to store as embedded blobs. Any content file thatexceeds the specified size is stored in the default way, as a linked object.

The embedded blob configuration option is a pool option. If set in a Centera store object,it applies only to content whose a_storage_type is set to that Centera store object. If thereare multiple Centera store storage areas that store content in the same Centera cluster,but each has a different maximum size set for embedded blobs, Content Server usesthe threshold set in the individual Centera store storage area definition to determinewhether to embed or link the content in the C-clip.

For instructions on configuring embedded blob use, refer to Configuring embeddedblob use, page 251.

This option is changeable after the storage area is created. You can start or stop its use orchange the size of embedded blobs.

The C-clip buffer size

The C-clip buffer is a client (SDK) buffer used by Centera to manage C-clips created byan application. The default size for this buffer is 150K. If an application is managing alarge number of concurrent sessions or using embedded C-clips or both, the default sizemay not be large enough. If the buffer is full, Centera pages out the overflow to files onthe local disks. This can be a performance issue. You can reset the buffer size.

For instructions on resetting the buffer size, refer to Setting the C-clip buffer size, page252.

Write retries

You can configure the retry behavior when content is written to the storage area. Youcan define the maximum number of times Content Server attempts to write a contentfile to the storage area, the interval between retries, and whether a final attempt is madeafter the maximum number of attempts has been made.


Content Management

For more information and instructions regarding the retry options, refer to Configuringwrite attempts in EMC Centera storage areas, page 253.

Override of the Centera storage strategy conguration

Centera systems can be configured to store a single copy of the content when the samecontent is submitted for storage multiple times. For example, that storage strategy isuseful when the content is an attachment to an email sent to multiple recipients. Inthese cases, you probably want to store only one copy of the attachment, instead of onefor each recipient.

In some cases, you may want to override the Centera storage strategy. You can set astorage parameter for a Centera store storage area so that all content saved to thatstorage area bypasses the storage strategy configured for the Centera host on which thestorage area resides. For instructions, refer to Overriding the Centera single-instancingconfiguration, page 253.

Maximum number of socket connections used by the Centera SDK

By default, the Centera SDK can use up to 99 socket connections with the Centera host.You can change that maximum by setting a storage parameter for the Centera storagearea. For instructions, refer to Resetting the maximum socket connections allowed,page 254.

Use of the memory map interface for writes to the storage area

If this option is configured, the memory map interface is only used when content ismoved from an unencrypted, uncompressed file store to the EMC Centera storage areausing MIGRATE_CONTENT or by setting an object’s a_storage_type.

Using the memory map interface increases the performance of the write operation. Thereare two pool options that configure this option. For instructions, refer to Configuring useof a memory map for write operations, page 254.

NetApp SnapLock storage

Network Appliance SnapLock (NetApp SnapLock) is a licensed software that providesstorage level retention capability through the creation of Write Once Read Many(WORM) volumes on Network Appliance systems. These WORM volumes enable usersto prevent altering or deleting content until a specified retention date.


Content Management

Use NetApp SnapLock storage systems to store massive amounts of unchanging data,such as email archives or check images. There are two types of NetApp SnapLock stores:• SnapLock Compliance store handles data retention to meet SEC regulations.• SnapLock Enterprise store handles data retention to help customers meet their

self-regulated date retention requirements.Refer to the SnapLock documentation provided by Network Appliance for moreinformation about the two types of stores.

Content Server communicates with the storage system through a plug-in and sharedlibrary installed with Content Server.

In the repository, a SnapLock storage area is defined using a ca store object. It alsodefines the default retention period, if any.

For instructions on setting up a NetApp SnapLock storage area, refer to Setting upNetApp SnapLock storage areas, page 255

Conguration options

You can set the following configuration options for a NetApp SnapLock storage areawhen you create the storage area:• A default retention value• Content compression

Content compression is supported only if you have also installed Content Serverwith the Content Storage Services license.

Default retention values

NetApp SnapLock provides basic retention enforcement capabilities. SnapLock storageareas support a default retention value for content stored in those storage areas. Thedefault is applied to all content saved into the storage area if a retention value is not setexplicitly for the content when it is saved.

The default retention value is defined at the storage-area level and is enforced by theSnapLock host system. Content saved with a retention value, either explicit or defaulted,cannot be removed from the storage system until the retention expires.

You can define the default retention value as a number of days or as a hard date. If youspecify a number of days, the content is held for the specified number of days countingfrom the time the content is saved to the storage area. If you specify a hard date, thecontent is retained until that date.


Content Management

Note: The retention value defined for a SnapLock storage area is independent of theretention policy management features supported by Content Server. However, if theSysObject that contains the content has an associated retention policy, the retentiondate defined by the policy is also stored in the SnapLock system, and the retention datefurthest in the future is enforced.

Compression

Content stored in a NetApp SnapLock storage area may be stored as compressed contentif you have installed Content Server with a Content Storage Services license. Contentcompression is enabled when the storage area is created and cannot be reset later. If thestorage area is configured to store compressed content, Content Server compresses thecontent when writing to the storage area and uncompresses the content when retrievingit.

Blob store storage areas

Content stored in blob storage is stored in the repository, in rows in an RDBMStable—one row for each content file. The content must be less than or equal to 64 K.

A blob storage area is implemented using a dm_blobstore object, and the name of theresulting table in the RDBMS is derived from the name you define for the blob storeobject.

Using blob storage can make backing up content easy, because the content isautomatically backed up when the repository is backed up. There is also a smallperformance enhancement when content is stored in blob storage.

You cannot define a blob storage area as the underlying area for a linked store or asa component of a distributed storage area. That is, blob storage cannot be accessedthrough a linked store storage area or through a distributed storage area.


One property, named ascii, is defined for the blob store type. It is a Boolean propertywhose value indicates whether the content in blob storage is ASCII strings or arbitrarysequences of 8-bit characters. TRUE indicates that the content is in ASCII format. FALSEindicates that it is arbitrary sequences of 8-bit characters.

Note: You can store ASCII content in a blob store that has the ascii property set to FALSE.However, you cannot store non-ASCII content in a blob store that has ascii set to TRUE.


Content Management

Turbo storage

Content in turbo storage is stored in the repository. Turbo storage is most useful ifyou are granulating the content of documents; for example, it works well for SGMLdocuments. It also provides enhanced performance for content retrieval.

Turbo storage areas are not represented by storage objects. The content is stored in thei_contents property of the dmr_content object. You can store up to 2000 bytes in theproperty if the RDBMS is Oracle or DB2. If the RDBMS is MS SQL Server or Sybase, youcan store up to 255 bytes in the property. If the content exceeds those limits, the excess isstored in one or more subcontent objects. Each subcontent object can store an additional2000 bytes (for Oracle or DB2) or 255 bytes (for MS SQL Server or Sybase).

Content stored in turbo storage must be in ASCII format.

You can use any of the content manipulation methods, such as getFile, setFile, andsetContent, to manipulate content in turbo storage. However, the server cannotautomatically generate renditions of content in turbo storage. If you want a renditionof a file in turbo storage, you must create the rendition externally and add it to therepository using an addRendition method.

Distributed storage areas

A distributed storage area does not contain content. Instead, it points to componentstorage areas that contain the content. The component storage areas of a distributedstorage area can be any mixture of file store and linked store storage areas, but all muststore the same kind of content (The component storage objects must have the same valuein their media_type property.)


Distributed storage areas are useful when repository users are located in widelyseparated locations. For example, a company might have offices in New York, SanFrancisco, Tokyo, and London, with users in each office using the same repository. Youcan define a distributed storage area with a component in each geographic locationand set up the appropriate content replication jobs to ensure that content is current ateach location. This provides users in each office with fast access to local copies of thedocuments.

The Documentum Content Server Distributed Configuration Guide describes how toimplement and administer a distributed storage area. The Documentum System ObjectReference Manual lists the properties defined for the distributed store object type.


Content Management

External storage areas

An external storage area represents an external storage device that is known to ContentServer but not managed by Content Server. For example, the device might be a CD-ROM,a file system, or an optical device. External storage areas are best used to handle legacycontent and data. Storing such content in external storage removes the necessity forimporting the content into the repository.

Note: Support of optical devices is deprecated. DFC versions 6 and later do not supportoptical storage devices.

Content Server communicates with the storage device through a user-defined plug-inlibrary. When a user or application issues a request to save or retrieve content in anexternal storage area, Content Server invokes the plug-in to perform the requestedoperations. To identify the content, the plug-in and Content Server use a token. Thetoken can be a file path, a URL, or user-defined.

Use constraints

Using external storage has the following functional constraints:• You cannot issue setContent, insertContent, or appendContent on objects in external

storage.• You cannot replicate objects in external storage.• You cannot dump with content or load with content.• The dmclean utility drops only the dmr_content object and does not delete the

physical content file.• The dmfilescan utility does not affect content stored externally.• You cannot access Macintosh files stored in an external storage area.

Types of external storage areas

There are three types of external storage areas. All are subtypes of the dm_extern_storeobject type. The external store type is a subtype of dm_store and its properties are thosethat are common to all external storage areas. The three subtypes of dm_extern_store are:• dm_extern_file• dm_extern_url• dm_extern_freeEach external storage area subtype represents one kind of token used to retrieve thecontent in that area.


Content Management

Use an external file storage area if the content in the external storage will be representedby a content token in the form of a file path. Typically, this content is legacy files onexternal file systems, optical disks, or CD-ROMs.

Note: Support for optical storage devices is deprecated. DFC versions 6 and later do notsupport optical storage devices.

Use an external URL storage area if the content is accessed using a content token in theform of a URL. The URLs must conform to the URL standard. EMC Documentum clientsand Content Server do not validate the format of the URL.

Use an external free store storage area if the content is accessed by a user-defined contenttoken that is not in the form of a file path or URL. An external free store lets you defineyour own token standard and means of retrieving the content associated with the token.

You can create renditions of content stored in an external file store when the plug-in isexecuted on the server host and rend_backing_store is specified in the server configobject. You cannot create renditions for content stored in external URL or external freestorage areas.

Note: Executing the plug-in on the client host is not supported by DFC version 6 or later.

You can create XML stores using the external free store subtype. Use XML stores to storeand query large volumes of XML content. An XML store is a native XML databasethat is fully optimized for XML content. To create an XML store using DocumentumAdministrator, follow the basic instructions to create an external free store. Thereare four attributes in the dm_extern_store type that are automatically inherited bydm_extern_free to support an XML store:• storage_class: Indicates the purpose the store is used for, such as XML.• is_writable: Indicates if content is pushed to an XML store that Documentum

manages.• a_storage_param_name: Indicates the path to the application server that hosts an

Xhive database.• a_storage_param_value: Indicates the location of the external XML file store.The Documentum XML Store Installation and Administration Guide provides moreinformation about external XML file stores.

Plug-in objects for external storage

Content Server invokes a user-defined shared library or DLL to handle content stored inan external storage device. The shared library or DLL is represented in the repositoryby a dm_plugin object. The shared library or DLL is stored as the content of the pluginobject, in a file store storage area. The content’s format must be set to a specified formatfor each platform. The required format object for each platform is created when Content


Content Management

Server is installed. When you create an external storage area and configure the plug-in,the format is set automatically.

For Documentum 6 and later, the plug-in must be configured to execute on the serverhost. DFC version 6 or later does not support executing the plug-in on the client host.

Documentum provides a sample plug-in for the external file store type in the%DM_HOME%\unsupported\plugins ($DM_HOME/unsupported/plugins) directory.

The API interface between the shared library or DLL and the server consists of Cfunctions for the plug-in library. The functions are described in detail in Appendix G,Plug-in Library Functions for External Stores.

Linked store storage areasNote: Linked store storage areas are deprecated. DFC versions 6 and later do notsupport linked store storage areas.

A linked store storage area does not contain any content. Instead, on Windows, it pointsto a logical link to the actual storage area and, on UNIX, it contains the logical link to theactual storage area. The actual storage area is a file store storage area. The DocumentumSystem Object Reference Manual lists the properties defined for the linked store object type.

On Windows platforms, the file store storage area is implemented as a shared directoryand the file system on which the underlying storage area resides must be a WindowsNTFS file system, not a Windows FAT file system.

Using a linked store provides a way to make files public to users who request themthrough Content Server while still maintaining operating system-level restrictions onthe actual storage directory and contained files. This means that you can ensure thatusers must access the files using Content Server instead of accessing them through theoperating system.

You can make the permissions on the actual storage directory and the files inside asrestrictive as you like.

When a Documentum user requests a file from the storage area, the following processoccurs:

1. The server makes the underlying file publicly readable.

2. The link is established between the link location and the actual file.

3. The server creates a link record object that stores information about that link.

4. When the session ends, if no other session is using the same link, the link and theassociated link record object are destroyed, and the file is no longer public.


Content Management

Summary of storage area conguration optionsTable 18, page 222, summarizes availability of the configuration options that are notspecific to a particular type of storage area by storage area type. There are someconfiguration options that are not included in this table because they are specific to EMCCentera storage areas. These options are listed in Configuration options, page 212.

Table 18. Summary of storage area conguration options

Configuration option

Storagearea type

Public orprivate

Encryp-tion

Compres-sion

Non-du-plicationof content

Digitalshredding

Distributedcomponent

File Store Yes Yes Yes*** Yes*** Yes Yes

EMCCenteraStore

No No Yes No No No

NetAppSnapLockStore

No No Yes No No No

Blob Store No No No No No No

TurboStore

No No No No No No

ExternalStore/XMLStore

No No No No No No

LinkedStore**

No* No* No* No* No* Yes

Dis-tributedStore

No* No* No No No No

* The configuration option may be set at the underlying component level, but is notsupported if set in the actual dm_linkedstore or dm_distributedstore object.

**Linked store storage areas are deprecated . DFC versions 6 and later do not supportlinked store storage areas.

***Compression and content duplication checking and prevention are not supportedfor file stores if the file store is a component of a distributed storage area.


Content Management

Content and full-text indexesContent in all types of storage areas is indexed. It is possible to turn off content indexingfor an individual document or object, but you cannot turn off indexing at the storagearea level or indexing of metadata values.

Content stored in an encrypted storage area is not encrypted in the index. Similarly,content stored in a compressed storage area is not compressed in the index.

For a complete description of full-text index architecture, how indexing works, andhow to turn off content indexing, refer to the Content Server Full-Text Indexing SystemInstallation and Administration Guide.

How objects, contents, and storage areconnected

Content objects are used to associate objects and their content files. The first time theserver places a content file in storage, it creates a content object for the file. The contentobject identifies the SysObject that contains the content file and the storage area in whichthe content file is stored.

The property parent_id in the content object contains the object IDs of all objects towhich the content file belongs. After the storage area is determined, it is recorded inthe storage_id property of the content object and in the a_storage_type property ofthe associated document object. The storage_id property contains the object ID of thestorage area. The storage_id value reflects the storage area defined for the first documentto which the content is added. The content file is stored in that area even if you later bindthe file to other documents for which a different storage area is defined.

The storage area’s storage object has a property that points, directly or indirectly, to anactual storage area:• If the storage type is file store, the property is called location_name. The

location_name property contains the name of the location object that contains thefull directory path of the storage area.


Content Management

• If the storage type is linked store, the property is called link_location.

On Windows platforms, the link_location property points to the location object thatreferences the mount point object representing the Windows shared directory that isthe linked storage area’s underlying file store storage area

On UNIX platforms, the property identifies the directory containing the logical linkto the actual storage directory.


• If the storage type is distributed store, the property is called r_component. Ther_component property is a repeating property that contains the object IDs of thestorage objects for the component storage areas.

• If the storage type is blob store, the property is the name property of the blob storeobject. The system creates a table in the repository that has the same name as theblob store object.

• If the storage type is turbo storage, the a_storage_type property contains the valuedm_turbo_store instead of the object ID for a storage object.

• If the storage type is an EMC Centera storage, the first index position [0] in thea_storage_params property is used to store the IP address of the storage system.Content Server passes this value to the plug-in, which uses it to connect to thestorage system.

• If the storage type is NetApp SnapLock storage, the Content Server uses the directorypath to pass the value to the mount point.

Allocating content to storage areasThe same administration guidelines that determine what storage areas are created for asite typically determine what content is stored in each storage area. Although users candesignate a particular storage area for a document’s content by setting the a_storage_typeproperty explicitly, generally, content is stored in accordance with business rules definedby system administrators.

The rules governing content assignment can be set up using content assignment policiesor by setting the appropriate property at the type or format object level and using thedefault storage algorithm. Using content assignment policies, page 225, describes theimplementation of content assignment policies and the requirements for using them.Using the default storage algorithm, page 229, describes how to use the default storagealgorithm.


Content Management

Using content assignment policies

The use of content assignment policies is supported only if you have installed ContentServer with a Content Storage Services license.

What content assignment policies are

Content assignment policies are a representation of the business rules that govern wherecontent is stored in an enterprise.

Content assignment policies define a content’s storage area based on rules. Therules are conditions based on content size or format. For example, a rule might becontent_size>10,000 (bytes) or format=’gif’. A rule can have up to five conditions ANDedtogether. You can also define a custom rule. The rules in a content assignment policyare stored as the policy’s content.

Note: Documentum Administrator’s online help or user guide provides informationabout creating rules based on document properties. Contact Documentum ProfessionalServices or Documentum Developer support if you need assistance in creating,implementing, or debugging a custom rule.

Each rule in a policy is identified with a particular storage area. The storage area canbe either a file store storage area, EMC Center store storage area, or NetApp SnapLockstorage area. When a policy is applied to a document, the document is tested againsteach rule in the policy and when a rule is satisfied, the content is stored in the storagearea identified with that rule and the remaining rules are ignored.

Creating content assignment policies

Define content assignment policies in Documentum Administrator. You must haveinstalled Content Server with a Content Storage Services license to access the links andpages that allow you to define a content assignment policy.

If the repository has such a license, Documentum Administrator allows users with atleast Sysadmin user privileges to define a policy based on document properties ora custom rule.

Note: Documentum Administrator’s online help or User Guide provides informationabout creating rules based on keywords or system-defined SysObject properties. ContactDocumentum Professional Services or Documentum Developer support if you needassistance in creating, implementing, or debugging a custom rule.


Content Management

The target storage areas of the rules you define in a policy can be either file store storageareas or distributed store storage areas.

Assignment policies are stored in a folder in the System cabinet. All users in therepository (dm_world) must have at least Read access to the policies.

Enforcement of assignment policies

Content assignment policies are enforced by a internal facility of DFC called the policyengine. Any client application built on the DFC enforces content assignment policiesautomatically if the Content Storage Services license is present and the policy enginein DFC is enabled. The dfc.storagepolicy.enable key in dfc.properties controls whetherthe policy engine is enabled or disabled. The key is T by default, meaning the policyengine is enabled.

The policy engine enforces content assignment policies:• When new content is created and saved or imported to the repository, whether the

content is a primary content file or a rendition, unless you explicitly identify astorage location for the content.

• When an application checks in an object.

The IDfSysObject.checkin method automatically issues a setFile method againstthe object, which invokes the policy engine, regardless of whether the content ischanged or not. For Documentum clients, this means that the policy engine isinvoked whether the object is checked in as a new or the same version. The policy isapplied to the new copy of the content file.

Assignment policies are not enforced if:• Fetch an object, change its properties, and save the changes.• An application sets the object’s a_storage_type property.

If a_storage_type is set to explicitly identify a storage area for the primary content,then the policy engine does not apply an assignment policy to the primary content.Note that Documentum client applications do not typically set a_storage_type.

• Similarly, if a storage area is specified explicitly in the arguments to an addRenditionmethod, the policy engine does not apply an assignment policy to the renditionthat is being added.

• The assignment policy for the particular object type is inactive and there are nopolicies or no active policies among the type’s supertypes.

• The DFC policy engine is turned off.• An assignment policy does not exist for the particular object type or for any of the

type’s supertypes.• The document does not satisfy any of the conditions in the applicable policy.


Content Management

• The content is associated with an object that is a replica, is added to the repositorythrough a dump and load operation, or is generated by a refresh method.

• The content is saved with a retention date.

Behavior on encountering a rule error

Each assignment policy defines one or more rules for content storage. At runtime, if thepolicy engine encounters an error in a rule, for example, because of a bad propertyname, by default, the policy engine returns an error, and the save operation fails. Youcan configure the policy engine to ignore such an error in a rule and continue evaluatingthe following rules in a policy. For instructions, refer to Configuring behavior onencountering a rule error, page 276.

DFC assignment policy information cache

DFC maintains a cache of assignment policy information. By default, the cache isupdated every 30 seconds. You can reset the interval. If you increase the interval, then ittakes longer for policy changes to be recognized by the policy engine. If you decrease theinterval, changes may be available for use sooner but performance may be degraded.

For instructions on resetting the interval, refer to Configuring the update interval forthe policy information cache, page 277.

Architectural implementation of assignment policies

Content assignment policies are stored in the repository as dm_ssa_policy objects andrelated to a SysObject object type by an object of type dm_relation_ssa_policy. Thedm_relation_ssa_policy type is a subtype of dm_relation. A relation ssa policy objectrecords the object ID of the ssa policy and an object type to which the policy applies.

A single content assignment policy (represented by an ssa policy object), can be relatedto multiple object types. However, a single SysObject object type can be related to onlyone content assignment policy. Figure 4, page 228, illustrates how content assignmentpolicies, as represented by ssa policy objects and object types are related.


Content Management

Figure 4. Relationship of content assignment policies and object types

Note: If you delete an object type that has a content assignment policy, the relation ssapolicy object that associates the type with the policy is automatically also deleted. Thessa policy object is not deleted automatically, as it may be related to other object types. Ifyou want to delete it, you must do so manually.

Algorithm used by the DFC policy engine

The DFC policy engine uses the following algorithm to determine the storage area forcontent files:

1. If the a_storage_type property of the object is explicitly set before the document issaved or a storage area is explicitly specified in an addRendition method, put thecontent in the specified storage area.

2. If a storage area is not explicitly specified, look for an assignment policy for theobject type of the document.

3. If a policy is found, test the document against the rules in the policy. When a rulematches, store the content in the storage area identified for that rule. If no rulematches, use the default storage algorithm to determine where to store the content.

4. If a policy is not found for the object type, traverse up the object’s supertypes, todetermine if any have an assignment policy. If a policy is found, test the documentagainst the rules in that policy. If a rule matches, store the content in the storagearea identified for the rule. If no rule matches, use the default storage algorithm todetermine where to store the content.

5. If no policy is found in the object’s type tree, use the default storage algorithm.


Content Management

Using the default storage algorithm, page 229, describes the default storage algorithm.

Assignment policy administration

There are a variety of administration-related operations that you can perform forcontent assignment policies. For example, you can turn on tracing of the policies. Youcan also disable the use of a particular policy, turn off use of all policies, and turn offerror reporting for individual policies. For instructions on these procedures, refer toAdministering content assignment policies, page 275.

Using the default storage algorithm

The default storage algorithm uses values in a document’s object, its associated formatobject, or type definition to determine where to assign the content for storage. Thealgorithm is different for primary content and renditions.

The default storage algorithm is used when• Storage policies are not enabled• Storage policies are enabled but a policy does not exist for an object type or for any

of the type’s supertypes• A content file does not satisfy any of the conditions in the applicable policy• Content is saved with a retention date.

Primary content algorithm

The default storage algorithm for primary content is:

1. If a_storage_type is set for the object, store the content in the storage area specified inthat property.

A user or application can specifically set the object’s a_storage_type property beforesaving the object, to assign the content file to a storage area.

2. If a_storage_type is not set, check for a value in the default_storage property of thecontent’s associated format object. If that property is set, store the content in thespecified storage area.

Note: Only the jpeg_th and jpeg_story formats have default_storage set by default.For those formats, the property is set to the thumbnail storage area. For all other


Content Management

formats, the property must be manually set if you want to store content in aparticular format in a particular storage area.

3. If neither a_storage_type nor the format’s default_storage is set, store the content inthe default storage area for the object type.

The SysObject type and every subtype has a default storage area for storingcontent files associated with objects of the type. The storage area is defined in thedefault_storage property of the type’s type info object. During Content Serverinstallation, the default storage area for the SysObject type is set to the file storestorage area created during the installation (filestore_01). The subtypes of SysObjectinherit this default. However, this can be changed, so filestore_01 may not be thedefault at your site or for a particular SysObject subtype.

4. If none of the above are defined, store the content in turbo storage.

This algorithm examines three properties:• a_storage_type for dm_sysobject• default_storage for the object’s format• default_storage for the object’s object typeThe a_storage_type property is defined for dm_sysobject and inherited by all itssubtypes. Typically, a_storage_type is set if you want to store an object of a particulartype in a location that is different from the default area for its content format or objecttype. You must set this property for an object before you save the object for the first time.

The default_storage property of a format object identifies a storage area by the storagearea’s object ID. By default, only the jpeg_th and jpeg_story format objects have a valuein the default_storage property. For those formats, the property is set to the object IDof the thumbnail storage area. (You must have Documentum Media TransformationServices installed to create and use thumbnails.) If you want to store content files inlocations specific to the file formats, set the default_storage property of the associatedformat objects before saving objects with content files in those formats.

The default storage area for an object type is defined in the default_storage property ofthe dmi_type_info object for the object type. The Content Server installation proceduresets the default_storage property for the SysObject type to the filestore_01 storage area.The value is inherited by all SysObject subtypes. You can change the default using theDQL ALTER TYPE statement.

By setting (or not setting) these three properties appropriately, you can direct content todesired storage areas when using the default storage algorithm. For example, supposeyou want all dm_documents except those in XML format to go to Storage_1 and youwant the XML documents to go to Storage_2. To obtain this behavior, you set the defaultstorage for the dm_document object type to Storage_1 and default storage for the XMLformat to Storage_2.


Content Management

Rendition algorithm

When the content file is a rendition of a primary content file, the following algorithm isused to determine where to store the file:

1. If a storage area is defined in the addRendition method, the rendition’s content file isstored in that location.

2. If a storage area is not defined in the addRendition method, the server checks for avalue in the default_storage property of the content file’s associated format object.

3. If a default storage area is not defined in the format object, the rendition is stored inthe same storage area as the object’s primary content.

Content RetentionBusinesses often must retain documents for a specified period of time. Content Serversupports three ways to ensure that documents, and their content, cannot be deleted untila specified retention period has expired:• You can associate the document with a retention policy.

Retention policies are defined and applied using Documentum Administrator.They may be applied to documents stored in any type of storage area. Usingretention policies requires a Retention Policy Services license. For more informationabout retention policies, refer to Content Server Fundamentals or the DocumentumAdministrator Users Guide. For information about defining a retention policy, refer toDocumentum Administrator online help.

• You can store documents in an EMC Centera storage area that has a defined orrequired retention period.

Documents whose content files are stored in an EMC Centera storage area cannot bedeleted until the retention period expires unless the user has privileges to performa forced deletion.

For information about defining a retention period for a Centera storage area, refer toDefining storage area retention requirements, page 247. Content Server Fundamentalshas information about forced deletions. Enabling forced deletion in EMC Centerastorage areas, page 265, describes how to enable forced deletions for a Centerastorage area.

This option, which can be used in conjunction with Retention Policy Services,requires a Content Services for EMC Centera license.


Content Management

• You can store documents in a Network Appliance (NetApp) SnapLock storage areathat has a defined or required retention period.

NetApp SnapLock is a licensed software that provides storage level retentioncapability through the creation of Write Once Read Many (WORM) volumes onNetwork Appliance storage systems. These WORM volumes enable users to preventaltering or deleting content until a specified retention date has expired. This option,which can be used in conjunction with Retention Policy Services, requires a NetAppSnapLock license.

There are two types of NetApp SnapLock stores:

— SnapLock Compliance store handles data retention to meet SEC regulations.

— SnapLock Enterprise store handles data retention to help customers meet theirself-regulated date retention requirements.

Refer to the SnapLock documentation provided by Network Appliance for moreinformation about the two types of stores.

Both EMC Centera and NetApp SnapLock systems provide retention capabilities.However, installing Retention Policy Services provides additional functionality as shownin Table 19, page 232.

Table 19. Availability of retention functionality

Functionality EMC Centera NetApp SnapLock

Default retention Yes Yes

Object-level retention Requires RPS Requires RPS

Retention holds Requires RPS Not available

Event-based retention Requires RPS Not available

Priviledged Delete Yes. Also available withRPS.

Not available

Note: In distributed environments, if a document is saved with retention, retention isenforced regardless of whether the content is written to the repository synchronouslyor asynchronously.

System-dened storage areasInstalling Content Server creates the following default file store storage areas for content:


Content Management

• filestore_01

This is the default storage area for all SysObjects except those that have thumbnail orstreaming files as content. Its media_type property is set to 0.

• thumbnail_storage_01

This is the default storage area for objects with primary content in thumbnail format.Its media_type property is set to 1.

• streaming_storage_01

This is the default storage area for object with primary content in streaming format.Its media_type property is set to 2.

• replicate_temp_store

This is where a dump file is stored in the target repository during a load operation.The file is removed after the load operation is completed.

• replica_filestorage_01

This is the default storage area for the content associated with object replicas ina repository.

The storage areas are created by the headstart.ebs script that runs duringthe installation procedure. By default, the storage areas are created under%DOCUMENTUM%\data\<repository_name> ($DOCUMENTUM/data/<repository_name>).

File paths and URLs for content les in storageThis section describes how to interpret a directory path or URL for content files in a filestore storage area.

Path specications for content in le stores

When you store a file in a file store storage area, the server creates a path specification forthe file using the following format

On Windows platforms:

storage_area_path\repository_id\8a\xx\yy\nn[.ext]

On UNIX platforms:

storage_area_path/repository_id/8a/xx/yy/nn[.ext]

where:


Content Management

• storage_area_path is the path specification in the storage area’s associated locationobject (for example, dmadmin\data\storage_01 or u12/dmadmin/data/storage_01).

• repository_id is the hexadecimal representation of the ID of the repository thatcontains the content.

Note: You can find a decimal representation of the repository ID in that server’sserver.ini file. This file is found in %DOCUMENTUM%\dba\config\repository_name($DOCUMENTUM/dba/config/repository_name).

The directories represented by 8a\xx\yy\nn(8a/xx/yy/nn) are named by convertingthe content’s data ticket value into hexadecimal format and dividing it into pairs. Thedata ticket value is generated when the file is first stored, and a subdirectory is createdand named for each of the first three pairs of numbers (8a xx yy) in the ticket. The xxdirectory is a subdirectory of the 8a directory and the yy directory is a subdirectory ofthe xx directory. The file is represented by the final two numbers (nn) and is stored inthe yy subdirectory. The a can be any number from 0 to f, and xx, yy, and nn can rangefrom 00 to ff. (The 8 increments after there are approximately 256 million content objectsin the repository.)

For example, a data ticket value of -2147483077 becomes 8000023b inhexadecimal. The file path generated for a content with this data ticket would bestorage_area_path\repository_id\80\00\02\3b (storage_area_path/repository_id/80/00/02/3b).

The name of the file is 3b.

If the use_extensions property for the storage area is set to TRUE and an extension isdefined for the file’s format (in its format object), the server appends the appropriateextension (.ext) to the file name.

URL specications for content les

Applications can access content files, particularly thumbnails or streaming content,using URLs. The URLs are obtained using the DQL keyword THUMBNAIL_URL or theGET_FILE_URL administration method.

URLs contain the following information:• The base URL defined for the storage area• A path relative to the storage area identified in the store property that points to

the content file• A store property that identifies the storage area containing the content fileIf the storage area’s require_ticket property is set to TRUE, the URL also contains a ticketthat contains an encryption of the path plus a time stamp.

For example:http://myserver.documentum.com:8080/getThumbnail?path=00232803/80/00/01/Ob.jpg


Content Management

&store=thumbnail_store_01&ticket=8002DWR670X

http://myserver.documentum.com:8080/getThumbnail? is the base URL.

path=00232803/80/00/01/Ob.jpg specifies the path to the file.

store=thumbnail_store_01 identifies the storage area.

ticket=8002DWR670X is the optional ticket.

Setting up storageThe steps required to implement a storage option depend on what option you choose.For example, setting up blob storage is as easy as creating a blob store object. To set upa file store storage area, you create one file store object and one location object. Turbostorage does not require any setup. You simply set a property of the content object.

Documentum Administrator is the preferred way to set up storage areas. You can useDQL, if needed, however.

This section includes the following topics:• Distributed storage setup, page 236, which briefly describes the implementation of

creating distributed storage areas• Setting up blob storage, page 236, which contains information and instructions for

creating a blob storage area• Setting up file store storage areas, page 237, which contains information and

instructions for creating a file store storage area.• Linked store setup, page 239, which contains information and instructions for

creating a linked store storage area.


• Setting up external storage, page 242, which contains information and instructionsfor creating external storage areas

• Setting up EMC Centera storage areas, page 245, which contains information andinstructions for setting up a Centera storage area

• Setting up turbo storage, page 257, which contains information and instructionsfor using turbo storage areas


Content Management

Distributed storage setup

A distributed storage area has one distributed store object and the location and storeobjects needed to define all component storage areas. The exact number and typedepend on what components you choose.

Because distributed storage areas are generally set up to implement a distributed contentarchitecture for distributed repositories, setting them up is described in the DocumentumDistributed Configuration Guide.

Setting up blob storage

Content stored in blob storage is stored in the repository. Consequently, when youcreate a blob storage area, Documentum Administrator creates only a blob store object;a location object is not created.

Blob storage is implemented as tables in the underlying RDBMS. Therefore, the namethat you assign to the blob store object for the storage area must conform to the rules thatgovern type names. Additionally, if the repository is running on DB2 and you createmultiple blob store storage areas, the names of the storage areas must be unique amongthemselves to 16 characters. The Documentum System Object Reference Manual describesthe rules that govern type names.

When you create a blob storage area, you must indicate what type of content will bestored in the storage area. You can choose either ASCII content or 8-byte characters. Thechoice is recorded in the ascii property of the blob object. If you set the content type toASCII, the property is set to T (TRUE), and you can store only ASCII characters in thestorage area. If you set the content type to 8-byte characters, the property is set to F(FALSE), and you can store non-ASCII or ASCII content in the storage area.

Using DQL to set up blob storage

To create a blob store object using DQL, use the CREATE...OBJECT statement. The syntaxfor the CREATE...OBJECT statement to create blob store objects is:CREATE "dm_blobstore" OBJECTSET "name" = 'object_name',SET "ascii" = true|false

For example:1>create dm_blobstore object2>set name = 'blobstore1',3>set ascii = true4>go


Content Management

object_name is the name you assign to the blob store object.

Setting up le store storage areas

Creating a file store storage area creates one dm_filestore object and one location object.The location object identifies the actual directory location of the storage area. If thelocation is a shared or mounted directory, one mount point object is also created.

The file store object defines the storage properties of the area. The root propertyof the file store object points to the location object that identifies the storage area’slocation. For example, if you created a storage area named engr_store located inD:\dctm\data\mydb\store_4 (or /u03/dctm/data/mydb/store_4 in UNIX), you createthe file store and location objects illustrated in Figure 5, page 237.

Figure 5. Relationship between a le store object and a location

Multiple file store objects cannot point to the same location object. Each file store objectin a repository must point to a different location object and the location objects mustspecify different directories.

Use Documentum Administrator to create file store storage areas, although you canalso use DQL.

File extensions and the use_extensions property

By default, Documentum Administrator checks Use Extensions. The server will add fileextensions to file names when it saves a file into a file store storage area. If you do notwant the server to add extensions to files saved to the storage area, uncheck the box. Youcannot set this after you put files in a storage area.

The choice is recorded in the use_extensions property of the area’s storage object. This isa Boolean property set to TRUE if the box is selected and FALSE if the box is not selected.

When the property is TRUE, only content files whose format definition (in the formatobject) includes a file extension are affected. If a content file has no extension defined forits format, no extension is set when the file is saved. Refer to Providing automatic fileextensions, page 258, for complete details about implementing the use of file extensionswhen storing and retrieving files.


Content Management

Setting the base URL

Set the base URL if the storage area will hold thumbnail renditions or content you wantto retrieve with a streaming server. A base URL identifies:• The protocol used for communications• The host machine on which the server retrieving the file resides• The port number to use when communicating with the server• The application rootThe format of a base URL is:protocol://machine_id:port_number/server_identification

The base URL for storage areas that will store thumbnail renditions isrecorded in the installation log file created when the Thumbnail Server wasinstalled. The log file is found in %DM_HOME%\thumbsrv\install\install.log($DM_HOME/thumbsrv/install/install.log).

To determine the base URL for storage areas that will store streaming content, consult thedocumentation provided with the streaming server to obtain the correct base URL value.

The URL you specify is recorded in the base_url property and is returned when anapplication issues a request for an URL.

Dening le store storage areas as public (Windows only)

To define a file store storage area as public, the file system on which the storagearea resides must be a Windows NTFS file system, not a Windows FAT file system.Additionally, if any clients are Macintoshes, the Windows server that services the filesystem must be an Advanced server.

Using DQL to set up le storage

The following procedure outlines how to create a file store storage area using DQL.

To create a le store storage area using DQL:1. Log in to the repository.

2. Use the CREATE...OBJECT statement to create the location object for the area.For example:1>create "dm_location" object2>set "object_name" = 'storage_3',3>set "file_system_path" = 'd:\documentum\data\store_3',


Content Management

4>set "path_type" = 'directory',3>go

or1>create "dm_location" object2>set "object_name" = 'storage_3',3>set "file_system_path" = '/u12/dmadmin/data/store_3',4>set "path_type" = 'directory',3>go

The Documentum System Object Reference Manual has detailed description of theproperties of location objects.

3. Use the CREATE...OBJECT statement to create the file store object for the area andset its properties.In addition to the required properties, you may also want to set the encryptionand compression modes, enable digital shredding, or enable content duplicationchecking and prevention. Some of these optional features must be set when thestorage area is created. Refer to File store storage areas, page 205, for a discussionof these features. The Documentum System Object Reference Manual has a detaileddescription of the properties of file store objectsThe following example sets only the basic properties.1>create "dm_filestore" object2>set "name" = 'engr_store3',3>set "root" = 'storage_3',4>set "is_public" = 'false',5>go

The value assigned to the file store’s root property is the object name of the locationobject.

Linked store setupNote: Linked store storage areas are deprecated. DFC versions 6 and later do notsupport linked store storage areas.

Linked storage areas are represented in the repository by two storage objects, twolocation objects, and one mount point object.

One storage object and location object pair represents the shared or mounted directorycontaining the link and the other storage object and location object pair represents thedirectory that actually stores the files. The mount point object is needed because theshared or mounted directory containing the link must be visible to both the client andthe server. Consequently, that directory must be mounted by clients and the installationmust be using NFS.

A mount point object has properties that let you specify the alias for the shared ormounted directory when referenced by clients. Set the appropriate property or properties


Content Management

depending on your site’s configuration. Refer to Chapter 2, Content Repositories, forinformation about creating mount points and setting these alias-related properties.

Documentum provides a default mount point object whose file_system_path defines%DOCUMENTUM%\share ($DOCUMENTUM/share) as a mounted directory.

The relationships for a linked storage area are shown in Figure 6, page 240.

Figure 6. The objects that dene a linked store storage area

Use file stores as the storage areas that underlie a linked storage area.

You can use Documentum Administrator or DQL to set up a linked storage area.For instructions on using Documentum Administrator, refer to the DocumentumAdministrator online help.

Using DQL to set up linked storage

The following procedure assumes that the underlying storage area is a file store.


Content Management

To create a linked store storage area using DQL:1. Log in to the repository.

2. Use the procedure in Setting up file store storage areas, page 237, to create the filestore storage area.

3. Create the location object for the shared directory (Windows) or the directorycontaining the link (UNIX).For example, on Windows:1>create "dm_location" object2>set "object_name" = 'link_05',3>set "file_system_path" = '\',4>set "path_type" = 'directory',5>set "mount_point" = 'link_mount_05'6>go

For example, on UNIX:1>create "dm_location" object2>set "object_name" = 'link_05',3>set "file_system_path" = '/data/link_05',4>set "path_type" = 'directory',5>set "mount_point" = 'link_mount_05'6>go

4. Create the linked store object.For example, on Windows:1>create "dm_linkedstore" object2>set "name" = 'linkedstore_05',3>set "component" = 'filestore_05',4>set "link_location" = 'link_05',5>go

For example, on UNIX:1>create "dm_linkedstore" object2>set "name" = 'linkedstore_05',3>set "component" = 'filestore_05',4>set "link_location" = 'link_05',5>set symbolic_link = <true/false>,6>go

5. Create a mount point object for the shared directory if the object does not alreadyexist. For example:For example, on Windows:1>create "dm_mountpoint" object2>set "name" = 'link_mount_05',3>set "file_system_path" = '\dm\dmadmin\data\prod\store_05',4>set "win_preferred_alias" = 'appropriate value'5>go

For example, on UNIX:1>create "dm_mountpoint" object2>set "name" = 'link_mount_05',


Content Management

3>set "file_system_path" = '/u12/dmadmin/data/link_dir',4>set "win_preferred_alias" = 'appropriate value'5>go

Setting up external storage

This section provides an outline of the basic steps to set up an external storage area.EMC Documentum provides standard technical support for creating a plug-in objector external storage object. However, contact Documentum Professional Services orDocumentum Developer Support for assistance in creating, implementing, or debuggingthe shared library or DLL that is the content of the plug-in object.

To create an external storage area:1. Create the shared library or DLL.

The shared library or DLL must implement the functions described in AppendixG, Plug-in Library Functions for External Stores. A sample for the externalfile store type is provided in the %DM_HOME%\unsupported\plugins($DM_HOME/unsupported/plugins) directory. You can use this to guide you whenyou create your own shared library or DLL.

2. Start Documentum Administrator and connect to the repository.

3. Create a plug-in object.

4. Create the external storage area.You must configure the plug-in to execute on the server host.Refer to Documentum Administrator online help if needed.

An example of importing documents stored on a CD-ROM

The following procedure outlines how files stored on a CD-ROM can be imported intothe repository using an external file store storage area.

To import les on a CD-ROM into the repository using external le store:This example assumes that the server is running on the Windows platform and theCD-ROM drive letter is E.

1. Create a location object for the CD-ROM drive with file_system_path set to E:\.

2. Create the plug-in object.

3. Create a dm_extern_file object.


Content Management

4. Create folders and sub-folders in the repository that resemble the directory structureon the CD-ROM.

5. For each file on the CD-ROM, create a document object under the appropriate folderthat uses external file store.The storage area for the document’s content must be the external file store storagearea.

6. Use IDfSysObject.setPath against each document to set the relative path as thecontent token.For example, to create a document object for E:\public\docs\extstore.doc, set thefileName argument in the Setpath command to:'public\docs\extstore.doc'.

Using the Mount methodNote: The information in this section is only useful if the plug-in is configured to executeon the client host. Executing the plug-in on the client host is not supported by DFCversion 6 or later.

The IDfSysObject.mount method provides a way to dynamically change the path tocontent in an external file store. Use the mount method to dynamically remap the clientroot location when executing the plug-in on the client if the path name specified in theclient root location is invalid or inaccessible.

For example, if you set up external file storage to enable access to files on a CD-ROMand then move the CD-ROM to a local client machine, you can use the mount methodto correct the path.

In the example in the previous section, if the a_exec_mode of the external file store objectis set to FALSE (plug-in is executed on the server), you do not need to issue a mountmethod. The client can retrieve content using getFile or getContent.

However, if the a_exec_mode of the external file store object is set to TRUE but theCD-ROM drive is now F:\, the client must issue a mount method.

Then, use getFile or getContent to retrieve the content from the CD-ROM.

If the a_exec_mode property of the external file store object is set to FALSE but a contentserver is configured on another machine on which the CD-ROM drive is F:, then specifyan a_config_name and a_location pair for the storage object before accessing the content.Set the file_system_path of the location object to F:\.

If the a_exec_mode property of the external file store object is set to TRUE (plug-inis executed on the client), the client application can issue the mount method in thefollowing format:mount,c,6000271280000120,local_CD-ROM_drive


Content Management

Then, use the getFile or getContent method to retrieve the content form the CD-ROM.

If the client application does not execute the mount method but issues getFile orgetContent, the content is retrieved on the server side and sent back to the clientapplication if a server side plug-in is available.

External URL storage setup

For objects that use dm_extern_url, the setFile and setPath methods require a validformat. The correct format is determined by the type of information the URL points to.Table 20, page 244 shows some examples of URLs and formats.

Table 20. Examples of URLS and formats

URL Format

http://www.documentum.com html

file:://C|/temp/sample.txt text

Before you set up an external URL store, decide what type of information the URL pointsto and decide which format to specify in the setFile or setPath method.

Use Documentum Administrator to set up external URL storage. For instructions, referto the Documentum Administrator online help.

Setting up external free storage

The configuration of the plug-in properties for external free stores is fully under thediscretion of users.

Depending on accessibility of the content, users decide whether to run the plug-in onthe server or the client.

Content retrieval for objects in external free stores depends on how the user-specifiedplug-in interprets the content token, so it is up to the user to decide which format to usewhen using setFile or setPath for objects that use external free stores.

Use Documentum Administrator to set up external free storage. For instructions, refer tothe Documentum Administrator online help.


Content Management

Conguring for optimal performance on retrieval

By default, each time a user in a session issues a getFile method to retrieve content storedin an external storage area, the content is physically retrieved from the storage deviceand copied to the user’s local disk. This default behavior occurs because the content isstored in a storage area that is not managed by Content Server, which means that thecontent may be changed without Content Server’s knowledge. However, if the content isstatic content that changes infrequently or not at all, you can avoid creating multiple localcopies, and possibly enhance getFile performance, by changing the default behavior.

To change the default behavior, set either the a_content_static property in the storagearea object for the external storage area or set the dfc.content.extern_store_content_statickey in the dfc.properties file. Both the property and the key are Booleans. They are F(FALSE) by default, which supports the default getFile behavior. If you set either to T(TRUE), the default behavior of getFile changes when a user fetches the same contentmore than once in a session. Instead of physically fetching the content from the externalstorage area for second and subsequent accesses, the method returns the file path to thelocal copy created by the first getFile on the content.

Setting the a_content_static property affects all getFile methods that access content inthat storage area. Setting the dfc.content.extern_store_content_static key affects onlygetFile methods issued by sessions established using that dfc.properties file.

Setting up EMC Centera storage areas

To use an EMC Centera store storage area, you must have purchased a Content Servicesfor EMC Centera license.

Using EMC Centera storage requires the EMC libraries, a plugin object, and adm_ca_store object. Installing Content Server automatically installs the EMC librariesand creates the plugin object. The ca store object is created when you create an EMCCentera storage area using Documentum Administrator.

The libraries are installed in %DM_HOME%\bin ($DM_HOME/bin). The names differby platform:• On Windows, the library is libemcplugin.dll• On Solaris, AIX, Linux, and HP Itanium, the library is libemcplugin.so• On HP-UX PA-RISC, the library is libemcplugin.slThe plug-in object is named CSEC Plugin. It stores the EMC library as its content. Thecontent is stored in a file store storage area. Storing the plug-in content in a file storestorage area is a requirement of the implementation. The storage area may be encrypted.

Note: The version number of the Centera Runtime libraries and the build version numberof the plug-in are recorded in the server log file when the server loads the plug-in.


Content Management

The properties in the ca store object identify the storage system metadata fields that youwant to set for content stored using that storage object, the location of the storage system,and the plug-in object. Optionally, you can also define the retention requirements inthe storage object.

Setup procedure

To set up an EMC Centera storage area:1. If the Content Server host machine has multiple versions of EMC Centera SDK

installed on it, to ensure that the version installed with Content Server is used byContent Server, make sure that DM_HOME/bin appears first in the appropriateenvironment variable:• For Windows hosts, the variable is PATH• For Solaris and Linux hosts, the variable is LD_LIBRARY_PATH• ForHP iTaniumhosts, the variable is either SHLIB_PATHor LD_LIBRARY_PATH• For all other HP-UX hosts, the variable is SHLIB_PATH• For AIX hosts, the variable is LIBPATH

2. Use Documentum Administrator to create the EMC Centera storage area.

Note: If you wish to create an EMC Centera storage area without specifying avalue for the a_plugin_id property, use IDQL or IAPI instead of DocumentumAdministrator to create the storage area. Creating the storage area withoutspecifying the plug-in is useful in distributed environments. Refer to , for details.

Use the following guidelines:• You can define up to 62 values for the Content Property Names. The names are

recorded in the a_content_attr_name property of the associated ca store object.The values defined for a_content_attr_name may not contain spaces.

• Defining storage area retention requirements, page 247, describes how to setretention requirements.

• Defining the connection string , page 248, describes how to set the connectionstring.

This section includes information about setting the connection string correctlyto configure use of Centera clusters.

• Configuring embedded blob use, page 251, describes how to configureembedded blobs.

• Setting the C-clip buffer size, page 252, describes how set the C-clip buffer size.• Configuring write attempts in EMC Centera storage areas, page 253, describes

how configure the number of write retries.


Content Management

• Overriding the Centera single-instancing configuration, page 253, describes howto configure the storage area to override the Centera host’s single-instancingconfiguration.

• Resetting the maximum socket connections allowed, page 254, describes how toconfigure the maximum number of socket connections the Centera SDKmay use.

• Configuring use of a memory map for write operations, page 254, describes howto configure the use of the memory map interface for certain write operations tothe storage area.

For additional help on setting the storage area properties, refer to DocumentumAdministrator online help.

Dening storage area retention requirements

An EMC Centera storage area will enforce a retention period if you choose to requireone for the storage area. When you create an EMC Centera storage area, DocumentumAdministrator provides two options if you choose to define a retention requirementfor the storage area. Whichever option you choose is applied to all content saved tothe storage area. The options are:• You can allow users or the client application to define the retention period when

saving content to the storage area.• You can specify a default retention date to be applied to all content saved to that

storage area.In addition to specifying how the retention period is defined, you must identify whichmetadata field in the EMC Centera storage area will be used to store the retention period.The name of chosen metadata field may not contain spaces.

The decision you make regarding retention requirements is recorded in these propertiesof the ca store object:• a_retention_attr_required

The a_retention_attr_required property defines whether content saved to thisstorage area requires a retention date. This property is set to T if you require users orapplications to provide a retention period when saving content.

• a_default_retention_date

If you choose to specify a default retention value as a date, the value is recorded inthe a_default_retention_date property.

• default_retention_days

If you choose to specify a default retention value as a number of days, the value isrecorded in the default_retention_days property.


Content Management

• a_retention_attr_name

The a_retention_attr_name property records the name of the metadata field thatstores the retention period for the content.

It is possible for an application to override a default retention date when setting thecontent object properties. This is done by including the name of the field storingthe retention period in the parameters argument of the SET_CONTENT_ATTRSadministration method or the DFC setContentAttrs method. If the retention field name isset when you set the content object properties, the retention period is set to the valuedefined by the a_default_retention_date property.

To allow users to save content to the storage area without a retention period, do not setany retention requirements when creating the storage area.

Note: If a document is associated with a retention policy and its content is stored in anEMC Centera storage area with a retention value, the content’s storage-based retentionperiod is set to the longest retention value. For example, if the retention policy mandateskeeping the document for five years and the storage area retention period is three years,the document’s recorded retention period is five years.

Dening the connection string

The connection string is the value used by Content Server to connect to the Centera host.You must define the connection string for the EMC Centera storage area. The connectionstring is recorded in a_storage_params[0].

Content Server supports any valid connection string documented and accepted byCentera. The typical format for a repository with a single server is:IP_address|hostname{,IP_address|hostname}?Centera_profile

where IP_address is the IP address of the Centera host, hostname is the host name of theCentera machine. If there are multiple Centera hosts identified in the connection string,the Centera SDK connects to the first available Centera node in the list.

The Centera_profile is a full-path specification of a Centera profile. The path must beaccessible from the Content Server host machine and the specified directory must bereadable by the Content Server installation owner. If there is no profile specified in theconnection string, the connection to the Centera host uses the anonymous profile.

If there are multiple servers servicing the repository, use the following format for theconnection string:svr_config_name="valid_Centera_connection_string"{,svr_config_name="valid_Centera_connection_string"}

where valid_Centera_connection_string is the format described for a single server.


Content Management

Note: The value defined for a_storage_params[0] is passed directly to the FPPool_Open()Centera SDK function. Contact your Centera administrator to determine the correctconnection string for your environment.

Required privileges for connection strings

The anonymous profile and any user-defined profile specified in a connection stringmust have the following EMC Centera permissions:• read• write• delete• existsA profile used by a connection that is requesting a privileged delete must have privilegeddelete permissions.

To ensure that security is maintained, do not give other applications any permissions tothe EMC Centera pool that Documentum Content Server uses.

Dening a connection string supporting EMC Centera clusters

Support for EMC Centera clusters is configured through the connection string. Thissupport allows you to configure a storage area that represents Centera clusters so:• A Content Server can write to the EMC Centera cluster closest to itself• A Content Server can read from the EMC Centera cluster closest to itself and, if

needed, fail over to read from another Centera cluster.

Note: Configuring bi-directional replication between the EMC Centera clusters willavoid the need for read failovers on the part of Content Servers.

The configuration is accomplished by identifying the primary and secondary clusters foreach Content Server in the connection string. The specified primary cluster is the clusterthat the associated Content Server will use for write operations and read operations.The specified secondary cluster is the cluster the server will use if an attempt to readcontent from the primary cluster fails.

The connection string is specified in a_storage_params[0], in the ca store object. Theformat for the connection string when you are identifying primary and secondaryclusters for one or more Content Servers is:srv_config_name="primary=cluster_id,secondary=cluster_id[?Centera_profile]"{,srv_config_name="primary=cluster_id,secondary=cluster_id[?Centera_profile]"}

where


Content Management

• The primary cluster_id is the name or IP address of the EMC Centera cluster to whichthe Content Server will write

• The secondary cluster_id is the name or IP address of the EMC Centera cluster fromwhich the Content Server will read if it cannot read from the specified primary cluster

Note: Including a Centera profile specification is optional.

The a_storage_params property is 1024 characters. Consequently, you must assignnames to the Centera cluster nodes that are short enough to allow the full connectionstring to fit within the property.

Example of use

Suppose you have single-repository distributed configuration with two Content Serversat different sites and a Centera cluster at each site. The server config names are:• sc1 for Content Server 1• sc2 for Content Server 2The names for the Centera cluster nodes are:• cc1 for Centera cluster 1• cc2 for Centera cluster 2For Content Server 1, the server should write to Centera cluster 1 and Centera cluster2 is the failover read cluster for the server. For Content Server 2, the server writes toCentera cluster 2 and Centera cluster 1 is the server’s failover read cluster. To obtain thatconfiguration, you set a_storage_params[0] to:sc1="primary=cc1,secondary=cc2",sc2="primary=cc2,secondary=cc1"

Figure 7, page 251, illustrates this configuration.


Content Management

Figure 7. Content Server and EMC Centera cluster conguration in single-repositorydistributed environment

Conguring embedded blob use

Embedded blobs are a storage option for content stored in Centera storage. (Embeddedblobs are described in Whether to link or embed the content in the C-clip, page 214.) Toconfigure embedded blob use, enter the following storage parameter value:pool_option:embedded_blob:size_in_KB

where size_in_KB is the maximum size of the content that you want to store as embeddedblobs. For example, if you want to store all content that is 60 KB or smaller as embeddedblobs, set the storage parameter value as:pool_option:embedded_blob:60

If multiple embedded blob pool_options are defined, Content Server only recognizes thelast option. For example, suppose you set a_storage_params to:a_storage_params[1]:pool_option:embedded_blob:100a_storage_params[2]:pool_option:embedded_blob:63


Content Management

Content Server uses 63 as the threshold size for embedded blobs. The setting of ’100’ isnot used or recognized.

There is no maximum set on the size of the embedded blob defined through the Centerastore storage area. However, Centera has a default maximum size for an embedded blobof 100 KB. The default can be overridden by setting a global environment variable in theCentera SDK. If you want to define an embedded blob size larger than 100 KB in thestorage area object, you must also override the Centera default by setting the appropriateenvironment variable in the Centera SDK. Refer to the Centera documentation forinformation about that variable.

Caution: If the maximum size set in the ca store object exceeds the maximum sizeaccepted by Centera, an attempt to write the content to that storage area will failwith an error like the following:[DM_STORAGE_E_CA_STORE_PLUGIN_ERROR_DURING_WRITE]error: "PluginID:<plugin ID> returned error: Wrong parameter detected :PF_PARAM_ERR, error code:-10006"

If the size defined in the storage area object is larger than the maximum size allowed byCentera, the lower of the two values is used to determine whether to store the content asan embedded blob or a linked blob. This also means that if an embedded blob size isnot configured in the storage area, the content is always stored as a linked blob even if athreshold is defined in the Centera cluster.

You can configure multiple ca store objects that put content in the same Centera clusterto use different thresholds for embedded blobs. When content is stored, the valuedefined in the individual ca store object is used to determine whether to store content asembedded blob or as a linked blob.

You can change the threshold after creating the storage area.

Setting the C-clip buffer size

The client (SDK) C-clip buffer is used by Centera to manage C-clips created byapplications. The default size is 150K. To change the size, set a pool option in thea_storage_params property of the ca store object (at index position 1 or greater). Theformat is:pool_option:clip_buffer_size:integer

where integer is an integer number representing the number of kilobytes. For example,suppose you want to enlarge the buffer to 200 kilobytes. You would specify the followingin a_storage_params:pool_option:clip_buffer_size:200


Content Management

Setting clip_buffer_size sets the FP_OPTION_BUFFERSIZE configuration parameter.This parameter controls the size of the client C-clip buffer.

If you require assistance determining the appropriate size for the C-clip buffer, contactCentera Technical Support.

Conguring write attempts in EMC Centera storage areas

By default, Content Server makes a maximum of three attempts to write content to anEMC Centera storage area. Between each attempt, Content Server waits a configuredinterval. You can reset the maximum number of attempts and the interval betweenattempts. You can also configure one last attempt (after the maximum number ofattempts are completed) in Full Blob Name mode.

Themaximum number of retries is defined in the dfc.content.castore.write_max_attemptskey in the dfc.properties file. The default value for that key is 3.

The interval between attempts is set by the dfc.content.castore.write_sleep_interval key.The value is specified in seconds and defaults to 3 if not set.

To direct Content Server to make a final attempt using Full Blob Name mode, setthe a_content_attr_name property in the EMC Centera storage area’s ca store objectto “dm_storage_strategy”. When this field name is present in a_content_attr_name,Content Server will make a final attempt to write content to the Centera storage areausing Full Blob Name mode.

Overriding the Centera single-instancing conguration

By default, the storage strategy configured on the Centera host is used when savingcontent to a Centera storage area. This configuration setting determines whether Centerachecks for an existing instance of a content file on the system when saving a file or not.To override that setting and force Centera to save content without checking for duplicateinstances of content on the host, set the following pool option in the a_storage_paramsproperty of the ca store object:pool_option:use_collision_avoidance:T

If the option is set to F or not set, the storage strategy configuration defined in theCentera system is used.


Content Management

Resetting the maximum socket connections allowed

By default, the maximum number of socket connections that the Centera SDK canestablish with the Centera host is 99. You can reset the maximum, up to 999. To do so,add the following pool option in the a_storage_params property:pool_option:max_connections:integer

where integer is the desired maximum number of connections.

Conguring use of a memory map for write operations

The memory map interface is only used when content is moved from an unencrypted,uncompressed file store to the EMC Centera storage area using MIGRATE_CONTENTor by setting an object’s a_storage_type.

To use the memory map interface, you must set two pool options for the storage area.Pool options are set in the a_storage_params property of the ca store object associatedwith the storage area. You can use Documentum Administrator to set the options.

The two pool options that configure the use of this feature are:• use_mmap

This pool option requires a Boolean value. It enables or disables the use ofthe memory map. For example, to enable the feature, set the following ina_storage_params:pool_option:use_mmap:T

This option false by default, which means the feature is not enabled.• max_mmap_file_size

This pool option defines the maximum size, in Kbytes, of the files that can be writtento the storage using the memory map interface. For example, to set the maximumfile size at 50 Kbytes, set the following in a_storage_params:pool_option:max_mmap_file_size:50

The default size when this feature is enabled is 100 Kbytes.The use of the memory map interface may require additional virtual memory.


Content Management

Setting clocks and time zones for Centera hosts and ContentServer hosts

The actual retention date stored in the Centera host for a content file is calculated usingthe clock on the Centera host machine. Consequently, to ensure calculation of correctretention periods, the time zone information and the internal clocks on Centera hostmachines and Content Server host machines must be set to matching times (within thecontext of their respective time zones). For example, if the Content Server host is inCalifornia and the Centera host machine is in New York, when Content Server’s time is1:00 p.m. PST, the time on the Centera host should read 4:00 p.m. EST.

Failure to synchronize the times may result in incorrect retention dates for the storedcontent.

Setting up NetApp SnapLock storage areas

To create a NetApp SnapLock storage area you must have purchased a NetworkAppliance SnapLock license and an EMC Connector license.

Using NetApp SnapLock storage requires a plugin object and a dm_ca_store object.Installing Content Server automatically installs the plugin object to use with NetAppSnapLock. The ca store object is created when you create a NetApp SnapLock storagearea using Documentum Administrator.

The libraries are installed in %DM_HOME%\bin ($DM_HOME/bin). The names differby platform:• On Windows, the library is netappplugin.dll• On Solaris, AIX, Linux, and HP Itanium, the library is libnetappplugin.so• On HP-UX PA-RISC, the library is libnetappplugin.slThe plug-in object is named SnapLock Connector. It stores the plug-in library tocommunicate with NetApp SnapLock. The content is stored in a file store storagearea. Storing the plug-in content in a file store storage area is a requirement of theimplementation. The storage area may be encrypted.

The properties in the ca store object identify the storage system, the location of thestorage system, and the plug-in object. Optionally, you can also define the retentionrequirements in the storage object.


Content Management

Setup procedure

To set up a NetApp SnapLock storage area:1. Ensure that DM_HOME/bin appears first in the appropriate environment variable:

• For Windows hosts, the variable is PATH• For Solaris and Linux hosts, the variable is LD_LIBRARY_PATH• ForHP iTaniumhosts, the variable is either SHLIB_PATHor LD_LIBRARY_PATH• For all other HP-UX hosts, the variable is SHLIB_PATH• For AIX hosts, the variable is LIBPATH

2. Use Documentum Administrator to create the NetApp SnapLock storage area.

Note: If you wish to create a NetApp SnapLock storage area without specifyinga value for the a_plugin_id property, use IDQL or IAPI instead of DocumentumAdministrator to create the storage area.

Use the following guidelines:• Enabling content compression, page 256 describes setting content compression

for a SnapLock store.• Defining SnapLock storage area retention requirements, page 256 describes how

to set retention requirements.For additional help on setting the storage area properties, refer to DocumentumAdministrator online help.

Enabling content compression

Content compression is a configuration option for a NetApp SnapLock store only if youhave a Content Storage Services license. Content compression is enabled when theSnapLock storage area is created and cannot be reset later. Content compression, page206 provides additional information about content compression.

Dening SnapLock storage area retention requirements

A NetApp SnapLock storage area will enforce a retention period if you choose to requireone for the storage area. When you create a SnapLock storage area, DocumentumAdministrator provides two options if you choose to define a retention requirementfor the storage area. Whichever option you choose is applied to all content saved tothe storage area. The options are:• You can allow users or the client application to define the retention period when

saving content to the storage area.


Content Management

• You can specify a default retention date to be applied to all content saved to thatstorage area.

In addition to specifying how the retention period is defined, you must identify whichmetadata field in the NetApp SnapLock storage area will be used to store the retentionperiod. The name of chosen metadata field may not contain spaces.

The decision you make regarding retention requirements is recorded in these propertiesof the ca store object:• a_retention_attr_required

The a_retention_attr_required property defines whether content saved to this storagearea requires a retention date. This property is set to T (TRUE) if you require users orapplications to provide a retention period when saving content.

• a_default_retention_date

If you choose to specify a default retention value as a date, the value is recorded inthe a_default_retention_date property.

• default_retention_days

If you choose to specify a default retention value as a number of days, the value isrecorded in the default_retention_days property.

• a_retention_attr_name

The a_retention_attr_name property records the name of the metadata field thatstores the retention period for the content.

NetApp SnapLock supports extending the retention period; however, shortening theretention period is not allowed. An application can override a default retention datewhen setting the content object properties. This is done by including the name of the fieldstoring the retention period in the parameters argument of the SET_CONTENT_ATTRSadministration method or the DFC setContentAttrs method. If the retention field name isset when you set the content object properties, the retention period is set to the valuedefined by the a_default_retention_date property.

Note: If a document is associated with a retention policy and its content is stored inan NetApp SnapLock storage area with a retention value, the content’s storage-basedretention period is set to the longest retention value. For example, if the retention policymandates keeping the document for five years and the storage area retention period isthree years, the document’s recorded retention period is five years.

Setting up turbo storage

Content stored in turbo storage is stored in the i_contents property of the associatedcontent object or in the i_contents property of a subcontent object if the turbo content is


Content Management

too large to be stored in a content object. The server automatically creates the subcontentobjects.

No architectural setup is required to implement turbo storage. To store an object’scontent in turbo storage, set the a_storage_type property of the object to dm_turbo_storebefore you issue a setFile method to associate the content with the object.

Providing automatic le extensionsContent Server does not automatically append file extensions to content files when thefiles are saved to a storage area, copied to the client local area, or copied to a servercommon area. However, your client applications or systems may require file extensions.If you use public or linked storage areas, the stored files may also need file extensions sothat your applications can access them directly.

Note: Linked storage areas are deprecated. DFC versions 6 and later do not supportlinked storage areas.

You can force the server to append file extensions to content files when they are stored.You can also force the server to append a file extension when the file is copied to aworking directory or common area.

Extensions are defined in the objects that define file formats. That is, you define anappropriate extension for a particular format, rather than for a specific file. This is doneby setting the dos_extension property for the format in its format object. If dos_extensionis set, the server appends that extension to any file of that format that is copied to aclient local area or server common area.

If you want the files stored in a storage area to have extensions, you must set theuse_extensions property for the area’s storage object when you first define the storagearea. This property is available for file store and linked store storage areas. It is aBoolean property. If it is set to TRUE, the server appends the extension defined indos_extension for the file’s format object to the internally generated name for the filewhen it saves the file.

File extension usage must be turned on when the storage area is first defined. You cannotturn it on for a storage area that already contains files without extensions.

It is not an error to save a file without a defined extension to a storage area that usesextensions. However, all files of one format in a storage area must either have extensionsor not have extensions. For this reason, you cannot turn on use_extensions after youstart saving files to a storage area.


Content Management

Moving content lesContent Server supports three ways to move content files:• MIGRATE_CONTENT administration method

This method allows you to move one content file or multiple content files.MIGRATE_CONTENT method is the recommended way to move multiple contentfiles if you do not have a Content Storage Services license and, consequently, cannotuse a content migration policy.

• Content migration policies

Content migration policies are implemented as jobs. The jobs automate themovement of content files from one storage area to another. A content migrationpolicy job invokes the MIGRATE_CONTENT method.

You must have installed Content Server with a Content Storage Services license touse content migration policies.

• Records migration jobs

A records migration job moves batches of content files based on criteria you define.

MIGRATE_CONTENT administration method

MIGRATE_CONTENT is the recommended way to move content files. It has a flexiblesyntax that allows you to move one content file, multiple content files, or all content in astorage area. The syntax also allows you to identify either a content object or instancesof SysObjects or a SysObject subtypes as the target of the operation. If you specify aSysObject or subtype, you can move the object’s first primary file (page 0), renditionsof the first page, or both. You can move content files associated with both changeableand unchangeable objects.

For Documentum 6.5 repositories, administrators can optionally enter a ContentMigration Threads value to enable the MIGRATE_CONTENTmethod to perform contentmigration in parallel. Use this option when performing mass migration of content tooptimize execution time. When the value of this option is 0, which is the default, themigration process is sequential and only one object at a time is migrated. When the valueof this option is greater than 1, the method executes in parallel using multiple internalsessions to concurrently migrate many content files. Each migration thread runs as aninternal session, which is a thread on Windows or a process on UNIX. Each internalsession requires at least one database connection and consumes additional system CPUcycles and memory. For this reason, it is recommended that mass migration be donewhen the system load is light or idle.

Note:


Content Management

• The Content Migration Threads option displays only if you have a Content StorageServices license and the license is enabled on the Content Server.

• The number of internal sessions is limited to the Maximum Content MigrationThreads value set in the server configuration object (dm_server_config), up to amaximum of 128.

MIGRATE_CONTENT lets you move files from a file store, EMC Centera store, NetAppSnapLock store, blob store, or distributed store. You can move the files to a file store,EMC Centera store, NetApp SnapLock store, or distributed store. You cannot move filesto a blob store, and migration to and from external stores or XML stores is not supported.A file in a retention-enabled storage area can only be moved to another retention-enabledstorage area. There are no restrictions on moving files out of a EMC Centera store orNetApp SnapLock store storage area that is not retention-enabled. If you move a fileto a distributed storage area, the file is placed in the distributed component local to theContent Server to which you are connected when executing the method.

If you move a file that has a retention policy to an EMC Centera or NetApp SnapLockstorage area, the retention set on the object is calculated from the retention policy even ifthe default retention for the storage area is further in the future. If there are multipleretention policies on the object, the method sets the retention on the file based on thepolicy with the retention date furthest in the future.

MIGRATE_CONTENT also generates an auditable event called dm_move_content.When the event is audited, an audit trail entry is created for each content file that ismoved by the method.

You can execute a MIGRATE_CONTENT method against an active storage directory. Itis not necessary to set the storage area’s state to read only to run the method.

For complete information about using this administration method, refer to the ContentServer DQL Reference Manual. You can execute the method using DocumentumAdministrator or DQL or DFC. You must be a Superuser to execute this method against acontent object. To execute the method against the content of a SysObject or SysObjectsubtype, you must have Write permission on the object.

Note: If you are moving content from an unencrypted, uncompressed file store storagearea to an EMC Centera store, you may wish to configure the storage area to use thememory-mapped interface. For more information, refer to Configuring use of a memorymap for write operations, page 254.

Content migration policies

Content migration policies are jobs that automate moving content between storageareas. You can use them to move content from file stores, EMC Centera stores, NetAppSnapLock store, blob stores, and distributed stores to file stores, EMC Centera stores,


Content Management

NetApp SnapLock stores, and distributed stores. Moving content to a blob store is notsupported.

Note: You must have installed Content Server with a Content Storage Services license touse content migration policies.

The policies are implemented using a job named dm_MoveContent that is installedwith Content Server. The dm_MoveContent job uses the MIGRATE_CONTENTadministration method to move content files from one storage area to another. The jobselects the content to be moved based on criteria you define when you configure the job.You can select the content based on content size, format, and date. You can also specify aDQL predicate to select the content. The restrictions discussed in MIGRATE_CONTENTadministration method, page 259, on moving content files from retention-enabled EMCCentera or NetApp SnapLock storage areas apply to content migration policies.

In addition to configuring the default job, you can create additional content migrationjobs. Content migration jobs are created and configured using DocumentumAdministrator. Use the Migration Policies node.

Note: You must have installed Content Server with a Content Storage Services licenseto configure the job or create additional content migration jobs. If you do not have aContent Storage Services license, Documentum Administrator does not display theMigration Policies node nor migration jobs in the list of jobs.

Congurable arguments

When you configure a content migration job, you can configure the job to query againstcontent objects or instances of SysObjects or SysObject subtypes. If the job runs againstSysObjects or a subtype, you can specify whether you want to move primary content,renditions of the primary content, or both. However, note that if a SysObject hasmultiple primary content pages, only the first primary content (page 0) or its renditionsor both are moved.

Additionally, you can specify:• The storage area to move the selected content files from, which can be a file store,

EMC Centera store, NetApp SnapLock store, distributed store, or blob store• The target storage area, which can be a file store, an EMC Centera store, NetApp

SnapLock store, or a distributed store storage area

If the target is a distributed store storage area, the file is placed in the distributedcomponent local to the Content Server to which the job is connected when executingthe method.

• The selection criteria for the content to be moved• How many content files you want to move in one execution• The maximum number of files to move in one execution


Content Management

• Optionally, the number of internal sessions to use to execute the method

The number of internal sessions is limited to the Maximum Content MigrationThreads value set in the server configuration object (dm_server_config), up to amaximum of 128.

For detailed information about configuring this job, refer to the DocumentumAdministrator online help or to the Documentum Administrator User Guide.

Note: By default, the job removes the migrated content files from the source storagearea. This is not a configurable parameter when you migrate content files using the job.Unless the content file is referenced by multiple content objects, the file is removed fromthe source storage area.

Generated log les

A content migration job generates a log file, like other system-defined jobs, that is storedin /dba/log/repository_id/sysadmin.

Records migration jobs

Records migration jobs are an alternate way to move a large number of content files ifyou do not want to execute MIGRATE_CONTENT manually or if you do not have aContent Storage Services license. Like storage management jobs, records migration jobsare a way to automate storage management rules. For example, you could use a recordsmigration job if you want to move all documents in an lifecycle state called obsolete toan archival storage area.

The target storage area can be another file store storage area or a secondary storagemedium, such as an optical juke box or a tape. If the target storage area is secondarystorage, the storage must be defined in the repository as a storage area. That is, it mustbe represented in the repository by some type of storage object.

When you define the records migration job, you can define parameters for selectingthe files that are moved. For example, you might want to move all documents thatcarry a particular version label or all documents created before a particular date. Allthe parameters you define are AND’ed together to build the query that selects thecontent files to move. Queries for records migration jobs operate on SysObjects only.Additionally, you cannot audit content moved using a records migration job.

When a records migration job runs, it generates a report that lists the criteria selectedfor the job, the query built from the criteria, and the files selected for moving. You canexecute the job in report-only mode, so that the report is created but the files are not


Content Management

actually moved. The report can be viewed through Documentum Administrator. Forinstructions, refer to Reports and trace log files, page 451.

Use Documentum Administrator to create Records migration jobs. You must haveSuperuser privileges to do so.

Auditing content movement

Executing a MIGRATE_CONTENT administration method generates adm_move_content event.

The dm_move_content event is not audited by default. To start auditing this event,you must explictly register to audit the event. You can register to audit the event for aparticular content object (representing one content file) or a SysObject, or the object types(dmr_content and dm_sysobject). The methods that register events for auditing arefound in the IDfAuditTrailManager interface.

If you audit the event for a content object, an audit trail entry for the event is createdwhenever MIGRATE_CONTENT is used to move the content file represented by thecontent object, regardless of whether the content is referenced in MIGRATE_CONTENTdirectly, by the content object ID, or indirectly, through the containing SysObject. If youaudit the event for a SysObject, an audit trail entry for the event is generated wheneverany content file contained by the SysObject is moved using MIGRATE_CONTENT,regardless whether the administration method references the content directly orindirectly.

Maintenance operations for storage areasThis section contains information and instructions to maintain storage areas. Somemaintenance operations, such as Moving file store storage areas, page 264, typically arenot necessary very often. Others, such as Removing orphaned content objects and files,page 266, should be performed on a regular basis.

Changing the state of a storage area

A storage area can have one of three states:• Online: Users can store files and copy files out when needed.


Content Management

• Offline: Users cannot save content in the area or retrieve content from the area. It issometimes necessary to put storage areas offline. For example, if you want to movea storage area, you must first put the area offline. Or an event such as a hardwareproblem can require you to put a storage area offline.

• Read only: Users can view the content in that area, but if they change a file, thechanged file must be stored in a different storage area.

Use Documentum Administrator to change a storage area’s state. You can also change thestate by executing the SET_STORAGE_STATE administration method. You can executethe administration method using a DQL EXECUTE statement or an IDfSession.apply()method. If you want to execute the method directly, refer to the Content Server DQLReference Manual for information about the arguments.

Determining the state of a storage area

You can check the status of a storage area to determine whether it is online or offlinethrough the Storage management pages in Documentum Administrator. Alternatively,you can query the r_status property directly. Use the following syntax to query the status:SELECT "r_status", "r_object_id" FROM "dm_store"WHERE "name" = 'storage_area_name'

Moving le store storage areas

You can move an entire file store storage area. For example, to reorganize your hardware,you may need to move a storage area to a different disk.

Use the following procedure to move a file store storage area. The procedure describeshow to move an entire storage area. It does not describe how to move individual filesfrom one storage area to another.

To move a le store storage area:1. Log in to the repository.

2. Set the storage area offline.EXECUTE set_storage_stateWITH store = 'filestore_name', offline = TRUE

3. Copy the files in the storage area to the new location.On Windows:c:>copy /s /e source_directory target_directory

On UNIX:


Content Management

% cp -r -p source_directory target_directory

where source_directory is the top-level directory in the current storage area andtarget_directory is the new directory for the storage area. If the target directory doesnot already exist when this command is issued, the command creates it and copiesthe files and subdirectories into it from the source directory.If the target directory does exist when this command is issued, the command copiesthe source directory (and all files and subdirectories) into the target directory as asubdirectory.

4. Set the file_system_path property of the dm_location object associated with the filestore object to point to the new directory for the storage area.UPDATE "dm_location" OBJECTSET "file_system_path" = new_directory_pathWHERE "object_name" = location_object_name

Note: In a file store object, the root property contains the object name of the locationobject associated with the storage area.

5. Reinitialize the server and make the change visible.

6. Put the storage area back online:EXECUTE set_storage_stateWITH store = 'filestore_name', offline = FALSE

You may remove the old storage area if you have no problems retrieving the contentsof documents from the new storage area.

Enabling forced deletion in EMC Centera storage areas

Forced deletion allows a user to delete a document whose retention period is unexpired.If the content is stored in an EMC Centera storage area, the user performing the forceddelete must connect through Documentum Administrator using a Centera profile thatgrants the privileged delete permission. Content Server Fundamentals has a completedescription of forced deletions.

To allow a user with the appropriate repository privileges to perform a forced delete on aCentera host, the profile must be available to the Content Server. The server sends theprofile to the Centera host when making the connection for the user. There are twoways to make the profile available for use:• You can include the full path to the profile file in the connection string specified in

a_storage_params property of the ca store object.

Instructions for setting the connection string in a_storage_params are found inDefining the connection string , page 248.


Content Management

• You can store the profile file in DOCUMENTUM/dba/config/repository_name/storage_object_name_centera_profile.pea

where repository_name is the name of the repository and storage_object_name is theobject name of the ca store object.

For example, if the repository is named MyTest and the ca store object is namedMyCAStore, create a profile for the appropriate Centera storage system and copy itto $DOCUMENTUM/dba/config/MyTest/MyCAStore_center_profile.pea.

Removing orphaned content objects and les

As users work with a repository, they delete unneeded documents or objects. Becausedestroying a document or other SysObject does not destroy any content files or contentobjects associated with that document, you should remove the orphaned files andcontent objects on a regular basis.

An orphaned content object is a content object that is not referenced by any SysObject.SysObjects have a property called i_contents_id that contains the object ID of the contentobject representing their content. An orphaned content file is a content file that has noassociated content object.

Documentum provides two automated system administration tools for this purpose.These tools automate two utilities:• dmclean• dmfilescanThe dmclean utility scans a repository and finds all orphaned content objects and,optionally, orphaned content files. It generates a script that you can run to remove theseobjects and files from the repository.

The dmfilescan utility scans a specified storage area (or all storage areas) and findsall orphaned content files. It generates a script that you can run to remove these filesfrom the storage area.

Use dmfilescan as a backup to dmclean. Use dmclean regularly, to clean up both contentobjects and files. The dmclean utility has better performance.

For information about using the tools, refer to Chapter 11, Administration Tools. Thissection describes how to use the utilities manually.

There are multiple options for executing the dmclean and dmfilescan utilities:• Documentum Administrator• System administration tools• DQL EXECUTE statement• An IDfSession.apply() method


Content Management

• From the operating system promptExecuting either utility through EXECUTE, apply, or the operating system prompt is atwo-step process. First, you execute the utility to generate a script, and then you run thescript to perform the actual operations. Executing the operation in two parts allows youto check which objects and files will be deleted before the work is actually performed.The scripts are in a format that you can read easily.

You must have Superuser or Sysadmin user privileges to execute these utilities.

Using dmclean

You can execute dmclean using Documentum Administrator, the DQL EXECUTEstatement, an apply method, or from the operating system prompt. The syntax variesslightly, depending on how you choose to execute the utility.

By default, dmclean operates on content objects representing content stored in any typeof storage area except external storage, EMC Centera storage, and NetApp SnapLockstorage. It also removes the associated content files from the storage areas. Youcan include an argument on the command line to include orphaned content objectsrepresenting files in EMC Centera and NetApp SnapLock storage in its processing. Ifyou include that argument, how it handles the associated orphaned content depends onthe retention requirements set for the storage area and the particular content. Includingcontent in retention type storage areas, page 268, describes the behavior in detail.

Additionally, dmclean also removes orphaned notes (annotations), internal ACLs, andSendToDistribution workflow templates by default. However, if you want it to removeaborted workflows (and the runtime objects associated with the workflow), you mustinclude the -clean_aborted_wf argument. dmclean does not remove aborted workflowsby default.

Table 21, page 267, lists the arguments that you can include to change the defaults.

Table 21. dmclean arguments


-no_note Directs the utility not to remove annotations.

-no_acl Directs the utility not to remove orphaned ACLs.

-no_content Directs the utility not to remove orphaned contentobjects and files.

-no_wf_templates Directs the utility not to remove orphanedSendToDistribution templates.


Content Management


-include_ca_store Directs the utility to include orphaned content objectsrepresenting files stored in EMC Centera or NetAppSnapLock storage.

Note: This argument is not supported when dmcleanis run through Documentum Administrator.

-clean_aborted_wf Directs the utility to remove aborted dm_workflowsand all related runtime objects.

-clean_deleted_lwso Directs the utility to remove deleted lightweightSysObjects and their parents.

If you need syntax help, enter the name of the utility with the -h argument at theoperating system prompt.

The executable that runs dmclean is launched by a method that is created when youinstall Content Server. By default, the dmclean executable is assumed to be in thesame directory as the Content Server executable. If you moved the server executable,modify the method_verb property of the method that launches dmclean to use a fullpath specification to reference the executable. You must be in the %DM_HOME%\bin($DM_HOME/bin) directory when you launch the dmclean executable.

Including content in retention type storage areas

The dmclean utility does not operate on content stored in EMC Centera or NetAppSnapLock storage areas by default. If you want to remove orphaned content files fromthese retention type storage areas, and their associated content objects, you must use the-include_ca_store argument in the utility’s command line.

When you include that argument, the utility includes all orphaned content objects whosestorage_id identifies a retention type storage area. Removing the content object andcontent file fails if the storage system does not allow deletions or if the content’s retentionperiod has not expired.

Note: To find and remove the repository objects that have expired content, usethe RemoveExpiredRetnObjects administration tool. Then use dmclean with the-include_ca_store argument to remove the resulting orphaned content files and contentobjects. Refer to Remove expired retention objects, page 506, for information aboutthe administration tool.

Running dmclean using an EXECUTE statement

To run dmclean using the EXECUTE statement, use the following syntax:


Content Management

EXECUTE do_methodWITH method = 'dmclean',arguments = 'list of constraining arguments'

Dmclean can remove a variety of objects in addition to content files and content objects.These objects include orphaned annotations (note objects), orphaned ACLs, and unusedSendToDistributed workflow templates. These objects are removed automatically unlessyou include an argument that constrains the utility not to remove them. For example,including -no_note and -no_acl arguments directs dmclean not to remove orphanedannotations and unused ACLs. If you include multiple constraints in the argumentlist, use a space as a separator.

The utility automatically saves the output to a document that is stored in the Tempcabinet. The utility ignores the DO_METHOD’s SAVE argument. The output is saved toa file even if this argument is set to FALSE. The output is a generated IAPI script thatincludes the informational messages generated by the utility.

Running dmclean from the operating system prompt

To run dmclean from the operating system prompt, use the following syntax:dmclean -docbase_name name -init_file init_file_name [listof constraining arguments]

As dmclean is executing, it sends its output to standard output. To save the output(the generated script) to a file, redirect the standard output to a file in the commandline when you execute dmclean.

name is the name of the repository against which to run the utility. init_file_name is thename of the server.ini file for the repository’s server. These two arguments are required.Refer to Chapter 3, Servers, for information about the server start-up file.

Dmclean can remove a variety of objects in addition to content files and content objects.These objects include orphaned annotations (note objects), orphaned ACLs, and unusedSendToDistributed workflow templates. These objects are removed automatically unlessyou include an argument that constrains the utility not to remove them. For example,including -no_note and -no_acl arguments directs dmclean not to remove orphanedannotations and unused ACLs. If you include multiple constraints in the argumentlist, use a space as a separator.

Executing the dmclean script

Executing dmclean as a job with the -clean_now argument set to FALSE, using theEXECUTE statement, an apply method, or from the operating system prompt, generatesa script. To actually perform the cleaning operations, you must execute the script usingthe IAPI utility.


Content Management

Using dmlescan

Use dmfilescan utility to find orphaned content files—content files that have noassociated content object. By default, the utility looks for all orphaned files that areolder than one week. Executing the utility generates a script that contains commands toremove the orphaned files found by the utility. The utility does not actually remove thefiles itself. After the utility completes, you must run the script to actually remove the files.

The utility scans one storage area or all storage areas, searching some or all of the area’ssubdirectories to find the content files that do not have associated content objects. Theutility ignores content files that have a content object. Even if the content object is anorphaned content object (not referenced by any SysObjects), dmfilescan ignores thecontent file if it has a content object in the repository.

Use dmfilescan as a backup to dmclean. You can execute dmfilescan using DocumentumAdministrator, the DQL EXECUTE statement, an IDfSession.apply() method, or fromthe operating system prompt. On Windows, the utility generates a batch file (a .batscript). On UNIX, the utility generates a Bourne shell script. The executing syntax andthe destination of the output vary, depending on how you choose to execute the utility.

If you need syntax help, enter the name of the utility with the -h argument at theoperating system prompt.

The executable that runs dmfilescan is launched by a method that is created when youinstall Content Server. By default, the dmfilescan executable is assumed to be in thesame directory as the Content Server executable. If you moved the server executable,modify the method_verb property of the method that launches dmfilescan to use a fullpath specification to reference the executable. You must be in the %DM_HOME%\bin($DM_HOME/bin) directory when you launch the dmfilescan executable.

dmlescan arguments

Table 22, page 270, lists the arguments to the dmfilescan utility.

Table 22. Arguments to the dmlescan utility

Argument Meaning

-s storage_area_name The name of the storage object thatrepresents the storage area you arecleaning up. If you do not specify thisargument, the utility operates on allstorage areas in the repository that are notdefined as far for the server.


Content Management

Argument Meaning

-from directory1 Subdirectory in the storage area at whichto begin scanning

-to directory2 Subdirectory in the storage area at whichto end scanning

-force_delete Boolean Controls whether the utility deletesorphaned files that are younger than 24hours. The default is F, meaning do notdelete files younger than 24 hours or less.

-no_index_creation Boolean Controls whether dmfilescancreates and destroys the indexeson dmr_content.data_ticket anddmr_content.other ticket or assumes theyexist.

T (TRUE) means that the utility assumesthat the indexes exist prior to the start ofthe utility. F (FALSE) means the utilitywill create these indexes on startup anddestroy them at the finish. The defaultis F.

Refer to Using the -no_index_creationargument, page 272 for details of use.

-grace_period integer Defines the grace period for allowingorphaned content files to remain inthe repository. The default is 1 week,expresssed as hours. Dmfilescan removesorphaned files whose age exceeds 1 weekor the value defined in the -grace_periodargument.

The integer value for this argument isinterpreted as hours.

Identifying the subdirectories of the scanned storage areas

The -from and -to arguments identify the storage area subdirectories you want to scan.The values for these arguments are the hexadecimal representations of the repository IDsused to identify subdirectories of a storage area.


Content Management

The top-level directory of a file store storage area is divided into subdirectories foreach repository in the installation. All content files from a particular repository storedin that storage area are stored in sudirectories under the directory named for therepository. For example, suppose the storage area is d:\documentum\data\storage_1(/u12/dmadmin/data/storage_1) and the repository ID is 000023e5. Any contentfiles from repository 000023e5 stored in storage_1 are stored in subdirectories ofd:\documentum\data\storage_1\000023e5 (/u12/dmadmin/data/storage_1/000023e5)

The values for the -from and -to arguments are the hexadecimal representations of therepository IDs that name the subdirectories. The utility scans all directories that fallnumerically between the directories you specify in the -from and -to arguments.

If you include only the -from argument, the utility starts at the specified directory andscans all the directories below it. If you include only the -to argument, the utility starts atthe top directory and scans down to that directory. If neither are specified, the utilityscans all subdirectories of the repository subdirectory. For a detailed explanation ofsubdirectory numbering, refer to Path specifications for content in file stores, page 233.

Using the -no_index_creation argument

The dmfilescan utility uses two indexes in its processing. These are indexes ondmr_content_s.data_ticket and dmr_content_s.other_ticket. By default, the utility createsthe indexes when it starts and destroys them when it completes executing. However, insome circumstances, dmfilescan cannot obtain enough database resources to create theresources. If the utility cannot create the indexes, the utility fails with an error. This canoccur in very busy or very large environments.

To avoid this issue, you can create the indexes manually and run the utility with the-no_index_creation argument set to T (TRUE). Use MAKE_INDEX to create the indexes.

Using the -force_delete argument

By default, the utility scans only for orphaned files that are over 24 hours old. To removecontent files that are younger than 24 hours, set the -force_delete argument to T (TRUE).This argument is F (FALSE) by default. Setting this argument to T is only recommendedif you must run dmfilescan to clear disk space. You can also use it to remove a dumpfile if a load operation fails and leaves behind the temporary dump file in the targetrepository directory. However, do not run dmfilescan with -force_delete set to T whenthere are any other processes or sessions creating objects in the repository.


Content Management

Running dmlescan using an EXECUTE statement

To run dmfilescan using the EXECUTE statement, use the following syntax:EXECUTE do_method WITH method = 'dmfilescan',[arguments = '[-s storage_area_name] [,-from directory1][,-to directory2]']

The utility automatically saves the output to a document that is stored in the Tempcabinet. (The utility ignores the DO_METHOD’s SAVE argument. The output is saved toa file even if this argument is set to FALSE.) The output is a generated script that includesthe informational messages generated by the utility.

Running dmlescan from the operating system prompt

To run the utility from the operating system, use the following syntax:dmfilescan -docbase_name name -init_file init_file_name[-s storage_area_name][-from directory1][-to directory2]

As dmfilescan executes, it sends its output to standard output. If you want to save theoutput, which is the generated script, to a file, you must redirect the standard outputto a file on the command line when you run the utility.

The two arguments, -docbase_name and -init_file, are required. The name is the nameof the repository that contains the storage area or areas you are cleaning up. Theinit_file_name is the name of Content Server’s server.ini file. This is one of the server startup files. (For more information about these, refer to Chapter 3, Servers.)

The generated script

Executing dmfilescan generates a script. The script comprises a series of removecommands that remove orphaned files found by the utility. For each file, the script listsits data ticket and storage ID. The script also contains a template DQL SELECT statementthat you can use in conjunction with the data ticket and storage ID values to check thefindings of the utility. Here is a sample of the script (generated on a Windows host):rem Documentum, Inc.remrem This script is generated by dmfilescan for later verificationrem and/or clean-up. This script is in trace mode by default. Torem turn off trace mode, remove '-x' in the first line.remrem To see if there are any content objects referencing a this filerem listed below, use the following query in IDQL:remrem c:> idql <docbase> -U<user> -P<pwd>rem 1> select r_object_id from dmr_contentrem 2> where storage_id = '<storage_id>' and data_ticket =


Content Management

<data_ticket>rem 3> goremrem If there are no rows returned, then this is an orphan file.remrem storage_id = '280003c980000100' and data_ticket = -2147482481del \dm\dmadmin\data\testora\content_storage_01\000003c9\80\00\04\8frem storage_id = '280003c980000100' and data_ticket = -2147482421del \dm\dmadmin\data\testora\content_storage_01\000003c9\80\00\04\cbrem storage_id = '280003c980000100' and data_ticket = -2147482211del \dm\dmadmin\data\testora\content_storage_01\000003c9\80\00\05\9d. . .

Executing the dmlescan script

Run the dmfilescan script from the operating system prompt.

On Windows:c:> script_file_name

On UNIX:% script_file_name

You may have to give yourself permission to execute this file. On Windows, do so usingFile Manager to add appropriate permission to your user account. On UNIX, use thefollowing command:% chmod ugo+x script_file_name

Replacing a full distributed storage component

Use this procedure to replace a distributed store component whose disk space hasfilled up.

To replace a distributed store component:1. Set the component storage area that resides on the full disk to the read only state.

You can use Documentum Administrator to set the component to read only, or youcan execute the following DQL statement:EXECUTE SET_STORAGE_STATE WITH STORE = 'component_name',READONLY=true

2. Connect to the server site with the full disk and create a new file store storage areaon a disk that has space available.

3. Add the new file store storage area as a component to the existing distributedstorage area in the repository.


Content Management

4. Add the new component to the list of far storage areas in the server config objects forall the servers in the repository except the server that is local to the component.

5. Reinitialize all the server config objects.

Resolving a compromised le store key

A file store key is the encryption key used to encrypt the content files in an encrypted filestore storage area. Each encrypted file store storage area has its own file store key.

If the file store key for a particular encrypted storage area is compromised, use thefollowing procedure to resolve the situation.

To resolve a compromised le store key:1. Create a new encrypted storage area.

2. Migrate the content from the compromised encrypted file store storage area to thenew encrypted storage area.Use the MIGRATE_CONTENT administration method to move the content.

3. Delete the compromised storage area.

Administering content assignment policiesThis section contains information about managing the features provided with ContentStorage Services, a separately licensed feature of Content Server. For information aboutthis feature, refer to Using content assignment policies, page 225.

Logging policy use

If you want to track the use of content assignment policies, you can turn on logging forpolicies. The logging feature is turned on at the DFC level. When it is turned on, thepolicy engine records a message each time a policy is applied. Here is an example ofthe logged message:20:26:15,991 INFO[Thread-5]com.documentum.fc.client.DfDocument- Using assignment policy "Content Assignment Policy 5" forcontent at page 0 in crtext format belonging to objectDocument 5.

20:26:15,991 INFO [Thread-5]com.documentum.fc.client.storagepolicy.DfStorageRuleEvaluator_objectID_13 -


Content Management

Storage rule used to determine store is :contentInfo.getContentSize()< 5 && contentInfo.getContentFormat().equals("crtext")-->strgpoltst_o2.

To turn on the logging messages, increase the logging level in the log4j.properties file inthe DFC installation. Modify the first line in the file to read:log4j.rootCategory=INFO,A1,F1

The generated log file is named log4j.log and is stored in the installation’s logs directory.Typically, this is C:\Documentum\logs\log4j.log.

Enabling and disabling assignment policies

When you create a content assignment policy, you must explicitly activate the policy.Whether or not a policy is active is controlled by the is_activated property in thedm_ssa_policy object. Use Documentum Administrator to set that property.

If an individual policy is inactive, the policy engine behaves as if no policy exists for theobject types that use that policy. When an object with an inactivated policy is savedwith new content, the policy engine traverses the object’s type tree to find a policyfor the object. If it cannot find a policy or no policy rules apply, the default storagealgorithm is used.

Turning off the policy engine

The policy engine is turned on by default. Turning it off disables the use of contentassignment policies for applications that use that particular DFC installation. To turnoff the policy engine for a particular DFC installation, add the following line to thedfc.properties file:dfc.storagepolicy.enable=false

All DFC-based applications that use that dfc.properties file are affected.

Conguring behavior on encountering a rule error

Each assignment policy defines one or more rules for content storage. At runtime, if thepolicy engine encounters an error in a rule, for example, because of a bad property name,by default, the policy engine returns an error, and the save operation fails. You canchange this behavior by setting the following dfc.properties key to T:dfc.storagepolicy.ignore_rule_errors=T


Content Management

The key is F (FALSE) by default. If set to T (TRUE), when the policy engine encountersan error in a rule, the policy engine ignores the faulty rule and continues by evaluatingthe next rule in the policy.

Conguring the update interval for the policyinformation cache

DFC maintains a cache of assignment policy information. The cache is updatedat intervals defined by the dfc.storagepolicy.validation_interval property in thedfc.properties file. The default interval is 30 seconds. You can reset the interval.

If you increase the interval, then it takes longer for policy changes to be recognized bythe policy engine. If you decrease the interval, changes may be available for use soonerbut performance may be degraded.

Archiving and restoring documentsAs repositories grow and age, you typically archive older or infrequently accesseddocuments to free up disk space for newer or more frequently used documents.There will also be occasions when you want to restore an archived document.Documentum provides a mechanism for archiving and restoring documents using theIDfSession.archive and IDfSession.restore methods and the Archive administration tool.

Note: If you want to archive fixed data such as email or check images that will notbe changed and must be retained for a fixed period, use the EMC Centera or NetAppSnapLock storage option, rather than the archiving capabilities described in this section.The EMC Centera or NetApp SnapLock storage option is capable of storing massiveamounts of data with a defined retention period. For information about this option,refer to EMC Centera storage, page 212.

How the process works

Five major components are involved in archive and restore functionality:• The client requesting the operation• The repository operator’s inbox, where the requests are queued• The Archive tool, which performs the actual operations• The archive directory, a staging area for the dump files created by the archiving

operations and read by the restoring operation


Content Management

• The offline storage area, where archived files are moved for permanent storage

When you archive a document, these components interact as follows:1. The client sends an archive request.

The client can be a user selecting a custom menu item requesting archiving (whichissues an IDfSession.archive method) or an application issuing an archive method.

2. The archive method queues a DM_ARCHIVE event in the repository operator’sinbox.

3. The Archive tool reads the DM_ARCHIVE event in the inbox and performs thearchiving operation.When the tool is finished, it sends a completion message to the user requesting theoperation and to the repository operator.

4. A user-defined DO_METHOD procedure moves the file from the archive directoryto permanent, offline storage.

When you restore a document, these components interact as follows:1. The client sends a restore request.

The client can be a user trying to open an archived document using a Documentumclient or an application issuing the restore method.

2. An IDfSession.restore method queues a DM_RESTORE event to the repositoryoperator’s inbox.

3. The Archive tool reads the DM_RESTORE event in the inbox.

4. If necessary the server calls a DO_METHOD function that moves the dump filecontaining the archived file back into the archive directory.

5. After the file is back in the archive directory, the Archive tool performs the restoreoperation.When the tool is finished, it sends a completion message to the user requesting theoperation and to the repository operator.Figure 8, page 279, illustrates the archive and restore mechanism. The followingsections describe the process in more detail.


Content Management

Figure 8. The archive and restore process


Content Management

The archive and restore methods

Executing an IDfSession.archive method queues a DM_ARCHIVE event in the inboxof the repository operator, and executing a IDfSession.restore method queues aDM_RESTORE event in the operator’s inbox. The repository operator is a repositoryuser, real or virtual, who is designated to receive all archive and restore requests. TheArchive tool, which processes these requests, polls this user’s inbox.

For information about the syntax of archive and restore, refer to the Javadocs.

Note: When you issue an archive or restore method, do not include the keyword (ALL)with the type name in the predicate. The dmarchive utility called by the Archive toolautomatically adds (ALL) to the type name. If you include (ALL) also, the utility failswith a syntax error when it tries to execute the query derived from the predicate.

The return value for both methods is the object ID of the queue item object that representsthe queued event.

The Archive tool

The Archive tool reads the queue in the operator’s inbox and archives or restores therequested documents. Refer to Options for archiving , page 283, for more informationabout this tool.

Archiving

Each time the Archive tool reads the operator’s inbox, it gathers the archiving requestsand performs a single dump operation. The resulting dump file contains all documentsthat had an outstanding archive request.

For each document, the Archive tool:• Dumps the document and any content files• Removes the content from the storage area• Sets the document’s a_archive property to TRUE• Sets three properties of the content’s content object:

— is_offline and is_archived are set to TRUE.

— set_file is set to the full path of the dump file in the archive directory.• Sends a message to the user who requested the archive indicating completionThe document object itself is not removed from the repository. Only its content isremoved from the storage area. However, if a user tries to open the document, the userreceives a message that the document is archived and inaccessible.


Content Management

To perform the dump, the Archive tool generates a dump record object, using theinformation supplied in the outstanding archive requests. For example, suppose theArchive tool found the following outstanding archive request:archive,c,dm_document where owner_name = 'carolinew'

This generates the following DQL statement to create the dump record object:create dm_dump_record objectset file_name = 'ARCHIVE_DIR\filename',set include_content = true,append type = dm_document,append predicate = (owner_name='carolinew' andr_lock_owner=' ') and a_archive=0,append type = dmr_content,append predicate =any parent_id_i in(select r_object_id_i from dm_document (all)where (owner_name='carolinew') and r_lock_owner=' ') andis_archived = 0)

Note: file_name is shown in Windows format. On UNIX, it would beARCHIVE_DIR/filename.

Including a_archive=0 in the qualification ensures that previously archived documentsare not archived again.

The dump file’s file name is assigned to the set_file property of the content objectsrepresenting the contents of the archived documents. The file name is generatedautomatically from the object ID of the dump record object and has the following format:ARCHIVE_DIR/dump_record_object_ID

where ARCHIVE_DIR is the path specification of the archive directory.

When the archive operation is finished, the Archive tool queues a notification to theuser who requested the archive and the repository operator. The Task Name for thisnotification is event and the Event value is dm_archive_done.

Because a queue method requires that an actual object be queued, the Archive tool createsa SysObject named dmarchive_action_complete that is queued with the notification.

The verbose argument on the Archive tool command line directs the tool to print tracemessages. Trace messages are messages issued by the Archive tool as it is executing. Ifyou want this functionality, append the verbose argument to the end of the Archivetool command line. For example:dmarchive docbase_name [-Uusername] -Ppassword-archive_dir directory -verbose

Restoring

Restoring a document loads the document’s content from the dump file back into therepository, into its original storage area, and sets the is_offline property of the content


Content Management

object to FALSE. It does not reset the content object’s a_archive or set_file properties,because although the document has been restored, it also still remains in the archive file.

Before the Archive tool can restore a document, the dump file that contains the documentmust be present in the archive directory.

The Archive tool creates a load record object to satisfy a restore request. When the loadrecord object is saved, the requested content is loaded back into the original storage areafrom the dump file. If there are multiple restore requests, the Archive tool groups themas much as possible, to reduce the number of necessary load operations.

For example, suppose the Archive tool finds the following restore request:restore,c,dm_document where owner_name = 'carolinew'

The tool generates the following DQL statement to create the necessary load recordobject:create dm_load_record objectset file_name = 'dump_file_name',append type = dmr_content,append predicate = any parent_id_i in(select r_object_id_i from dm_document (all)where owner_name = 'carolinew')and is_archived = 1 and is_offline = 1and set_file = '%dump_file_name'

When the restore operation is finished, the tool queues a notification to the user whorequested the restore and the repository operator. The Task Name for this notification isevent and the Event value is dm_restore_done.

Because the queue method requires that an actual object be queued, the Archivetool creates a SysObject named dmarchive_action_complete that is queued with thenotification.

Moving dump les on and off line

The archive directory is intended as a staging area. The Archive tool puts dump filesgenerated by archive requests in this directory and reads dump files in this directorywhen processing restore requests. The archive directory is not usually a permanentstorage area for these dump files. The dump files are generally moved to offline storage,such as a tape or optical storage device, and moved back to the archive directory onlyif they are needed for a restore request.

Documentum provides three DO_METHOD procedures to move files out of and intothe archive directory. Each procedure is a script that contains comments about itsuse and an example command that is commented out. To use these scripts, edit theprocedures. The scripts are located in %DOCUMENTUM%\product\version\bin($DOCUMENTUM/product/version/bin). Copy the scripts to %DOCUMENTUM%\dba


Content Management

($DOCUMENTUM/dba) and edit the versions in this directory. That way, you willnot lose any script customizations if you upgrade your server. The scripts exit witha return value of 0.

The procedures are:• post_archive

The post_archive procedure moves a dump file to offline storage. The procedureaccepts the dump file name as an argument.

• pre_restore

The pre_restore procedure moves a dump file from off-line storage back to thearchive directory. The procedure accepts the dump file name as an argument.

• post_restore

The post_restore procedure removes a dump file from the archive directory. Use thisprocedure only if a copy of the dump file remains in off-line storage.

Archiving content used in multiple documents

If you archive a document that contains a content file that appears in additionaldocuments, the Archive tool does not actually move the content file offline unless all thedocuments containing that content are archived.

Options for archiving

Because the Archive tool is configurable, you have several options about how toimplement archiving at your site.

Be careful of creating extremely large archive files. Each time the utility checks the inboxand archives, it puts all the documents it is archiving in one dump file. This meansyou must move the entire dump file back to the archive directory to restore a singledocument in the file. If the files are extremely large, this can be a significant performancehit for restore operations.

Scheduling archiving

You can change the schedule for the Archive tool and run the tool on demand. Refer toScheduling jobs, page 150, and Running administration jobs on demand, page 454, formore information.


Content Management

Shortening the run interval may give you a faster response time for requests. However,the archive tool works more efficiently when operations can be executed in groups—thatis, when it can operate with as few dumps and loads as possible.

Note: The clock for the polling interval starts when the utility completes all theoperations requested.

Types of requests

The Archive tool can be configured to process:• A specific event• Archive events only• Restore events onlyYou can start two instances of the tool and separate the archive and restore operations.

The repository operator

When you set up archiving, decide who to designate as the repository operator. Therepository operator is the user whose inbox receives all archive and restore requests. Thisis where the Archive tool looks for unprocessed archive and restore requests.

Your repository operator may or may not be a real person. You may find it more practicalto create a virtual user—a user who exists only within the repository. This gives you aninbox dedicated to archive and restore requests. This is a good choice if you want to keepan audit trail of archive and restore activity.

If a repository operator is not explicitly named on the Archive tool command line or inthe archive or restore method, the server assumes the operator is the user named in theoperator_name property of its server config object. By default, this property is set tothe repository owner. Documentum users with Sysadmin or Superuser privileges canchange this property. Use Documentum Administrator to change the property. Youmust reinitialize the server after changing the property.

Moving the dump le in and out of the archive directory

Although you can use the post_archive and pre_restore procedures to move files in andout of the archive directory, you can also use an alternative automatic archiving product.For example, if the archive directory is on a NetStor device, NetStor manager can takecare of moving the files to and from optical storage.


Content Management

Choosing an archive directory

The archive directory is the disk location where the Archive tool places the dump files itcreates when archive requests are processed. It is also the location where the Archivetool expects to find the dump files when it processes restore requests. This location is notexpected to be a permanent storage location for the archive file. (Refer to Moving dumpfiles on and off line , page 282, for more information about using this directory.)

When you archive a document, the tool records the location of the archive directory in theset_file property of the content object that links the document and its content. The set_fileproperty is set to the full path of the dump file that contains the archived document.

During a restore operation, the tool expects to find the dump file in the directoryspecified in the set_file property. Consequently, the disk location that you choose for thearchive directory must be:• Large enough to accommodate all dump files you might reasonably expect to be

there at the same time• Permanent

Implementing archivingTo implement archiving for a repository:1. Choose a location for the archive directory. Create the directory if necessary.

The location should have enough disk space to accommodate all dump files expectedto be there at any given time, and it should be permanent.

2. Choose a user to serve as the repository operator, or create a new virtual user to bethe repository operator.

3. Set the operator_name property of the server’s server config object to the user nameof the user you chose as the repository operator.UPDATE "dm_server_config" OJBECTSET "operator_name" = 'username'WHERE "object_name" = 'server_config_name'

If there are multiple servers running for the repository, be sure to set this propertyfor each server.

4. Identify which requests you want the Archive tool to process.Use Documentum Administrator to modify the arguments of the dm_DMArchivejob to define the requests you want to archive.


Content Management

• To archive a specific event, typequeue_event event_idwhere event_id is the object ID of the queue item object representing the eventin the queue.

• To process only Archive events, type -do_archive_events.• To process only Restore events, type -do_restore_events.

5. To change the window interval for the Archive tool, use DocumentumAdministrator.

6. To use the post_archive, pre_restore, and post_restore programs:

a. Copy the programs from %DM_HOME%\bin ($DM_HOME/bin) to%DOCUMENTUM%\dba ($DOCUMENTUM/dba).

b. Edit the programs, if needed.Appendix C, Archiving scripts, contains the text of these programs. For adescription of their purpose and use, refer to Moving dump files on and offline , page 282.

Starting the Archive tool

The Archive tool is active by default. For more information, refer to Activation, page 453.

Restoring documents

When users attempt to open an archived document in a client application, the applicationprompts them to indicate whether they want to restore the document. If they answeraffirmatively, the client application queues a DM_RESTORE event. When the Archivetool polls the operator’s inbox and finds the event, it will attempt to restore the document.

For a successful restoration, the dump file containing the archived document must bepresent in the archive directory. You can use a pre_restore script to copy the requireddump file back to the archive directory if you have moved it to offline storage. Refer toMoving dump files on and off line , page 282 for information about the pre_restore script.

Archiving restored documents

Restoring an archived document does not remove the copy of the document from thearchive file. It simply copies the document’s content back into the original storage areaand marks the content on line by setting the is_offline property in the content object toFALSE. If the document is archived again, the Archive tool does not actually dump the


Content Management

document again. It resets the is_offline property to TRUE and removes the contentfrom the storage area. The set_file property in the content object still contains the fullpath to the original archive (dump) file.

Custom restoration

If you are not using a Documentum client as your client interface, you can implementautomatic restoration using a custom surrogate get feature. Using surrogate get, you canimplement the same restoration functionality found in the Documentum clients.

The surrogate get feature is implemented with a program you define and is supportedby two properties defined for the storage area types. The user-defined program isrepresented in the repository by a dm_method object. The storage area properties are:• get_method• offline_get_methodThe get_method property contains the name of the method object representing theuser-defined program in the repository.

The offline_get_method property is a Boolean property that indicates whether theprogram actually restores the requested document or only queues a DM_RESTORErequest. You must set it before you execute the user program. Set the value to FALSE ifthe program restores the document and to TRUE if the program queues a DM_RESTOREevent.

When get_method is set for a storage area and a user attempts to access an archiveddocument that was originally stored in that area, the server runs the specified program. Ifoffline_get_method is FALSE, when the program completes, the server assumes that thedocument is now available and will attempt to fetch the document. If offline_get_methodis TRUE, the server assumes that the document is not available when the programcompletes and does not attempt to fetch the document.


Content Management


Chapter 8Users and Groups

This chapter contains information and procedures for administering local users and groups in yourrepositories. The chapter includes the following topics:• User names, page 290• User privilege levels, page 291• Privileged groups, page 294• Adding users, page 295• Granting and revoking user privileges, page 301• Modifying users, page 303• Renaming users, page 304• Deleting users, page 304• Deactivating, locking, and reactivating users, page 305• Adding groups, page 307• Modifying groups, page 309• Deleting groups, page 309• Changing the membership setting of a dynamic group, page 310• Querying groups, page 311Use the procedures in this chapter to create and manage local users and groups. To create and manageglobal users or groups (users and groups common to the repositories in a federation or across allrepositories in the enterprise), use:• The procedures in theContent Server Distributed Configuration Guide, or• The procedures in the LDAP directory server documentation if you have an LDAP directory

server installed and the repositories are set up to use it.


Users and Groups

User namesUser objects represent Documentum users in the repository. User objects have fourproperties that define user names:• user_name

The user_name property holds the user’s Documentum user name. If you are usingDocumentum Administrator to create users, this is the name that you assign in theUser Name field. The user name can be the same as the user_os_name or it can bea different name. If it is different, then it can contain characters such as spaces orapostrophes. For example, Henry VIII or Molly O’Leary are valid Documentum usernames. Documentum assigns the user_name value to the owner_name property fornew objects created by that user. If your user name is Henry VIII, any objects youcreate will be owned by Henry VIII. Every user must have a Documentum user name.

• user_os_name

The user_os_name property is the user’s name on the operating system, if the userhas an operating system account. If the user is an LDAP user or is authenticated withan in-line password, the user_os_name property may be blank.

• user_login_name

The user_login_name property contains user name that Content Server uses toauthenticate the user when he or she connects to a repository. This name is passed tothe authentication mechanism (along with the user’s password) for authenticationwhenever the user starts a repository session. Every Documentum user must have auser_login_name. The default value of the user_login_name is the user_os_name.

• user_db_name

The user_db_name property holds the user’s RDBMS login name. This name isoptional for most users. It is only required if:

— The user is a repository owner.

The server uses the repository owner’s user_db_name property value to makeconnections to the underlying RDBMS.

— The user wants to register tables in the repository.

A user can register any table that the user owns in the underlying RDBMS. Toperform this operation, the user must have a user_db_name.

It is possible for all four properties to have the same value; however. However, if youhave assigned a name with spaces or apostrophes, such as Henry VIII or Jane Doeto user_name, you cannot assign that name to user_os_name, user_login_name, oruser_db_name.

The names in all four properties must be compatible with the code page defined in theserver_os_codepage property of the server config object. This is the code page of the


Users and Groups

operating system of the server host machine. If the repository is part of a multi-repositoryenvironment and the repositories have different values for the server_os_codepage,the names must be ASCII characters only.

User privilege levelsThe user privileges define what administrative operations a user can perform in arepository. This section describes the user privileges that may be assigned to users.Granting and revoking user privileges, page 301, contains information on setting userprivileges.

Basic user privileges

There are six basic levels of user privileges. The basic privileges define the operationsthat users can perform on SysObjects in the repository.Table 23, page 291, lists the basicuser privileges.

Table 23. Basic user privileges

Privilege Description Corresponding IntegerValue

None User has no special privileges 0

Create Type User can create object types 1

Create Cabinet User can create cabinets 2

Create Group User can create groups 4

Sysadmin User can• Create, alter, and drop usersand groups

• Create, modify, and deletesystem-level ACLs

• Grant and revoke CreateType, Create Cabinet, andCreate Group privileges

• Create types, cabinets, andprinters

8


Users and Groups


• Manipulate workflows orwork items, regardless ofownership

• Manage any object’s lifecycle• Set the a_full_text property

Superuser User can• Perform all the functionsof a user with Sysadminprivileges

• Unlock objects in therepository

• Modify or drop anotheruser’s user-defined objecttype

• Create subtypes that have nosupertype

• Register and unregisteranother user’s tables

• Select from any underlyingRDBMS table regardless ofwhether it is registered or not

• Modify or remove anotheruser’s groups or privateACLs

• Create, modify, or removesystem ACLs

• Grant and revoke Superuserand Sysadmin privileges

• Grant and revoke extendedprivileges

• View audit trail entries

16

The None privilege allows a user to perform only the actions allowed by the permissionsdefined at the object level. Typically, the majority of repository users have the Noneprivilege.

The Create Type, Create Group, and Create Cabinet privileges allow a user to create theitem identified by the privilege name. These privileges do not override object-levelpermissions and having one of the privileges does not automatically bestow any of the


Users and Groups

others. For example, a user may have the privilege to create cabinets but not object types.Another user may have only the privilege to create groups. A user who creates an objecttype, group, or cabinet is the owner of the item and can also modify or remove it.

The Sysadmin privilege does not override object-level permissions.

The Superuser privilege gives a user a minimum of Read access to all SysObjects if theACL does not explicitly grant the user a higher permission. A Superuser also alwayshas the Change Permit extended user permission. Evaluating a Superuser’s permissions,page 376, describes how Content Server evaluates the entries in an ACL for a Superuser.

Note: On UNIX platforms, Superuser privilege is not the equivalent of root user.

Extended user privileges

These privileges define security-related operations that users can perform. Table 24,page 293, lists the extended user privileges.

Table 24. Extended user privileges


Config Audit User can execute themethods to start and stopauditing.

8

Purge Audit User can remove audit trailentries from the repository.

16

View Audit User can view audit trailentries.

32

These privileges are not hierarchical. For example, granting a user Purge Audit privilegedoes not confer Config Audit privilege also.

Repository owners, Superusers, and users with the View Audit permission can view allaudit trail entries. Other users in a repository can view only those audit trail entries thatrecord information about objects other than ACLs, groups, and users.

Only repository owners and Superusers may grant and revoke extended user privileges,but they may not grant or revoke these privileges for themselves.


Users and Groups

Privileged groupsInstalling Content Server installs a set of privileged groups. Privileged groups aregroups whose members are allowed to perform privileged operations even though themembers do not have the privileges as individuals. The privileged groups are dividedinto two sets.

The first set of privileged groups are those that are available for use in applications orfor administration needs. With two exceptions, these privileged groups have no defaultmembers when they are created. You must populate the groups. Table 25, page 294,describes these groups.

Table 25. Privileged groups

Group Description

dm_browse_all Members of this group can browse any object in the repository.

The dm_browse_all_dynamic is a member of this group bydefault.

dm_browse_all_dynamic

This is a dynamic role group whose members can browse anyobject in the repository. The dm_browse_all_dynamic groupis a member of the dm_browse_all group.

dm_retention_managers

Members of this group can:• Own retainer objects (representing retention policies)• Add and remove a retainer from any SysObject.• Add and remove content in a retained object• Change the containment in a retained virtual document

This is a non-dynamic group.

dm_retention_users Members of this group can add retainers (retention policies)to SysObjects.

This is a non-dynamic group.

dm_superusers Members of this group are treated as Superusers in therepository.

The dm_superusers_dynamic group is a member of thisgroup by default.

dm_superusers_dynamic

A dynamic role group whose members are treated asSuperusers in the repository. The dm_superusers_dynamicgroup is a member of the dm_superusers group.


Users and Groups

Group Description

dm_sysadmin Members of this group are treated as users with Sysadminuser privileges.

dm_create_user Member of this group have Create User user privilege.

dm_create_type Member of this group have Create Type user privilege.

dm_create_group Member of this group have Create Group user privilege.

dm_create_cabinet Member of this group have Create Cabinet user privilege.

The second set of privileged groups are privileged roles that are used internally by DFC.You may not add or remove members from these groups. The groups are:• dm_assume_user• dm_datefield_override• dm_escalated_delete• dm_escalated_full_control• dm_escalated_owner_control• dm_escalated_full_control• dm_escalated_relate• dm_escalated_version• dm_escalated_write• dm_internal_attrib_override• dm_user_identity_override

Adding usersAdding a new user to a repository creates a dm_user object in the repository. To adda user to a repository, you must be the repository owner or installation owner, or haveSysadmin or Superuser privileges or be a member of the dm_create_users group.

New users can be added through Documentum Administrator or DQL. If you usean LDAP directory server to authenticate and manage users, then you add the newusers as entries in the LDAP directory server using the procedures from the directoryserver documentation. The new users in LDAP are then propagated automatically tothe repository.

If you are not using an LDAP directory server, Documentum Administrator is the fastestand most convenient way to add one user or a few users. If you are adding a largenumber of users, you can use an LDIF file imported using Documentum Administrator.

New users may also require an operating system user account. If user authentication isperformed by Content Server against the operating system, then an operating system


Users and Groups

account is required. If you use an LDAP directory server for user authentication, anactual operating system account is not required for the user. If the user is authenticatedusing a password stored in the repository, an operating system account is not required.

A repository includes a group named admingroup which includes all Superusers withinthe repository. If you grant Superuser privileges to a user after creating or updating theadministrative tools, add that user to the admingroup group.

Note: If the repository belongs to a federation and you add a local user with the samename as a global user, the local user is overwritten by the global user when the federationupdate jobs execute.

Setting user properties

When you create a new user, you must define the user’s:• User name• Authentication name• Email addressThe user’s name is defined in the user_name property. The name can be the same as theuser’s authentication name or it can be a more readable name, such as John Doe. The username must be unique within the set of user names and group names in the repository.

The authentication name is defined in the user_login_name property. This name is usedby Content Server to authenticate a user when he or she connects to the repository. Ifa domain name is not required in the repository, the user_login_name must be uniquewithin the repository. If a domain name is required in the repository, the combination ofuser_login_name and user_domain_name must be unique within the repository.

The user’s address is defined in the user_address property. The value is the user’s emailaddress. The server uses the email address to send electronic mail to the user wheneveran event occurs for which the user is registered or a method is executed that generatesan email message for the user.

The values for user_name, user_login_name, and user_address must consist of charactersthat are compatible with Content Server’s host operating system code page (theserver_os_codepage value). If the repository is in a multi-repository environment andthe repositories have different server_os_codepage values, the values must be ASCIIcharacters only.

In addition, you can also define a variety of other properties for the user, including :• Default folder

The default folder is the cabinet or folder in which Content Server stores objectscreated by the user if the user does not identify an alternate storage location. If youdo not define a default folder for a user, it defaults to the Temp cabinet.


Users and Groups

• Whether a user’s access is restricted to particular folders in the repository• User privileges• A default ACL• Client capability• A home repositoryThe Documentum System Object Reference Manual has a complete list of the properties ofthe user object type. The following sections describe some of the values you can set.

User privileges

A user’s user privileges define the operations that a user can perform in the repository.User privilege levels, page 291, lists the valid user privileges.

If you are setting the user_privileges property directly, using DQL, when you create theuser, define the user privileges as an integer value.

To give multiple user privileges by integer value, add the values. For example, to give auser Create Type and Create Cabinet privileges, use the integer 3, the sum of the integersrepresenting the Create Type and Create Cabinet privileges.

You can assign user privileges after you create a user. Granting and revoking userprivileges, page 301, contains information on how to do this.

Dening the default ACL

You can set two security properties for new users: acl_name and acl_domain. Table 26,page 297, describes these properties and how they are handled for a new user.

Table 26. Security properties for new users

Property Description

acl_name The name of an ACL to assign to the user.The ACL can be any ACL you own or anyACL owned by the system (the repositoryowner). If you do not set this property,the server creates an internal ACL in theuser’s domain as the default ACL.

The ACL grants the followingpermissions: dm_world receivesRead permission; the owner receives


Users and Groups

Property Description

Delete permission; and the user’s groupreceives Version permission.

acl_domain The name of the user who owns the ACLidentified by acl_name. If you do notset this property, the server sets it to therepository owner or the user’s name,based on the ACL specified in acl_name.

Setting user_db_name

If the user will be a repository owner or wants to register RDBMS tables, you must alsoset the user_db_name property. This property holds the user’s RDBMS login name.

Setting default_folder

The default_folder property specifies the user’s default storage folder. A user’s defaultfolder is the default storage place for any object the user creates. Depending on how youhave set up your site, you may need to create a folder for the user. For example, you maychoose to give each user a personal default folder. In this case, it is likely that you willneed to create the folder. If several users share a folder, the folder may already exist.

You must specify a folder path identifying a cabinet or folder as the default folder. Afolder path has the following syntax:/cabinet_name{/folder_name}

You can specify a folder path that does not exist.

Setting accessible folders

A user’s repository access can be restricted to designated folders. Set the repeatingproperty restricted_folder_ids to the full repository paths of each of the folders orcabinets to which the user has access, or use Documentum Administrator.

Note: When a user who is restricted to designated folders starts a repository sessionthrough Webtop, the user is also given the ability to access the /System folder and theirdefault folder or cabinet for the length of the repository session.


Users and Groups

Setting client capability

The client capability setting is used by Documentum client products, such as Webtop, todetermine which functionality to deliver to the user. Content Server does not recognizeor use the client capability setting. For information about the client features availablewith each setting, refer to the Documentum client documentation.

Creating a new user with DQL

Creating a new user with DQL is a two-step process.

To add a user using DQL:1. Create a default cabinet for the user if necessary.

Use the CREATE...OBJECT statement. For example:1>create dm_cabinet object2>set object_name = 'florabelle'3>go

2. Use the CREATE...OBJECT statement to create the user object and set its properties.For example:1>create dm_user object2>set user_name = 'florabelle',3>set default_folder = '/florabelle',4>set user_privileges = 35>go

The only required properties are user_name, user_login_name, and user_address.The Documentum System Object Reference Manual, contains a list of all user properties.Setting user properties, page 296, contains a discussion of other commonly setproperties.To set additional properties later or to modify a property setting, use theUPDATE...OBJECT statement. Modifying users, page 303, contains moreinformation.

Adding multiple users in a single operation

To add multiple users in one operation, you can create a file in LDIF format that definesthe users and use Documentum Administrator to read the file and create the users.

This section describes how to create the file. For instructions on importing the file usingDocumentum Administrator, refer to the Documentum Administrator online help.


Users and Groups

LDIF le contents

The LDIF file used to import users contains property values for the dm_user objectrepresenting each user, including the privileges, permits, and group assigned to the user.

The values specified in this file override any values specified in DocumentumAdministrator. The values you specify in Documentum Administrator are only usedif corresponding values are not specified in the file. If the values are not specified ineither the file or Documentum Administrator, the server uses the default values listed inTable 27, page 300.

Table 27. Default values for new users

Argument Default

user_login_name username

privileges 0 (None)

folder /username

group docu

client_capability 1

There are no default values for acl_domain, acl_name, and user_login_domain.

Setting up the le

The file that Documentum Administrator reads must be in LDIF format. Each line inthe file has format:property_name:value

The entry for each user must begin with:object_type:dm_user

That line marks the beginning of the description of the properties for a user. Anythingbetween object_type:dm_user and the next line that starts with object_type:dm_userdescribes one user object for the server to create.

The properties you can set through the LDIF file are:user_nameuser_os_nameuser_os_domainuser_login_nameuser_login_domainuser_passworduser_addressuser_db_name


Users and Groups

user_group_nameuser_privileges (set to integer value)default_folderuser_db_namedescriptionacl_domainacl_nameuser_source (set to integer value)home_docbaseuser_state (set to integer value)client_capability (set to integer value)globally_managed (set to T or F)alias_set_id (set to an object ID)workflow_disabled (set to T or F)user_xprivileges (set to integer value)failed_auth_attempt (set to integer value)

The properties user_name and user_os_name are required.

The properties may be included in any order after the first line (object_type:dm_user).The Boolean properties are specified using T (for true) or F (for false). Use of “true”,“false”, “1”, or “0” is deprecated.

Any ACLs that you identify by acl_domain and acl_name must exist before you run thefile to import the users. Additionally, the ACLs must be system ACLs. They cannot beprivate ACLs.

Any groups that you identify in user_group_name must exist before you run the fileto import the users.

Content Server will create the default folder if it does not already exist.

Extended characters in the le

If the file contains extended characters, such as an umlaut, the file must be saved asan UTF-8 file.

Granting and revoking user privilegesUser privileges define what administrative operations a user can perform in a repository.(User privilege levels, page 291, describes the user privileges.) By default, users haveno special privileges in a repository. You can give a user higher privileges when youcreate the user in the repository or you can do so later. To assign privileges to a user, useDocumentum Administrator, DQL, or DFC.

Granting and revoking user privileges is subject to the following constraints:


Users and Groups

• You must have Sysadmin or Superuser privileges to grant the Create Type, CreateCabinet, or Create Group privileges.

• You must have Superuser privileges to grant Superuser or Sysadmin privileges.• Only repository owners and Superusers can grant and revoke the extended user

privileges, but they may not grant the privileges to themselves or revoke themfrom themselves.

A user’s basic user privileges are stored in the user_privileges property of the user’sdm_user object. The user’s extended user privileges are stored in the user_xprivilegesproperty.

Each privilege you grant a user is added to any current privileges. For example, if auser has the Create Type privilege and you grant that user the Sysadmin privilege, theSysadmin privilege does not replace the Create Type privilege but is added to it. If youlater revoke the Sysadmin privilege, the user retains the Create Type privilege.

Superuser privileges and the admingroup group

When you grant Superuser privileges to a user, you may also need to add that userto the admingroup group to enable them to run jobs or administration methods. Theadmingroup group is created at server installation or upgrade, when the administrationtool suite is installed. It contains all the Superusers in the repository. At serverinstallation, these are the repository owner and installation owner. After an upgrade, itcontains all Superusers in the repository.

Members of the admingroup group have no inherent privileges other than those theyhave as Superusers. However, administrative jobs, methods, and other related objectsuse an ACL which restricts their use to the admingroup group.

When you revoke Superuser privileges from a user, remember to also remove that userfrom the admingroup group.

Modifying groups, page 309, contains instructions on adding and removing users toand from groups.

Granting and revoking privileges using DQL

Use the DQL GRANT statement to assign user privileges and the REVOKE statementto remove them. You must have Sysadmin or Superuser privileges to grant and revokethe basic user privileges. You must be the repository owner to grant and revoke anextended user privilege.

The syntax of the GRANT statement is:


Users and Groups

GRANT privilege{,privilege} TO user{,user}

The syntax of the REVOKE statement is:REVOKE privilege{,privilege} FROM user{,user}

To include multiple privileges in either statement, separate the privileges with commas.Similarly, to identify more than one user, separate the user names with commas. Forexample:GRANT CREATE TYPE,CREATE CABINET TO jane,jeffrey,ashley

orREVOKE CREATE TYPE,CREATE CABINET FROM jane,jeffrey,ashley

Granting and revoking privileges using DFC

To grant or revoke user privileges through DFC, use the setUserPrivileges andsetUserXPrivileges methods in the IDfUser interface. The user’s basic user privileges,set by setUserPrivileges, are recorded in the user_privileges property. The user’sextended user privileges, set by setUserXPrivileges, are recorded in the user_xprivilegesproperty. The user_privileges and user_xprivileges properties are integer properties.Consequently, each method takes an integer argument, representing the integer valuerepresenting the privilege or privileges you want to assign. (Table 23, page 291, and Table24, page 293, list the integer values assigned to the basic and extended user privileges.)

The privilege values are additive. For example, to assign a user the privilege to createtypes, set the argument to 1. To assign the user the privileges to create types and createcabinets, set argument to 3 (1 for Create Type plus 2 for Create Cabinet).

The value in the argument for either method overwrites the current value of thecorresponding property. To add or revoke a user’s privileges, check the value of theproperty first and reset the value accordingly. For example, suppose you want to add theCreate Cabinet privilege (value 2) to a user who already has Create Group (value 4) andCreate Type (value 1). The current value in the user_privileges property is 5 (4+1). To addCreate Cabinet, set user_privileges to 7. Or, suppose you want to remove the Create Typeprivilege from that user. To do that, set the user_privileges property to 4 (subtracting thevalue of Create Type from the current setting and reseting the property to the remainder).

Modifying usersYou can use Documentum Administrator, DQL, or DFC to modify a user’s definition inthe repository. You must have at least Sysadmin or Superuser privileges to modify a


Users and Groups

user. Refer to Granting and revoking user privileges, page 301, for information aboutthe privileges needed to grant or revoke user privileges.

If you use Documentum Administrator to change a user’s default group, the user isautomatically added to the default group unless he or she already belongs to that group.

Using DQL

Use the DQL UPDATE...OBJECT statement to modify a user. The Content Server DQLReference Manual contains a description of this statement and its use.

As an example, here is an excerpt from an IDQL session that changes florabelle’s defaultgroup to support:1>update dm_user object2>set user_group_name = 'support'3>where user_name = 'florabelle'4>go

Renaming usersUse Documentum Administrator to rename a user. Renaming a user changes the user’sname recorded in all objects in the repository, including ACLs and alias sets.

Documentum Administrator executes the User Rename administration tool to renamethe user. You cannot execute this tool manually. You must use DocumentumAdministrator to run User Rename. For information about the tool arguments and thegenerated report, refer to User Rename, page 523.

You cannot rename the repository owner, installation owner, or yourself.

Deleting usersYou can delete users using Documentum Administrator, DQL, or DFC. However, it isbetter to deactivate users rather than deleting them. Deactivating a user means that theuser is no longer allowed to log into the repository, but the user’s user object is notdeleted from the repository. (Deactivating, locking, and reactivating users, page 305,contains more information on this.) You must have Sysadmin or Superuser privileges todelete a user.

When you delete a user, the server does not remove the user’s name from objects inthe repository such as groups and ACLs. Consequently, when you delete a user, you


Users and Groups

must also remove or change all references to that user in objects in the repository. Forexample, every SysObject or SysObject subtype in the repository has a property calledowner_name that identifies the user who owns that object. Before you delete a userfrom a repository, update the objects created by the user, changing the owner_name toidentify a different user.

You can delete a user and then create a user with the same name. However, the recreateduser will not inherit the previous user’s group memberships and object permissions.

If you delete a user, the server also removes all registry objects that reference the user asthe subject of audit or event notification requests.

You cannot delete the repository owner, installation owner, or yourself.

Using DQL

Use the DQL DELETE...OBJECT statement to delete a user. The qualification in thestatement’s WHERE clause identifies the user you want to delete. For example, here is anexcerpt from an IDQL session that deletes the user florabelle:1>delete dm_user object2>where user_name = 'florabelle'4>go

The Content Server DQL Reference Manual has the full syntax.

Deactivating, locking, and reactivating usersBy default, users are created in the repository in the active state. Active users may bedeactivated or locked and, if needed reactivated. A user’s activation state is recorded inthe user_state property of the user’s user object. Active users may log into the repositoryand perform those operations for which they have permissions. Deactivated or lockedusers cannot log into the repository.

It is more convenient to deactivate or lock a user than to delete a user because it allowsyou to stop a user’s access to the repository without requiring you to also modify all thedocuments or other objects that might reference the user in a property.

Deactivating or locking users

You must have Sysadmin or Superuser privileges to deactivate or lock a repository user.


Users and Groups

To deactivate or lock a user, use Documentum Administrator or DQL to change the user’slogin state. In Documentum Administrator, you can choose either Inactive, Locked, orInactive and Locked to deactivate a user.

If you are using an LDAP directory server to manage users, deleting the user’s LDAPentry may automatically deactivate the user the next time the dm_LDAPSynchronizationjob runs. This depends on the particular directory server you are using and how yoursite is configured.

A user may be deactivated automatically if the value in the user’s failed_auth_attemptproperty exceeds the maximum number of failed authentication attempts defined in therepository configuration, in the max_auth_attempt property of the docbase config object.(Limiting authentication attempts, page 356, describes how this feature works.)

If you deactivate or lock a user who is currently logged in, the user is allowed tocomplete the repository session but can only perform Assume or Disconnect operations.After disconnecting, the user is not allowed to log in subsequently.

If necessary, a user with Superuser privileges can use a login ticket to log in as adeactivated or locked user, and a user with Superuser privileges can add a deactivated orlocked user to a group.

You cannot change the login state of the repository owner, installation owner, or yourself.

Reactivating users

Use Documentum Administrator or DQL to reactivate a user that is in the inactive orlocked state. You must have Sysadmin or Superuser privileges to reset the user to active.

If the user was inactivated automatically because he or she experienced more than themaximum number of failed authentication attempts when logging in, reactivating theuser resets the value in the user’s failed_auth_attempt property to 0.

Using DQL to change a user’s login state

Use the DQL UPDATE...OBJECT statement to change a user’s login state. To deactivatethe user, set the user_state property to 1, 2, or 3. Setting the property to 1 sets the userstate to Inactive. Setting it to 2 sets the user state to Locked. And, setting it to 3 setsthe user’s state to Inactive and Locked.

For example, to set the user to Inactive, the syntax is:UPDATE "dm_user" OBJECTset "user_state" = 1WHERE "user_name"='user name'


Users and Groups

To activate a user, set the property to 0:UPDATE "dm_user" OBJECTset "user_state" = 0WHERE "user_name"='user name'

For example, here is an excerpt of an IDQL session that deactivates the user florabelle:1>update dm_user object2>set user_state = 13>where user_name = 'florabelle'4>go

TheContent Server DQL Reference Manual has a full description of the UPDATE OBJECTstatement.

Adding groupsYou can use Documentum Administrator, DQL, or DFC to create a group. The easiestway to add a group is using Documentum Administrator. To create a group, you musthave Create Group, Sysadmin, or Superuser user privileges.

Note: If the repository belongs to a federation and you add a local group with the samename as a global group, the local group is overwritten by the global group when thefederation update jobs execute.

By default, a group is owned by the user who creates it. To assign group ownership toanother individual user, you must be a superuser. To assign group ownership to a group,you must be a member of the group to which you are assigning ownership.

Groups can be either public or private. By default, groups created by a user with CreateGroup privilege are private, and groups created by a user with Sysadmin or Superuserprivileges are public. To change the default, set the is_private property to the appropriatevalue. If is_private is TRUE, the group is a private group. If is_private is FALSE, thegroup is a public group.

If the Collaborative Services with Rooms feature is enabled, groups can be assigned toa Room and designated as ’room private groups’. A room private group is any groupfor which the group_native_room_id property has a value. A room private groupmust also have a group_display_name assigned that is unique within the Room, andthe group_display_name together with group_native_room_id must be unique in therepository. (For more information on Collaborative Services, refer to the documentationfor Documentum Webtop.)

A group can also be dynamic. A dynamic group is a group whose member list is a list ofpotential members. By default, a new group is not a dynamic group. (Dynamic groups,page 361, contains more information about dynamic groups.) If you define the group asa dynamic group, then you have the option of defining whether members are consideredmembers by default or non-members by default.


Users and Groups

The default membership setting for dynamic groups controls whether group membersare considered in or out of the group when a session is started. It is FALSE by default,meaning that users are not considered members by default, and an application mustissue a session call to “add” the user to the group at connection time. (This setting isrecorded in the is_dynamic_default property.) If the members are considered in thegroup by default, then the application must issue a session call to “remove” a user fromthe group if needed. Changing the membership setting of a dynamic group, page 310,contains instructions on changing the default membership setting.)

The members of a group can be individual users or other groups. A non-dynamicgroup may contain a dynamic group as a member. A dynamic group can contain otherdynamic groups or non-dynamic groups as members. (If a non-dynamic group is amember of a dynamic group, the members of the non-dynamic group are treated aspotential members of the dynamic group.)

The name you assign to a group must consist of characters compatible with the ContentServer’s server OS code page. Group names are not case sensitive. All group namesare stored in the repository in lowercase.

Content Server makes no use of the is_private flag. The flag is provided so thatuser-written applications can determine which groups to display under circumstancesthat the applications define.

Using DQL

Use DQL to create a group if you want to accept the default group ownership and grouptype. (A group is owned by its creator by default and is created as a standard group bydefault.) If you want to create a group owned by another user or by a group or wantto create a group whose class is role or domain, use Documentum Administrator tocreate the group.

Use the DQL CREATE...GROUP statement to create a group. The syntax is:CREATE [PUBLIC|PRIVATE] GROUP group_name[WITH][ADDRESS email_address][MEMBERS members]

members is a comma-separated list of the users and groups that belong to the group.Identify users by their user_name values. Identify groups by the group_name values.For example, the following statement creates a group called editors and adds johnr,sallyt, and haroldw to the group:CREATE GROUP "editors" ADDRESS "editors" MEMBERS johnr,sallyt,haroldw

Alternatively, you can use a SELECT statement to obtain the member names. Forexample, assuming that user_dept is a user-defined property for the dm_user type:CREATE GROUP "editors" ADDRESS "editors"MEMBERS (SELECT "user_name" FROM "dm_user"WHERE "user_dept" = 'documentation')


Users and Groups

Include the PUBLIC keyword to create the group as a public group. Include PRIVATE tocreate the group as a private group. Refer to Adding groups, page 307, for informationabout public and private groups.

Modifying groupsYou may need to modify a group’s definition in the repository. For example, you maywant to change the email address, add or remove a member, or change the defaultmembership setting. You can use Documentum Administrator, the DQL ALTER GROUPstatement, or DFC to modify a group.

To modify a group, you must be one of the following:• The group’s owner• A superuser• A member of the group that owns the group to be modified• Identified in the group’s group_admin property, either as an individual or as a

member of a group specified in the propertyOnly a Superuser can change the ownership of an existing group. Only a Superuser orthe owner of a group can change the group_admin property of a group.

To add a deactivated user to a group, you must have Superuser privileges.

Using DQL

Use a DQL ALTER GROUP statement to modify a group. For example, here is an excerptfrom an IDQL session that adds florabelle to the engr group and changes the group’smail address:1>alter group engr add florabelle2>alter group engr set address base_engr3>go

The Content Server DQL Reference Manual has a full description of the ALTER GROUPstatement.

Deleting groupsYou can use Documentum Administrator, DQL, or DFC to delete groups.


Users and Groups

When you delete a group, Content Server does not remove references to the group’sname from other objects in the repository. Consequently, before you delete a group, ifyou do not intend to create another group with the same name, remove all references tothe group in repository objects. Groups are referenced by name in a variety of propertiesin repository objects. For example, a group may be referenced as the owner of an object,a member of another group, or a value in an alias set.

Deleting a group does remove all registry objects that reference the group as the subjectof an audit or event notification request.

To delete a group, you must be one of the following:• The group’s owner• A Superuser• A member of the group that owns the group to be modified (if the group is owned by

a group)

Caution: Do not delete the admingroup group from the repository. Theadmingroup group, which includes all Superusers within the repository, is used bythe jobs that make up the administration tool suite.

Using DQL

Use the DQL DROP GROUP statement to delete a group. The syntax is:DROP GROUP group_name

group_name identifies the group you want to delete. For example, here is an excerpt froman IDQL session that deletes the group engr:1>drop group engr2>go

The Content Server DQL Reference Manual has a full description of the DROP GROUPstatement.

Changing the membership setting of a dynamicgroup

Dynamic groups allow you to determine whether users in the group’s membership listare considered members of the group or not by default when the users connect to therepository. This behavior is controlled by the setting in the is_dynamic_default propertyof the group object.


Users and Groups

When a dynamic group is created, the property is set to F by default. That settingmeans that users are not considered members of the group automatically. Whenthe user connects to the repository, the application he or she is using must issue anIDfSession.addDynamicGroup call. If you reset the property to T, the server considersthe users to be group members by default. To remove the user from the group, theapplication must issue an IDfSession.removeDynamicGroup method at session startup.

To reset that property, use Documentum Administrator.

Querying groupsThis section describes how to obtain two kinds of commonly needed information aboutgroups:• Names of users in a particular group• List of the groups in a repository and a count of users in each.

Obtaining a list of members in a group

To obtain a list of users in the group, you can query the _all_users_names computedproperty. This property returns a list of all users directly or indirectly contained ina group.

The first time you query _all_users_names in a session, the property’s value is cachedon the server and client side. If the property is queried again in the session, the returnvalues are retrieved from the cache.

If the group membership is changed during the session, the cached values are invalidatedand the value is re-computed when the you query the property again. However, anychanges made to the group by users in other, concurrent sessions aren’t visible to yourcurrent session’s server process. Consequently, to ensure that the values returned arecorrect, you can issue an IDfSession.revert method on the group object before queryingthe computed property. Issuing the revert method invalidates the cached copy, forcingthe server to recompute the property’s value.

Obtaining a list of groups with a count of the membersin each

You can use the following query to obtain a list of groups in a repository and a countof the members in each group:


Users and Groups

SELECT gr2.i_supergroups_names, count(gr1.users_names)FROM dm_group_r gr1, dm_group_r gr2WHERE gr1.r_object_id=gr2.r_object_id ANDgr2.i_supergroups_names IS NOT NULLGROUP BY gr2.i_supergroups_names


Chapter 9Managing User Authentication

This chapter describes the options available for user authentication and how to implement them. Thechapter includes the following topics:• Authentication options, page 313• The assume user and change password programs, page 315• Using the default authentication mechanism, page 316• Using a custom external password checking program, page 319• Using Windows domain authentication for UNIX users, page 320• Using an LDAP directory server, page 323• Using authentication plug-ins, page 346• Using an in-line password, page 351• Trusted logins, page 351• Unified logins, page 351• Managing encrypted passwords, page 352• Limiting authentication attempts, page 356

Authentication optionsUser authentication typically occurs when a user attempts to connect to a repository.(It can also occur when another client application, such as Document Control Manager,requires user authentication prior to performing an operation.) Content Serverdetermines whether the user is a valid, active repository user and, if so, authenticates theuser name and password. Documentum supports a variety of options for implementinguser authentication. You can perform user authentication using• The default mechanism• A custom dm_check_password program• An LDAP directory server


Managing User Authentication

• A authentication plug-in• An in-line password

Default mechanism

The default mechanism authenticates the user against the operating system. Thisimplementation is the simplest to set up. Using the default authentication mechanism,page 316, contains information about how the default mechanism works and how toset it up.

Custom password checking program

You can create a custom password checking program and set up the servers to call thatprogram for user authentication. This option is particularly useful if you want to useWindows domain authentication for UNIX users. Using a custom external passwordchecking program, page 319, contains instructions on creating custom passwordchecking programs.

LDAP directory server

LDAP is the acronym for Lightweight Directory Access Protocol, a TCP/IP-based protocolfor communication between a client (in this case, Content Server) and a directory server.Content Server supports several directory servers (refer to the Content Server Release Notesfor a complete list). If you use a directory server, you have the following options:• Authenticate against the directory server directly, using a secure or a non-secure

connection• Authenticate using an LDAP-enabled dm_check_password programUsing an LDAP directory server, page 323, contains complete information about LDAPsupport and how to set up and use a directory server with a repository.

Authentication plug-in

Authentication plug-ins provide an alternate way to customize user authentication.Documentum provides two authentication plug-ins with Content Server; one for EMCRSA and one for CA SiteMinder.



The EMC RSA Plugin for Documentum allows you to use the RSA Access Manager withContent Server for user authentication.

The CS Siteminder plug-in allows you to use CA SiteMinder with Content Server.

Both plug-ins support Web-based Single Sign-On (SSO) and strong authentication.(Strong authentication is the use of authentication tokens such as smart cards orbiometrics.)

Using the RSA plug-in, page 348, contains a listing of the platforms supported by theRSA plugin and instructions on using the plugin.

Using the CA SiteMinder plug-in, page 348, contains a listing of which platforms aresupported by the CA SiteMinder plug-in and instructions on using the plug-in.

You can write and install your own authentication plug-in. Implementing a customauthentication plug-in, page 349, contains instructions.

In-line password

A user can be authenticated using an encrypted password that is stored in theuser_password property of the user object. Using an in-line password, page 351 ,contains instructions for using in-line passwords.

The assume user and change passwordprograms

The assume user and change password programs are two programs that Documentumprovides and implements by default for your installation.

Assume user

The assume user program is called whenever a client (end user or application) executes aDO_METHOD function for a procedure for which the run_as_server attribute is set toFALSE. When the procedure is executed (and the server knows where to find the assumeuser program), the server runs the procedure as the logged-in user. If the server cannotfind the assume user program because assume_user_location is set to null, or if therun_as_server attribute is set to TRUE, the procedure executes under the server’s account.



This feature is enabled by default. The Setup program copies the assume user programto the $DOCUMENTUM/dba directory and sets the assume_user_location property ofthe server config object to this location.

If you want to disable this feature, set the assume_user_location property in the serverconfig object to blank and reinitialize the server.

Change Password

Change password is called whenever the server receives a request to change a password.

This program is copied by the Setup program to $DOCUMENTUM/dba. The installationscript also sets the change_password_location property of the server config object topoint to the file in $DOCUMENTUM/dba.

If you want to disable this capability, set the change_password_location property toblank and reinitialize the server.

Using the default authentication mechanismThe default authentication mechanisms for UNIX and Windows are different.

UNIX platforms

The default authentication mechanism is an external password checking program. Theprogram must be external because the operating systems on which Content Server issupported use C-2 security level password validation. At this level, user passwords arestored in a manner that requires root-level privileges to access. Rather than requiringContent Server be setuid to root, an external password checking program is providedthat is setuid to root. This program calls the appropriate operating system calls to verifythe users’ passwords. The source code for this program is also provided so you canverify its functionality and add any required customizations.

The files in which the passwords are actually stored are:• /etc/shadow on Solaris and Linux• /secure/etc/password on HP-UX• /etc/security/passwd on AIXDocumentum provides a default program called dm_check_password. During serverinstallation, the program is copied to the $DOCUMENTUM/dba directory. A locationobject, named validate_user, created during installation, points to the location of the



check password program. The location object is referenced in the server config objectby the user_validation_location property. When a user is authenticated, the server usesthe location object named in the user_validation_location property to find the passwordchecking program.

dm_check_password is provided as both source code and compiled code. If you have aC compiler, you can recompile the program and use the recompiled version.

To use the default mechanism on UNIX, repository users must have operating systemaccounts.

You can create your own password checking program. Using a custom externalpassword checking program, page 319, contains instructions.

You can also configure Content Server to use the password checking programto authenticate UNIX users against Windows domain. Using Windows domainauthentication for UNIX users, page 320, contains instructions.

Windows platforms

OnWindows platforms, the default authentication is an internal process. Content Serverdoes not use dm_check_password. When Content Server is installed on a Windowsplatform, the validate_user property in the server config is not set.

To use the default mechanism on Windows, repository users must have an operatingsystem account.

Authenticating in domains

On Windows platforms, if you are authenticating against the operating system, ContentServer authenticates the user’s operating system name and password within a domain.A user’s domain is stored in the user’s user_os_domain property. A default domain isdefined for all users in the repository in the server.ini file, in the user_auth_target key.

Whether the server uses the user-specific domain or the default domain for authenticationdepends on whether the server is running in domain-required mode or not.

The Content Server installation procedure installs a repository in no-domain requiredmode. If your Windows configuration has only one domain whose users access therepository, the no-domain required mode is sufficient. If the users accessing therepository are from varied domains, using domain-required mode provides bettersecurity for the repository.



No-domain required mode

In no-domain required mode, users are not required to enter a domain name when theyconnect to the repository. In this mode, a user’s operating system name must be uniqueamong the user_os_name values in the repository.

How the server authenticates a user depends on what value is found in the user’suser_os_domain property. The property can contain an asterisk (*), a blank, or a domainname:• If user_os_domain contains an asterisk or blank, Content Server authenticates the

user using operating system name and the domain specified in the connectionrequest. If no domain is included in the connection request, the server uses thedomain defined in the user_auth_target key in the server.ini file.

• If user_os_domain contains a domain name, Content Server authenticates againstthe domain identified in the user_os_domain property.

Domain-required mode

In domain-required mode, users must enter a domain name or the name of an LDAPserver when they connect to the repository. The domain value is defined when the useris created and is stored in the user_login_domain property in the dm_user object.

In domain-required mode, the combination of a user’s login name and domain or LDAPserver name must be unique in the repository. This means it is possible to have multipleusers with the same user login name if each user is in a different domain. For example,the repository could have mark in the finance domain and mark in the engineeringdomain. It is also possible for one user to be several users in the repository—mark infinance and mark in engineering could be the same person.

Trusted logins are the only exceptions to the rule about supplying a domain name.Trusted logins do not require a domain name even under domain-required mode.

Determining the repository’s authentication mode

If you are unsure which mode the repository is running in, you can examine theauth_protocol property in the docbase config object. If the repository is in the defaultmode, this property is blank. If the repository is in the domain-required mode, thisproperty’s value is domain-required.



Converting to domain-required mode

After a repository is changed to the domain-required mode, the only way to return it tothe default mode is to create a new repository and dump and load the domain-requiredmode into the new repository.

Documentum provides the dm_domain_conv script to convert to domain-requiredmode. You cannot change to domain-required mode by setting any properties manually.The script not only resets the auth_protocol property, but also recreates some indexesused by Content Server. The script is found in %DM_HOME%\install\tools.

To change to domain-required mode:1. Log into the repository as a user with Sysadmin or Superuser privileges.

2. Execute the dm_domain_conv script using the following command line:dmbasic -f dm_domain_conv.ebs

The script prompts you for the repository to convert, the name of a user withSuperuser privileges, the Superuser’s password, the Superuser’s domain, the users’domain, and a log file for output.

Using a custom external password checkingprogram

You can write and install a custom password checking program to use regardless of theplatform on which the server is running.

Caution: This section outlines the basic procedure for creating and installing acustom password checking program. Documentum provides standard technicalsupport for the password checking program that is created and provided with theContent Server software, as part of the product release. For assistance in creating,implementing, or debugging a custom password checking program, contactDocumentum Professional Services or Documentum Developer support.

Basic steps

The following procedure outlines how to implement a custom password checkingprogram. Use Documentum Administrator to perform steps 3 and 4.



To use a custom password checking program:1. Write and compile the program.

2. Put the program in %DOCUMENTUM%\dba ($DOCUMENTUM/dba).

3. Create a new location object to point to the location of the custom program.

4. Set the validate_user property in the server config to the name of the new locationobject.

Writing the program

A custom program must• Accept the same input arguments as the default dm_check_password program.• Return the same values as the dm_check_password program.Additionally, if the program is to be installed on a UNIX host, the program must meetthe following requirements:• The program must be owned by root• Its group ownership must be the Documentum system administrator’s group

(admingroup)• Its permissions must be set to 4550

Setting the permissions to 4550 means that only the program’s owner and membersof the administrator’s group can run the program and that the program will setUID on execution.

Using Windows domain authentication forUNIX users

You can configure Content Server to authenticate UNIX users against a Windowsdomain. To do so, you must:

1. Create and install a custom dm_check_password.

2. Set the auth_protocol property in the docbase config object to unix_domain_used.

3. Set up a domain controller map.

4. Modify the user_source property for the users in the repository.



Note: UNIX users who are authenticated against a Windows domain cannot executemethods under their own accounts. All methods executed by such users must be runwith run_as_server set to TRUE.

Modifying the dm_check_password program

You must obtain the source code for SMB from GNU in order to recompile thedm_check_password program so that it can authenticate users against a Windowsdomain.

You can use GNU’s C compiler, which is called gcc, or you can use the C compilersupplied by your operating system vendor. You must have GNU’s gmake utility.

Caution: Documentum Technical Support provides no support for Steps 1 and2 in the following procedure.

To modify dm_check_password:1. Obtain the GNU SMB library source code.

This is available at Samba sites on the Web.

2. Build the GNU SMB library.

3. Copy the smbvalid.a library from the /smbval directory to the $DM_HOME/install/external_apps/checkpass directory.

4. Copy the valid.h file from the /include directory to the $DM_HOME/install/external_apps/checkpass directory.

5. In the $DM_HOME/install/external_apps/checkpass directory, open themake_check_prog script.

6. In the make_check_prog script, set the do_domain variable to -Ddomain_authentication.set do_domain = -Ddomain_authentication

7. Set the domain_lib variable to smbvalid.a.set domain_lib=smbvalid.a

8. Follow the other instructions in the comments to the make_check_prog script.

9. Run the make_check_prog script.A new dm_check_password program is produced.

10. Copy dm_check_password to the $DOCUMENTUM/dba directory.

11. Log in as root.



12. Change the ownership of dm_check_password to root:chown root dm_check_password

13. Change dm_check_password’s group to the group defined for the Documentuminstallation.chown group_name dm_check_password

14. Change the permissions on dm_check_password:chmod 6711 dm_check_password

Setting auth_protocol

Use Documentum Administrator to modify the docbase config object to set theauth_protocol property to unix_domain_used. For instructions, refer to the DocumentumAdministrator online help.

Setting up the domain controller map

A domain controller map provides information about domain controllers to ContentServer. In a repository, a domain controller map is stored in a dm_auth_config object.The dm_auth_config object is created by Documentum Administrator when you useDocumentum Administrator to set up the domain controller map. A repository has onlyone dm_auth_config object. The object type has three repeating properties:• domain_name, which stores the names of Windows domains• primary_controller, which stores the names of the primary controllers for the domain• backup_controller, which stores the names of the backup controllers for the domainThe values at a particular index position in the primary_controller and backup_controllerproperties identify the primary and backup controllers for the domain at thecorresponding index position in domain_name.

To define a domain controller map, modify the docbase config object using DocumentumAdministrator. The values entered in all three properties must be in lowercase.Additionally, do not enter a fully qualified name for a primary or backup domaincontroller. Enter only the host name. For complete instructions, refer to the DocumentumAdministrator online help.



Setting the user_source property

The value in the user_source property is used by Content Server to determine whichauthentication mechanism to apply to the user. To direct Content Server to use awindows domain for a UNIX user, set the user_source property for each UNIX userto one of the following:• domain only

Indicates that a user is authenticated only against a Windows NT domain.• UNIX first

Indicates that a user is authenticated first against the UNIX password file or NISdatabase, and if that fails, the user is authenticated against a Windows domain.

• domain first

Indicates that a user is authenticated first against a Windows domain, and if thatfails, the user is authenticated against the UNIX password file or NIS database.

Use Documentum Administrator to modify the user’s property. For instructions, refer tothe Documentum Administrator’s online help.

Using an LDAP directory serverAn LDAP directory server is a third-party product that maintains information aboutusers and groups. (Refer to the Content Server Release Notes for a list of the directoryservers supported with Content Server.) Documentum Content Servers use LDAPdirectory servers for two purposes:• To manage users and groups from a central location• To authenticate usersIt is not necessary for all users and groups in a repository to be managed through anLDAP directory server. A repository can have local users and groups in addition to theusers and groups managed through a directory server.

You can use more than one LDAP directory server for managing users and groups ina particular repository.

This section provides information and instructions about using an LDAP directoryserver for user authentication.



Benets

Using an LDAP server provides a single place where you canmake additions and changesto users and groups. The changes from the directory server are automatically propagatedto all the repositories using the directory server by the dm_LDAPSynchronization job.

The LDAP support provided by Content Server allows you to map LDAP user and groupattributes to user and group repository properties or a constant value. When the user orgroup is imported into the repository or updated from the directory server, the repositoryproperties are set to the values of the LDAP properties or the constant. The mappings aredefined when you create the LDAP config object. You can also change them later, addingadditional mapped properties, changing their mapping, or deleting mappings.

Using an LDAP directory server to manage users and groups in the Documentumsystem ensures that:• The users and groups defined in the directory server are in each repository using

the directory server• The values of the mapped properties for users and groups are the same in each

participating repository

Note: Changing or deleting the mapping for user_name, user_login_name, orgroup_name after the first synchronization for the user or group is not recommended.Doing so may result in inconsistencies in the repository.

Constraints

Using an LDAP directory server has the following constraints:• The changePassword method is not supported for users managed through an LDAP

directory server.• Dynamic groups are supported only on Sun Java System directory servers.

Integrating an LDAP directory server with a repository

When you add an LDAP directory server to an existing Documentum installation, theusers and groups defined in the LDAP directory server are given precedence. If a useror group entry in the LDAP directory server matches a user or group in the repository,the repository information is overwritten by the information in the LDAP directoryserver when synchronization occurs.



Using multiple LDAP directory servers

It is possible to have multiple LDAP servers accessible to the Content Server or Serversservicing a repository. The LDAP servers that are available to a particular server aredefined in the server config object, in the ldap_config_id and extra_directory_config_idsproperties.

Typically, LDAP synchronization synchronizes with all the LDAP servers specified inthese properties. However, you can configure synchronization to synchronize with any orall of the directory servers identified in a server config object.Dm_LDAPSynchronization,page 479, contains instructions.

You can also define secondary LDAP servers for authentication failover. Those serversare specified in the ldap config object. For information on how authentication failoverworks and which properties are used, refer to Authentication failover, page 330.

User and group synchronization

This section describes how synchronization of LDAP users and groups occurs andis managed within a repository.

Synchronization and federations

In a federation, only the governing repository can communicate with an LDAP serverfor the purposes of managing users and groups. Entries in the directory server aresynchronized with the governing repository and it is the responsibility of the governingrepository to propagate the changes to the member repositories.

dm_LDAPSynchronization job

Content Server uses the dm_LDAPSynchronization job to synchronize the entries in thedirectory server and the repository. This job is part of the Content Server’s administrationtool suite. The job is installed in the inactive state. (Dm_LDAPSynchronization, page479, contains details about the job and Activating the dm_LDAPSynchronization job,page 341, describes how to activate it.)

The LDAPSynchronization job updates the repository to match the entries in thedirectory server. This is a one-way operation. Changes in the directory server arepropagated to the repository. Changes in the repository are not propagated to thedirectory server.



The first time the LDAPSynchronization job is run, non-directory users and groups inthe repository are matched to directory users and groups in the LDAP directory server,converting them to directory users and groups and updating them from the directoryserver. First-time synchronization can be used optionally in future synchronizations.Enabling first-time synchronization rules, page 344, contains information on usingfirst-time synchronization.

The job can perform the following operations in synchronizations subsequent to the first:• Import into the repository any new users and groups in the directory server.• Rename in the repository any users and groups whose names are changed in the

directory server.

For users, the renaming occurs if a change is detected in the LDAP attribute orattributes to which the user’s user_name property is mapped. For groups, renamingoccurs if a change is detected in the LDAP attribute or attributes to which the group’sgroup_name property is mapped.

• Inactivate users in the repository if they are deleted in the directory server.If you are using iPlanet, you must enable the changelog feature to use the inactivationoperation. (Instructions for enabling the changelog feature are found in the vendor’siPlanet Administration Guide.)

You can also define the operations performed by setting properties in the associatedLDAP configuration object or by setting command line arguments for the job. Forexample, you can direct the job to only import and change users or only groups. You candisable the inactivation updates or the renaming changes.

When the job creates a new user in the repository, it sets any user properties that aremapped to LDAP attributes or a constant. It can also create the user’s default group andfolder if needed. The job will create the folder and group if the associated user properties,default_folder and user_group_name, are mapped to LDAP attributes and the valueresolves to a non-existent folder or group. If default_folder is not mapped to a value, thejob sets the default folder to /Temp. There is no default value for user_group_name.

When the job creates a new group in the repository from an LDAP group, it populatesthe group with the members defined in the LDAP group. If the users in the group do notexist in the repository, the job creates them in the repository.

For rename operations, the LDAPSynchronization job creates a job request for eachname change and marks the job to run immediately. The job is run as soon as theLDAPSynchronization job completes.

Note: If you delete an LDAP user or group, the repository user or group is not deleted.Doing so would cause referential integrity problems in the repository. However, ifthe inactivation operation is available and in use, deleting an LDAP user will set therepository user inactive.



How the synchronization job determines which LDAP servers to use

The dm_LDAPSynchronization job has an argument called -source_directory. Thisargument accepts a list of ldap config object names or the value dm_all_directories.When the job runs, it checks to determine which of the directories specified in theargument are found in the following properties of the server config object:• ldap_config_id

This is a single-valued property.• extra_directory_config_id

This is a repeating property.The job uses all the directories specified in the argument that are also identified in one ofthose properties for synchronization. If the value of the -source_directory argument isdm_all_directories, the job synchronizes with all the LDAP directories identified in theproperties. The job connects to each LDAP server in turn and synchronizes users andgroups in the repository based on the users and groups in the LDAP server entries.

Attributes set by the dm_LDAPSynchronization job

The dm_LDAPSynchronization job sets the following properties in addition to themapped repository properties:• For users:

— user_source

— user_login_domain

— user_global_unique_id• For groups:

— group_directory_id

— group_global_unique_idThe job sets the user_source property of users to LDAP when it updates or creates usersin a repository. The user_source property is examined by Content Server to determinewhich authentication mechanism to use for authentication (unless a plug-in module isspecified explicitly in the connection request). For LDAP users, user_source must beset to LDAP.

For users, the job sets the user_login_domain to the object name of the ldap config objectrepresenting the Content Server’s primary LDAP directory server. For groups, the jobsets the group_directory_id to the object name of the ldap config object.

The job also sets the user_global_unique_id property for users and thegroup_global_unique_id property for groups. In both cases, the property value is set to:



ldap_config_id:objectGUID

where ldap_config_id is the object ID of the ldap config object representing the LDAPserver from which the user or group was synchronized, and objectGUID is the unique IDof the user or group object in the LDAP server.

On-demand user synchronization

Content Server supports on-demand user synchronization, a feature allowing directoryusers to be synchronized in the repository between scheduled synchronization jobs.On-demand user synchronization means that users added between job runs may stillbe allowed to connect to a repository because they are synchronized—added to therepository—on-demand, when they attempt to connect to the repository.

On-demand synchronization is controlled by the setting of the dir_user_sync_on_demandproperty of the docbase config object. When the dir_user_sync_on_demand property is T(TRUE) and a new unsynchronized LDAP user attempts to connect to the repository, theserver searches for the user in the LDAP directory servers listed in the ldap_config_idand extra_directory_config_id properties of its server config object. (If the user provideda domain at connection time, only the directory server designated is searched.) If the useris found and authenticated, the user record is immediately copied from the directoryserver to the repository.

User authentication

This section describes the implementation and behavior of user authentication when anLDAP directory server is used to authenticate users.

Authentication and federations

To support user authentication, the member repositories must contain local LDAPconfiguration objects that point to the directory server used by the governing repositoryor a local replicated directory server. (A replicated directory server is a feature ofdirectory servers. It is not replicated using Content Server’s object replication.)



How Content Server determines which server to use forauthentication

A Content Server uses the following properties to authenticate an LDAP user:• dm_user.user_login_domain• dm_server_config.ldap_config_id• dm_server_config.extra_directory_config_idThe values in those properties are used for authentication in the following manner:

1. Content Server examines the value of user_login_domain.

For LDAP users, this property is set to the object name of the LDAP directory serverto be used for authenticating the user. This server is considered the primary LDAPserver for that user’s authentication.

Note: By default, if the user is not found in the repository, authentication fails.However, you can configure on-demand synchronization, so that users in theLDAP server that have not yet been synchronized (created in the repository) aresynchronized when they attempt to connect to the repository. Refer to On-demanduser synchronization, page 328, for more information.

2. Using the object name, Content Server obtains the object ID of the ldap config objectfor that server.

3. Content Server then examines the values in ldap_config_id andextra_directory_config_id to determine if the object ID of the ldap config objectis recorded in one of those properties.

• If the object ID is present, Content Server uses that LDAP server to authenticatethe user.

Content Server makes a number of attempts to connect to the primary LDAPserver. The value in the retry_count property of the ldap config object determineshow many times Content Server attempts to contact the chosen LDAP server.

If these attempts fail and there are secondary, failover LDAP servers configuredfor the primary LDAP server, Content Server attempts to use one of thoseservers. If there are no failover LDAP servers configured or if the user cannot beauthenticated using a failover server, user authentication fails. Authenticationfailover, page 330, describes how authentication failover servers are specifiedand chosen.

• If the object ID is not present in either property, Content Server determines if anyother authentication scheme can be used to authenticate the user.



LDAP authentication options

To authenticate an LDAP user, Content Server can perform the checking itself or invokean external password checking program called dm_check_password. You can use theexternal password checking program provided by Documentum or create a customprogram.

If Content Server performs the checking, you can config the LDAP server to use a secureconnection with Content Server. (You cannot use a secure LDAP connection if you areusing an external password checking program.)

If a secure connection is in use, when Content Server connects to the directory server forthe first time, the directory server identifies itself by returning its certificate to ContentServer. Content Server verifies the certificate against a certificate database. This is calledSSL server authentication. Documentum implements secure LDAP connections usingNetscape/iPlanet CSDK.

Implementing an LDAP directory server, page 332, contains instructions for setting upuse of an LDAP directory server.

Connection retry attempts

Two ldap config properties control how many times Content Server attempts to contactLDAP server chosen as the primary server for user authentication. These properties are:• retry_count• retry_intervalThe retry_count property defines how many attempts Content Server makes to contactthe LDAP server if the first attempt fails. This property is set to 3 by default. Youcan change the default. However, if you set this to 0, Content Server does not makemultiple attempts. Instead, Content Server immediately reports that it failed to contactthe primary LDAP directory server if the first attempt fails.

The retry_interval property defines the interval between each attempt. This property isset to 2 for the interval between the first and second attempts. You can change this value.You can also override the value by setting two environment variables. The variablesallow you to define different time intervals between each attempt. For instructions, referto Setting the retry_interval property for user authentication, page 343.

Authentication failover

You can configure secondary, failover LDAP servers for the primary LDAP servers usedfor authentication. Each primary LDAP server can have one or more failover LDAP



directory servers for authentication. However, an LDAP server created as a secondaryserver can only be designated as the failover server for one LDAP server. You cannot usethe same LDAP server as a failover server for multiple LDAP servers. Content Serverwill use the failover LDAP servers if the LDAP server initially chosen for authenticationis not available.

The failover behavior is controlled by two properties in the ldap config object. Thesetwo properties are:• failover_ldap_config_ids• failover_use_intervalThe failover_ldap_config_ids property records the object IDs of the secondary LDAPservers that will serve as the failover servers for the LDAP server represented by theldap config object.

The failover_use_interval property defines how long Content Server will use a failoverserver for authentication before attempting again to contact the primary LDAP serverchosen for authentication.

If the binding attempts to the primary server fail, Content Server attempts to contactthe secondary LDAP directory servers in the order that they are configured infailover_ldap_config_ids. After it binds to a secondary LDAP directory server, ContentServer uses that server for any subsequent attempts to authenticate the user for theduration of time configured in the failover_use_interval property. When the specifiedtime period has elapsed, Content Server attempts to contact the primary LDAP directoryserver for user authentication.

If the secondary LDAP directory server is unavailable or becomes unavailable withinthe specified use interval, Content Server contacts the remaining secondary LDAPdirectory servers. The servers are contacted in the order in which they are listed infailover_ldap_config_ids of the primary server. Content Server only contacts thesecondary LDAP directory servers that are configured for the primary LDAP directoryserver; it will not contact the LDAP servers listed in the failover_ldap_config_idsproperty of the secondary servers.

If all attempts to contact the secondary LDAP directory servers fail, Content Servercontacts the primary LDAP server again. If all LDAP servers are unavailable, userauthentication fails.

Note: LDAP failover is supported for user authentication only. LDAP failover is notsupported for user or group synchronization or on-demand user synchronization.

Failover for extra directory LDAP servers

When the user_login_domain or the user_global_unique_id points to one of the LDAPdirectory servers as configured in the extra_directory_config_id property, Content Serverwill use that LDAP directory server for authentication. If the extra LDAP directory server



is down, it checks for any secondary LDAP directory servers that might be configuredfor the extra LDAP directory server and attempts to contact them for user authentication.

Tracing failover

Failover details, including information on the switches between LDAP servers, arecaptured in the authentication trace in the Content Server log.

Implementing an LDAP directory server

This procedure creates an LDAP config object. If this is the first ldap config objectconfigured for the Content Server, it also sets the server’s ldap_config_id property inthe server config to the object ID of that object. If it is not the first ldap config objectcreated through that server, the object ID of the ldap config object is recorded in theextra_directory_config_ids property of the server config object.

To use an LDAP directory server with a repository:1. Install the LDAP directory server and add the user and group entries.

Refer to the documentation from the directory server’s vendor for instructions oninstallation and adding entries. Documentum does not support dynamic LDAPgroups.

2. Define the LDAP set-up values and optionally, mapped properties for the repository.Use the LDAP configuration facilities in Documentum Administrator. Refer toDefining the set-up values, page 333, for information about the set-up values.Mapping LDAP attributes to repository user or group properties, page 335,has information about defining mapped attributes. (Refer to the DocumentumAdministrator online help for instructions on using the user interface.)You must be connected as a Superuser to perform this step.

3. To use external password checking:

Note: This option is not supported if you are using a secure connection.

a. If the program will run on a UNIX platform, use the procedure in Building andinstalling an LDAP-enabled password checking program (UNIX only), page 341,to build and install an LDAP-enabled dm_check_password program.

b. Set the use_ext_auth_prog property in the LDAP config object.

c. Set user_validation_location in the server config object to the name of thelocation object pointing to the location of the dm_check_password program.

4. To use a secure connection:



Note: This option is not supported if you are using external password checking.

a. Enable secure connections using the SSL server authentication feature of theLDAP directory server.Refer to the documentation accompanying the directory server for instructionon enabling secure connections for the server. You must enable the SSL serverauthentication option.

b. Configure the LDAP set-up values for a secure connection.The secure connection properties, page 335, contains information about therequirements.

c. Download the certutil utility and the issuing Certificate Authorities all the wayup to the self-signed root certificate.Downloading certutil and the certificate authorities, page 340, containsinformation about obtaining the certutil utility and the Certificate Authorities.

d. Install the certificate database and Certificate Authorities.Installing the certificate database and CA certificates, page 340, containsinstructions.

5. Activate the dm_LDAPSynchronization job in the repository after ensuring thatthe default schedule meets your needs.The default schedule for the synchronization job is once a day at 4 a.m. Activatingand scheduling administration tools, page 453, contains instructions on changingthe schedule. Activating the dm_LDAPSynchronization job, page 341, containsinstructions on activating the job.

Dening the set-up values

Defining the set-up values creates an LDAP config object. To define these values, youmust have Superuser privileges and must use Documentum Administrator.

This section provides information and guidelines for defining the following set-upvalues:• Distinguished name and bind type, page 334• Search bases and filters, page 334• The secure connection properties, page 335For information about mapping LDAP attributes to repository properties, refer toMapping LDAP attributes to repository user or group properties, page 335.



Distinguished name and bind type

As part of the definition, you are asked to provide a distinguished name and passwordfor the Content Server. The name and password are used to ensure that the client askingfor user authentication is a valid client of the LDAP directory server. The client, eitherContent Server or the check password program, must provide a distinguished name andpassword to validate its request.

The distinguished name and password for the client are encrypted and storedin %DOCUMENTUM%\dba\config\repository_name\ldap_ldapconfigid.cnt($DOCUMENTUM/dba/config/repository_name/ldap_ldapconfigid.cnt). The file systempermissions on this file allow only the Documentum installation owner to access the file.

You are also asked what bind type you want to use. The bind type defines how theclient obtains a user’s distinguished name for authentication purposes. If the bind_typeproperty is set to bind_search_dn, the client uses the user’s operating system name toobtain the distinguished name from the directory server. If the bind_type property isset to bind_by_dn, the user’s distinguished name is obtained directly from the user’suser_ldap_dn property. The bind_type property defaults to bind_search_dn.

For more information about binding names, refer to the LDAP directory server’sdocumentation.

Search bases and lters

The set up values also include a definition of the search bases and filters. A search baseidentifies the point in the LDAP schema at which the search for a particular user orgroup begins. A filter is a defined condition that confines the users or groups in thesearch to a particular set.

Oracle Intranet Directory uses indexes to make directory properties available forsearches. Some properties are indexed by default. However, there are three propertiesthat you must explicitly index if you are using Oracle Intranet Directory as the LDAPdirectory:• createTimestamp• modifyTimestamp• operationTimeThe createTimestamp and modifyTimestamp properties must be indexed in order for theLDAP synchronization job to run correctly. The operationTime property must be indexedif you selected the Deactivate users option for the LDAP configuration. In addition tothese properties, you can also index additional properties for use in a search filter. TheOracle Intranet Directory Admin Guide contains instructions on indexing properties.

For more information about search bases and the format of a filter definition, refer to theLDAP directory server’s documentation.



The secure connection properties

There are three set-up values that must be defined to use a secure LDAP connection:• SSL mode• SSL port• Certifcate Database LocationSSL mode, represented in the ldap config object by the ssl_mode property, defineswhether the LDAP server is using a secure or non-secure connection. You must set thiswhen defining the LDAP set-up values. To configure a secure connection, select Secureas the SSL mode. When you select Secure as the SSL mode, the interface enables youto edit the SSL port field.

SSL port, represented in the ldap config object by the ssl_port property, identifies theport the LDAP server uses for the secure connection. This value is 636 by default. Youcan reset this.

Certificate Database Location, represented in the ldap config object by the certdb_locationproperty, identifies the location of the certificate database. The property value is the nameof the location object pointing to the certificate database. The value is ldapcertdb_loc.The directory that ldapcertdb_loc points to is %DOCUMENTUM%\dba\secure\ldapdb($DOCUMENTUM/dba/secure/ldapdb).

The certificate database location is set automatically when you define the LDAP set-upvalues.

Mapping LDAP attributes to repository user or group properties

LDAP directory servers enable you to define attribute values for user and group entriesin the directory server. Content Server supports mapping those directory server valuesto user and group properties in the repository. Using mapping automates setting userand group properties.

Mappings between LDAP attributes and repository properties are defined when youcreate the ldap config object in Documentum Administrator. You can map the LDAPvalues to system or user-defined properties. You can map a single directory value to arepository property or you can map multiple directory values to a single repositoryproperty.

For example, you can map the LDAP attribute homepage to a custom property calledweb_page. A common use of the ability is to map the LDAP attributes givenname and sn(surname) to the dm_user.user_name property.

To map multiple LDAP properties to a single repository property, you use an expression.For example, the following expression uses the LDAP attributes sn and givenname togenerate a user_address value:



${sn}_${givenname#1}@company.com

If the user’s sn (surname) is Smith and the givenname is Patty, the expression aboveresolves to [email protected]. The “1” at the end of givenname directs the systemto only use the first letter of the given name.

Note: You can specify an integer at the end of an LDAP attribute name in an expressionto denote that you want to include only a substring of that specified length in theresolved value. The integer must be preceded by a pound (#) sign. The substring isextracted from the value from the left to the right. For example, if the expression includes${sn#5} and the surname is “Anderson”, the extracted substring is “Ander”.

Values of repository properties that are set through mappings to LDAP attributes mayonly be changed either through the LDAP entry or by a user with Superuser privileges.

Note: Changing mappings for the user_name, user_login_name, or group_name afterthe user or group is synchronized for the first time is not recommended. Doing so maycause inconsistencies in the repository.

Required mappings

Content Server requires three properties to be defined for a user and one property tobe defined for a group. The mandatory properties are:

• user_name• user_login_name• user_address• group_nameWhen you define an LDAP configuration object in Documentum Administrator, defaultmapped values are provided for these properties. You can change the defaults, butyou must provide some value or mapping for these properties. Users cannot be savedto the repository without values for these three properties, nor can a group be savedto the repository without a group name.

If your LDAP directory server is Active Directory, user_name must be mapped to eithera common name (CN) or a display name. If user_name is not mapped to either a CNor display name, the repository inactivation operation does not function properly forthe users.

Dening mapping rules

For each mapped repository user or group property, you specify a mapping rule. Therule determines what is an acceptable mapped value for that property. If a mappedvalue fails to meet the criteria specified in the rule, the user or group is not created or



updated in the repository by the synchronization job. If there are multiple mappedproperties for a user or group and the mapping for any property fails to satisfy its rule,the LDAPSynchronization job rejects the user or group entry and does not update orcreate the user or group in the repository.

The choices for the mapping rule are:• Reject synchronization of the entry if the LDAP attribute is empty or has insufficient

characters.• Reject synchronization of the entry if the LDAP attribute is empty.• Never reject the entry.For the mandatory properties, the rule is set to reject entry synchronization if any LDAPattribute referenced in the property’s mapping is empty or has an insufficient number ofcharacters. You cannot change the rule for mandatory properties.

All rejected entries are captured in the LDAPSynchronizationDoc.txt file. Youcan find this file in %DOCUMENTUM%\dba\log\repository_id\sysadmin($DOCUMENTUM/dba/log/repository_ id/sysadmin).

Mapping guidelines

In addition, the following rules apply when mapping LDAP group or user attributesto a repository property:

• In expressions, spaces are not required between references to LDAP attributes due tothe bracket delimiter. If there is a space between mapped values, it will be appear inthe result of the mapping.

• The length of the expression mapped to a single repository property cannot exceed64 characters. Expressions that exceed 64 characters will be truncated.

The expression is recorded in the map_val property of the ldap config object. Thisproperty has a length of 64.

• All standard Documentum property lengths apply to the mappings. For example,the mapping string for user_name must resolve to 32 characters or less.

Repository storage of mappings

Mappings between LDAP attributes and repository properties are recorded in fiveproperties of an ldap config object. The properties are repeating properties and thevalues across the properties at any particular index position represent the mapping forone repository property. These ldap config properties are:• map_attr

This identifies the repository property that is the target of the mapping.



• map_val

This is the data that is mapped to the repository property. The data is one of: anLDAP attribute name, an expression referencing LDAP attributes, or an actual value.

• map_attr_type

This identifies the source of the property named in map_attr. The value is dm_user,a subtype of dm_user, or dm_group. Any user subtype identified in this propertymust also be identified in user_subtype of the ldap config object.

• map_val_type

This identifies the kind of data stored in map_value. It is one of A, meaning LDAPattribute; E, meaning expression; or V, meaning actual value.

• map_rejection

This records the rejection rule chosen for the mapping. Valid values are:

— 0, meaning synchronization always occurs even if an LDAP attribute referencedin the mapping is missing, empty, or does not have sufficient characters.

— 1, meaning that synchronization does not occur if an LDAP attribute in themapping is missing or empty. However, synchronization will occur even ifan LDAP attribute in the mapping has fewer characters than specified in themapping.

— 2, meaning that synchronization does not occur if an LDAP attribute referencedin the mapping is missing, empty, or has fewer characters than specified in themapping.

Mapping examples

This section provides some mapping examples that use expressions. In these examples,setting up some mappings for user properties is shown. If the example demonstates anerror, the reason the entry is rejected is explained. If the mapping is accepted and theentry is created, the example also shows how the values are recorded in the repositoryin the ldap config object. Assume that mapped entries are recorded in the ldap configobject in the order in which the accepted examples are shown.

Example 9-1. A simple expression mapped to default_folderSuppose you want to name the default folders for new users using the user’s givenname and surname. You can map the LDAP attributes givenname and sn to the defaultfolder. The expression for that mapping is:${givenname} ${sn}

In this case, the rejection rule is to reject the entry if either attribute is empty.

The values in the ldap config object properties are:



map_attr[0]=default_foldermap_val[0]=${givenname} ${sn}map_attr_type[0]=dm_usermap_val_type[0]=Emap_rejection[0]=1

For example, if a user entry in the LDAP server has a givenname of Patsy and a surnameof Doe, then the value set in default_folder by the synchronization job is Patsy Doe.

Example 9-2. An expression with a string limitationYou also want to map the given name and surname to the user_name property. However,you only want to include the first 2 characters of the given name and you want thesurname to appear first. The expression for that mapping is:${sn},${givenname#2}

Because the user_name is a mandatory property, the rejection rule is to reject the entry ifeither attribute is empty or if either has insufficient characters.

The values in the ldap config object properties are:map_attr[1]=user_namemap_val[1]=${sn},${givenname#2}map_attr_type[1]=dm_usermap_val_type[1]=Emap_rejection[1]=2

For a givenname of Patsy and an sn (surname) of Doe, the job sets the value in user_nameto Doe, Pa.

If the user’s givenname is less than 2 characters, the LDAPSynchronization job rejects theentry and the user is not created (or updated) in the repository.

Example 9-3. A more complex expressionNow, suppose you also want to create the user_address value by mapping the first initialof the given name and the full surname, separated by an underscore. The expression is:${givenname#1}_ ${sn}@mycompany.com

Because the user_address is a mandatory property, the rejection rule is to reject the entryif either attribute is empty or if either has insufficient characters.

The values recorded in the ldap config object properties are:map_attr[2]=user_addressmap_val[2]=${givenname#1}_${sn}@mycompany.commap_attr_type[2]=dm_usermap_val_type[2]=Emap_rejection[2]=2

For our user Patsy Doe, the job sets user_address to: [email protected]

Example 9-4. Mapping to a single attributeFinally, you want to map the LDAP attribute cn (common name) to the custom propertyuser_nickname. In this case, the rejection choice is to never reject the entry—some people



do not have nicknames and a nickname can be any length. There is no expressionrequired for this mapping. The values recorded in the ldap config object for the mappingare:map_attr[3]=user_nicknamemap_val[3]=cnmap_attr_type[3]=dm_usermap_val_type[3]=Amap_rejection[3]=0

Patsy Doe has no nickname, but the job creates her user object in the repository anyway,as the rule is to never reject for this mapping. Her best friend Elizabeth Dingle, however,has a nickname, Betty, which is recorded in the LDAP attribute cn. When the jobprocesses her LDAP entry, it sets Elizabeth’s user_nickname to Betty.

Downloading certutil and the certicate authorities

The certutil utility is used to create a certificate database and load CA certificates into thedatabase. Download the certutil utility from the following site:ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/

Copy the utility to %DM_HOME%\bin ($DM_HOME/bin).

You can obtain information about the utility from:http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html

Download CA certificates from the Web site of the vendor who provided the directoryserver with the SSL server certificate. You must download the Root Certificate Authorityand the issuing certificate authorities all the way up to the self-signed root certificate.

Installing the certicate database and CA certicates

Use the certutil utility to install the certificate database and the CA certificates.

To install the certicate database and CA certicates:1. Create the cert.db file.

On Windows:certutil -N -d %DOCUMENTUM%\dba\secure\ldapdb

On UNIX:certutil -N -d $DOCUMENTUM/dba/secure/ldapdb

2. Add the Root Certificate Authority to the database and provide the necessary trustlevel.



certutil -A -n "documentum ldap root" -t "C,C,C" -i rootcert.crt

3. Install the remaining CA certificates in the chain (if there are any):certutil -A -n "documentum ldap sub root" -t "C,C,C" -i subrootcert.crt

Activating the dm_LDAPSynchronization job

The dm_LDAPSynchronization job is installed in the inactive state. To activate the job,use Documentum Administrator. By default, the dm_LDAPSynchronization job executesonce a day at 4 a.m when activated. If needed, change the schedule before activatingthe job. Activating and scheduling administration tools, page 453, contains informationon how to change the schedule. Refer to Documentum Administrator online help forinstructions on activating a job.

Building and installing an LDAP-enabled password checkingprogram (UNIX only)

Use the following procedure to build and install an LDAP-enabled password checkingprogram. This procedure is only necessary if you want to run an LDAP-enabledpassword checking program on a UNIX platform.

To build an LDAP-enabled password checking program:1. Log in to the Documentum installation as the installation owner.

2. Change directory to the $DM_HOME/install/external_apps/checkpass directory.

3. Open the make_check_prog script in a text editor.

4. Set the do_ldap variable to -Dldap_authentication.do_ldap=-Dldap_authentication

5. Set the ldap_lib variable to $DM_HOME/bin.ldaplibdir=$DM_HOME/bin

6. Run the make_check_prog script.

7. Copy the dm_check_password program to $DOCUMENTUM/dba.

8. Log in to the host as the root user.

9. Change the ownership, group, and permissions of the dm_check_password program:chown root dm_check_passwordchgrp group_name dm_check_passwordchmod 6750 dm_check_password



group_name is the name of the default group.

Note on using Active Directory

If you are using Active Directory to perform LDAP user authentication (user_source is setto LDAP), the Active Directory can be configured in either mixed mode or native mode.

If you are not using LDAP authentication but have Active Directory set up to performdomain authentication (user_source is not LDAP), Active Directory must be configuredin mixed mode.

Note on using LDAP directory servers with multiple Content Servers

If multiple Content Servers are running against a particular repository, you must performsome additional steps to enable LDAP authentication regardless of the particularContent Server to which a user connects.

To enable LDAP authentication with multiple Content Servers:1. Install the Content Server software and create a Content Server and repository.

2. Install the LDAP directory server and follow the directions in Implementing anLDAP directory server, page 332 to properly configure the directory server andrepository for LDAP authentication.

3. Create the nonprimary Content Servers.

4. Using Documentum Administrator, connect to one of the nonprimary ContentServers.

5. Navigate to the existing ldap config object.

6. Re-enter the Binding Name and Binding Password for the LDAP directory server.

7. Save the ldap config object.

8. Perform steps 4 to 7 for each nonprimary Content Server.

Deleting an LDAP directory server from a repository

Deleting an LDAP config object from a repository removes the connection to the LDAPdirectory server represented by the config object. All users and groups synchronizedfrom that LDAP directory server are either deleted from the repository or convertedto non-directory users and groups. When a user is converted to a non-directory user,



the user_source property of the user object is set to inline password. The user is notautomatically supplied with a password and cannot connect to the repository until apassword is assigned by a System Administrator or Superuser or until the user accountis converted back to a directory user.

Setting the retry_interval property for userauthentication

The retry_interval property in an ldap config object defines the time interval betweenattempts by Content Server to contact the LDAP server represented by the ldap configobject. This value is used when the LDAP server is chosen as the primary server for auser’s authentication if the first attempt to contact the server fails. By default, the value isset to 5 seconds. So, if retry_count is set to 3 (its default), Content Server waits 5 secondsbetween each attempt to contact the primary LDAP server.

You can change the default. You can also override the property setting, to define differentintervals between each attempt.

To override the property setting, you set two environment variables:• LDAP_RECONNECT_TIME_SECONDS• LDAP_RECONNECT_INCREMENT_SECONDS

How the environment variables are used

If you set the LDAP_RECONNECT_TIME_SECONDS and LDAP_RECONNECT_INCREMENT_SECONDS, the server uses them to calculate the length of time betweenattempts to connect to the primary LDAP server. The formula for the calculation is:LDAP_RECONNECT_TIME_SECONDS + (retry_no * LDAP_RECONNECT_INCREMENT_SECONDS) = interval length

where LDAP_RECONNECT_TIME_SECONDS is the value in that variable; retry_nois the sequential number of the retry attempt. starting from 0 for the first attempt;and LDAP_RECONNECT_INCREMENT_SECONDS is the value in that environmentvariable.

For example, suppose that you set LDAP_RECONNECT_TIME_SECONDS to 3 andLDAP_RECONNECT_INCREMENT_SECONDS to 4, and that retry_count is set to 3.If the first attempt at connection fails, Content Server waits for 3 seconds before tryingagain:3+(0*4)=3



If the second attempt fails, Content Server waits 7 seconds before attempting for a thirdtime:3+(1*4)=7

How to set the environment variables

On Windows, set the variables as system-level environment variables.

On UNIX, set the variables by adding the following lines to the dm_start_repositorynamescript:LDAP_RECONNECT_TIME_SECONDS=value export LDAP_RECONNECT_TIME_SECONDSLDAP_RECONNECT_INCREMENT_SECONDS=value exportLDAP_RECONNECT_INCREMENT_SECONDS

where value is an integer representing a number of seconds.

You must restart Content Server to make the variable values take effect.

Enabling rst-time synchronization rules

First-time synchronization matches non-directory users and groups in the repositoryto directory users and groups in the LDAP directory server, converts them to directoryusers and groups and updates them from the directory server. For users, a matchoccurs when the user_name or user_login_name matches an LDAP entry (after applyingattribute mapping) and the value of user_login_domain is an asterisk (*), empty, or thename of the ldap config object.

To force the first-time synchronization rules to be used on a subsequent synchronization,set the first_time_sync property in the ldap config object to T (TRUE). You can do thisusing DQL or by checking First time sync in Documentum Administrator.

Binding LDAP users to a different directory server

You can bind existing LDAP users to a directory server different from their currentdirectory server.

To bind LDAP users to a different directory server:1. Delete the LDAP config object for the current directory server.

Use Documentum Administrator to delete the LDAP config object. This converts theusers and groups to non-directory users.



2. Ensure that the users and groups are represented in the new directory server.

3. Create a new LDAP config object corresponding to the new directory server.

4. Enable the LDAP synchronization job.When the synchronization job runs, the first-time synchronization rules are used.The non-directory users and groups are matched with the directory users andgroups and converted to directory users and groups.

Listing certicates in the certicate database

You can execute the certutil utility with the following command line to obtain a listing ofthe certificate authorities currently installed in the certificate database:certutil -L -d <certdb_file_directory_path>

where certdb_file_directory_path is the directory path of the certx.db file, and x is theversion number of the file.

For example, on Windows:certutil -L -d %DOCUMENTUM%\dba\secure\ldapdb

For example, on UNIX:certutil -L -d $DOCUMENTUM/dba/secure/ldapdb

Troubleshooting the synchronization job

To troubleshoot the LDAPSynchronization job, you can examine the regular job report. Ifmethod_trace_level is set is set to a value greater than zero for the job, it also generatesa log file for the job. Both the report and regular trace file can be easily accessed fromDocumentum Administrator. Reports and trace log files, page 451, contains instructionson viewing job reports and log files and information about where they are stored inthe repository.

If dfc.tracing.enable is set to T in the dfc.properties file, trace messages are also recordedin the DFC trace file.

Examining the ldap config object can also be useful when troubleshooting.

Obtaining the Content Server and Java version in use can also be helpful. You can obtainthe Java version using one of the following commands at the operating system prompt:java -fullversion

orjview -version



Finally, the ldapsearch utility, if available with your directory server, is a useful tool. Youcan pass the search base, class, and filter values from the ldap config object to the utilityand generate output that lists all users and groups that the LDAPSynchronization jobwill import into the repository.

Using authentication plug-insContent Server supports the use of authentication plug-ins. Authentication plug-ins areimplemented as DLLs or shared libraries, depending on the platform hosting the plug-in.

Two plug-ins are provided with Content Server. One supports RSA. The other supportsCA SiteMinder. Using the RSA plug-in, page 348, describes how to use the RSA plug-in.Using the CA SiteMinder plug-in, page 348, describes how to use the CA SiteMinderplug-in.

You can also write and install custom modules. Implementing a custom authenticationplug-in, page 349, describes how to write and install a custom module.

Plug-in scope

You can use a plug-in to authenticate users connecting to a particular repository or to anyrepository in the installation. The choice is defined by where the modules are installed.All plug-in modules are installed in a base directory. If they are installed directly in thebase directory, they are loaded by the servers for all repositories in the installation. Ifthey are installed in repository-specific directories under the base directory, they areloaded only by the servers for the specific repositories.

When you install Content Server, the procedure creates the default base directory,%DOCUMENTUM%\dba\auth ($DOCUMENTUM/dba/auth). When a repository iscreated, the procedure creates a subdirectory under the base directory specific to therepository. The repository configuration procedure also creates a location object, calledauth_plugin, that points to the base directory and sets the auth_plugin_location propertyin the server config object to the name of the location object.

Any plug-in installed in %DOCUMENTUM%\dba\auth ($DOCUMENTUM/dba/auth)is loaded into every server that starts, for all repositories in the installation. To use aplug-in only with a particular repository, place the plug-in in the repository-specifiecsubdirectory under%DOCUMENTUM%\dba\auth ($DOCUMENTUM/dba/auth). Forexample, if you want to use the CA SiteMinder plug-in with a repository called engr_db,move the CA SiteMinder module to the %DOCUMENTUM%\dba\auth\engr_db($DOCUMENTUM/dba/auth/engr_db) directory.



When a Content Server starts, it loads the plug-ins found in its repository-specificdirectory first and then those found in the base directory. If two or more plug-ins loadedby the server have the same identifier, only the first one loaded is recognized. Theremaining plug-ins with the same name are not loaded.

Identifying a plug-in for use

There are two ways to identify a plug-in to use for authentication:• Include the plug-in identifier in the connection request arguments• Set a user’s user_source property to the module’s plug-in identifierWhen Content Server receives a connection request, it checks to determine whether aplug-in identifier is included in the arguments. If not, the server examines the user’suser_source property to determine which authentication mechanism to use.

To use a plug-in to authenticate users for connection requests issued by an application,the application must prepend the plug-in identifier to the password argument beforesending the connection request to the DMCL.

Set the user_source property to a plug-in identifier when you want to use a plug-in toauthenticate a particular user regularly.

Dening a plug-in identier

Plug-in identifiers are defined as the return value of the dm_init method in the plug-inmodule’s interface. A plug-in identifier must conform to the following rules:• It must be no longer than 16 characters.• It cannot contain spaces or non-alphanumeric characters.• It cannot use the prefix dm_. (This prefix is reserved for Documentum.)For example, the following are legal identifiers:• myauthmodule• authmodule1• auth4modulTo include a plug-in identifier in a connection request, the application must prepend thefollowing syntax to the password argument:DM_PLUGIN=plugin_identifier/

Plug-in identifiers are accepted in all methods that require a password.



Using the RSA plug-in

The EMC RSA Plugin for Documentum allows Content Server to authenticate usersbased on RSA ClearTrust single sign-on tokens instead of passwords.

EMC Documentum Webtop and WebPublisher, and other Documentum WDK-basedapplications, support the RSA plug-in, with some configuration required. Theconfiguration requirements are described in the Web Development Kit and ClientApplication Development Guide.

The Content Server installation procedure stores the plug-in in the %DM_HOME%\install\external_apps\authplugins\RSA ($DM_HOME/install/external_apps/authplugins/RSA) directory. There is a README.txt file that describes how to install theplug-in. Table 28, page 348, lists the files for the plug-in on the supported platforms.

Table 28. RSA plug-in modules

Platform Plug-in module

Windows dm_rsa.dll

Solaris, Linux, and AIX dm_rsa.so

HP-UX PA-RISC dm_rsa.sl

HP Itanium dm_rsa.so

Using the CA SiteMinder plug-in

Documentum provides an authentication plug-in supporting authentication against aCA SiteMinder Policy Server. The plug-in enables validation of CA SiteMinder tokenssent to Content Server by Web-based clients.

Note: The CA SiteMinder plug-in is not supported on the HP Itanium platform.

EMC Documentum Webtop supports the CA SiteMinder Plug-in, with someconfiguration required. The configuration requirements are described in the WebDevelopment Kit Deployment Guide.

The Content Server installation procedure stores the plug-in in the %DM_HOME%\install\external_apps\authplugins ($DM_HOME/install/external_apps/authplugins/) directory. There is a README.txt file that describes how to install theplug-in. Table 29, page 349, lists the files for the plug-in on the supported platforms.



Table 29. CA SiteMinder plug-in les

Platform File

Windows dm_netegrity_auth.dll

Solaris, Linux, and AIX dm_netegrity_auth.so

HP-UX on PA-RISC dm_netegrity_auth.sl

The directory also includes the CA Siteminder header files and libraries, to allow you torebuild the plug-in if you wish.

To use the plug-in after you install it, include the plug-in identifier in connection requestsor set the user_source property in users to the plug-in identifier. (Identifying a plug-infor use, page 347, contains more information.)

The plug-in identifier for the CA SiteMinder plug-in is dm_netegrity.

Implementing a custom authentication plug-in

You can write and install custom authentication plug-ins. On a Windows platform, theplug-in must be a DLL. On a UNIX platform, the plug-in must be a shared library.

Authentication plug-ins that require root privileges to authenticate users are notsupported. (If you want to write a custom authentication mechanism that requires rootprivileges, use a custom external password checking program. Using a custom externalpassword checking program, page 319, contains instructions.)

Caution: This section outlines the basic procedure for creating and installing acustom authentication plug-in. Documentum provides standard technical supportfor plug-ins that are created and provided with the Content Server software, as partof the product release. For assistance in creating, implementing, or debugginga custom authentication plug-in, contact Documentum Professional Services orDocumentum Developer support.

To implement a custom authentication plug-in:1. Write the plug-in.

Writing the authentication plug-in, page 350, contains instructions.

2. Install the plug-in.Plug-in scope, page 346, contains information about where to install anauthentication plug-in.

3. Enable its use.



Identifying a plug-in for use, page 347, contains information about enabling plug-inuse.

4. Restart Content Server to load the new plug-in.

Writing the authentication plug-in

To write an authentication plug-in, you must implement the following interface:dm_init(void *inPropBag, void *outPropBag)dm_authenticate_user(void *inPropBag, void *outPropBag)dm_change_password(void *inPropBag, void *outPropBag)dm_plugin_version(major, minor)dm_deinit(void *inPropBag, void *outPropBag)

The inPropBag and outPropBag parameters are abstract objects, called property bags,used to pass input and output parameters.

The dm_init method is called by Content Server when it starts up. The method mustreturn the plug-in identifier for the module. The plug-in identifier should be uniqueamong the modules loaded by a server. If it is not unique, Content Server uses the firstone loaded and logs a warning in the server log file.

dm_authenticate_user performs the actual user authentication.

dm_change_password changes a user’s password.

dm_plugin_version identifies the version of the interface in use. 1.0 is the only supportedversion.

dm_deinit is called by Content Server when the server shuts down. It frees up resourcesallocated by the module.

You can find detailed comments on each of the interface methods in the dmauthplug.hheader file. All authentication plug-ins must include this header file. It is foundin %DM_HOME%\install\external_apps\authplugins\include\dmauthplug.h($DM_HOME/install/external_apps/authplugins/include/dmauthplug.h).

Additionally, all plug-ins must link to the dmauthplug.lib file. (OnSolaris, the dmauthplug.lib file is named dmauthplug.a.) This file isfound in %DM_HOME%\install\external_apps\authplugins\include($DM_HOME/install/external_apps/authplugins/include).

Internationalization

An authentication plug-in can use a code page that differs from the Content Server codepage. To enable that, the code page must be passed in the output property bag of thedm_init method. If the code page is passed, Content Server translates all parameters



in the input property bag from UTF-8 to the specified code page before calling thedm_authenticate_user or dm_change_password methods. The server also translatesback any error messages returned by the plug-in. A list of supported code pages isincluded in the header file, dmauthplug.h.

Tracing authentication plug-in operations

Plug-ins are responsible for writing their own trace files. The trace level is determined bythe DM_TRACE_LEVEL parameter in the input property bag. The initial value of theparameter is taken from the server start up flag -otrace_authentication. However, if auser issues a SET_OPTIONS administration method that changes the trace authenticationlevel, the new level will be reflected in the plug-in tracing.

The suggested location of the trace file is defined by the DM_LOGDIR_PATH parameterin the dm_init method.

Using an in-line passwordTo authenticate a user with an encrypted password stored in the repository, theuser_password property of the user object must be set. Use Documentum Administrator,DFC (IDfUser.setUserPassword), or DQL to set the password. When users are createdusing an imported LDIF file, passwords cannot be set in the LDIF file. You must set thepassword manually for any user created with an LDIF file.

Trusted loginsTrusted logins occur when the client is running on the same machine as the ContentServer, the client user is the installation owner, and the installation owner’s domain is thesame as that defined in user_auth_target.

Unied loginsUnified login is a feature available for Documentum Desktop users on Windowsplatforms. It allows the users to connect to a repository through Documentum Desktopusing their Windows login credentials.



To enable unied login:1. Set the a_silent_login property of the server config object to T.

2. Set the Use Windows Login option on the Desktop client interface for each repositoryfor which you want to use unified login.Refer to the Desktop online help for instructions.

For users on Webtop, you can configure single sign-on (SSO) on to provide functionalitysimilar to unified logins.

Managing encrypted passwordsContent Server and many of the internal jobs that manage repositoryoperations use passwords stored in files in the installation. These passwordsare stored in encrypted format by default. The passwords are encryptedusing the AEK when you install Content Server or create the job. Table 30,page 352, lists the password files whose content is encrypted by default.All the files are found in %DOCUMENTUM%\dba\config\repository_name($DOCUMENTUM/dba/config/repository_name). You must be the installation owner toaccess or edit these files.

Table 30. Password les encrypted by default

File Description

dbpasswd.txt This file contains one line with the database password used byContent Server to connect to the RDBMS. (This is password for therepository owner.)

docbase_name.cnt The file contains one line with the password used by an objectreplication job and the distributed operations to connect to therepository as a source or target repository.

If this file is present, the dm_operator.cnt file is not.

dm_operator.cnt The file contains one line with the password used by an objectreplication job and the distributed operations to connect torepositories.

If this file is present, docbase_name.cnt files are not used.



File Description

federation.cnt Contains the information, including passwords, used by agoverning repository server to connect to member repositories.The file is stored with the governing repository.

The format of the file’s content is:

member_repository_name:user_name:password:[domain]

ldap_object_id.cnt Contains the password used by Content Server to bind to an LDAPserver.

Using encryptPassword

Use encryptPassword to encrypt any password that you want to pass in encrypted formto the one of the following methods:

• IDfSession.assume • A method to obtain a new or sharedsession

• authenticateIn IDfSessionManager,IDfSession, or IDfClient

• IDfPersistentObject.signoff

• IDfSession.changePpassword

Passwords encrypted with encryptPassword cannot be decrypted explicitly by anapplication or user. There is no method provided to perform decryption of passwordsencrypted with encryptPassword. DFC decrypts those passwords internally when itencounters the password in the arguments of one of the above methods.

Passwords encrypted with encryptPassword are prefixed with DM_ENCR_PASS.

For complete information about using this method, refer to the Javadocs.

If you do not want to use encrypted passwords

If you do not want to use an encrypted password for a particular operation, use a texteditor to edit the appropriate file. (Table 30, page 352, contains a list of the files.) Removethe encrypted password and replace it with the clear text password.



Changing an encrypted password

If you find it necessary to change one of the encrypted passwords described in Table30, page 352, use the dm_encrypt_password utility to do so. This utility takes anunencrypted password, encrypts it, and writes it to a specified file. If the file is oneof the password files maintained by Content Server, the utility replaces the currentencrypted password in that file with the new password. You must be the repositoryowner to use this utility.

To encrypt or change a password in a password file maintained by Content Server,use the following syntax:dm_encrypt_password [-location AEK_location][-passphrase [passphrase]]-docbase repository_name -remote remote_repository_name |-operator | -redbms [-encrypt password]

To create or change an encrypted password in a file that you have created, use thefollowing syntax:dm_encrypt_password [-location AEK_location][-passphrase [passphrase]]-file file_name [-encrypt password]

The arguments have the following meanings:

-location AEK_location Identifies the location of the AEK fileto be used to encrypt the password. Ifthis argument is not set, the environmentvariable DM_CRYTPO_FILE must be set.

-passphrasepassphrase Specifies the passphrase used to protectthe AEK file.

If the argument is included without apassphrase, the utility prompts for apassphrase.

If the argument is not included, the utilityattempts to use the default passphrase.(The default passphrase can be definedwhen the dm_crypto_boot utility is runto set up the AEK.)

If a default passphrase is not defined,the utility checks the shared memorylocation, based on the location argumentor the default location, for an AEK orpassphrase. If neither is found in sharedmemory, the utility exits with an error.



-docbase repository_name Identifies the repository for which thepassword is being encrypted.

Do not include this argument if youinclude the -file argument.

-remote remote_repository_name Identifies the file to operate on as%DOCUMENTUM%\dba\config\repository_name\remote_repository_name

You must include the -docbase argumentif you include -remote.

-operator Identifies the file to operate on as%DOCUMENTUM%\dba\config\repository_name\dm_operator.cnt

You must include the -docbase argumentif you include -operator.

-rdbms Identifies the file to operate on as%DOCUMENTUM%\dba\config\repository_name\dbpasswd.txt

You must include the -docbase argumentif you include -rdbms.

-file file_name Identifies the file on which to operate.

Do not include this argument if youinclude the -docbase argument.

-encrypt password Defines the password to encrypt. Ifspecified, the password is encryptedand written to the file identified in the-file argument. If unspecified, the utilityencrypts the first line found in the file andwrites it back to the file.

For example, executing the utility with the following command line replaces thedatabase password used by the Content Server in the engineering repository to connectwith the RDBMS:dm_encrypt_password -docbase engineering -passphrase jdoe -rdbms

-encrypt 2003password

The AEK location is not identified, so the utility reads the location from theDM_CRYPTO_FILE environment variable. The passphrase jdoe is used to decrypt theAEK. The utility encrypts the password 2003password and replaces the current RDBMSpassword in dbpasswd.txt with the newly encrypted password.



This next example identifies a user-defined file as the target of the operation.dm_encrypt_password -passphrase jdoe

-file C:\engineering\specification.enc -encrypt devpass

The AEK location is not identified, so the utility reads the location from theDM_CRYPTO_FILE environment variable. The password jdoe is used to decrypt theAEK. The utility encrypts the password devpass and writes the encrypted value tothe file C:\engineering\specification.enc.

Limiting authentication attemptsContent Server supports an optional feature that allows you to limit the number of failedauthentication attempts. You define the maximum number of allowed failures andif a user exceeds that number, he or she is inactivated in the repository. The featureis controlled by two properties:• max_auth_attempt in the docbase config object• failed_auth_attempt in the user objectsThemax_auth_attempt property defines the maximum number of allowed authenticationfailures. Failures that count toward the maximum include not only failed connectionattempts, but also failures of any of the following methods on behalf of the user: assume,authenticate, changePassword, and signoff.

max_auth_attempt is set to 0 by default. To enable the feature, set the property to themaximum number of authentication failures you wish to allow.

The failed_auth_attempt property records how many authentication failures haveoccurred on behalf of a user. The property is set to 0 when a user is created and reset to 0each time a user is successfully authenticated.

The failed_auth_attempt property is incremented by one for each failure. Ifmax_auth_attempt is set to a positive number, Content Server inactivates theuser when the value in the user’s failed_auth_attempt property exceeds the valuein max_auth_attempt. The inactivation is recorded in the server log file. Thefailed_auth_attempt property is reset to 0 when a system administrator reactivates theuser by setting the user_state property to 0.

Note: If the maximum is lowered and a user has a value in failed_auth_attemptthat exceeds the lowered maximum, his or her account remains active. If the nextauthentication attempt for that user succeeds, the property is reset to 0. If it does notsucceed, the account is inactivated at that time.

If the user is the installation owner, inactivating the user shuts down the serverautomatically. For other users, inactivation puts restraints on any other open sessions theuser may have. After the inactivation, those sessions allow only assume and disconnect



operations. In a multi-repository distributed environment, inactivating a user in onerepository has no effect on any open sessions the user may have in another repository.

To disable this feature for a particular user, set the failed_auth_attempt property to-1 for the user.

Note: The property is set to -1 for the installation owner by default when ContentServer is installed.




Chapter 10Protecting Repository Objects

This chapter contains procedures for managing and using the features that provide security for theobjects in a repository. For a description of all security features supported by Content Server, refer toContent Server Fundamentals. This chapter includes the following topics:• Overview of repository security, page 359• Turning repository security on and off, page 362• Turning folder security on and off, page 363• Setting the default permission level for application-level control of SysObjects, page 364• Object-level permissions, page 364• Managing ACLs, page 368• Table permits, page 386• Auditing, page 387• Implementing signature support, page 417• Managing the encryption keys, page 429• Managing the login ticket key, page 436• Configuring a repository’s trusted repositories, page 437• Configuring login ticket use, page 437• Configuring application access control token use, page 439• Troubleshooting an application access control token, page 444

Overview of repository securityIn the Documentum system, every SysObject and SysObject subtype has associatedsecurity permissions that regulate access to the object. There are seven base access levels,ranging from no access to the permission to delete the object from the repository. Thereare also extended permissions that allow users to perform operations such as changingan object’s owner or an object’s location.


Protecting Repository Objects

Object-level permissions are initially set when the object is created. If they are notexplicitly set by the object’s creator, then the system provides a default value. During thelife of the object, its object-level permissions can be reset as many times as you like.

Enforcement of the permissions depends on whether security is turned on for therepository and the Access Control Lists (ACLs) associated with the object.

Note: Repositories are configured with security turned on by default.

ACLs

An ACL is a list of access control entries that define access permissions and restrictionsenforced for objects to which the ACL is applied. Every SysObject has one (and only one)associated ACL. When repository security is on, a user attempting to access a SysObject,such as a document, must own the object or be granted permission to access the objectthrough an entry in the ACL. If neither condition is true, the user cannot access theobject. (A user always has at least Read access to the objects he or she owns.)

The basic server functionality supports ACLs that allow you to define a user’s base andextended object level permissions. If the server was installed with a Trusted ContentServices license, you can also create entries in an ACL that:• Restrict a user’s access to a specific permission level even if other entries in the ACL

provide a higher level of access• Require a user to belong to a specified group or groups before allowing the user

access at his or her defined level• Require a user to belong to at least one of a set of groups before allowing the user

access at his or her defined level• Include a user-defined permission recognized by applicationsFor complete information about ACLS, their implementation and how to create them,refer to Managing ACLs, page 368.

Additional security options

In addition to the object-level permissions enforced using ACLs, Content Server supportsthe following security options.



Application-level control of SysObjects

Application-level control of SysObjects ensures that objects created by a particularapplication or client can only be modified by that application or other authorizedapplications. The feature is implemented using application codes. For more information,refer to Setting the default permission level for application-level control of SysObjects,page 364 in this manual and a more general description in Content Server Fundamentals.

Dynamic groups

A dynamic group is a group, of any group class, whose list of members is considered alist of potential members. A dynamic group is created and populated with members likeany other group. Whether or not a group is dynamic is part of the group’s definition. It isrecorded in the is_dynamic property and may be changed after the group is created.

When a session is started, whether Content Server treats a user in a dynamic group as anactual member is dependent on two factors:• The default membership setting in the group object• Whether the application from which the user is accessing the repository requests that

the user be added or removed from the groupThe is_dynamic_default property in a group object determines whether ContentServer treats a user in a dynamic group’s list of members as a group member or as anon-member. By default, the group setting directs Content Server to treat a user as anon-member of the group. If the application wants the user to be treated as a member,the application must issue an IDfSession.addDynamicGroup call. The alternative groupsetting directs Content Server to treat a user in the potential member list as membersof the group unless the application issues an IDfSession.removeDynamicGroup call.(For information about setting this property, refer to Changing the membership settingof a dynamic group, page 310.)

You can use dynamic groups to model role-based security. For example, suppose youdefine a dynamic group called EngrMgrs. Its default membership behavior is to assumethat users are not members of the group. The group is granted the privileges to changeownership and change permissions. When a user in the group accesses the repositoryfrom a secure application, the application can issue the session call to add the user tothe group. If the user accesses the repository from outside your firewall or from anunapproved application, no session call is issued and Content Server does not treat theuser as a member of the group. The user cannot exercise the change ownership or changepermissions permits through the group.

The session calls to add or remove users from a dynamic group can be audited. Theevents are named dm_add_dynamic_group and dm_remove_dynamic_group.



Folder security

Folder security is an optional level of security that is turned off or on using a propertyin the docbase config object. It not only checks permissions on the object, but also onone or more folders where the object is found. For more information, refer to Turningfolder security on and off, page 363.

User privileges

A user privilege defines a user’s capabilities within the repository. Each user hasdefined privileges. The default privilege is the lowest level, which gives a user no extraprivileges. The other privileges must be granted specifically. There are two sets of userprivileges, basic and extended. The highest basic privilege allows the user to read anyobject and to change the permissions on any object. The extended privileges define whocan set, view, or delete audit trails. Like object-level permissions, user privileges aregenerally set when the user is created in a repository and can be changed later if desired.User privileges are described in detail in Chapter 8, Users and Groups.

Table permits

The table permits define access to RDBMS tables through Content Server. There are fivelevels of table permits, from none to delete. Table permits can be set for three user levels:owner, group, and world. Table permits are described in Table permits, page 386.

Turning repository security on and offThe security_mode property in the docbase config object controls whether object-levelsecurity is imposed on the repository. This property has two possible settings, listed inTable 31, page 362.

Table 31. Repository security settings

Security setting Description

none There are no security checks—all SysObjectsare considered public objects.

acl Security is enforced using Access Control Lists(ACLs) defined for all SysObjects. This is thedefault.



By default, the property is set to acl. If the security mode is none, ACLs are notenforced. Neither, by extension, is folder security. The security setting is recorded in thesecurity_mode property of the docbase config object. Use DQL to change the securitysetting if desired.

Turning folder security on and offFolder security is a supplemental level of repository security. It is turned on by defaultwhen the repository is installed, but only functions when repository security is alsoturned on. When folder security is turned on, the server performs the permission checksrequired by repository security and for some operations, also checks and appliespermissions on the folder in which an object is stored or on the object’s primary folder.

Folder security does not prevent users from working with objects in a folder. It providesan extra layer of security for operations that involve linking or unlinking, such as creatinga new object, moving an object, deleting an object, and copying an object.

If folder security is turned on, the following security conditions are imposed in additionto any imposed by object-level security:• Creating new objects requires Write permission or Change Folder Links permission

on the folder or cabinet in which you want to store the new object.• Linking an object to a folder or cabinet requires Write permission or Change Folder

Links permission on the target folder or cabinet.• Unlinking an object from a folder or cabinet requires Write permission or Change

Folder Links permission on the affected folder or cabinet.• Moving an object using link and unlink methods requires Write permission or

Change Folder Links permission on both the folder or cabinet from which you areunlinking and the folder or cabinet to which you are linking the object.

• Removing objects from the repository with Destroy and Prune requires Writepermission or Change Folder Links permission for the object’s primary folder.

• Prune cleans up a version tree, generally removing multiple versions of an object.You must have Write permission or Change Folder Links permission on the primaryfolder of each version removed by a prune method.

• Copying an object using a saveAsNew method or with a drag and drop operationor a key sequence in the Documentum clients requires Write permission or ChangeFolder Links permission on all the folders or cabinets to which the new object will belinked. The new copies have all the same links as the object that was copied.

For example, suppose you fetch DocA, which is linked to Folder1 and Folder2. Thenyou use Saveasnew to create a copy of DocA. This copy has the same links as theDocA. When you issue the Saveasnew method, the server checks the permissions onFolder1 and Folder2 because you created new links to the copy in those folders.



Changing folder security

You can change the folder security setting from Documentum Administrator. Arepository’s folder security setting is recorded in the folder_security property in thedocbase config object.

Setting the default permission level forapplication-level control of SysObjects

Application-level control of SysObjects ensures that objects controlled by a particularapplication or client can only be modified through that application or other authorizedapplications.

When a user accesses an object, Content Server determines whether the user’s access isrestricted because the object is controlled by a particular application. If so, the serverchecks to determine if the user is accessing the object through the controlling applicationor another application authorized to handle the object.

If a user isn’t using the controlling application or another authorized application toaccess the object, then the user’s access permission for the object is controlled by thesetting in the default_app_permit property of the docbase config object or the user’spermission as defined in the ACL, whichever is more restrictive.

The default value for default_app_permit is Read, meaning that users who attemptto access a controlled object through an unauthorized application are granted Readpermission to the object unless the ACL for the object is more restrictive.

To change the default_app_permit setting, you must have Sysadmin or Superuserprivileges. The lowest level to which this property can be set is Browse.

Object-level permissionsThe object-level permissions consist of two sets of permissions: basic permissions andextended permissions. There are seven basic permissions and six extended permissions.

Object-level permissions are defined in ACLs. (For information about setting permissionsthrough ACL entries, refer to Managing ACLs, page 368.)



Basic permissions

The access levels provided by the basic permissions are hierarchical. That is, the accesscapabilities at each level include those of all the levels below. For example, if a user isgranted Version access, he or she can not only version the object but can also annotate itor examine its properties. Table 32, page 365, describes the seven access levels.

Table 32. Object-level permissions

Level Permission Description

1 None No access is permitted.

2 Browse The user can look at property values but notat associated content.

3 Read The user can read content but not update.

4 Relate The user can attach an annotation to theobject. For information about how thispermission level is applied to user-definedrelationships, refer to Note on the Relatepermit level, page 366.

5 Version The user can version the object.

6 Write The user can write and update the object.

7 Delete The user can delete the object.

Table 33, page 365, presents a simple overview of the operations allowed at eachpermission level.

Table 33. Permitted operations for object-level permissions

Permitted actions

Permit Fetch Getfile Annotate Check-out/in

Save Destroy

None

Browse X

Read X X

Relate X X X

Version X X X X

Write X X X X X

Delete X X X X X X



Note on the Relate permit level

Content Server allows users to create user-defined relationships between two objects.The two objects involved in the relationship are termed the parent and child. That is, theuser must, at the time that he or she creates the relationship, name one of the objects asthe parent and one as the child.

The system uses these designations in conjunction with the defined security level forthe relationship to enforce security. There are four security levels for user-definedrelationships: system, parent, child, and none.• If the system security level is defined, then you must have Sysadmin or Superuser

privileges to create, modify, or destroy any relationships of that type.• If the security level is parent, you must have at least Relate permission for the object

defined as the parent to create, modify, or destroy the relationship.• If the security level is child, you must have at least Relate permission for the object

defined as the child to create, modify, or destroy the relationship.• If the security level is none, there are no permissions necessary to create, modify, or

destroy the relationship.

Extended permissions

The access levels provided by the extended permissions are not hierarchical. Thesepermissions work together with the basic permissions.

Table 34, page 366, describes the extended permissions.

Table 34. Extended object-level permissions

Permission Description

change_location In conjunction with the appropriate base permissionlevel, allows the user to move an object from onefolder to another.

All users having at least Browse permission on anobject are granted Change Location permission bydefault for that object.

Note: Browse permission is not adequate to move anobject. For a description of privileges necessary to linkor unlink an object, refer to the descriptions of the linkand unlink methods in the Javadocs.

change_owner The user can change the owner of the object.



Permission Description

change_permit The user can change the basic permissions of theobject.

change_state The user can change the document lifecycle state ofthe object.

delete_object The user can delete the object. The delete objectextended permission is not equivalent to the baseDelete permission. Delete Object extended permissiondoes not grant Browse, Read, Relate, Version, or Writepermission.

execute_proc The user can run the external procedure associatedwith the object.

All users having at least Browse permission on anobject are granted Execute Procedure permission bydefault for that object.

Viewing extended permissions

Table 35, page 367, lists the computed properties that return information about theextended permissions.

Table 35. The extended permission computed properties

Property Single/ Repeating Description

_allow_execute_proc S A Boolean value indicating whetherthe user has the Execute Procedurepermission

_allow_change_location S A Boolean value indicating whetherthe user has the Change Locationpermission

_allow_change_state S A Boolean value indicating whetherthe user has the Change Statepermission

_allow_change_permit S A Boolean value indicating whetherthe user has the Change Permissionpermission



Property Single/ Repeating Description

_allow_change_owner S A Boolean value indicating whetherthe user has the Change Ownershippermission

_accessor_xpermit R The integer value of the extendedpermissions assigned to each user orgroup returned by _accessor_name.

The values, expressed as integers,are associated with the user or groupat the corresponding index level.For example, the permit level at_accessor_xpermit[4] is assignedto the user or group specified by_accessor_name[4].

_accessor_xpermit_names

R A list of the extended permissions, instring form, assigned to each user orgroup returned by _accessor_name

_xpermit R The integer value of the extendedpermissions that the current user orthe specified user has on the object

_xpermit_names S The list of extended permissions, instring form, that the current user orthe specified user has on the object.

_xpermit_list S A full list of the extended permissions,in string form, currently supported bythe server. Note that this computedproperty returns the same listregardless of the object ID.

Managing ACLsThis section describes how access control lists (ACLs) are implemented, how theybehave in the Documentum system, and how to work with them. The following topicsare included:• The ACL object type, page 369• How ACL entries are evaluated, page 374• Disabling ACL restrictive entries, page 377• External and internal ACLs, page 378



• System, public, and private ACLs, page 379• Template ACLs, page 379• Creating ACLs, page 380• How ACLs and objects are connected, page 380• The default ACLs, page 381• Modifying an ACL, page 384• Destroying an ACL, page 385

The ACL object type

Access control lists are stored as persistent objects of type dm_acl. The single-valuedproperties of an ACL object contain information about the ACL, such as its name and itsowner. The repeating properties define the access control entries. An ACL can containany number of access control entries.

Although ACLs are persistent objects having an object ID, they are not SysObjects. Youcannot version an ACL. If you modify an ACL, the server either overwrites the ACL withthe changes or copies the ACL and changes the copy. Which option it chooses dependson whether you reference the ACL directly to make the changes or reference an objectthat uses the ACL.

Access control entries

The access control entries are defined in the repeating properties in an ACL. The valuesat one index position across the properties represent one access control entry. Eachentry defines one of the following:• An access permission, extended permission, or both, for a user or group• An access restriction, extended restriction, or both, for a user or group• A required group• A required group set• An application permission• An application restriction

Note: Access permissions and extended permissions are supported by the basic ContentServer functionality. Creating restricting entries, required group entries, required groupset entries, or application entries requires a Trusted Content Services license.

An entry’s permit type identifies what is defined in the entry. The identification isrecorded in the r_permit_type property as an integer value. Access and extended



permissions for a given user or group are always stored in the same entry. The permittype for that entry is set to the integer value representing an access permission. Similarly,access restrictions and extended restrictions for a given user or group are alwaysstored in the same entry, and the permit type for that entry is set to the integer valuerepresenting an access restriction.

AccessPermission and ExtendedPermission entries

An access permission entry defines a base object-level permission for a user or group.The base object-level permissions are None, Browse, Read, Relate, Version, Write, andDelete. The permit type of an access permission entry is AccessPermit.

An extended permission entry defines an extended object-level permission for a useror group. The extended object-level permissions are: change_location, change_owner,change_state, change_permit, delete_object, and execute_proc. The permit type for anextended permission is ExtendedPermit.

In the ACL, both access permissions and extended permissions are stored in thesame entry, whose permit type is set to AccessPermit. However, when you grant orrevoke these permissions, you must specify whether you are granting or revoking anAccessPermit or ExtendedPermit.

AccessRestriction and ExtendedRestriction entries

Restriction entries restrict a user or group’s access. Creating entries of these typesrequires a Trusted Content Services license.

AccessRestriction entries

An access restriction entry removes the right to the base object-level permission levelspecified in the entry. The user or group members have access at the level up to thespecified restriction. Access restriction entries are useful when you want give a group aparticular base object-level permission, but restrict access for individual members or asubgroup of members. For example, suppose that Olivia is a member of the ProjTeamgroup and that an ACL has the following entries:ACCESSOR_NAME: ProjTeamPERMIT_TYPE: AccessPermitPERMIT_LEVEL: delete

ACCESSOR_NAME: OliviaPERMIT_TYPE: AccessRestrictionPERMIT_LEVEL: version



All members of the ProjTeam except Olivia have permission to delete objects governedby this ACL. Olivia’s permission is restricted to browsing, reading, or annotating theobjects even though she is a member of the ProjTeam. She cannot version the objects,or write or delete them.

The permit type for an access restriction entry is AccessRestriction.

ExtendedRestriction entries

An extended restriction entry restricts a user or the members of a specified group fromexercising the specified extended object-level permission. For example, suppose that anACL has the following entries and that HortenseJ is a member of the ProjTeam group:ACCESSOR_NAME: ProjTeam_grpPERMIT_TYPE: ExtendedPermitPERMIT_LEVEL: change_owner,change_permit

ACCESSOR_NAME: HortenseJPERMIT_TYPE: ExtendedRestrictionPERMIT_LEVEL: change_permit

In this example, HortenseJ is restricted from the change_permit permission even thoughshe is a member of a group whose members are granted this permission. She cannotchange the permissions of any object governed by this ACL.

The permit type of an extended restriction is ExtendedRestriction.

Storage in the ACL

In the ACL, both access restriction entries and extended restriction entries for aparticular user or group are stored in the same ACL entry, with the permit type set toAccessRestriction. However, when you grant or revoke an access restriction or extendedrestriction, you must specify whether you are granting or revoking an AccessRestrictionor ExtendedRestriction.

ApplicationPermission entries

You must have installed Content Server with a Trusted Content Services license to createapplication permission entries.

An application permission entry specifies a user-defined permission level that isrecognized by one or more user-written applications. Content Server does not recognizepermission levels identified in application permission entries. The user application mustrecognize and enforce any application permissions.

The permit type for an application permit entry is ApplicationPermit.



ApplicationRestriction entries

You must have installed Content Server with a Trusted Content Services license to createapplication restriction entries.

An application restriction entry identifies a user or group that is not allowed to exercisethe privileges associated with a user-defined application permission level. For example,suppose that HarleyJ is a member of the ProjTeam group and that an ACL has thefollowing entries:ACCESSOR_NAME:ProjTeam_grpPERMIT_TYPE:ApplicationPermitAPPLICATION_PERMIT: shred

ACCESSOR_NAME: HarleyJPERMIT_TYPE:ApplicationRestrictionAPPLICATION_PERMIT: shred

This ACL grants shred permission to the ProjTeam group, but restricts HarleyJ from thatpermission even though he is a member of the ProjTeam group.

Application restriction entries, like application permissions, are not recognized byContent Server, but must be enforced by the user-defined applications that enforce theapplication permissions.

The permit type of an application restriction is ApplicationRestriction.

RequiredGroup entries

You must have installed Content Server with a Trusted Content Services license to createrequired group entries.

A required group entry requires a user requesting access to an object governed by theACL to be a member of the group identified in the entry. For example, suppose anACL has the following entries:ACCESSOR_NAME: GaryGPERMIT_TYPE: AccessPermitPERMIT:Delete

ACCESSOR_NAME:ProjTeamPERMIT_TYPE:RequiredGroupPERMIT:NULL (not applicable)

ACCESSOR_NAME:EngrPERMIT_TYPE:RequiredGroupPERMIT:NULL (not applicable)

When GaryG attempts to access a document governed by this ACL, Content Serverchecks to determine whether he is a member of both the ProjTeam and Engr groupsbefore allowing access. GaryG must belong to both groups. If he is not a member of both



groups, the server does not allow him to access the document. The only exception to thisis a Superuser. A Superuser is not required to be a member of any required group toaccess a document.

The permit type for a required group entry is RequiredGroup. Entries of typeRequiredGroup cannot have an alias as the value for the r_accessor_name. A requiredgroup entry must have an actual group name for the r_accessor_name value.

RequiredGroupSet entries

You must have installed Content Server with a Trusted Content Services license to createrequired group set entries.

A required group set entry requires a user requesting access to an object governed by theACL to be a member of at least one group in the set of groups. An ACL that enforces arequired group set typically has multiple required group set entries. Each entry identifiesone group in the set. The user must belong to at least one of the groups identified bythe required group set entries in the ACL.

For example, suppose an ACL has the following entries:ACCESSOR_NAME: HollyHPERMIT_TYPE: AccessPermitPERMIT:Delete

ACCESSOR_NAME:ProjTeamPERMIT_TYPE:RequiredGroupSetPERMIT:NULL (not applicable)

ACCESSOR_NAME:EngrPERMIT_TYPE:RequirdGroupSetPERMIT:NULL (not applicable)

When HollyH tries to access an object governed by this ACL, Content Server determineswhether she is a member of either the ProjTeam or Engr group. She must be a memberof one of these groups to be given access to the object. The only exceptions to this areSuperusers. A Superuser is not required to be a member of any required group set toaccess a document.

Because required group set entries in an ACL are all considered to belong to that sameset, each ACL can have only one required group set.

The permit type for a required group set entry is RequiredGroupSet. Entries of typeRequiredGroupSet cannot have an alias as the value for the r_accessor_name. A requiredgroup set entry must have an actual group name for the r_accessor_name value.



How ACL entries are evaluated

This section describes how Content Server uses the entries in an ACL to evaluate accessfor users.

Note: A Content Server evaluates all entries in an ACL regardless of whether the serverwas installed with a Trusted Content Services (TCS) license or not. Lack of a TCS licenseonly restricts the ability to create or modify the ACL entries. Lack of a TCS license doesnot restrict the ability to evaluate such entries when present in an ACL.

Evaluation for non-owners and non-superusers

When a user who is not an object’s owner or not a Superuser requests access to aSysObject, Content Server evaluates the entries in the object’s ACL in the followingmanner:

1. The server checks that there is an AccessPermit type entry that gives the user therequested base or extended access level (browse, read, write, and so forth)

Note: Users are always given Read access if the user owns the document regardlessof whether there is an explicit entry granting Read access or not.

2. The server next checks that there are no AccessRestriction type entries that denythe user access at the requested level.

A restricting entry, if present, may restrict the user specfically or may restrict accessfor a group to which the user belongs.

3. If there are RequiredGroup type entries, the server checks that the user is a memberof each specified group.

4. If there are RequiredGroupSet type entries, the server checks that the user is amember of at least one of the groups specified in the set.

If the user has the required permission, with no access restrictions, and is a member ofany required groups or a required group set, the user is granted access at the requestedlevel.

How access is evaluated for object owners and Superusers

Content Server uses a different algorithm to evaluate access for owners of an object orSuperusers than it uses for users who do not own the object or are not Superusers.



Access evaluation for an object’s owner

Content Server uses the algorithm described in this section if the owner is not asuperuser. If the owner is also a superuser in the repository, the algorithm used isdescribed in Evaluating a Superuser’s permissions, page 376.

To determine access permissions for an owner who is not a superuser, Content Server:

1. Checks that the owner belongs to any required groups or a required group set.

If the owner does not belong to the required groups or group set, then the owner isallowed only Read permission as his or her default base permission and the owner isgranted none of the extended permissions.

2. Determines what base and extended permissions are granted to the ownerthrough entries for dm_owner, the owner specifically (by name) or through groupmembership.

3. Then, applies any restricting entries for dm_owner, the owner specifically (by name),or any groups to which the owner belongs.

4. The result constitutes the owner’s base and extended permissions.

• If there are no restrictions on the base permissions of the owner and thedm_owner entry does not specify a lower level, the owner has Delete permissionby default.

• If there are restrictions on the base permission of the owner, the owner has thepermission level allowed by the restrictions. Note that the owner cannot berestricted below Browse permission. An owner cannot be restricted to Nonepermission. If an entry attempts to restrict an owner to None, it is disregardedand the owner is given Browse permission by default.

• If there are no restrictions on the user’s extended permissions, the user has, atminimum, all extended permissions except delete_object by default. The usermay also have delete_object if that permission was granted to dm_owner, theuser by name, or through a group to which the user belongs.

Note: In addition to restrictions that may be imposed by AccessRestrictionentries, the owner_xpermit_default key in the server.ini file may impose arestriction on the extended permissions accorded to an object owner. Refer toowner_xpermit_default, page 101, for details.

• If there are restrictions on the user’s extended permissions, then the user’sextended permissions are those remaining after the restrictions are applied.

To illustrate how extended permissions are evaluated, here is an example. Suppose thatJorge is a member of the QA_grp and that Jorge opens a document he owns whoseACL entries are:



ACCESSOR NAME: dm_ownerACCESS PERMIT: deleteEXTENDED PERMIT: delete object

ACCESSOR NAME: QA_grpACCESS PERMIT: versionEXTENDED PERMIT: change location, execute procedure

ACCESSOR NAME: QA_grpEXTENDED RESTRICTION: change permit

By default, as owner, Jorge has all extended permissions except delete_object. Workingfrom this default, Content Server adds the extended permissions granted to dm_ownerand subtracts any extended restrictions that apply to Jorge or any groups to which hebelongs. In this example, Jorge gains the delete_object extended permission, but loses thechange_permit permission. His result set of extended permissions is:• change location• change owner• change state• execute procedure• delete object

Evaluating a Superuser’s permissions

When Content Server evaluates a Superuser’s access to an object, the server does notapply AccessRestriction, ExtendedRestriction, RequiredGroup, or RequiredGroupSetentries to a superuser. A Superuser’s base permission is determined by evaluating theAccessPermit entries for the user, for dm_owner, and for any groups to which the userbelongs. The Superuser is granted the least restrictive permission among those entries. Ifthat permission is less than Read, it is ignored and the Superuser has Read permissionby default.

A Superuser’s extended permissions are all extended permits other than delete_objectplus any granted to dm_owner, the Superuser by name, or to any groups to which theSuperuser belongs. This means that the Superuser’s extended permissions may includedelete_object if that permit is explicitly granted to dm_owner, the Superuser by name, orto groups to which the Superuser belongs.

Resolving multiple entries for a user

A user can have an entry as an individual and as a member of one or more groupsthat have access. In such cases, the user’s basic permission is the least restrictive of the



entries applicable to the user, and the user’s extended permissions are all applicableextended permissions.

For example, suppose that johnpq is a member of engr and qa_test groups. An ACL iscreated with the following entries:• User johnpq has an entry that gives him Delete permission.• The engr group has entries that give engr Write permission and the Change Location

and Change Permission extended permissions.• The qa_test group has entries that give qa_test Version permission and the Execute

Procedure extended permission.When the server evaluates the permissions given to johnpq by this ACL, it determinesthat johnpq has Delete permission on objects (the least restrictive) and Change Location,Change Permission, and Execute Procedure permissions (the combined set).

Disabling ACL restrictive entries

Caution: If a repository is licensed for Collaborative Services, do not disable the useof restrictive entries. Collaborative Services features do not work when restrictiveentries are disabled.

You can turn off the use of the following types of ACL access control entries that restrictaccess:• AccessRestriction• ExtendedRestriction• RequiredGroup• RequiredGroupSetUse of these entries can be disabled at the repository level by setting themacl_security_disabled property to TRUE. When that property is TRUE, only base andextended access permissions in an ACL are used to determine a user’s access to an object.

Disabling the evaluation of restrictive entries does not affect the ability to add suchentries to an ACL. It only stops enforcement of those entries.

Use Documentum Administrator to change the property’s setting. When Content Serveris installed with a Trusted Content Services license, the property is set to FALSE bydefault, meaning all ACL entries are used to evaluate access.



External and internal ACLs

ACLs are either external or internal ACLs, depending on whether they are created andmanaged externally by a user or internally by Content Server.

External ACLs are created explicitly by users and managed (modified or deleted) by theuser who created them. Typically, they are created using Documentum Administrator.You can also create them using DFC.

Internal ACLs are created by the server as a response whenever a user sets or modifiesan object’s permissions by directly referencing the object. This can occur in the followingsituations:• A user creates a SysObject and sets permissions for that object but does not explicitly

associate an ACL with the object.

In this situation, the server creates an internal ACL based on the default ACL definedat the server level (in the default_acl property of the server’s server config object). Itcopies that default ACL, makes the specified changes, and then assigns the copy tothe document. The copy is an internal ACL. (The default ACLs, page 381, containsinformation about the default ACLs.)

• A user creates a SysObject, associates an ACL with the object, and then modifiesthe access control entries in the ACL.

Content Server copies the ACL that the user associated with the object, makes thechanges in the copy, and then assigns the copy to the object, replacing the first ACL.The copy is an internal ACL.

• A user creates a document, does not assign an ACL to the document and issues auseACL method directing the server not to assign a default ACL, and then grantspermissions for the document.

Note: Important: When an internal ACL is created in this manner, the server doesnot automatically give the object’s owner or the world access to the object. In thesecases, the server sets the access for dm_owner and dm_world to 1 (None). Althoughthe server automatically gives an object’s owner Read access to the object, you mustgrant any higher access to the owner explicitly. You must also explicitly grant accessto dm_world in such cases.

• The user fetches an existing document and modifies its permissions

When this occurs, the server copies the document’s current ACL, makes the specifiedchanges in the copy, and then assigns the copy to the document. The new copy is aninternal ACL. In this way, the changes only apply to the specified document.

Internal ACLs are managed by the server. (Internal ACLs are called custom ACLs inContent Server Fundamentals.)



ACL names

An ACL name can be any valid name up to 32 characters long. (The Documentum SystemObject Reference Manual for all naming rules.)

Internal ACLs are named by the server. The server assigns a unique name in the format:

dm_acl_object_id

For example: dm_450000230006453f

If a user does not specify a name for an external ACL when he or she creates it, the serverassigns a name. The format is the same as for internal ACLs:dm_acl_object_id.

System, public, and private ACLs

Every ACL, whether external or internal, is either a public ACL, a system ACL, or aprivate ACL.

Public ACLs are ACLs that are available for anyone in the repository to use. Only theowner of a public ACL or a user with Sysadmin or Superuser privileges can modifyor delete the ACL.

System ACLs are a subset of public ACLs. They are public ACLs that are owned by therepository owner.

Private ACLs are ACLs that are available only to the users who create them. Any user inthe repository, except the repository owner, can create private ACLs. A repository ownerhas no private ACLs. All ACLs created by the repository owner are system ACLs. Onlythe owner of a private ACL, or a Superuser, can modify or delete the ACL.

After an ACL is created, only a Superuser can change its name or owner. However,because ACLs are referenced internally by their names and owners, it is stronglyrecommended that names and owners not be changed. If you do so, you must alsochange the references on all objects associated with the ACL.

Template ACLs

A template ACL is an ACL that has the acl_class property set to 1. Typically, templateACLs have one or more r_accessor_name values set to alias specifications. When usedin ACLs, aliases are place-holders for user and group names. Use template ACLs withaliases in applications that are intended to run in a variety of contexts. The aliases ensurethat the r_accessor_name values are always appropriate for the context of the application.



Note: An alias cannot be defined for the r_accessor_name value in ACL entries of typeRequiredGroup or RequiredGroupSet.

When you assign a template ACL to an object, the server copies the template, resolvesthe aliases and replaces them in the copy with the real names, and assigns the copy tothe object. The copy is always instantiated as a system-level ACL with an acl_classproperty value of 2. Users cannot change the copy. If a template ACL or the alias setused to resolve the template’s aliases is modified, the server automatically updates theinstantiated copies also.

Creating ACLs, page 380, contains information about creating an ACL template.

Creating ACLs

Use Documentum Administrator to create an ACL. You can use DFC to create an ACLalso, if you need to create one programmatically. You cannot use DQL to create an ACL.

You must have installed Content Server with a Trusted Content Services license to createentries of the following types in the ACL:• AccessRestriction and Extended Restriction• RequiredGroup and RequiredGroupSet• ApplicationPermit and ApplicationRestrictionYou must have Superuser or Sysadmin privileges or be the repository owner to create asystem ACL.

Any user in a repository except the repository owner can create a private or public ACL.ACLs created by the repository owner are always system ACLs.

Any user can create a template ACL. To create a template ACL, use DocumentumApplication Builder. You can also create one programmatically. If you do so, you mustset the acl_class property to 1 and set the r_accessor_name values to aliases.

The Content Server Fundamentals has a complete description of aliases, the format of analias specification, and a description of how the server resolves an alias.

How ACLs and objects are connected

Every object with an ACL has two properties that define which ACL is associated withthat object. The two properties are:



• acl_domain

This property identifies the owner of the ACL associated with the object. For privateACLs, this is the name of the user who created the ACL. For system ACLs, this is thename of the repository owner.

• acl_name

This property contains the name of the ACL. This will either be the name specifiedby the user who created the ACL or a string with the format:

dm_acl_object_id

For example: dm_4500025400002e7f

All internal ACLs have names that use their object IDs. External ACLs are generallynamed by the user who creates them. If the user does not name them, the server willname them using the same format that it uses for internal ACL names.

For SysObjects, these two properties define the ACL that contains the access permissionfor the object. For user and type definitions, the properties identify the associated defaultUSER and TYPE ACLs. (For types, these properties are found in the type’s associatedtype info object. Type info objects contain all the non-structural information about a type.There is one type info object for each type in the repository.)

The default ACLs

Businesses often want to define a default set of ACLs for users. A business may do thisas a business rule, to provide standard controls for document access. Default ACLs mayalso be provided as a service to end users, to make it easy for them to create new objectswithout worrying about security settings.

You can define three possible default ACLs:



• Folder

A folder ACL is an ACL that is associated with a folder or cabinet. A folder ACLhas two purposes:

— It can be used as the default ACL for any object that has the folder or cabinetas its primary folder.

Note: The primary cabinet or folder is recorded in an object’s i_folder_id[0]value. If an object is placed directly in a cabinet, instead of in a folder, then thecabinet’s object ID is found in i_folder_id[0], and the cabinet is both the object’sprimary storage location and its primary folder.

— It may be used to determine access rights to the folder or cabinet if folder securityit turned on for the repository.

A folder or cabinet’s default ACL is recorded in the object’s acl_name and acl_domainproperties.

• User

A user ACL is an ACL that is associated with a user object. When the repositoryowner or a user with Sysadmin or Superuser privileges creates a user in therepository, he or she also assigns or defines an ACL for the user. This ACL can beused as the ACL for any object created by the user. Because user objects are notsubtypes of SysObject, the ACL is not used to enforce any kind of security on theuser; a user’s ACL can only be used as a default ACL.

A user’s default ACL is recorded in the user’s acl_name and acl_domain properties.• Type

A type ACL is an ACL that is associated with the type definition of a SysObject orSysObject subtype. For example, you can define a default ACL for all objects of typedm_document. When a user creates a new document, he or she can assign the type’sdefault ACL to the new object. (If the type has no default ACL, the system willsearch the type hierarchy until it finds a type with a default ACL to assign.)

The type’s default ACL is defined in the type’s type info object. Each object typehas an associated type info object that contains all the non-structural informationabout the type.

There are no ACLS defined for object types by default. If you wish to use this optionas the default ACL, you must modify the object types to add the default ACL to eachtype definition. Use ALTER TYPE to add the ACL to the object type definition.When this default is being used, if a particular type has no defined ACL, ContentServer will traverse an object’s type tree to find an ACL. Consequently, if you areusing this option, it is recommended that, at the least, you define and ACL for thedm_sysobject type.



Creating default ACLs

A default ACL has no special properties. To create one, you simply create an ACL thathas the access control entries you wish and then associate the ACL with the appropriatefolder, user, or type info object.

It is recommended that you use Documentum Administrator to assign default ACLs tousers, cabinets, folders, and object types.

Caution: When you assign an ACL to a folder or type definition, be sure to assign asystem ACL if the folder or type is publicly accessible. If you assign a private ACLas the folder or type default, when a user who does not own the ACL attempts toassign it to an object, the operation will fail.

Assigning a default ACL to an object

There are two ways to assign a user, type, or folder ACL to an object. First, a user canassign one explicitly with a useACL method. Alternatively, if a user does not assign anypermissions to a new object, the server will automatically assign a one of the three basedon the value in the default_acl property of the server’s server config object.

Note: If the new object is a cabinet and the user does not explicitly assign an ACL, theserver assigns the user’s default ACL to the cabinet rather than the ACL specified inthe server’s default_acl property.

For details about using useACL, refer to Content Server Fundamentals. For informationabout setting the default_acl property, refer toIdentifying the default ACL for use,page 383.

Identifying the default ACL for use

If a user does not identify an ACL for a new object or does not explicitly indicate that theobject should not have a default ACL, the server attempts to assign the object a defaultACL. To identify which ACL to assign as the default, the server uses the value in thedefault_acl property of its server config object. This property contains an integer valuethat represents one of three candidate ACLs: 1, which is the folder ACL; 2, which is thetype ACL; or 3, which is the user ACL. A value of 4 means that there is no default ACL.

When you install Content Server, the default_acl property is set to 3, for the user ACL.This means that whenever a user creates an object and does not explicitly assign it anACL or grant it permissions, the server assigns the default ACL associated with theuser’s dm_user object to the new object.



You can change the default_acl property using Documentum Administrator or the API.

Modifying an ACL

As the owner of system ACLs, you may have to modify their access control entries. Forexample, as users join or leave the company, you may have to make appropriate changesin the system ACLs. To make these changes, you can use Documentum Administrator orgrant and revoke methods. Grant methods add an entry to an ACL. Revoke methodsremove entries for a particular user or group, or remove an extended permission.

You must have installed Content Server with a Trusted Content Services license tomodify, add, or delete the following types of entries:• AccessRestriction and Extended Restriction• RequiredGroup and RequiredGroupSet• ApplicationPermit and ApplicationRestriction

Adding entries

You can use Documentum Administrator or DFC to add an entry to a system ACL. Youcan only change an ACL if you own the ACL or have Superuser privileges. The changesyou make affect every object that uses the ACL.

If you use Documentum Administrator, refer to the online help for instructions. If youuse DFC, use a grant method (IDfSysObject.grant or grantPermit). For the syntax andusage notes, refer to the Javadocs.

Removing entries

You can use Documentum Administrator or DFC to remove access control entries. Youmust own the ACL or have Superuser privileges to remove entries from an ACL.

If you use Documentum Administrator, refer to the online help for instructions. If youuse DFC, use a revoke method (IDfSysObject.revoke or revokePermit). For the syntaxand usage notes, refer to the Javadocs.



Destroying an ACL

Removing ACLs from the repository must be done explicitly. The server does notautomatically remove ACLs that are no longer referenced by any object.

When you delete an ACL, Content Server also deletes any registry objects that referencethe ACL as the subject of an audit or event notification request.

Removing unreferenced external ACLs

When you decide that you no longer want to use an external ACL and it is not referencedby any objects in the repository, you can remove it from the repository by usingDocumentum Administrator or the IDfPresistentObject.destroy method.

To destroy an external ACL, the following conditions must be true:• You must be either the owner of the ACL or have Superuser privileges.• The ACL cannot be referenced by any objects in the repository.

Removing unreferenced internal ACLs

To remove unreferenced internal ACLs from the repository, use the dmclean utility.You must have Sysadmin or Superuser user privileges to run dmclean. You can rundmclean using:• Documentum Administrator• A DQL EXECUTE statement

The syntax is:EXECUTE do_methodWITH method = 'dmclean',arguments = '-no_content -no_note -no_wf_template'

The dmclean utility removes all internal ACLs that are not referenced by any object.Specifying -no_content, -no_note, and -no_wf_template ensures that only unreferencedACLs are removed from the repository. If these arguments are not included, the utilityalso scans the repository for orphaned content objects and files, orphaned note objects,and orphaned SendToDistributed workflow templates.. Orphaned note objects andworkflow templates are removed and a script is generated for removing orphanedcontent objects and files.



Table permitsThe table permits work in conjunction with object-level permissions to control access tothe RDBMS tables that underlie registered tables. To query an RDBMS table underlyinga registered table, users must have:• At least Browse access for the dm_registered object representing the RDBMS table• The appropriate table permit for the desired operationThe only exception to the above constraints applies to Superusers. Users with Superuserprivileges can issue SELECT queries against any RDBMS table, including unregisteredtables.

There are five levels of table permits, described in Table 36, page 386.

Table 36. Table permits

Level Permit Description

0 None No access is permitted

1 Select The user can retrieve data from the table.

2 Update The user can update existing data in the table.

4 Insert The user can insert new data into the table.

8 Delete The user can delete rows from the table.

The permits are not hierarchical. For example, assigning the permit to insert does notconfer the permit to update.

Setting table permits

The table permits are defined for owner, group, and world access through propertiesof the registered object representing the registered table. (ACLs are not used.) Theproperties are:• owner_table_permit• group_table_permit• world_table_permitThe owner is the user who created the registered object for the RDBMS table. The grouprepresents all users who belong to the group defined for the registered object. The worldis all users who are not the owner and not part of the registered object’s group.

When you create a registered table, the system sets the default permit level to Select forthe owner. The default permit level for the group and world levels is None. You canchange the defaults by resetting the properties.



You can set these properties at any time after you create the registered table. Theproperties have an integer datatype. When you set them, you define the integer valuethat corresponds to the permit level you want to assign. To assign more than one permit,you add together the integers representing the permits you want to assign and set theappropriate property to the total. For example, if you want to give the owner of aregistered table the insert and update permissions, you would assign the value “6” to theowner_table_permit property of the dm_registered object representing the RDBMS table.

Table permits and object-level permissions

You must have at least Browse permission for the dm_registered object that representsan RDBMS table in order to access the RDBMS table at any table permit level. However,other than this exception, table permits and object-level permissions do not affect eachother.

It is possible to have only Read access to a dm_registered object and have a Deletepermit for its underlying RDBMS table. Similarly, you might have Write access to thedm_registered object, but only a Select permit for its underlying RDBMS table.

Table permits and dump and load operations

Table permit values are carried over to the target repository when a registered tableis dumped and loaded.

AuditingAuditing is a security feature that allows you to monitor events that occur in a repositoryor application. Events are operations performed on objects in a repository or somethingthat happens in an application.

Auditing an event creates an audit trail, a history in the repository of the occurrence ofthe event. Creating an audit trail is a useful way to prove compliance with a businessrule. You can also use the information in an audit trail to:• Analyze patterns of access to objects• Monitor when critical documents change or when the status of a critical document

changes• Monitor the activity of specific usersThere are many ways to conduct auditing. For example, you can audit:



• All occurrences of a particular event on a given object or given object type• All occurrences of a particular event in the repository, regardless of the object to

which it occurs• All workflow-related events in the repository• All occurrences of a particular workflow event for all workflows started from a

given process definition• All executions of a particular job• All events in the repositoryDepending on the particular event and its target, you can also choose to audit an eventonly when the target is controlled by a particular application, attached to a particularlifecycle, or in a particular state in a particular lifecycle.

What events are auditable

There are two kinds of auditable events: system events and application events. Systemevents are events that Content Server recognizes and can audit automatically. Forexample, checking in a document can be an audited system event. Application eventsare events that are recognized and audited by client applications. For example, a useropening a particular dialog can be an audited application event. (A complete list ofauditable system events is in Appendix F, System Events.)

Audit trails

An audit trail is the history of an audited event. Each occurrence of an auditedevent is recorded in one entry in an audit trail. Audit trail entries are stored in therepository as persistent objects. Depending on the event, the objects are dm_audittrail,dm_audittrail_acl, or dm_audittrail_group objects. Audit trail entries store pertinentinformation about the events, such as when the events occurred, what objects wereinvolved, and who performed the actions.

Auditing properties

Whether property values are audited, and which properties are audited, is controlledby two factors:• Whether you register properties for auditing when you start auditing for the event.



• Whether the audit_old_values property in the docbase config object is set to trueor false.

The default for this property is T (true).

Note: On repositories created on RDBMS platforms with a page size of less than 8K, theaudit_old_values property is always false and cannot be set to true.

Table 37, page 389, summarizes the behavior for each combination of these factors.

Table 37. Behaviors for audit properties combinations

audit_old_values=T audit_old_values=F

One or moreproperties areregistered forauditing

Old and new values ofthe registered propertiesare recorded in theaudit trail entries.Ifaudit_old_values is T,page 389, describes thisoption in detail.

The values of the propertiesregistered for auditing are recordedin the attribute_list property of theaudit trail entry. If audit_old_valuesis F, page 390, describes this optionin detail.

No propertiesare registered forauditing

Old and new values ofany changed property,with the exception ofinternal (i_) properties,are recorded in theaudit trail entry. Ifaudit_old_values is T,page 389, describes thisoption in detail.

No property values are recorded inthe audit trail entry.

If audit_old_values is T

The audit_old_values property of the docbase config object is true by default. When theproperty is true and there are no properties registered for auditing, by default, changesto properties are audited for objects of type dm_document and any subtype of thedm_document type. The audit trail records changes for all properties except those whosenames begin with i_ or r_ prefixes. Custom properties are audited also.

Both old and new values are recorded in the audit trail by default. The property nameand new value are recorded in the attribute_list property of the audit trail entry. Theproperty name and old value are recorded in the attribute_list_old property of the audittrail entry. If the list of changed properties is longer than the length of the attribute_listand attribute_list_old properties, the overflow is recorded in an audit trail attrs object.



The audit trail entry records the values of the audited properties at the time the eventoccurred.

If you only want to audit specific properties, you can register those properties forauditing when you initiate auditing for the event. If you register specific properties forauditing, only changes to those properties are recorded in the audit trail. Any otherproperty that changes is not recorded in the audit trail.

To illustrate how auditing specific properties behaves, suppose you have a dm_documentsubtype called vendor_info with a property named vendor_number, and you want toaudit all changes in vendor_number. You also want to record both the current andold values of the vendor_number. First, ensure that audit_old_values is set to truein the docbase config object. Then, register the dm_checkin and dm_save events forauditing whenever a vendor_info object is the target of the checkin or save and identifythe vendor_number as an audited property. Each time a user checks in a vendor_infodocument, Content Server creates an audit trail entry. In that entry, the server records theold vendor_number value in the attribute_list_old property and the new vendor_numbervalue in the attribute_list property. For example, if the vendor_number is changed from048125 to 04837S the entries in the audit trail are:attribute_list = vendor_number="04837S"attribute_list_old = vendor_number="048125"

The attribute_list property records the new value of the property, When you specifyproperties for auditing only changed properties are audited. If the value of an auditedproperty is not changed, its value is not recorded in the audit trail entry.

If multiple properties are audited, the attribute_list property records the new values ofthe properties at the time the event occurred and the attribute_list_old property recordsthe previous values of those audited properties that changed. The audited propertiesand their values are recorded in a comma-separated list in each audit trail property.For example:attribute_list=vendor_number="04837S",vendor_type="hardware",

For application events, the application is responsible for recording the names and valuesof audited properties in the audit trail entry.

If audit_old_values is F

By default, if audit_old_values is F, the audit trail entry does not record changes toproperties unless you specifically register the properties for auditing when you registerthe event for auditing. If you register properties for auditing, then the propertiesare recorded in the attribute_list property of the audit trail entry. If the number ofaudited properties overflows the attribute_list property, the overflow is recorded in admi_audittrail_attrs object.



For example, suppose you have a subtype called vendor_info with an attribute namedvendor_number. You want to audit all changes to current vendors. To do so, registerthe dm_checkin event for auditing whenever a vendor_info object is the target of thecheckin and identify the vendor_number as an audited attribute. Each time a user checksin a vendor_info document, Content Server creates an audit trail entry and includes thevendor_number attribute name and value in the entry, providing you with informationthat identifies which vendor has changed information.

For system events, the values of audited attributes stored in the audit trail entries arethe values of the attribute after the audited object is saved to the repository. If the objectis versioned, the value is the value of the attribute in the new version. For example,suppose the vendor_info object type has an attribute called vendor_address. If you areauditing that attribute for checkin events, the new address appears in the audit trailentry. Similarly, if you audit the r_object_id attribute when checkin events are audited,the audit trail entry records the object ID of the new version of the document as theaudited value of the r_object_id attribute.

Default auditing

Content Server audits the following events by default:• All executions of methods that register or unregister events for auditing.

The event names are dm_audit and dm_unaudit.• All executions of a IDfPersistentObject.signoff method

The event name is dm_signoff.• All executions of an addDigitalSignature method

The event name is dm_adddigsignature. By default, audit trail entries createdfor the dm_adddigsignature event are not signed by Content Server. If you wantthose entries signed, register the event explicitly for auditing and set the argumentto require signing.

• All executions, successful or unsuccessful of an addESignature method.

If the execution is successful, the event name is dm_addesignature. The audit trailentries for the dm_addesignature event are signed by Content Server automatically.

If the execution fails, the event name is dm_addesignature_failed• Removal of an audit trail entry from the repository

A dm_purgeaudit event is generated whenever a destroy method is executed toremove an audit trail entry from the repository or a PURGE_AUDIT administrationmethod is executed. All dm_purgeaudit events are audited.

• User login failure



• A default set of events on objects of type dm_document and its subtypes. Thisdefault set of events is represented by the event named dm_default_set. This event isregistered against the docbase config object, and Content Server audits the events inthe set for dm_document type and its subtypes.Table 38, page 392, lists the eventsthat are included in this set.

Table 38. Events audited by the dm_default_event

Object type Audited events

dm_docbase_config

dm_archive dm_checkin dm_restore

dm_assemble dm_checkout dm_save

dm_bp_attach dm_destroy dm_setfile

dm_bp_demote dm_freeze dm_signoff

dm_bp_promote dm_link dm_unfreeze

dm_bp_resume dm_lock dm_unlink

dm_bp_suspend dm_mark dm_unlock

dm_branch dm_prune

Turning off default auditing

With the exception of user login failure and the dm_default_set events, there areno default registry objects for the events audited by default, and consequently, youcannot turn off auditing for them. There are registry objects for user login failures anddm_default_set.

To turn off auditing of either login failures or dm_default_set events, you must haveConfig Audit permission. Use one of the methods in the IDfAuditTrailManager interfaceto remove the appropriate registry object.

For log in failures, the event name is dm_logon_failure.

Turning off auditing of the dm_default_set event for the docbase config type turns offauditing of all events represented by the dm_default_set event. It is not possible to turnoff a subset of the events represented by dm_default_set. If you want to audit onlysome of those events, you must remove the registration for the dm_default_set event,and then add individual audit registrations for those events you do wish to audit. Theindividual registrations should name the specific object type as the target, rather thanthe docbase config type.



Modifying the default auditing

You can modify the default auditing by registering against the events audited by default.If you do, Content Server creates the audit trail entry based on the criteria you define forthe event and target. Similarly, you can remove your registration. Content Server willreturn to creating the default audit trail entry for the event and target.

Auditing system events

Content Server recognizes a wide range of system events. System events are associatedwith DFC methods, lifecycles, workflows, and jobs. (Refer to Appendix F, System Events,for a list of recognized system events.) When an audited system event occurs, ContentServer automatically generates the audit trail entry.

Note: You cannot use a system event to audit the DQL EXECUTE statement or a DQLINSERT or DELETE statement that modifies registered tables. If you want to audit suchevents, you must define and audit them as application events. Auditing applicationevents, page 393, describes how that is done.

To initiate auditing of a system event, you must have Config Audit privileges. You canuse Documentum Administrator or a method in the IDfAuditTrailManager interface.Instructions for using Documentum Administrator to register for auditing are found inthe Documentum Administrator online help. To use DFC, refer to the description in theIDfAuditTrailManager interface in the Javadocs.

Initiating auditing for a system event creates a dmi_registry object that records theevent’s registration for auditing.

Remember, the more events you audit, the more audit trail entries are created in therepository. To conserve space, audit the minimum number of events necessary andmanage the audit trail actively. (Refer to Removing audit trail entries, page 416, for moreinformation about audit trail management.)

Auditing application events

To audit application events, an application must recognize when the event occurs andcreate the audit trail entry programmatically. Application events are not recognizedby Content Server.

You can use a method in the IDfAuditTrailManager interface to create a dmi_registryobject for an application event. If you do, then applications can check for the presence ofthe registry object to determine whether or not to create the audit trail entry for the event.This is the most flexible way to administer and manage auditing of application events. To



turn auditing on or off for an application event, you simply create or destroy the event’sregistry object. You do not have to rewrite and recompile your application each time.

When the event occurs, use an IDfAuditTrailManager.createAudit method to create theaudit trail entry. If you use createAudit, Content Server sets all the entry propertiesexcept the generic properties (string_n and id_n) and attribute_list.

If you wish to record values for audited properties, create the audittrail object explicitly,instead of using a createAudit method. If the total length of the property names andvalues that you want to record is greater than the size of the attribute_list property, createthe audittrail attrs object also. If you require an audittrail attrs object for overflow, youmust create and save that object before you save the audittrail object.

If you create the audittrail object directly and set and save its properties, Content Serversets only the r_gen_source property automatically. The r_gen_source property indicateswhether the audit trail entry was created as a result of system event or an applicationevent. 0 indicates that the audit trail object was created by a user other than ContentServer.

Signing audit trail entries

As an added security feature, audit trail entries can be signed by Content Server. Signingan entry increases security by making it possible to detect whether the entry waschanged after it was saved to the repository. A signature on an audit trail entry appliesto the entry and an associated dmi_audittrail_attrs object, if one exists.

Use the signAudit argument when issuing a method to register for auditing to request asignature on audit trail entries for the event. This argument is false by default. Settingit to true directs Content Server to sign the audit trail entries generated by that auditregistration.

Note: You cannot set the signAudit argument to true if the event is “all”, “dm_all”,or “dm_all_workflow”.

Content Server uses the AEK (Administration Encryption Key) to sign the entries. TheAEK is a symmetric key that is created when Content Server is installed. To create thesignature, Content Server obtains the value of the _sign_data computed property for theaudit trail entry and generates a hashed value from that output. The hashed value is thenencrypted using the AEK. The final result is stored in the audit_signature propertyof the audit trail entry.

For information about how to use a signature to verify the security of an entry, refer toVerifying signed audit trail entries, page 415.



Conicting registration resolution

Sometimes Content Server might find multiple event registrations that could apply to asingle occurrence of an event. That is, the event might have multiple registry objects thatcould be used to generate the audit trail record. This can occur if:• One registration registers an object type and its subtypes for an event and another

registers one of the subtypes specifically for the event• One registration registers an object type for an event and another registration

registers a specific instance of the object type for the event.• One registration registers an object type for an event and defines a controlling

application and another registers the same object type for the same event but definesa policy ID.

If the conflict is between a general and a more specific registration (the first two caseslisted described), Content Server uses the more specific registry object to generate theaudit trail entry.

For example, suppose you register the dm_save event for the dm_document objecttype with the auditSubtypes argument set to true and do not identify any propertiesin the attributeList argument. And, suppose you have also registered the dm_saveevent on sop_doc, a dm_document subtype and have identified three properties in theattributeList argument. When an sop_doc document is saved, Content Server uses theregistry object that identifies the sop_doc object type as the target of the event rather thanthe more general registry object that identifies dm_document objects as the target.

In the third situation, in which the difference in the registrations is that one has acontrolling application defined and the other has a policy ID defined, Content Server usesthe registration that defines a controlling application to generate the audit trail entry.

Suppose there are two registry objects for the dm_save event for the dm_documentobject type. One registration defines the controlling application as dm_dcm and does notidentify any properties for inclusion in the audit trail entry. The other defines a policyID and defines the property list as “title,keywords”. When a save event occurs on adocument controlled by dm_dcm, Content Server creates the audit trail entry based onthe registration that includes the controlling application definition. Consequently, theaudit trail entry does not include the values of the title and keywords properties.

If you are unsure which registration was used to generate an audit trail entry, examinethe registry_id property of the audit trail entry. The property records the object ID of thedm_registry object that generated the event.



Stopping auditing

To stop auditing a system event, use the methods in the IDfAuditTrailManager interface.You can also use these methods to destroy a registry object that represents an applicationevent. Stopping auditing through Documentum Administrator or using DFC methodsdestroys the registry object that represents the event.

You must have Config Audit privileges to stop auditing by destroying the registryobject for an event.

For information about using the IDfAuditTrailManager interface, refer to the Javadocs.

Viewing audit trails

Use DocumentumAdministrator to view an audit trail. What you can view is determinedby your privileges and the value in an audit trail entry’s i_audited_obj_class property.The following rules are applied to entries for system events:• Users with Superuser or View Audit privileges can view any audit trail entry.• Users without Superuser or View Audit privileges can view audit trail entries for

SysObject-related system events (i_audited_obj_class is set to 0) if they have at leastBrowse privileges for the audited object.

• Users without Superuser or View Audit privileges cannot view audit trail entries forACL, group, and user-related events (i_audited_obj_class is set to 1, 2, or 3)

• Users who are the owner of an audited object can always view audit trail entriesfor the object.

All users, regardless of privilege level, can view audit trail entries for application events.

If you do not have Superuser or View Audit privileges, the following properties of theaudit trail entries are excluded from view for both system and application events:

• acl_name • object_name

• acl_domain • object_type

• attribute_list • owner_name

• attribute_list_old • session_id

• attribute_list_id • version_label

• chronicle_id



Querying and retrieving audit trail entries

You can query and retrieve audit trail objects directly, using a DQL SELECT statement orDFC. Which audit trail objects are returned is subject to the same restrictions as thoseimposed for viewing audit trail entries through Documentum Administrator, with oneexception.

You must have Superuser or View Audit privileges to query or retrieve objects oftype dmi_audittrail_attrs. If you do not have either of those privileges and wish toretrieve all audited property values for a particular event, including any stored in admi_audittrail_attrs object, query the computed property, _property_list_values.

Interpreting audit trails of DFC method, workow, andlifecycle events

Audit trail entries for DFC method, workflow, and lifecycle events are stored in therepository as audit trail objects. Each audit trail object records one occurrence of aparticular event. The properties in an audit trail object describe the event.

Audit trail properties with a common purpose

An audit trail object has many properties that are used by all system events and areavailable for use in user-defined audit trail entries. The properties that have a commonpurpose for entries generated by Content Server include all the properties other than thestring_x and id_x properties. For example, the user_id property contains the dm_userobject ID of the user who caused the event to happen.

Properties available for varied purposes

Each audit trail object has five ID-datatyped properties and five string properties. Theseproperties are named generically, id_1 to id_5 and string_1 to string_5. In audit trailentries for workflows and lifecycle events, Content Server uses these properties to storeinformation specific to the particular kinds of events. Some of the events generated bymethods other than workflow or lifecycle-related methods use these generic propertiesand some do not. A user-defined event can use these properties to store any informationwanted.



Use in audit trails for events generated by non-workow or lifecycle methods

Table 39, page 398, describes how Content Server uses the generic string and id propertiesin audit trails generated by methods other than workflow or lifecycle methods. Onlythose events that use the generic properties are listed. If an event is not listed in this table,Content Server does not use the generic properties in audit trails generated by that event.

Table 39. Usage of generic properties by API events

Event Generic property use

Adddigsignature string_1, User name provided as an argument tothe method or the name of the connected user if theuser argument was not specified

string_2, Reason for the signing

Addesignature (success) string_1, User who signed the object

string_2, Justification text

string_3, The number of the signature, the nameof the method used to generate the signature, andthe pre-signature hash argument. For example:2/PDFSign/pre-signature hash_argument

string_4, Hash of the primary content (page number0)

string_5, Hash of the signed content. Note that ifthe signed content is the primary content (ratherthan a rendition), this value is the same as the hashin string_4.

Addesignature (failure) string_1, User who signed the object

string_2, Error message indicating why the failureoccurred

string_3, The number of the signature, textindicating the reason for the audit entry, andthe pre-signature hash argument. For example:2/ENTRY_F0R_FAILED_ESIGN_OPERATION/pre-signature hash_argument




Addnote id_1, Object ID of document to which the note isattached

id_2, Object ID of the note

Addrendition id_1, Object ID of the content object

string_1, Format of the rendition

string_2, Either “Replace Old Rendition” or “SaveNew Rendition”, depending on whether the addedrendition replaces an existing rendition or is a newrendition.

Addretention id_1, Object ID of the retainer object

Appendcontent See Setfile

Appendfile See Setfile

Appendpart id_1, Object ID of the virtual document to whichyou are appending the component

id_2, Object ID of the component

id_3, Object ID of the containment object that linksthe virtual document and the component

string_1, The version label of the component

string_2, The use_node_ver_label setting

string_3, The follow_assembly setting

string_4, The copy_child setting

Assume string_1, The success or failure of the userauthentication

Audit string_1, The audited operation

Authenticate string_1, The success or failure of the userauthentication

Bindfile See Setfile

Checkin id_1, Object ID of the version from which the newversion created by the checkin was derived




Connect string_1, Identifies the authentication mechanismused to authenticate the user. Values are:ticket, for ticketed logintrusted, for trusted loginunified, for Windows unified loginOS password, for OS password authenticationplugin password, for plugin authenticationLDAP password, for LDAP authenticationOS external, for authentication with OS passwordby an external password checking programLDAP external, for authentication by an externalpassword checking program that uses LDAP

string_4, Host name of the client machine fromwhich the user connected

string_5, IP address of the client machine fromwhich the user connected

Destroy Destroy uses the generic properties only when theobject to be destroyed is a dm_audittrail object or asubtype of dm_audittrail. For details, see the PurgeAudit entry in this table.

Getcontent See Getfile

Getfile id_1, Object ID of the content object for the contentfile

Getlogin id_1, Object ID of the user object representing theuser identified in string_1.

string_1, Name of the user for whom the ticket wasrequested

Getpath See Getfile

Insertcontent See Setfile

Insertfile See Setfile




Insertpart id_1, Object ID of the virtual document to whichyou are inserting the component






string_4, The copy_child setting

Kill id_1, Session ID of the terminated session

Link id_1, Object ID of the folder to which the object islinked.

id_2, Object ID of the linked object

string_1, Name of the folder to which the object islinked

string_2, Name of the linked object

Logon Failure string_1, User_name value

string_2, User name as entered by the user

Note: string_1 is empty if the user enters an invaliduser name. If the user enters a valid user name,string_1 and string_2 are the same value.

Mark string_1, Name of the version label

Note: One audit trail entry is created for each labelassigned in the Mark method.

Move Content string_1, Name of the storage area from which thecontent was moved

string_2, Name of the storage area to which thecontent was moved.

id_1, Object ID of the SysObject containing themoved content file.




Purge Audit string_1, the time_stamp value of the first deletedaudit trail entry in the transaction

string_2, the time_stamp value of the last deletedaudit trail entry in the transaction

string_3, the actual number of audit trail entriesdeleted in the transaction

string_5, the list of arguments defined in the methodcommand line

id_1, the object ID of the first audit trail entrydeleted by the transaction

id_2, the object ID of the last audit trail entry deletedby the transaction

Removecontent id_1, Object ID of the content object representing thecontent file removed from the SysObject.

string_1, The page that was removed.

Removenote id_1, Object ID of the objec to which the note wasattached

id_2, Object ID of the note

Removepart id_1, Object ID of the virtual document from whichyou are removing the component



string_1, If specified, the order_no that identifies thecomponent to be removed

Removerendition id_1, Object ID of the content object representingthe rendition’s content file

string_1, Rendition format

Removeretention id_1, Object ID of the retainer object

Setcontent See Setfile




Setfile id_1, Object ID of the content object for the contentfile

string_1, Name of the API

string_2, Name of the file (unused forAppendcontent, Bindfile, Inserttcontent, Setcontent)

string_3, Page number of the content file

string_4, Format of the content file

Setpath See Setfile

Setoutput id_1, Object ID of the workflow

id_2, Object ID of the work item

string_1, Activity sequence number

string_2, Activity name

string_5, Output port name

Setretentionstatus string_1, Original status of the retainer

string_2, New status of the retainer

Unaudit string_1, Name of the operation from whichauditing was removed

Unlink id_1, Object ID of the folder to which the object islinked.

id_2, Object ID of the linked object

string_1, Name of the folder to which the object islinked

string_2, Name of the linked object




Unmark string_1, Name of the version label.

Updatepart id_1, Object ID of the virtual document into whichyou are inserting the component






string_4, The copy_child setting, if specified

string_5, The order_no if specified

Use in lifecycle audit trails

Table 40, page 404, describes how Content Server uses the generic string and idproperties in audit trails generated by lifecycle events.

Table 40. Usage of generic properties by lifecycle events


Attach id_1, Object ID of the business policy

string_1, State to which object is being attached

Demote id_1, Object ID of the business policy

string_1, State from which object was demoted

string_2, State to which the object was demoted

Install Does not use the generic properties.

Promote id_1, Object ID of the business policy

string_1, State from which object waspromoted

string_2, State to which object was promoted




Resume id_1, Object ID of the business policy

string_1, State to which the object is returned

Suspend id_1, Object ID of the business policy

string_1, The object’s business policy state atthe time of suspension

Uninstall Does not use the generic properties.

Validate string_1, Number of states in the businesspolicy.

Use in workow audit trails

Table 41, page 405, describes how Content Server uses the generic string and idproperties in audit trails generated by workflow events.

Table 41. Usage of generic properties by workow events


Abort workflow id_1, Object ID of the workflow

Add attachment id_1, Object ID of the workflow

id_5, Object ID of the attached object

string_5, Name of the attached object

Add note id_1, Object ID of the workflow

id_5, Object ID of the note object



string_5, Value of the note’s keep_permanentflag




Add package id_1, Object ID of the workflow

id_2, Object ID of the work item (used onlyif addPackage is called with the work itemreferenced in the arguments)

id_5, Object ID of the document in thepackage. If there are multiple documents,there are a corresponding number of audittrail entries, each with a different value inid_5.



string_3, Names of the components identifiedin the componentIds argument. This is onlyset if package control is not enabled.

string_5, Package name

Auto Delegation of Activity Failed id_1, Object ID of the workflow



Auto Transition of Activity id_1, Object ID of the workflow



string_5, Index position of the TRUE conditionin the dm_cond_expr object examined for thetransition.

(This event is supported for backwardscompatibility. The Portselect event providesadditional or more current information aboutan automatic transition.)




Change activity instance state id_1, Object ID of the workflow


id_5, Value in the r_exec_results property ofthe work item



string_5, Value of the return_value propertyof the work item

Change process state string_3, Previous state

string_4, New state

Change

supervisor

id_1, Object ID of the workflow

string_4, New supervisor name

string_5, Old supervisor name

Change workflow state id_1, Object ID of the workflow

string_3, Previous state

string_4, New state

Change work item priority id_1, Object ID of the workflow that containsthe work item


string_1, Sequence number of the activity thatgenerated the work item

string_2, Name of the activity

string_3, Old priority value

string_5, New priority value




Completed work item id_1, Object ID of the workflow


id_5, For automatic work items: ObjectID of the document containing the resultsof the execution. (This is the value in ther_exec_results property.)



string_3, Comma-separated list of work itemproperties and their values. The properties are:user_time, user_cost, a_wq_name, a_wq_flag,and a_wq_doc_profile. (a_wq_name anda_wq_doc_profile are enclosed in doublequotes)

string_5,Value in the return_value propertyof work item

Create workflow id_1, Object ID of the workflow

string_4, Supervisor name

string_5, Name of the workflow

Delegated work item id_1, Object ID of the workflow




string_3, Activity type (Manual or Automatic)

string_4, Name of the workqueue, if any, towhich the task is assigned

string_5, Name of the user to which the taskis delegated

Finish workflow id_1, Object ID of the workflow

Install workflow or activity definition Does not use the generic properties.




Invalidate workflow or activitydefinition

Does not use the generic properties.

Pause work item id_1, Object ID of the workflow




Port select id_1, Object ID of the workflow



string_5, Selected output port. If multipleports are selected, a corresponding numberof audit trail entries are created, each with adifferent value in string_5.

Pseudo-completed work item id_1, Object ID of the workflow


string_1, Sequence number of the activity

string_2, Name of the activity

string_3, State of the work item prior topseudo-completion

string_5, Name of the task owner

Remove attachment id_1, Object ID of the workflow

id_5, Object ID of the attached object that wasremoved

string_5, Name of the attached object that wasremoved




Remove note id_1, Object ID of the workflow

id_5, Object ID of the note object. If theremove note event is triggered by a removepackage event that removes a package withmultiple notes attached to its components,there are multiple remove note audit trailentries, each with a different id_5 value.



Remove package id_1, Object ID of the workflow




string_5, Package name

Repeat work item id_1, Object ID of the workflow




Resume work item id_1, Object ID of the workflow







Save a workqueue id_1, Object ID of the workqueue

id_2, Value of the wq_policy_id property ofthe workqueue object

string_1, Name of the workqueue

string_2, Number of users in the workqueue

Save a workqueue policy id_1, Object ID of the workqueue policy object

string_1, Name of the workqueue policy

string_2, Maximum threshold of the policy

Selected work item

(a work item has been acquired)

id_1, Object ID of the workflow




string_4, Name of the workqueue, if any, towhich the task is assigned

Sign off work item id_1, Object ID of the workflow



string_1, For Windows, the user’s domain anduser name (used to validate signature)

string_5, Text provided by reason argument inSignoff method.




Started work item id_1, Object ID of the workflow


id_5, For automatic activities, the object IDof the dm_method object for the methodexecuted by the activity. For manual activities,this is null.



string_3, Comma-separated list of workitem properties and their values. Theproperties are: r_priority, a_wq_name,and a_wq_doc_profile. a_wq_name anda_wq_doc_profile are enclosed in doublequotes.

string_4, Name of the performer of the workitem

string_5, Value in the dependency_typeproperty of the corresponding queue itemobject.

Start workflow id_1, Object ID of the workflow

Suspend workqueue task id_1, Object ID of the workflow

id_2 Object ID of the work item



string_4, Workqueue name

Uninstall workflow or activitydefinition





Unsuspend workqueue task id_1, Object ID of the workflow

id_2 Object ID of the work item



string_4, Workqueue name

Validate workflow or activitydefinition


Interpreting ACL and group audit trails

Audit trail entries generated when ACLs are created, changed, or destroyed are recordedin dm_audittrail_acl objects. Entries generated when groups are created, changed, ordestroyed are recorded in dm_audittrail_group objects. The dm_audittrail_acl anddm_audittrail_group object types are subtypes of the dm_audittrail type.

The properties defined for the dm_audittrail_acl object type store information aboutan audited ACL. The properties identify the event (dm_save, dm_saveasnew, ordm_destroy), the target ACL, the ACL entries or changes to the entries. For example,suppose you create an ACL with the following property values:r_object_id:451e9a8b0001900r_accessor_name [0]:dm_world

[1]:dm_owner[2]:John Doe

r_accessor_permit [0]:6[1]:7[2]:3

r_accessor_xpermit [0]:0[1]:0[2]:196608

r_is_group [0]:F[1]:F[2]:F

The audit trail acl object created in response has the following property values:r_object_id:<audit trail acl obj ID>audited_obj_id :451e9a8b0001900event_name :dm_savestring_1 :Createaccessor_operation[0] :I

[1] :I[2] :I

accessor_name [0] :dm_world



[1] :dm_owner[2] :John Doe

accessor_permit [0] :6[1] :7[2] :3

accessor_xpermit [0] :0[1] :0[2] :196608

application_permit [0]:[1]:[2]:

permit_type [0]:0[1]:0[2]:0

is_group [0] :F[1] :F[2] :F

The event_name records the repository event, a save method, that caused the creationof the audit trail entry. The string_1 property records the event desciption, in this case,Create, indicating the creation of an ACL. The accessor_operation property describeswhat operation was performed on each accessor identified at the corresponding indexposition in accessor_name. The accessor_permit and accessor_xpermit propertiesrecord the permissions assigned to the user (or group) identified in the correspondingpositions in accessor_name. Finally, the is_group property identifies whether the valuein accessor_name at the corresponding position represents an individual user or a group.

Now suppose you change the ACL. The changes you make are:• Add the Sales group• Remove John Doe• Change the world’s access to NoneThe resulting audit trail acl object has the following properties:r_object_id :<audit trail acl obj ID>audited_obj_id :451e9a8b0001900event_name :dm_savestring_1 :Saveaccessor_operation [0] :U

[1] :I[2] :D

accessor_name [0] :dm_world[1] :Sales[2] :JohnDoe

accessor_permit [0] :0[1] :2[2] :3

accessor_xpermit [0] :0[1] :0[2] :196608

application_permit [0]:[1]:[2]:

permit_type [0]:0



[1]:0[2]:0

is_group [0] :F[1] :T[2] :F

dm_world is found in accessor_name[0]. Consequently, the values in the correspondingposition in the accessor_operation, accessor_permit, and accessor_xpermit propertiesidentify the changes made to dm_world. In this case, the operation is U, meaning update.The values in accessor_permit and accessor_xpermit show the updated permissionsfor dm_world.

Sales is found in accessor_name[1]. The value in accessor_operation[1], I, shows that anentry for Sales was added (inserted) into the ACL. The values in accessor_permit andaccessor_xpermit show the permissions assigned to Sales.

JohnDoe is found in accessor_name[2]. The value in accessor_operation[2], D, indicatesthat the entry for JohnDoe was removed from the ACL. The values in the correspondingpositions in accessor_permit and accessor_xpermit identify the permissions previouslyassigned to JohnDoe.

Audit trail group objects are interpreted similarly. The values in the correspondingindex positions in users_names and users_names_operations represent one individualuser who is a member of the audited group. The values in the corresponding positions ingroups_names and groups_names_operation represent one group that is a member ofthe audited group. The operations property defines what operation was performed onthe member at the corresponding names property.

Verifying signed audit trail entries

A signed audit trail entry is an entry that has a value in the audit_signature property.The value is a signature generated by Content Server when the entry was created. Asignature on an entry is an added security feature because it allows you to determinewhether the entry was changed after it was saved to the repository.

If you need to check whether an entry was changed, use the IDfAuditTrailManager.verifyAudit method. This method regenerates the signature and compares the newlygenerated signature with the signature stored in the audit_signature property. If themethod returns T, then the audit trail entry is secure and has not been changed.

If you are working in a repository that has multiple servers, the method fails if theservers are using different AEKs and a server attempts to verify a signature createdby another server with a different AEK. To ensure that this does not occur, either allservers for a particular repository must use the same AEK or the application must checkthat the server issuing the verifyAudit method is the same server that generated the



signature. The server that generates the signature is recorded in the host_name propertyof the audit trail entry.

Removing audit trail entries

If the audit trail becomes too large, it can fill the available space in the underlyingRDBMS database. If there is no space in the database, you will not be able to save anyobjects in your repository. Monitor the size of the audit trail carefully.

When necessary, archive audit data that you want to keep by copying it or moving it outof the audit trail. Then, run the Audit Management tool or execute the PURGE_AUDITadministration method to remove unneeded audit trail entries from the database. Theaccount under which the tool runs must have Purge Audit privileges. Similarly, if youuse PURGE_AUDIT, the user executing the method must have Purge Audit privileges.

The Audit Management tool removes only system-generated audit trail entries bydefault. You can reset a default parameter to direct it to remove both system- anduser-generated entries or only user-generated entries. For more information on the AuditManagement tool, refer to Audit Management , page 456. The Audit Management toolis installed in the inactive state.

PURGE_AUDIT provides several options for determining which audit trail entries toremove. For example, you can remove all entries created within specified dates or allentries that reference a specific object as the target of the audit. For complete detailsabout using this administration method, refer to the reference description in the ContentServer DQL Reference Manual.

Removing an audit trail entry also removes the dmi_audittrail_attr object associatedwith the entry if one exists.

Auditing in a distributed environment

In a mulit-repository distributed environment, the audit trail is generated at the sourcerepository. For example, suppose you are auditing the check out operations on adocument. If a user in a remote repository checks out the document, the audit trail entryis written to the audit trail in the document’s source repository.

If you are auditing a virtual document that has component documents stored inmultiple repositories, the assemble audit trail is written to the repository to which youare connected when the assemble method is executed, but the checkin audit trail forindividual components is written to the corresponding source repository.



To collect all audit trail information for one compound document, you need to checkmultiple audit logs. Use the timestamp to merge the audit logs when you generatea report.

Implementing signature supportThis section describes the administration tasks that support the use of an electronicsignature feature in applications. There are three options for electronic signatures:• Electronic signatures using addESignature

Electronic signatures are implemented through Content Server and providerigorous accountability. This option requires a Trusted Content Services license.For information on using and customizing electronic signature support, refer toCustomizing electronic signatures, page 417. Electronic signatures are not supportedon the Linux and HP Itanium platforms.

• Digital signatures using addDigitalSignature

Digital signatures are implemented in client applications, using third-party software.No additional Content Server license is needed. For instructions on supportingdigital signatures, refer to Supporting digital signatures, page 427.

• Simple signoffs

Simple signoffs are the least rigorous way to enforce an electronic signaturerequirement. No additional Content Server license is needed. For instructions onusing and customizing simple signoffs, refer to Customizing simple signoffs, page428.

Customizing electronic signatures

There a variety of options for customizing electronic signatures. If you are using thedefault signature page template and signature creation method, you can:• Add or remove properties from the template page• Change the property delimiters on the page• Change the look of the template by adding, removing, or rearranging elements on

the page or changing the font and point size of the properties• Define separate templates for different document types• Configure the number of signatures allowed on a version of a document and whether

the signature page is added to the front or end of the content.For instructions on customizing the default functionality, refer to Customizing thedefault functionality, page 418.



If you want the signature in non-PDF format, you must implement a custom signaturecreation method. If you use a custom method, you can use a custom signature pagetemplate if you wish, but it is not required. The signature can be in any form thatyour method implements. Creating custom signature creation methods and associatedsignature page templates, page 425, contains instructions for implementing a custommethod.

Customizing the default functionality

Use the procedures in this section to customize the default signature page providedwith Content Server. Figure 9, page 418, shows a portion of the default signature pagetemplate.

Figure 9. Default signature template

The text in angle brackets (< >) identifies properties. When a signature page is created,the creation method replaces the text and angle brackets with the value of the property.For example, <begin.doc_name>...<end.doc_name> is replaced with the value of theobject_name property, and <doc.vsn> is replaced with the object’s numerical versionlabel. Some of the properties are values of properties for the object. Others, such as<sig.date>, are values associated with the electronic signature.



Content Server supports a set of system-defined properties for use on the defaulttemplate page. The pre-defined properties represent properties of the documentbeing signed and values associated with the signature. You can also add user-definedproperties to the signature page template.

On the template page, properties are formatted as either simple properties or textboxproperties. A simple property cannot break across lines in the signature page and isrepresented by a single placeholder in the template. For example, <doc.vsn> on thedefault template is a simple property. Textbox properties represent values that mayrequire multiple lines on the signature page. They are represented by begin and endplaceholders. For example, <begin.doc.name>...<end.doc.name> represent the textboxproperty doc.name on the default template.

Some of the system-defined document properties can be formatted as either simple ortextbox properties on a signature template page, and some can only be formatted assimple properties. All of the properties associated with the signature can be formatted aseither simple or textbox properties.

Table 42, page 419, lists the system-defined properties associated with documents, andTable 43, page 420, lists those associated with signatures. In addition, you can addcustom properties. For instructions, refer to Adding or removing properties on thepage, page 420.

Table 42. System-dened document properties for the signature page template

Property Simple/textbox Replaced with

doc.id Simple Object ID of the object being signed

doc.name Simple orTextbox

Object name of the object being signed

doc.title Simple orTextbox

Title of the object being signed

doc.path Simple orTextbox

Folder path of the object being signed,including the object’s name. Forexample:MyCabinet/Proposals/Engineering/NewProject.doc

doc.vsn Simple The numeric version label of the objectbeing signed

doc.status Simple The a_status value of the object beingsigned

doc.owner Simple Name of the owner of the object beingsigned



Property Simple/textbox Replaced with

doc.modifier Simple Name of the last person to havemodified the object being signed (thevalue of the r_modifer property)

doc.modify_date Simple Date on which the object was lastmodified (the r_modify_date value)

doc.authors Simple orTextbox

Authors of the object being signed

fdr.path Simple orTextbox

Folder path of the object inthe repository, without thedocument name. For example:MyCabinet/Proposals/Engineering

sig.requestor Simple orTextbox

The name of the user requesting thecurrent signature

sig.count Simple The number of signatures currentlyrecorded for the document

Table 43. System-dened signature properties for the signature page template

Property Replaced with

sig.requestor The user issuing the addESignature method

sig.no Signature number

sig.user_id User authentication name provided in theaddESignature arguments

sig.user_name Repository user name of the user identified in theaddESignature arguments

sig.reason The justification text for the signature

sig.date Date and time at which the signature was generated.The format is mm/dd/yyyy hh:mm:ss

sig.utc_date Date and time at which the signature was generated,expressed as UTC time.

Adding or removing properties on the page

You can add any of the system-defined properties or user-defined properties. When youadd a system-defined property, the default signature creation method will automaticallyreplace the property placeholder on the page with the appropriate value. If you add



a user-defined property, applications must pass the property name and value to thesignature creation method through an argument in the addESignature method.

To add or remove a property on the default signature page template:1. Check out the template from the repository.

The template is stored in /Integrations/Esignatures/Templates and its object name isDefault Signature Page Template.

2. Open the document for editing.

3. To add a property, enter the property name enclosed in the appropriate delimiters atthe location desired in the document.By default, the delimiters are angle brackets. If you have changed that default, besure to use the delimiters you have chosen. Note that you may also add displaylabels or place the value in a table or format the alignment of the property’s value.(For instructions on formatting alignment, refer to Configuring the appearance ofthe page, page 422.)

4. To remove a property, delete the entry and any associated formatting (such as labeltext).

5. Check in the template.

6. Use PDFWriter to generate a PDF rendition of the template.

7. Replace the current PDF rendition of the template with the new template, setting thepage_modifier of the PDF rendition to dm_sig_template.

Changing the property delimiters

On the default signature page template, the delimiters for properties on the page areangle brackets (< >). To change that default, set the begin_tag and end_tag propertiesof the template’s dm_esign_template object. You cannot set the beginning and endingdelimiters to the same character. For example, if you set begin_tag to the pound sign(#), you cannot set end_tag to a pound sign. You must choose a character other thanthe pound sign for the ending delimiter.

To set the delimiters for properties on the default signature page template:1. Fetch or checkout the template from the repository.


2. Set the begin_tag property to the desired delimiter for the beginning of the propertyplaceholders.



3. Set the end_tag property to the desired delimiter for the ending of the propertyplaceholders.

4. Save or checkin the template.

5. Use PDFWriter to generate a new PDF rendition of the template.

6. Replace the current PDF rendition of the template with the new rendition, setting thepage_modifier property of the rendition to dm_sig_template.

Conguring the appearance of the page

You can modify the appearance and arrangement of the default signature page in anymanner allowed by a Word editor. You can add display labels, graphics, tables, tabletitles, and so forth. You can also change the font and point size of the properties that areplaced on the page. To do that, select the property name in the editor and reset the font,point size, or both in the editor. When the template is used, text on the resulting signaturepage will use the font and point size of its associated property name on the template.

You can also change the alignment of the property values on the page. You do this bypositioning the property name inside the angle brackets using spaces. For example, thefollowing property designation right-justifies the property value, with four leadingspaces (each carot represents one space for the purposes of illustration):<^^^^doc.name>

If you wanted to center the value, insert equal numbers of spaces before and after theproperty name:<^^^^doc.name^^^^>

Simple property designations must include enough space to hold the longest valueexpected for that property. If a value is too long for the space provided, the value istruncated. The space provided is determined by counting the characters in the propertydesignation. For example, suppose you add the user-defined property <doc_creator> tothe template page, to add the name of the document’s creator to the page. This propertydesignation has 13 characters, and therefore user names longer than 13 characters wouldbe truncated. To allow for longer document names, include spaces (shown as carets forpurposes of illustration) to represent the extra characters:<doc_creator^^^^^^^^>or<^^^^^^^doc_creator>or<^^^^doc_creator^^^^>

To modify the appearance of the signature template page:1. Check out the template.




2. Open the template in a Word editor.

3. Make the desired modifications.

4. Check in the template.

5. Generate a new PDF rendition of the template using PDFWriter.

6. Replace current PDF rendition of the template with the new rendition, setting thepage_modifier property to dm_sig_template.

Dening separate templates for different document types

The default signature page template is defined for use on any dm_document object ordm_document subtype. However, your business requirements for signature pages maybe different for different document subtypes. For example, a signed legal documentmight require display labels of “Plaintiff signature” or “Defendant signature” on thesignature, while a medical document might require a display label of “Patient signature”on the signer’s name. You can create different default signature page templates fordifferent object types.

Which object types a particular signature page template is applied to is defined by thedocument_type property of the template. A signature page template is used to generatesignature pages for the object type (and its subtypes) defined in this property. Forexample, the property is set to dm_document in the default template, which means thatthe template can be used to generate signature pages for any dm_document object or anyobject that is a subtype of dm_document.

To create a default template page for a particular object type:1. Check out the template.


2. Open the template in a Word editor.

3. Save the template as a new document with a name appropriate for the intended use.For example, if the new template will be used with legal documents, you might setthe name to Legal_Doc Signature Page Template.

4. On the new copy of the source template, make the changes you need.

5. Save the new template.

6. Import or check in the new template to the repository.



The template must be defined as an object of type dm_esign_template. If you needhelp importing or checking in the new document, refer to the client documentationor online help.

7. Set the new template’s document_type property to the name of the documentsubtype that the template will be used to sign.For example, if you want the template to be used for legal documents of subtypelegal_document, set document_type to legal_document.

8. Generate a PDF rendition of the new template using PDFWriter.

9. Append the PDF rendition to new copy of the template.

Conguring the number of allowed signatures and signature positioning

The default signature page template allows up to six signatures on a document version.Also by default, the signature page is appended to the end of the content being signed.You can increase or decrease the number of allowed signatures and you can direct themethod to add the signature page to the beginning of the content. Both of these defaultsare controlled by properties of the template object.

The number of signatures allowed is controlled by the max_signatures property. Thedefault signature page template includes six entries for signatures. If you increase themaximum number of signatures, you should also modify the template page to addentries for the additional signatures. (If you do not add the entries for the additionalsignatures, when those additional signatures are added to the document, the signatureoperation succeeds and audit trail entries are created for the event, but the signatureswill not appear on the signed content.) If you decrease the maximum number, it is notnecessary to modify the template page unless you want to remove the unnecessarysignature entries. If you do modify the signature page template, you must generate a newPDF version of the template and replace the old PDF rendition with the new rendition.

Whether the signature page is prepended or appended to the content is controlled by theappend_to_body property of the template object. By default, this property is T (TRUE),meaning to append the signature page to the end of the content. Setting this property toF (FALSE) causes the signature creation method to prepend the signature page to thebeginning of the content.

You can set either property using DFC or DQL.

It is not necessary to generate a new PDF of the template when you change the template’spositioning.



Creating custom signature creation methods and associatedsignature page templates

Caution: This section outlines the basic procedure for creating and installinga user-defined signature creation method. Documentum provides standardtechnical support for the default signature creation method and signature pagetemplate installed with the Content Server software. For assistance in creating,implementing, or debugging a user-defined signature creation method or signaturepage template, contact Documentum Professional Services or DocumentumDeveloper Support.

If you do not want to use the default functionality, you must write a signature creationmethod. Using a signature page template is optional if you write a custom program.

Creating custom signature-creation methods

Use the following guidelines when writing the method:• The method should check the number of signatures currently on the object to ensure

that adding another signature does not exceed the maximum number of signaturesfor the document.

• The method must return 1 if it completes successfully or a number greater than 1if it fails. The method cannot return 0.

• If the trace parameter is passed to the method as T (TRUE), the method should writetrace information to standard output.

The addESignature method passes the parameters listed in Table 44, page 425, to themethod.

Table 44. Parameters passed by addESignature to the signature-creation method

Parameter Description

docbase Name of the repository

user Name of the user who is signing

doc_id Object ID of the document to be signed

file_path The name and location of the content fileto be signed in the file system.



Parameter Description

signature_properties A set of property and value pairs thatcontain data about the current andprevious signatures. The information canbe used to fill in a signature page. The setincludes:• sig.requester_0...n• sig.no_0...n• sig.user_id_0...n• sig_user_name_0...n• sig.reason_0...n• sig.date_0...n• sig.utc_date_0...n

The number at the end of each parametercorresponds to the number of thesignature to which the informationapplies.

application_properties User-defined set of property names andvalues specified in the Addesignaturecommand line.

trace If tracing is turned on for SysObjects, thisparameter is passed as T (TRUE).

passThroughArgument1 User-defined information specified in theaddESignature command line.

passThroughArgument2 User-defined information specified in theaddESignature command line.

Use the following procedure to create a custom method.

To create a custom signature-creation method:1. Write the method program.

2. Create a dm_method object that references the method program.Implementing a method, page 136, describes how to create method objects.

To use the custom method, applications must specify the name of the method object thatrepresents the custom method in the addESignature arguments.



Creating custom signature page templates

If you create a new signature template page, you define the format, content, andappearance of the page. You can store the template as primary content of an object or asa rendition. For example, you might create an XML source file for your template andgenerate an HTML rendition for use by your custom signature creation method. If youstore the template as a rendition, set the template’s page modifier to dm_sig_template.Setting the page modifier to dm_sig_template ensures that the Rendition Manageradministration tool will not remove the template rendition.

Tracing electronic signature operations

You can trace the operations of the addESignature method and the default signaturecreation method by setting the trace level for the DM_SYSOBJECT facility to 5 (or higher).

The tracing information for the addESignature and verifyESignature methods is recordedin the session log file. The tracing information for the signature creation method isrecorded in the server log file.

If you are using a custom signature creation method, trace messages generated by themethod written to standard out are recorded in the server log file if tracing is enabled.

Note: When tracing is enabled, the AddESignature method passes the trace parameterset to T (TRUE) to the signature creation method.

You can also set the DM_DEBUG_ESIGN_METHOD environment variable. Whenthat is set to 1, Content Server logs additional information about electronic signaturesgenerated by addESignature to the repository log file. You must restart Content Serverafter setting this variable.

Supporting digital signatures

Digital signatures, like electronic signoffs, are a way to enforce accountability. Digitalsignatures are obtained using third-party client software and embedded in the content.The signed content is then stored as primary content or a rendition of the document. Forexample, you might choose to implement digital signing using based on Microsoft OfficeXP, in which case the signature is typically embedded in the content file and stored in therepository as primary content for the document.

The implementation and management of digital signatures is almost completely withinthe context of the client application.The only system administration task is registeringthe dm_adddigsignature event for signature by Content Server. This is an optional task.When an application issues the addDigitalSignature method, to record a digital signoff



in an audit trail entry, that entry can itself be signed by the Content Server. To configuresigning by the server, an explicit registration must be issued for the dm_adddigsignatureevent. For information about how Content Server signatures on audit entries areimplemented and how to configure their use, refer to Signing audit trail entries, page394. Content Server Fundamentals has a description of how applications implement theuse of digital signatures.

Customizing simple signoffs

Simple signoffs are implemented using a IDfPersistentObject.signoff method and asignature validation program. Documentum provides a default signature validationprogram that authenticates a user based on the user’s user authentication name andpassword passed as arguments in the signoff method. If the authentication succeeds,Content Server creates an audit trail entry of event type dm_signoff that records whatwas signed, who signed it, and some information about the context of the signing. Theaudit trail entry is not signed by Content Server.

You can customize the simple signoff feature by:• Creating an alternate validation program that uses the user authentication name and

password to validate the user• Passing data other than a password through signoff’s password argument and

creating a custom validation method to authenticate the user with that data

For example, you might pass some biometric data and then validate that usinga custom validation program.

• Use an argument in a registration method to force Content Server to sign thedm_signoff events or to add additional information to the entries

Note: Documentum provides standard technical support for the default signaturevalidation method installed with the Content Server software. For assistance increating, implementing, or debugging a customized signature validation program or auser-defined signature validation method, contact Documentum Professional Services orDocumentum Developer Support.

Customizing the signature validation program

Use the following procedure to create and implement a customized simple signoff.

To use a custom signature validation program:1. Create a custom signature validation program.



The program must accept two arguments: the user’s name and the signature datapassed using the user-password argument of the signoff method. If the personal datais binary, you can use the uuencode program to convert the data to a string. Datapassed in the user-password argument cannot be longer than 127 bytes.The validation program must return 0 if it succeeds; otherwise, it must return 1.

2. Create a location object that identifies where the program is installed.

3. Modify the signature_chk_loc property in the server config object to point to thelocation object created in Step 2.The signature_chk_loc property identifies the location of the signature validationprogram to Content Server.

Registering for notication

Users can register the dm_signoff event so that when the signoff method is executed,the server sends mail notifications to users. You do not need to register a separate auditevent, because the server always generates an audit trail for signoff executions.

Querying the audit trail for signoffs

To return a collection of document objects signed by a specific user within a certain timeframe, use a DQL statement like the following:SELECT "audited_obj_id" FROM "dm_audittrail" WHERE"event_name" = 'dm_signoff' AND"user_name" = 'tom' ANDsubstr ("audited_obj_id", 1, 2) = '09'AND"time_stamp" >= DATE('01/01/1998', 'dd/mm/yy') AND"time_stamp" <= DATE(TODAY)

To find everyone who signed off a specific object whose ID is xxx, use the followingDQL statement:SELECT "user_name" FROM "dm_audittrail" WHERE"audited_obj_id" = 'xxx' AND"event_name" = 'dm_signoff'

Managing the encryption keysIn each Content Server software installation there is one master key, called theAdministration Encryption key, or AEK. Additionally, in each repository, there is onerepository encryption key.



The AEK

There is one AEK in each Content Server software installation. It is created and installedduring the Content Server software installation procedure or when an existing repositoryis upgraded from a version prior to 5.2. The AEK is used to encrypt:• The repository keys• Documentum passwords, such as those used by Content Server to connect to the

RDBMS, an LDAP directory server, or other repositoriesThe AEK is itself encrypted using a default passphrase provided by Documentum.You can change the passphrase to a custom passphrase using a utility provided byDocumentum. Using a custom passphrase is recommended. Changing a passphrase,page 434, has instructions for changing the passphrase.

The AEK is installed in the following location:

On Windows:%DOCUMENTUM%\dba\secure\aek.key

On UNIX:$DOCUMENTUM/dba/secure/aek.key

The file is a read only file. You cannot change the AEK file.

Content Server and all server processes and jobs that require access to the AEK usethe following algorithm to find it:

1. If a location is explicitly passed, look for the AEK in that location.

2. If the AEK is not found in the specified location or a location is not passed, use thelocation defined in the DM_CRYPTO_FILE environment variable.

3. If the DM_CRYPTO_FILE environment variable is not available,assume that the location is %DOCUMENTUM%\dba\secure\aek.key($DOCUMENTUM/dba/secure/aek.key).

Sharing the AEK or passphrase

If there are multiple Documentum products installed on one host, the products can usedifferent AEKs or the same AEK.

If the products use different AEKs, they can use the same passphrase. If you want thatpassphrase to be a custom passphrase, perform the following procedure after you installthe Content Server software.



To implement the same passphrase for multiple products:1. Shutdown Content Server if it is running.

2. Run the dm_crypto_change_password to change the passphrase to a custompassphrase.Refer to Changing a passphrase, page 434, for instructions.

3. Run the dm_crypto_boot utility using the -all argument.Refer to Using dm_crypto_boot, page 432, for instructions.

4. Restart Content Server.

5. Install the remaining products on the host machine.If the products use one AEK, theymust use the same passphrase. Also, it is recommendedthat you set the DM_CRYPTO_FILE environment variable to the location of the AEK andconfigure each product to reference the location defined in the environment variable.(Refer to the individual product documentation for instructions.)

The AEK and distributed sites

If your repository is a distributed repository, all servers at all sites must be using thesame AEK. After you install the remote sites, you must copy the AEK from the primarysite to the same location in each the remote site.

In multiple-repository distributed sites, each repository maintains its own AEK. Whenusers work across the repositories, the servers in each repository take care of anyencryption or decryption requirements locally.

Backing up the AEK

It is strongly recommended that you back up the AEK file separately from the repositoryand content files. Backing up the AEK and the data it encrypts in different locationshelps prevent a “dictionary-based” attack on the AEK.

Repository encryption keys

A repository encryption key is created for a repository when the repository is created.The key is encrypted using the AEK and stored in the i_crypto_key property of thedocbase config object. This property cannot be changed after the repository is created.



Content Server uses the repository encryption key to create the signature on audit trailentries. The server also uses the repository encryption key to encrypt file store keys.

Encryption utilities

There are three utilities that are used to manage the AEK:• dm_crypto_boot

Use this utility if you are protecting the AEK with a custom passphrase. Use it to:

— Install an obfuscated AEK or passphrase in the host machine’s shared memoryafter you define a custom passphrase.

— Reinstall an obfuscated AEK or passphrase in the host machine’s shared memoryif you stop and restart a server host machine.

— (Windows only) Reinstall an obfuscated AEK or passphrase in the host machine’sshared memory if you log off the host machine after you stop Content Server.

— Clean up the shared memory used to store the obfuscated AEK and passphrase.

It is not necessary to use this utility if you are protecting the AEK with the default,Documentum passphrase. Refer to Using dm_crypto_boot, page 432, for moredetails and instructions on using the utility.

• dm_crypto_create

This utility is run automatically, during the Content Server installation process, tocreate and install the AEK. You can use this utility to determine if an AEK exists ata specified location and can be decrypted with a specified passphrase. Refer toTroubleshooting with dm_crypto_create, page 433, for instructions.

• dm_crypto_change_passphrase

The dm_crypto_change_passphrase utility changes the passphrase used to encryptan AEK. Refer to Changing a passphrase, page 434, for instructions.

Using dm_crypto_boot

The dm_crypto_boot utility obfuscates the AEK or the passphrase used to decrypt theAEK and puts the obfuscated AEK or passphrase in shared memory. The utility is onlyused when you are protecting the AEK with a custom passphrase. It is not necessary ifyou are using the Documentum default passphrase. If you are protecting the AEK with acustom passphrase, you must run the utility in the following situations:



• When you stop and restart the host machine

After you stop a host machine, run this utility after restarting the host and beforerestarting the product or products that use the AEK.

• After you install the Content Server software and before you install the remainingproducts

You can also use this utility to clean up the shared memory region used to store the AEK.

To run this utility, you must be a member of the dmadmin group and you must haveaccess to the AEK file.

The syntax for the utility is:dm_crypto_boot[-passphrase passphrase] -location location|-all[-remove][-help]

The -passphrase argument identifies the passphrase used to encrypt the AEK. If you donot include the argument or if you include the argument keyword but not its value,the utility prompts for the passphrase. (If the user is prompted for a passphrase, thepassphrase is not displayed on screen when it is typed in.)

You must include either the -location or -all argument. Use -location if only one productis accessing the AEK. Using -location installs an obfuscated AEK in shared memory. The-location argument identifies the location of the AEK in the installation. If you do notinclude the argument, the utility looks for the location defined in DM_CRYPTO_FILE.If that environment variable is not defined, the utility assumes the location%DOCUMENTUM%\dba\secure\aek.key ($DOCUMENTUM/dba/secure/aek.key).

Use the -all argument if there are multiple products on the host machine that use thesame passphrase for their AEKs. If you include -all, the utility obfuscates the passphraseand writes it into shared memory instead of the AEK. Each product can then obtain thepassphrase and use it to decrypt the AEK for their product.

To clean up the shared memory used to store the obfuscated AEK or passphrase, executethe utility with the -remove argument. You must include the -passphrase argumentif you use -remove.

The -help argument returns help information for the utility. If you include -help, youcannot include any other arguments.

Troubleshooting with dm_crypto_create

You can run the dm_crypto_create utility with the -check argument to determinewhether an AEK exists at a specified location and whether a particular passphrase can beused to decrypt it. The syntax is:dm_crypto_create [-location location][-passphrase passphrase|-noprompt] -check [-help]



The -location argument identifies the location of the AEK whose existence youwish to determine. If you do not include the argument, the utility looks forlocation defined in DM_CRYPTO_FILE. If that environment variable is notdefined, the utility assumes the location %DOCUMENTUM%\dba\secure\aek.key($DOCUMENTUM/dba/secure/aek.key).

The -passphrase argument identifies the passphrase whose use you wish to check. If youdo not include the -passphrase argument, the utility assumes the default passphrase butprompts you for confirmation. Consequently, if you are checking the default passphraseand wish to avoid the confirmation request, include the -noprompt argument. (The-passphrase and -noprompt arguments are mutually exclusive.)

If the AEK file does not exist at the specified location, the utility returns 0. If the AEKexists but decryption fails, the utility returns 1. If the AEK exists and decryptionsucceeds, the utility returns 2.


Changing a passphrase

Use dm_crypto_change_passphrase to change the passphrase used to encrypt the AEKin the installation. Installing the Content Server software installs the AEK encryptedusing a default passphrase. It is strongly recommended that you change the default to acustom passphrase of your choosing. Use this utility, also, if business rules or a securitybreach require you to change the passphrase. All Documentum products that use theaffected AEK must be stopped before running the utility.

The syntax is:dm_crypto_change_passphrase [-location location][-passphrase[old_passphrase]][-newpassphrase [new_passphrase]][-noprompt][-help]

The -location argument identifies the location of the AEK whose passphraseyou wish to change. If you do not include the argument, the utility looks forlocation defined in DM_CRYPTO_FILE. If that environment variable is notdefined, the utility assumes the location %DOCUMENTUM%\dba\secure\aek.key($DOCUMENTUM/dba/secure/aek.key).

The -passphrase argument identifies the current passphrase associated with the AEK.The -newpassphrase argument defines the new passphrase you wish to use to encryptthe AEK. Both phrases interact in a similar manner with the -noprompt argument. Thebehavior is described in Table 45, page 435.



Table 45. Interaction of dm_crypto_change_passphrase arguments

-noprompt included -noprompt not included

-passphrase argument notincluded

Utility prompts for apassphrase

Utility assumes theDocumentum defaultpassphrase

-passphrase keyword isincluded but no value

Utility prompts for apassphrase


-newpassphrase argumentnot included

Utility prompts for a newpassphrase


-newpassphrase keywordis included but no value

Utility prompts for a newpassphrase


You must include a value for at least one of the passphrases. You cannot be prompted forboth values or allow both values to default.

To illustrate the use of this utility, here are some examples. The first example changesthe passphrase for the Content Server host AEK from the Documentum default to“custom_pass1”. The -passphrase argument is not included and the-noprompt isincluded, so the utility assumes that the current passphrase is the default passphrase.dm_crypto_create -location %DOCUMENTUM%\dba\secure\aek.key-newpassphrase custom_pass1 -noprompt

This next example changes the passphrase from one custom passphrase to another:dm_crypto_create -location %DOCUMENTUM%\dba\secure\aek.key-passphrase genuine -newpassphrase glorious

This final example changes the passphrase from a custom passphrase to the default:dm_crypto_create -location %DOCUMENTUM%\dba\secure\aek.key-passphrase custom_pass1 -noprompt

Because the new passphrase is set to the Documentum default passphrase, it isn’tnecessary to include the -newpassphrase argument. The utility assumes that the newpassphrase is the default if the argument is not present and the -noprompt argumentis present.




Managing the login ticket keyThe login ticket key is used to generate and validate login tickets and application accesscontrol tokens. The key is installed automatically when a repository is created. Eachrepository has one login ticket key.

Note: Content Server Fundamentals describes login tickets, application access controltokens, and how each are used.

Exporting and importing a login ticket key

If you are using global login tickets or global application access control tokens, boththe repository generating the ticket or token and the repository accepting the ticketor token must be using the same login ticket key. When you install a repository, theinstallation configures a login ticket key for the repository. However, each key is unique.Consequently, to use global login tickets or tokens, you must export a login ticket keyfrom one repository among those that will be exchanging global login tickets or tokensand import that key into the other repositories exchanging global tickets or tokens.

To export a login ticket key, use the EXPORT_TICKET_KEY administration method. Toimport the key, use IMPORT_TICKET_KEY. Use Documentum Administrator to executethese methods. These methods are also available as DFC methods (exportTicketKey andimportTicketKey) in the IDfSession interface.

You must restart Content Server after importing a login ticket key to make the newlogin ticket key take effect.

Resetting a login ticket key

Resetting a login ticket key replaces a repository’s current login ticket key with anewly generated key. You may need to reset a login ticket key if the current key iscompromised. If you reset the login ticket key, the repository’s server will not accept anylogin tickets generated using the old key.

To reset a login ticket key, execute the RESET_TICKET_KEY method. Use DocumentumAdministrator to execute that method. You can also use the DFC method, resetTicketKey,in the IDfSession interface.

You must restart Content Server after resetting a login ticket key.



Conguring a repository’s trusted repositoriesA repository that accepts a global login ticket or global application access control tokenmust trust the repository in which the login ticket or token was generated. To definewhich repositories are trusted, you must define the repository’s trust mode. You canconfigure a repository to:• Trust all other repositories• Trust only specifically identified repositoriesUse Documentum Administrator to define the trust mode for a repository. If you chooseto allow the repository to trust all other repositories, the choice is recorded in thetrust_by_default property (in the docbase config object), which is set to TRUE.

If you choose to allow the repository to trust only a specific set of repositories, thetrust_by_default property is set to FALSE, and you must provide the names of thetrusted repositories. Those names are recorded in the trusted_docbases property ofthe docbase config object.

For detailed instructions, refer to the Documentum Administrator online help. For anoverview of trusted repositories and how they function with login tickets and tokens,refer to Content Server Fundamentals.

Conguring login ticket useUse the following procedures to customize login tickets at your site.

Conguring the default login ticket timeout

Login tickets are only valid for a specified period of time. A ticket’s validity period isdefined by either:• An argument when the ticket is generated• The value in the login_ticket_timeout property of the server issuing the method to

generate the ticketIf you do not specify a validity period when a ticket is generated, the period defaultsto the value defined in the login_ticket_timeout property. The value of that property isset to 5 minutes by default when a repository is installed.

Neither the property value nor the argument value can exceed the maximum intervaldefined in the max_login_ticket_timeout property defined in the server’s server configobject. This property is set to 43200 minutes (30 days) by default when a repository is



installed. (If the argument exceeds the maximum, the argument value is ignored and themaximum value is used.)

To reset either or both the login_ticket_timeout and max_login_ticket_timeout properties,use Documentum Administrator. Refer to the Documentum Administrator’s onlinehelp if needed.

Restricting a Superuser’s use of global tickets

You may want to restrict Superusers from using global login tickets to ensure that auser in one repository cannot use a global login ticket to gain Superuser privileges inanother repository.

The restriction is configured at the server level. You can decide on a server-by-serverbasis, for each repository, whether the server can accept global login tickets forSuperusers in the repository. Use Documentum Administrator to record the choice foreach server. The choice is recorded in the restrict_su_ticket_login property of the serverconfig object.

Revoking tickets for a specic repository

It is possible to set a cutoff date for login tickets accepted by a repository. If you do so,the repository’s servers consider any login ticket issued before that date as invalid, andthe servers refuse to accept them.

Use Documentum Administrator to set a login ticket cutoff date for a repository. Thedate is recorded in the login_ticket_cutoff property of the docbase config object.

Troubleshooting a login ticket

To troubleshoot a login ticket, use the IDfSession.getLoginTicketDiagnostics method.This method returns details about the ticket extracted from the login ticket.



Conguring application access control tokenuse

Application access control (AAC) tokens are a security feature that you can use to controlaccess to a repository based on who is requesting access, the application or host fromwhich the request is issued, or some combination of these factors.

AAC tokens are enabled at the server level, to give you flexibility in designing yoursecurity. For example, you can set up a server that requires a token to service usersoutside a firewall and another server that does not require a token for users inside thefirewall.

Tokens are used in addition to user names and passwords (or login tickets) when issuinga connection request. They are not a substitute for either. If a server requires a tokenand the user making the connection request is not a Superuser, the connection requestmust be accompanied by a token. Only Superusers can connect to a repository through aserver requiring a token without a token.

For complete information about tokens and how they are implemented and used, referto Content Server Fundamentals.

Enabling AAC token use by a server

Use Documentum Administrator to enable the use of application access control tokensby a particular server. If use is enabled, non-Superuser users cannot access the repositorythrough that server unless the constraints specified in the token are satisfied. Whether aserver has AAC token use enabled is recorded in the application_access_control propertyof its server config object.

Enabling machine-only AAC tokens

An application access control token can be created to be valid only when sent froma particular host machine. This token authentication mechanism is dependent onknowledge of the host’s machine ID. If you are using such tokens, you must set thedfc.machine.id key in the dfc.properties file used by client applications on that host sothat DFC can include that when sending the application token to Content Server. Setthe key to the host’s machine ID.



Enabling token retrieval by the client library

You can configure client library behavior to allow the client library to automaticallyretrieve a token from storage and append that token to an application’s connectionrequest if a token is required and none is provided in the connection request. If retrievalis enabled, the client library searches for a token file whose name matches the name ofthe repository specified in the connection request. If such a token file is found, the tokenit contains it is appended to the connection request. If such a token file is not found, theclient library appends the token from the token file named default.tkn, if one is available.

This feature helps ensure that the appropriate token is provided when an applicationis run from different machines and that older applications can connect to a server thatrequires an AAC token for connection.

To enable token retrieval:1. Generate the token files using dmtkgen.

For instructions on using the utility, refer to Generating tokens for storage, page 441.

2. Configure the retrieval behavior in the dfc.properties file.

a. Set dfc.tokenstorage.enable to true.

b. Set dfc.tokenstorage.dir to the desired token storage directory.The dfc.tokenstorage.enable key is a Boolean key that controls whether the client librarycan retrieve tokens from storage. If it is set to true, the client library will attempt toretrieve a token from storage for use when a connect request without a token is issued toa server requiring a token. If the key is set to false, the client library does not retrievetokens from storage.

The dfc.tokenstorage.dir key tells the client library where to find the token files generatedby the dmtkgen utility. Any tokens that you generate using dmtkgen must be placed inthis location. If they are not, the client library will not find them.

When you install DFC on a client host machine for the first time, the installation setsthe dfc.tokenstorage.enable key to false and the dfc.tokenstorage.dir to <user-selecteddrive>:\Documentum\apptoken. If you upgrade or reinstall DFC, the procedure will notreset those keys if you have changed them.

When you install Content Server installation for the first time on a host machine, theprocess also installs DFC. The DFC installation process sets the dfc.tokenstorage.enablekey in the dfc.properties file on the server host to false and the dfc.tokenstorage.dirto %Documentum%\apptoken ($DOCUMENTUM/apptoken). However, when theContent Server installer runs, it resets the tdfc.tokenstorage.enable key to true. Thedfc.tokenstorage.dir is not reset.

The dfc.properties file on the server host is used by the internal methods to connectto repositories. The dfc.tokenstorage.enable and dfc.tokenstorage.dir settings in this



dfc.properties file affect methods associated with dm_method objects. Replication andfederation methods are not affected by the settings in this dfc.properties file becausethese jobs execute as a Superuser.

Note: Content Server Fundamentals has additional information about how internalmethods are affected by this setting.

If you are installing an upgrade to Content Server or a previous DFC installationoccurred and a dfc.properties file already exists on the host machine with these keys set,installing Content Server and a new DFC does not overwrite their values.

Generating tokens for storage

Use the dmtkgen utility to generate application access control tokens to be stored onhost machines. The utility is found in %DM_HOME%\bin ($DM_HOME/bin). Eachexecution of the utility creates one token file in XML format. The file is an ASCII file.The file contains the token and the information used to generate the token. Here is asample of the file’s format:<token><docbase>mytestdb</docbase><user>me</user><scope>global</scope><timeout>40000</timeout><appidhash>hash_of_application_id</appidhash><machineonly>T</machineonly><tokendata>DM_TOKEN=tokenstring</tokendata></token>

Table 46, page 441, lists the arguments accepted by this utility.

Table 46. dmtkgen utility arguments


-u username User as whom the utility is running

This is a required argument.

-p password Password for the user identified in username


-d domain Domain of the user identified in username

This argument is required only if a domain is required toauthenticate the user.




-b repository_name Name of the repository to which to connect to create thetoken.


-a user|group name Name of the user or group who can use this token. If agroup is specified, all members of the group can use thistoken.

This is an optional argument. If unspecified, then all userscan use the token.

-s scope Scope of the generated token. Valid values are• docbaseSpecifying docbase restricts the token’s use tothe repository identified in the output file’s name.

• globalSpecifying global allows the token to be used toconnect to any repository having the same login ticketkey as the repository in which the token was generated.

This is an optional argument. The default is global.

-t timeout Validity period for the generated token. The value isinterpreted in minutes.

This is an optional argument. The default is one year,expressed in minutes.

-i application_identifier User-defined application identifier representing theapplication for which this token is valid.

This is an optional argument. If unspecified, the tokenis valid for all applications.

-m machine_only Boolean flag indicating whether the token is valid onlywhen used on the machine on which the token wasgenerated. T means the token may only be used from themachine on which it was generated. F means that thetoken may be sent from any machine.

This is an optional argument. The default is F.

-o output_file The name of the generated XML token file. You canspeicify a full file path or only the file name.

The file name must be either:

default.tknor




repository_name.tkn

This is an optional argument. It defaults torepository_name.tkn where repository_name is the repositoryidentified in the -b argument. If you include a name butnot a file path, the file is stored in the current directory.

The implementation imposes a naming constraint onglobal tokens. Refer to Naming the output file, page 443,for information.

Naming the output le

Token files are retrieved by repository name. If the client library is looking for a tokenin storage for a particular connection request, it searches for a token whose name is thename of the requested repository in the connection request. If the library cannot find atoken whose name matches the repository name in the connection request, it searches fora token file called default.tkn. Because of this token file search algorithm, if you create aglobal token file for use across multiple repositories, you must name the file default.tkn.

Storing tokens generated by dmtkgen

The client library looks for the stored tokens in the location identified by thedfc.tokenstorage.dir key in the client’s dfc.properties file. After you generate the tokenfile, you can copy the file to that location for each client machine where the token will beused. Because the generated file is an ASCII file, you can copy the file across operatingsystems. For example, if it was generated on a Windows host machine, you can copyit to a UNIX host machine. Similarly, if it was generated on a UNIX host machine, youcan copy it to a Windows host machine.

If the location specified in dfc.tokenstorage.dir is visible to the machine on which yougenerate the token, you can specify the location in the -o argument and the token file willbe saved to the correct location automatically.

The dfc.tokenstorage.dir key is set automatically when the DFC is installed. For moreinformation about its setting, refer to Enabling token retrieval by the client library,page 440.



Troubleshooting an application access controltoken

To troubleshoot a login ticket, use the IDfSession.getApplicationTokenDiagnosticsmethod. This method returns details about the token extracted from the applicationaccess control token.


Chapter 11Administration Tools

This chapter contains information about the automated tools you can use to manage and monitorrepositories and associated file systems. The chapter includes the following topics:• Essential tool concepts, page 446• Activating and scheduling administration tools, page 453• Running administration jobs on demand, page 454• Archive , page 454• Audit Management , page 456• Consistency Checker, page 459• Content Replication, page 465• Content Warning , page 468• Create Full-Text Events, page 470• Data Dictionary Publisher, page 475• Database Space Warning , page 476• Dm_LDAPSynchronization, page 479• Dmclean , page 482• Dmfilescan , page 487• File Report , page 493• Group Rename, page 498• Index Agent Startup, page 498• Log Purge , page 499• Queue Management , page 503• Remove expired retention objects, page 506• Rendition Manager , page 509• State of the Repository Report , page 514• Swap Info , page 518• ToolSetup, page 519


Administration Tools

• Update Statistics , page 519• User Chg Home Db, page 522• User Rename, page 523• Version Management , page 525• Tool maintenance and troubleshooting, page 529

Essential tool conceptsDocumentum provides a suite of automated tools installed with Content Server that cansimplify your system administration tasks. For example, the Database Space Warningtool helps prevent unexpected downtime by warning you when space on a storage diskis running low. Each tool identifies a job to run on a specific schedule.

The tools are described briefly in Table 47, page 446. Typically, the tools are managed bythe Documentum system administrator. However, some tools might be managed moreefficiently by another person. For example, you may want the RDBMS administratorto manage the Database Space Warning tool because this tool monitors space andfragmentation in the underlying database.

Documentum Administrator provides a graphical interface for defining, modifying, andmonitoring the tools and their associated jobs.

Table 47. EMC Documentum tool suite

Tool Description

Archive Automates archive and restore betweencontent areas

Audit Management Deletes unneeded audit trail objects

Consistency Checker Checks the repository for consistency across avariety of object types.

Content Replication Automates replication of document contentwhen using distributed file stores

Content Storage Warning Monitors disk space on the devices usedto store content and index files. Queues awarning message when a disk used for contentand index storage reaches a user-definedpercentage of capacity



Tool Description

Create Full-Text Events Creates events for objects not indexed becausethe objects were created or modified betweenthe creation of a full-text index and when therepository was upgraded. Can optionally beused to generate events to fully reindex arepository.

Data Dictionary Publisher Publishes data dictionary information to makeit visible to users and applications

Database Space Warning Monitors the RDBMS. Queues a warningmessage when the RDBMS reaches auser-defined percentage of capacity.

Note: This tool is not installed for installationsrunning against MS SQL Server or DB2.

Dm_LDAPSynchronization Determines all changes in the LDAP directoryserver information and propagates the changesto the repository.

Dmclean Automates the dmclean utility, which removesorphaned content objects, notes, ACLs, andSendToDistribution workflow templates froma repository

Dmfilescan Automates the dmfilescan utility, whichremoves orphaned content files from aspecified storage area of a repository

DistOperations Performs the distributed operations necessaryto manage reference links. This is an internaljob that is installed as part of the tool suitebut is not available for users to manipulate orchange. Consequently, it is not described indetail in this chapter. Refer to the DistributedConfiguration Guide for more details.

File Report Utility Provides a report to help restore deleted orarchived document content using your filesystem backups. This is a method that appliesonly when using distributed storage areas.

Group Rename Renames a group in the repository. This isexecuted when you change a group namethrough Documentum Administrator.



Tool Description

Index Agent Startup Starts the index agent. This is not available formanual execution. It is called automaticallywhenever Content Server is started.

Log Purge Deletes log files for the server, session,connection broker, and agent and the trace logfiles resulting from method and job executions

Queue Management Deletes dequeued objects in thedmi_queue_item tables

Remove Expired Retention Objects Removes objects from the repository whosecontent, stored in an EMC Centera storagearea, has an expired retention date.

Rendition Management Manages the removal of unwanted renditionsof a document

State of the Repository Report Provides information about the status of theDocumentum environment

Swap Info Reports on swap space availability and usage

Note: The Swap Info tool is not installed ifthe Content Server is installed on an HPUXplatform.

ToolSetup Installs system administration tools

Update Stats Updates stored statistics on the underlyingRDBMS tables, to aid in query performance.

User Chg Home Db Changes a user’s home repository. Thistool is executed through DocumentumAdministrator, when changing a user’s homerepository. You may not execute the tooldirectly.

User Rename Changes a user’s name in the repository. Thisis executed when you change a user namethrough Documentum Administrator.

Version Management Manages the removal of unwanted versionsof documents



How tools are implemented

Most tools are implemented as jobs, which are objects that reference a method object andhave properties that define an execution schedule for the method. Refer to Chapter 4,Methods and Jobs, for more information about jobs and methods.

Jobs are automatically executed on the schedule defined by their properties. A serverprocess named agent exec regularly checks the jobs in a repository and runs those thatare ready for execution. A job is ready for execution when its scheduled next run timeis less than or equal to the current time. Jobs can also be run on demand. (Refer toActivating and scheduling administration tools, page 453 for instructions on setting jobschedules. Information about running tools on demand is in Running administrationjobs on demand, page 454.)

ToolSetup is an exception in that it is not implemented as a job. ToolSetup is the utilitythat installs the tool suite. The utility is integrated into dm_configure for installations ineither a single node environment or in a distributed environment. However, you canalso run the utility manually if needed.

Standard arguments

When the agent exec launches a job, it passes the four standard arguments listed inTable 48, page 449, to the job’s method.

Table 48. Standard arguments passed to jobs

Argument Datatype Value Description

DOCBASE _NAME string(64) repository_name Identifies therepository

USER_NAME string(64) user_name The user of the tool

JOB_ID ID job_object_id Object ID of the job

METHOD_TRACE_LEVEL

integer level Method trace level touse. The default is 0(no tracing).

Each job-implemented tool also has arguments which are defined in themethod_arguments property for the job. These argument values are obtained from thejob object (using the job ID value) when the job executes. Refer to the individual tooldescriptions for information about the tool-specific arguments.



The QUEUEPERSON argument

Many tools accept an argument called -queueperson. This argument defines whichrepository user receives the Inbox and email notifications sent by the tools. If you donot define -queueperson (in the method_arguments property), the Inbox and emailnotifications are sent to the user identified in the operator_name property of the server’sserver config object. (That property is set to the name of the repository owner by default.)However, you may want to change this for some tools. For example, the Database SpaceWarning tool provides status information about the RDBMS, and you may want itsnotifications sent to the RDBMS DBA.

The window interval

When you restart a server, the tools scheduled to run while the server was shut downwill not necessarily run immediately. Some tools have a default window on eitherside of the scheduled run time that allows the tool schedule to recover gracefully. Forexample, suppose that a tool has a window_interval of 120 minutes (2 hours) and it isnormally supposed to execute at 9 p.m. The tool will only be able to run between thehours of 7 p.m. and 11 p.m. If it is started before 7 p.m., it aborts and is rescheduled torun at 9 p.m. the same day. If is started after 11 p.m., it aborts and is rescheduled to runat 9 p.m. the next day.

To illustrate, suppose a tool is scheduled to execute daily at 11 p.m. and that the server isshut down from 9 a.m. on July 21 to 9 a.m. on July 22. When you restart the server at 9a.m. on the July 22, the server attempts to execute the tool. However, because 9 a.m. isnot within the tool’s window, the tool aborts the July 21, 11 p.m. job, and is rescheduledto run at 11 p.m. that night (July 22).

This window of execution is provided for most tools to ensure that server start-ups arenot delayed by the execution of tools. You can change the size of the window by settingthe -window_interval argument for the job (in the method_arguments property). Thisargument takes an integer value that expresses the length of the desired interval inminutes. For example if you wanted to reset the interval to 1 hour on either side of thejob’s scheduled execution time, you would set -window_interval to 60 for that job.

Refer to the description of each tool to determine if the tool takes the -window_intervalargument and, if so, the argument’s default value.



Reports and trace log les

All jobs in the tool suite generate reports. Trace log files are only generated if tracingis turned on for the job.

Reports

The job reports summarize the results of the job in an easily interpreted format. Thereports are named for the tool that creates them. In a distributed environment, the reportfor the primary site is named with the tool’s name and the reports for the remote siteshave the site’s server config name appended to the tool’s name. The following toolsgenerate site-specific reports in a distributed environment:• ContentWarning• Dmclean• Dmfilescan• LogPurge• SwapInfoAll job reports are returned using the UTF-8 code page. You can view job reportsthrough Documentum Administrator. To see examples of some of the reports, refer tothe descriptions of the individual tools.

The content files for job reports are stored in the default storage area for SysObjects.Job reports are indexed.

Storage

In the repository, job reports are stored in /System/Sysadmin/Reports. Each time a jobexecutes, the job report in this location is versioned.

The reports are also stored in the file system in%DOCUMENTUM%\dba\log\repository_id\sysadmin ($DOCUMENTUM/dba/log/repository_id/sysadmin). The reports in thisdirectory are overwritten each time the job executes.

The job reports are also stored in %DOCUMENTUM%\share\temp\ldif\repository_name($DOCUMENTUM/share/temp/ldif/repository_name) for access through DocumentumAdministrator.



Trace log les

Trace logs contain status information logged by the job and the text of the report. Tracelogs file for jobs are created whenever the method_trace_level argument in the job is setto any value except 0. A trace level of 0 turns off tracing. The default trace level for alljobs in the tool suite is 0.

To view a trace log file, use Documentum Administrator.

Note: If the dfc.properties file used by the Content Server has a trace file locationspecified, the tracing information generated by the job is recorded in the location definedby that key. When that occurs, Documentum Administrator cannot display the tracefile for the job.

Storage

In the repository, job log files are stored in /Temp/Jobs/tool_nameTrace. The file is namedfor the tool that generated it. For example, the job log file for the Rendition Managementtool is called RenditionMgtTrace. The log files in this directory are versioned whenthe jobs execute.

The log files are also stored in the file system in%DOCUMENTUM%\dba\log\repository_id\sysadmin ($DOCUMENTUM/dba/log/repository_id/sysadmin). The log file in thisdirectory is overwritten each time the job executes.

The job log files are also stored in%DOCUMENTUM%\share\temp\ldif\repository_name($DOCUMENTUM/share/temp/ldif/repository_name) for access through DocumentumAdministrator.

Email messages

Tools can generate an email message in addition to a report. Messages are generated ifan error occurs while the tool is executing or if a warning tool (such as Content Warning)encounters a condition that requires a warning.

The message is sent to the queueperson for the tool described above. It identifies therepository, the event ID, the trace log file name, who sent the message, and the taskname. This message may also contain a warning.

For example, here is an email message sent by the Content Warning tool to the repositoryowner:X-UIDL: 827528501.002Date: Fri, 22 Mar 1996 12:02:34 +0800From: test1@lapdog (Trashable Repository - SunOS5)



To: stevek@lapdogSubject: Event storage_01 has occurred on ContentWarning.Result(090007d080045f8d) by testsolREPOSITORY: test1EVENT: storage_01NAME: ContentWarning.ResultSENT BY: test1TASK NAME: eventTake a look at /export/nfs1-4--it's 90% full!!!

Activating and scheduling administration toolsBefore a tool can be executed, it must be in an active state and it must have an executionschedule.

Activation

Some of the tools are installed in the active state and some are installed in the inactivestate. For example, the tools that remove objects from the repository or file system,such as the Version Management and Rendition Management tools, are installed in theinactive state because they require you to set arguments that define what you wantto remove. Consequently, they are installed in the inactive state so you can set thearguments before activating them.

Use Documentum Administrator to activate (or inactivate) an administration job. After atool is activated, it is executed at the interval defined in its schedule.

Dening job schedules

Each administration job is installed with a default schedule. Typically, the defaultschedules run a job once a day or once a week. You can change the schedules to fit theneeds of your site.

You can schedule a job to run independently of other jobs or include it in a job sequence.A job sequence identifies a set of jobs that are dependent on one or more jobs within thesequence. The dependent jobs cannot be executed until the job or jobs on which theydepend are completed successfully. Both the dependent jobs and the jobs on which theydepend are included in a job sequence.

To view or reset a job’s schedule or to create a job sequence, use DocumentumAdministrator. For information about setting schedules, refer to the Documentum



Administrator online Help or to Scheduling jobs, page 150. Refer to Introducing jobsequences, page 146 for more information about job sequences.

Running administration jobs on demandYou can execute a tool on demand. For example, after a project is completed, youmay want to run the Version Management tool to remove old versions of the project’sdocumentation, using the tool’s custom_predicate property to constrain the search to oldversions. Or, you may want to run the Swap Space Info tool during a peak usage time,to see how swap space is being affected.

You can run a tool on demand at any time within its window interval. You cannot runa tool on demand outside of its window interval. (Refer to The window interval, page450 for information about the window interval.)

Running a tool on demand does not affect its normal schedule. A tool does not needto be active for you to run it on demand. Use Documentum Administrator to run atool on demand.

ArchiveThe Archive tool automates archive and restore between content areas. Archive olderor infrequently accessed documents to free up disk space for newer or more frequentlyused documents. Restore archived documents to make the archived documents availablewhen users request them. For complete information on configuring archiving, refer toArchiving and restoring documents, page 277.

The Archive tool is active by default, and runs once daily.

Arguments

Table 49, page 454 describes the arguments for the tool

Table 49. Archive arguments

Argument Datatype Default Description

-docbase_namerepository

string(64) - Identifies the repositorythat contains the documentor documents to archive.Use the repository’s name.




-Uusername string(64) - Identifies the userexecuting dmarchive.If unspecified, the currentuser is assumed.

-Ppassword string(64) - Password for the userexecuting dmarchive. Ifunspecified, the user isprompted.

-archive_dirdirectory

string - The location of the archivedirectory. Use a full pathspecification.

-queue_name name string - Identifies the repositoryoperator. Specify theoperator’s repository username. If unspecified,the tool assumes theuser named in theoperator_name property ofthe server config object.

-queue_eventevent_id

ID - Object ID of the queueitem object representing anarchive or restore event.

If set, the tool processesonly the specified event.

-do_archive _events Boolean - TRUE directs the tool toprocess only archive events.

-do_restore _events Boolean - TRUE directs the tool toprocess only restore events.

-verbose Boolean T TRUE directs the tool toprint trace messages.

-window_interval integer 720 Defines window in whichthe tool can run. Value isinterpreted in minutes.

-queueperson string - Identifies the user whoreceives Inbox and emailnotifications from the tool.



Guidelines

The Archive tool puts all the documents it is archiving in one dump file. This meansyou must move the entire dump file back to the archive directory to restore a singledocument in the file. If the files are extremely large, this can be a significant performancehit for restore operations.

Audit ManagementThe Audit Management tool deletes audit trail entries. When an audited event occurs,an audit trail entry is created for that event. If the audit trail entries are not removedperiodically, the tables for the dm_audittrail object type can grow quite large, andperformance degrades when audited events occur. The Audit Management toolautomates the task of removing unneeded audit trail objects.

The tool runs under the Documentum installation owner’s account to execute thedm_AuditMgt job. The job uses the PURGE_AUDIT administration method toremove the audit trail entries from the repository. Consequently, to use this tool, theDocumentum installation owner must have Purge Audit privileges. All executions of thetool are audited. The generated audit trail entry has the event name dm_purgeaudit.

The cutoff_days and custom_predicate arguments determine which audit trail objectsto remove. The cutoff_days argument specifies the age of the objects to delete. Thecustom_predicate argument is then applied to those items meeting the age requirement.

By default, the cutoff_days argument is set to 90 and the custom_predicate argument isset to remove only audit trail objects generated by system-defined events. (The tool doesnot delete audit trail objects generated by user-defined events by default.)

To change the age cutoff, reset the cutoff_days argument.

To choose the objects to remove from the subset selected by cutoff_days, change thecustom_predicate argument. By default, the custom predicate includes three conditions:• delete_flag=TRUE• dequeued_date=value (value is computed using the cutoff_days argument)• r_gen_source=1You cannot change the first two conditions. The third condition, r_gen_source=1, directsthe server to delete only audit trail objects generated by system-defined events. If youwant to remove only audit trail objects generated by user-defined events, reset this tor_gen_source=0. If you want to remove audit trail objects generated by both system- anduser-defined events, remove the r_gen_source expression from the custom predicate.

Youmay also add other conditions to the default custom predicate. If you add a conditionthat specifies a string constant as a value, you must enclose the value in two single quotes



on each side. For example, suppose you want to remove only audit trail entries thatrecord dm_checkin events. To do so, add the following to the custom_predicate:event_name=''dm_checkin''

dm_checkin is enclosed by two single quotes on each side. Do not use double quotes.These must be two single quotes.

The Audit Management tool generates a status report that lists the deleted dm_audittrailentries. The report is saved in the repository in /System/Sysadmin/Reports.

If an error occurs while the tool is executing, the server sends email and inbox notificationto the user specified by the -auditperson argument.

The Audit Management tool is installed in the inactive state. The first time you executethe tool, it may take a long time to complete.

Arguments

Table 50, page 457, lists the arguments to the Audit Management tool.

Table 50. Audit Management arguments


-window_interval integer 120 Defines the executionwindow for the tool. Value isinterpreted in minutes.

-queueperson string(32) - User who receives emailand inbox notificationsfrom the tool. The defaultis the user specified in theoperator_name property ofthe server config object.

-custom_predicatequalification

string - A WHERE clause qualificationfor the query that selects audittrail entries for deletion.

The qualification must be avalid qualification and canreference only audit trailobject type properties. Forexample, a valid qualificationis event=’approved’ orname=’dmadmin’. (Refer tothe general discussion of the




tool, above, for details ofsetting this argument.)

Refer to the Content ServerDQL Reference Manual forcomplete information aboutWHERE clause qualifications.

-cutoff_days integer 90 A minimum age, in days, forobjects to delete. All audittrail objects older than thespecified number of daysand that meet the specifiedqualification are deleted.

To delete all audit trailobjects, set this value to zero(0).

Guidelines

Audit trail entries are the result of audited events. The more events you audit, the moreaudit trail entries are generated in a fixed period of time.

You must decide if there are any reasons to keep or maintain audit trail entries. Forexample, you may want to keep certain items for traceability purposes. If so, leavethis tool inactive or set the cutoff_days argument to a value that will save the audittrail items for a specified length of time.

After you have made your decisions, formulate a scheduling plan.

If you do not supply a value for custom_predicate or cutoff_days, all system-generateddm_audittrail entries older than 90 days are deleted.

Report sample

Here is a sample of the report generated by the Audit Management Tool.AuditMgt Report For repository BLD9A As Of 10/19/98 12:26:31 PM

Parameters for removing audit trail items:--------------------------------------------- No items audited before 90 days will be removed...



- There is no custom predicate...

Looking for audit trail items to delete...Destroying audit trail item with ID 5f00010080000124Destroying audit trail item with ID 5f00010080000125Destroying audit trail item with ID 5f00010080000126Destroying audit trail item with ID 5f00010080000127Destroying audit trail item with ID 5f00010080000128Destroying audit trail item with ID 5f00010080000129Destroying audit trail item with ID 5f0001008000012aDestroying audit trail item with ID 5f0001008000012dDestroying audit trail item with ID 5f0001008000012eDestroying audit trail item with ID 5f0001008000012fDestroying audit trail item with ID 5f00010080000130Destroying audit trail item with ID 5f00010080000131Destroying audit trail item with ID 5f00010080000132Destroying audit trail item with ID 5f00010080000133Destroying audit trail item with ID 5f00010080000134Destroying audit trail item with ID 5f00010080000135Destroying audit trail item with ID 5f00010080000136Destroying audit trail item with ID 5f0001008000013718 audit trail items deleted...

End of Audit Trail Management ReportReport End 10/19/98 12:26:33 PM

Consistency CheckerThe Consistency Checker tool scans the repository and reports any inconsistencies suchas type or object corruption, objects that reference a user, group, or other object that isnonexistent in the repository and so forth. The tool does not attempt to fix any of theinconsistencies. Contact Documentum Technical Support for assistance in correctingerrors in your repository found by the consistency checker.

Appendix A, Consistency Checks, lists the consistency checks conducted by the tooland the error number assigned to each.

The job generates a report that lists the categories checked and any inconsistencies found.The report is saved to the repository in /System/Sysadmin/Reports/ConsistencyChecker.If no errors are found, the current report overwrites the previous report. If an error isfound, the current report is saved as a new version of the previous report.

It is recommended that you run this tool on a repository before upgrading the repositoryto a new version of the Documentum Server.

The Consistency Checker job is active by default, running once a day.



Running the job from a command line

The Consistency Checker job is implemented as a script called consistency_checker.ebs.You can run the script manually, from the operating system prompt. The syntax is:dmbasic -fconsistency_checker.ebs -eEntry_Point --repository_name superuser password

repository_name is the name of the repository against which you are running theconsistency checker, superuser is the user name of a repository superuser, and password isthe password for the superuser’s account.

When you run the consistency checker from the command line, the results of the checksare directed to standard output.

Arguments

The Consistency Checker job has no arguments.

Report sample

Here is a sample of a Consistency Checker report. This run of the tool found Xinconsistencies.Beginning Consistency Checks.....

Repository Name: buzzardServer Version: 5.1.0.63 Win32.SQLServerDatabase: SQLServer

##################################################### CONSISTENCY_CHECK: Users & Groups#### Start Time: 09-10-2002 10:15:55#####################################################

Checking for users with non-existent groupWARNING CC-0001: User 'docu' belongs to

non-existent group ''WARNING CC-0001: User 'engr' belongs to

non-existent group ''WARNING CC-0001: User 'marketing' belongs tonon-existent group ''WARNING CC-0001: User 'nagboat' belongs to

non-existent group ''WARNING CC-0001: User 'admingroup' belongs to



non-existent group ''Rows Returned: 5

Checking for users belonging to groups not in dm_userChecking for users not listed in dmi_object_typeChecking for groups not listed in dmi_object_typeChecking for groups belonging to non-existent groupsChecking for groups with non-existent super groups

######################################################## CONSISTENCY_CHECK: ACLs ###### Start Time: 09-10-2002 10:15:55######################################################

Checking for ACLs with non-existent usersChecking for ACLs with missing dm_acl_r table entriesChecking for sysobjects with acl_domain set tonon-existent userChecking for sysobjects that belong tonon-existent usersChecking for sysobjects with non-existent ACLsChecking for ACL objects with missing dm_acl_s entryChecking for ACL objects with r_accessor_permitvalue but missing r_accessor_name valueChecking for ACL objects with r_accessor_name valuebut missing r_accessor_permit valueChecking for ACL objects with r_is_group value butmissing r_accessor_permit valueChecking for ACL objects with r_is_group value butmissing r_accessor_name valueChecking for ACL object with r_accessor_name valuebut missing r_is_group valueChecking for ACL object with r_accessor_permit valuebut missing r_is_group value

###################################################### CONSISTENCY_CHECK: Sysobjects###### Start Time: 09-10-2002 10:15:58#####################################################

Checking for sysobjects which are not referenced indmi_object_typeChecking for sysobjects that point to non-existentcontentChecking for sysobjects that are linked to non-existentfoldersChecking for sysobjects that are linked to non-existentprimary cabinets



Checking for sysobjects with non-existent i_chronicle_idChecking for sysobjects with non-existent i_antecedent_idChecking for sysobjects with missingdm_sysobject_r entriesChecking for sysobjects with missingdm_sysobject_s entry

####################################################### CONSISTENCY_CHECK: Folders and Cabinets#### Start Time: 09-10-2002 10:16:02#####################################################

Checking for folders with missing dm_folder_r tableentriesChecking for folders that are referenced in dm_folder_rbut not in dm_folder_sChecking for dm_folder objects that are missing anentry in dmi_object_typeChecking for dm_folder objects that are missingcorresponding dm_sysobject entriesChecking for folders with non-existent ancestor_idChecking for cabinet that have missing dm_folder_rtable entriesChecking for cabinets that are missing an entry indmi_object_typeChecking for folder objects with missingdm_sysobject_r entriesChecking for folder objects with null r_folder_path

####################################################### CONSISTENCY_CHECK: Documents###### Start Time: 09-10-2002 10:16:03#####################################################

Checking for documents with a dm_sysobject_s entrybut no dm_document_s entryChecking for documents with missing dm_sysobect_sentriesChecking for documents with missing dmi_object_typeentry

####################################################### CONSISTENCY_CHECK: Content#### Start Time: 09-10-2002 10:16:03##



#####################################################

Checking for content objects that referencenon-existent parentsChecking for content with invalid storage_idChecking for content objects with non-existent format

####################################################### CONSISTENCY_CHECK: Workflow###### Start Time: 09-10-2002 10:16:03#####################################################

Checking for dmi_queue_item objects with non-existentqueued objectsChecking for dmi_workitem objects that referencenon-existent dm_workflow objectsChecking for dmi_package objects with missingdmi_package_s entriesChecking for dmi_package objects that referencenon-existent dm_workflow objectsChecking for workflow objects with non-existentr_component_idChecking for workflow objects with missingdm_workflow_s entryChecking for work item objects with missingdm_workitem_s entry

###################################################### CONSISTENCY_CHECK: Types#### Start Time: 09-10-2002 10:16:04####################################################

Checking for dm_type objects with a non-existent dmi_type_info objectChecking for dmi_type_info objects with a non-existentdm_type objectChecking for type objects with corrupted propertypositionsChecking for types with invalid property counts

####################################################### CONSISTENCY_CHECK: Data Dictionary#### Start Time: 09-10-2002 10:16:04##



###################################################

Checking for duplicate dmi_dd_attr_info objectsChecking for duplicate dmi_dd_type_info objectsChecking for any dmi_dd_attr_info objects that aremissing an entry in dmi_dd_common_info_sChecking for any dmi_dd_type_info objects that aremissing an entry in dmi_dd_common_info_sChecking for any dmi_dd_attr_info objects that aremissing an entry in dmi_dd_attr_info_sChecking for any dmi_dd_type_info objects that aremissing an entry in dmi_dd_type_info_s

###################################################### CONSISTENCY_CHECK: Lifecycles#### Start Time: 09-10-2002 10:16:11###################################################

Checking for sysobjects that reference non_existentpolicy objectsChecking for any policy objects that referencenon-existent types in included_typeChecking for any policy objects with missingdm_sysobject_s entryChecking for any policy objects with missingdm_sysobject_r entriesChecking for policy objects with missing dm_policy_rentriesChecking for policy objects with missing dm_policy_sentry

###################################################### CONSISTENCY_CHECK: FullText#### Start Time: 09-10-2002 10:16:11##################################################

Checking for tdk index objects that point tonon-existent fulltext index objectsChecking for any tdk collect objects that point tonon-existent tdk index objectsChecking for any fulltext index objects that pointto non-existent tdk index objectsChecking for any tdk index objects that point tonon-existent tdk collect objectsChecking for any non-orphaned dmr_content objectsthat point to types that do not existChecking for any non-orphaned dmr_content objectsthat point to non-existent formatsChecking for any dmr_content objects that point toa non-existent fulltext index



Checking for any fulltext index propertys that areno longer in dm_type

####################################################### CONSISTENCY_CHECK: Indices#### Start Time: 09-10-2002 10:16:11###################################################

Checking for dmi_index objects that referencenon-existent typesChecking for types with non-existent dmi_indexobject for <type>_s tableChecking for types with non-existent dmi_indexobject for <type>_r tableChecking for index objects with invalid propertypositions

###################################################### CONSISTENCY_CHECK: Methods#### Start Time: 09-10-2002 10:16:11##################################################

Checking for java dm_method objects that referencejview

Consistency Checker completed successfullyTotal number of inconsistencies found: 5Disconnected from the server.

Content ReplicationThe Content Replication tool automates content replication between the componentstorage areas of a distributed storage area. The tool uses dump and load operations, butunlike manual dump and load operations, only requires enough temporary disk space totransfer the largest individual content file to be replicated.

By default, the tool processes the content files in batches. It retrieves up to 500 contentfiles (the default batch size) and releases resources in the source database beforereplicating the files. You can adjust the size of the batches by setting the -batch_sizeargument. Each execution of the job may process multiple batches, depending on thenumber of content files to be replicated and the batch size.

If the -batch_size argument is set to 0, the DQL hint FETCH_ALL_RESULTS 0 is usedin the query. All files to be replicated are cached in the Content Server’s memory and



transferred individually. Set -batch_size to 0 only if you have a very large amount ofmemory available.

If the -batch_size argument is set to 1, the FETCH_ALL_RESULTS hint is not used andquery results are not cached.

If the -batch_size argument is set to any value greater than 1 and content transferoperations fail for the whole batch, the job exits and displays an error message.

The job uses a login ticket to connect to each source server. If you include the-source_servers argument, the job connects only to the servers in the list. If you do notinclude that argument, the job attempts to connect to each server in the repository.

Note: The clocks on the host machines of the source servers must be using UTC timeand must be synchronized with the host machine on which the job runs. The login ticketfor the job is valid for 5 minutes. If the clocks are not synchronized or the machines areusing times set to different time zones, the source server to which the job is connectingmay determine that the ticket has timed out and the job will fail.

A content replication job looks for all content not locally present, gets the files whileconnected to other sites, and performs an IMPORT_REPLICA for each content file inneed of replication. The job generates a report that lists each object replicated. The reportis saved to the repository in /System/Sysadmin/Reports/ContentReplication.

Note: If the report was run against the content at a remote distributed site, the report namewill have the site’s server config name appended. For example, if London is a remote site,its report would be found in /System/Sysadmin/Reports/ContentReplicationLondon.

Installing the tool suite at a site creates a content replication job for the installation site.In a distributed environment, the job’s argument values for the remote sites are based onthose of the Content Replication job for the primary site, but the job name and targetserver will be unique for each site. The job name has the format:dm_ContentReplicationserverconfig.object_name

The job’s target_server property identifies the local server performing the replicationusing the format repository.serverconfig@hostname.

The ContentReplication job is inactive by default.

Arguments

Table 51, page 467, describes the arguments for the tool.



Table 51. Content Replication arguments


-window_interval integer 120 Defines window in whichthe tool can run. Value isinterpreted in minutes.

-queueperson string(32) - User who receives email andinbox notifications from thetool. The default is the userspecified in the operator_nameproperty of the server configobject.

-batch_size integer 500 Number of content files toprocess in each batch.

-custom_predicate string - Qualification applied to thecontent to be replicated.Enter what would normallyappear after WHERE in a DQLqualification (For example,

FOLDER ('/xyz', descend)

-source_servers string - Comma-separated list ofContent Servers to which toconnect. Use the names of theservers’ server config objects.

The argument accepts amaximumof 255 characters. Thespecified names are recordedin the job’s method_argumentsproperty.

If this argument is not included,the job attempts to connect to allother servers in the repository.

Report sample

Here is a sample of a ContentReplication report.ContentReplication Report For repository wagnerdbAs Of 3/16/97 4:58:34 PM



Making lists of distributed components that arelocal and farFar Store: StoreCNear Store: StoreEGetting the source user for connecting toother sites...Getting the source password for connectingto other sites...Now connected to WagnerAReplicated 1 KB, format text for document

DBWarningReplicated 7 KB, format text for documentStateOfDocbaseReplicated 14 KB, format text for documentLogPurgeReplicated 2 KB, format text for document

ContentReplicationReplicated KB, format text for documentContentReplicationReplicated KB, format text for documentContentReplicationReplicated KB, format text for documentContentReplicationReplicated 3 KB, format text for documentContentWarningReplicated 5 KB, format text for documentDMCleanReplicated 4 KB, format text for documentDMFilescanReplicated KB, format text for documentDisconnected from WagnerA

Report End 3/16/97 4:58:53 PM

Content WarningThe Content Warning tool notifies you when disks that you use for content storageapproach a user-defined capacity. The notification is sent to the repository Inbox of thequeueperson and as an email message. The tool also generates a report that is stored inthe Reports folder under the Sysadmin folder in the System cabinet.

The tool determines where the repository is storing its content and then uses operatingsystem commands to determine whether these disks are reaching the specified threshold.When the disk space used meets or exceeds the value in the tool’s percent_full argument,a notification is sent to the specified queueperson and a report is generated and saved tothe Docbase in /System/Sysadmin/Reports/ContentWarning.

Note: If the tool was run against the content at a remote distributed site, the report namewill have the site’s server config name appended. For example, if London is a remotesite, its report would be found in /System/Sysadmin/Reports/ContentWarningLondon.

The Content Warning tool is installed in the active state by default.



Arguments


Table 52. Content Warning arguments


-percent_full integer 85 Percent-full threshold at whicha message is sent.


-window_interval integer 720 Execution window for the tool,expressed in minutes. Referto The window interval, page450 for a complete description.

Report sample

Here is a sample of a ContentWarning report.Object: test1_file_storeType : dm_filestorePath : /export/nfs2-4/dmadmin/data/test1/test1_storage_locationTotal Disk Total Used Total Free Percent Used1,952,573 1,620,019 137,304 93

DocBasic Total Free: 1,124,794Content File (Document) Space UtilizationIn test1_file_store

-Active 2,485,090-Deleted 81,397-Total 2,566,487

Object: test1_file_store2Type : dm_filestorePath : /export/nfs2-1/dmadmin/data/test1/storage_02

Total Disk Total Used Total Free Percent Used1,952,573 1,113,666 643,657 67

DocBasic Total Free: 977,871

Content File (Document) Space Utilization



In test1_file_store2-Active 733,532-Deleted 3,821-Total 737,352

Object: support_file_storeType : dm_filestorePath : /export/nfs2-1/dmadmin/data/test1/docs_from_test2

Total Disk Total Used Total Free Percent Used1,952,573 1,113,666 643,657 67

DocBasic Total Free: 977,871

Content File (Document) Space Utilization Intest2_file_store-Active 863-Deleted-Total 863

Create Full-Text EventsThe Create Full-Text Events tool generates events for unindexed objects in a repository.The Create Full-Text Events tool (dm_FTCreateEvents) may be used in two ways:• To complete an upgrade by generating events for any objects missed by the

pre-upgrade indexing operations

The job generates events for each indexable object added to a repository between thetime a new 5.3 or later full-text index is created for a 5.2.5 repository and when therepository is upgraded to 5.3

For example, a copy of a 5.2.5 repository can be used to create a new 5.3 index.Depending on when the production repository is upgraded, new indexable objectsmay be created in the production repository after the new 5.3 index is created. Whenthe production repository is upgraded to 5.3 and begins to use the new index, therepository contains objects that are not yet indexed. Running dm_FTCreateEventsgenerates events for the new objects. An index agent running in normal mode usesthe events to submit the objects for indexing.

This is the default behavior of the job.• To generate the events required to reindex an entire 5.3 or later repository

The -full_reindex argument must be set to TRUE to generate the required events.Reindexing the repository does not require deleting the existing index. If you runthe tool to reindex the repository, schedule the job to run daily and do not changethe default batch size of 50,000 items.

The tool itself does not update the index; it only generates the events that will be usedto update the index. The tool can optionally generate a list of object IDs of objects thatmust be indexed, rather than generating events for those objects. The list is used to



submit objects to the index agent in file mode for indexing. The Content Server Full-TextIndexing System Installation and Administration Guide contains instructions for using theindex agent’s file mode.

The first time the job runs in its default mode, the job determines the last object indexedby an index agent running in migration mode and the date on which that object wasindexed. The job searches for objects modified after that date and before the job runsfor the first time and generates events for those objects. On its subsequent iterations,the job searches for objects modified after the end of the last iteration and before thebeginning of the current iteration.

Before the job is run in a 5.3 or later repository with full_reindex set to TRUE, you mustcreate a high-water-mark queue item (dmi_queue_item) manually and then specifythe r_object_id of the queue item as the -high_water_mark_id argument of the CreateFull-Text Events tool.

By default, the tool is installed in the active state to run daily at 11 p.m. The toolprocesses new objects in batches of 50,000. If all objects are not processed in one run,the tool continues executing each day at 11 p.m. When it finds no more objects toprocess, it sets itself to inactive. When the -full_reindex argument is set to TRUE, theevents are created in reverse chronological order by r_modify_date and therefore themost recently-modified or created objects are indexed first.

Create Full-Text Events generates a status report that is saved in the repository in/System/Sysadmin/Reports/FTCreateEvents.

Arguments

Table 53, page 471. describes the tool’s arguments. When the job is run in the defaultmode, all arguments are provided by the job itself. When the job is run in full-reindexmode, you must set -full_reindex to TRUE and provide the r_object_id of themanually-created queue item as the value of -high_water_mark_id.

Table 53. Create Full-Text Events arguments


-max_events_per_run

integer 50000 The maximumnumber of eventsgenerated eachtime the job runs.If max_events_per_run is not setor is set to zero,the job creates




events for all objectschanged or createdbetween min_dateand max_date.

-high_water_mark_id

- Object ID of thequeue item to usefor obtaining thelast date for whichqueue items werecreated. If it is notspecified, the jobqueries for the mostrecently createddmi_queue_itemin which the valueof item_name is“Full-text re-indexhigh water mark”and the valueof task_state is“done.”

In full reindexmode, you mustprovide ther_object_id of themanually-createdhigh-water-markqueue item.

-min_date Date When not in fullreindex mode,the value ofthe date_sentproperty of themigration-modequeue item forindexing.

The earliest dateon which objectswere modifiedfor which the jobcreates events.




-max_date Date When not in fullreindex mode, thedate on which thejob runs for the firsttime.

The most recentdate on whichobjects weremodified for whichthe job createsevents.

-file string - When submittedwith a filename, theobject IDs of objectsthat require eventsare written to a file.The syntax is:

-file full_path_of_file

-full_reindex Boolean FALSE When set tofalse, the jobgenerates eventsfor each indexableobject added to arepository betweenthe time a new5.3 full-text indexis created for a5.2.5 repository andwhen the repositoryis upgraded. Thisis the behavior ofthe job when it isinstalled.

When set toTRUE, eventsare generatedfor all indexableobjects in reversechronological orderby the value of ther_modify_date.




-current_only Boolean FALSE Use when-full_reindex is setto TRUE. Whenset to TRUE,new events aregenerated onlyfor the CURRENTversion of eachindexable object.

-queueperson string(32) - User who receivesemail and inboxnotifications fromthe tool. Thedefault is the userspecified in theoperator_nameproperty of theserver config object.

-window_interval integer 12000 Execution windowfor the tool,expressed inminutes. Referto The windowinterval, page450 for a completedescription.

Report sample

Here is a sample of a Create full-text events report.2005/07/19 14:07:41:552 ---------------------------------------2005/07/19 14:07:42:395 Located High Water Mark dmi_queue_item '1b0014dc8000210e'

as the most recent one that was marked complete.2005/07/19 14:07:42:395 min date from hwm: '07/18/2005 18:26:27'.2005/07/19 14:07:42:395 High Water Mark dmi_queue_item has no router_id set,

hence it's a brand new iteration of this job.2005/07/19 14:07:42:395 Updating High Water Mark '1b0014dc8000210e',

setting actual_start_date to '07/19/2005 14:07:42'.2005/07/19 14:07:42:474 Query begin: select r_object_id, r_modify_date fromdm_sysobject (all) where r_modify_date >= DATE('07/18/2005 18:26:27','mm/dd/yyyy hh:mi:ss') and r_modify_date < DATE('07/19/2005 14:07:42','mm/dd/yyyy hh:mi:ss') and r_object_id > '0000000000000000'



order by r_object_id2005/07/19 14:07:42:505 Query end2005/07/19 14:07:42:505 Query result: 080014dc800002c2 07/19/2005 14:07:412005/07/19 14:07:42:708 Query result: 090014dc80001906 07/19/2005 14:03:432005/07/19 14:07:42:755 Query result: 090014dc80001908 07/19/2005 14:03:432005/07/19 14:07:42:786 Created 3 events or dmi_queue_item objects(Batch Size used was 50000).2005/07/19 14:07:42:786 Done creating events.

Updating the High Water Mark '1b0014dc8000210e',by setting the router_id to '0000000000000000'.2005/07/19 14:07:42:895 ---------------------------------------Report End 2005/07/19 14:07:42

Data Dictionary PublisherThe Data Dictionary Publisher tool publishes the data dictionary information. The datadictionary is information about object types and properties stored in internal objectsby Content Server and made available to client applications through the publishingoperation. Publishing the information creates dd type info and dd attr info objects.These are persistent objects whose properties store the data dictionary information.Client applications that use the data dictionary information can reference or query theseobjects and their properties. (For more information about the data dictionary, referto Content Server Fundamentals.)

Data Dictionary Publisher generates a status report that is saved in the repository in/System/Sysadmin/Reports/DataDictionaryPublisher.

Arguments

Table 54, page 475, describes the tool’s argument.

Table 54. Data Dictionary Publisher argument





Report sampleConnected To sqlntX.sqlntXJob Log for System Administration ToolDataDictionaryPublisher-----------------------------------------------

This job log consists of three distinct parts:1) All print statements from the execution of the job2) The report for the tool which is saved as a

separate document in the Docbase in/System/Sysadmin/Reports.

3) The trace file results from the trace API,if the job's trace level is > 0.

Note: The report and trace file are also maintainedunder the Documentum log location in:$DOCUMENTUM/dba/log/<docbase hex id>/sysadminThey are overwritten each time the job executes.

Start of log:-------------DataDictionaryPublisher Tool Completed at11/8/2000 12:15:25. Total duration was 0 minutes.Calling SetJobStatus function...

--- Startc:\Documentum\dba\log\000145df\sysadmin\DataDictionaryPublisherDoc.txt report output ----DataDictionaryPublisher Report For DocBase sqlntXAs Of 11/8/2000 12:15:24DataDictionaryPublisher utility syntax:apply,c,NULL,EXECUTE_DATA_DICTIONARY_LOGExecuting DataDictionaryPublisher...Report End 11/8/2000 12:15:25

--- Endc:\Documentum\dba\log\000145df\sysadmin\DataDictionaryPublisherDoc.txt report output ---

Database Space WarningThe Database Space Warning tool scans the RDBMS to determine:• How full the tablespace (Oracle) or device (Sybase) is• Whether any tables are fragmented beyond a user-specified limit• Whether the expected number of Documentum indexes are presentThe tool also recreates any indexes that are identified by dmi_index objects but notfound in the database.

Note: The Database Space Warning Tool is not needed, and therefore not installed, forinstallations running against MS SQL Server or DB2.



If the tool finds that the space has reached the limit specified in the tool’s percent_fullargument, it sends a notification to the user specified in queueperson. When it sendsa notification, it also includes a message about any RDBMS tables that are fragmentedbeyond the limits specified in the max_extents argument and a message regardingindexes, if it does not find the expected number in the RDBMS. The notifications are sentto the user’s repository Inbox and through email.

In addition to these notifications, the tool generates a status report that is saved in therepository in /System/Sysadmin/Reports/DBWarning.

The Database Space Warning tool is installed in the active state.

For Sybase, you must set the ddl in tran database option to TRUE to run this job. Theisql syntax is:sp_dboption dbname, "ddl in tran", true

where dbname is the name of the database for your repository.

Arguments

Table 55, page 477, lists the tool’s arguments.

Table 55. Database Space Warning arguments


-percent_full integer 85 Percent-full threshold at whicha message is sent.

-max_extents integer 50 The number of extents that anRDMBS table may have beforebeing reported as fragmented.





Report sample

Here is a sample of a Database Space Warning report. It shows the total number ofblocks allocated for the database, how many are currently used for tables and indexes,the percentage used of the total allocated, and the number of free blocks. It also lists thenumber of fragments for all tables and indexes with more than max_extents fragmentsand lists the number of Documentum indexes in the repository.Database Block AllocationTable Index TotalUsed Free Total %Used/Total620 647 1,267 81,929 83,196 2

DBMS Tables With Multiple Extents# of Segs Type Name

6 TABLE DM_TYPE_R5 INDEX DMINDEX_1F000963800000094 TABLE DM_SYSOBJECT_S3 TABLE DMI_OBJECT_TYPE3 INDEX DMI_OBJ_TYPE_INDEX3 INDEX DMI_OBJ_ID_INDEX3 TABLE DM_FORMAT_S3 TABLE DM_SYSOBJECT_R

Inbox and email message samples

Here is a sample Inbox message sent by the Database Space Warning tool:Take a look at your DBMS tablespace--it's 90% full!You have 8 fragmented tables in your DBMS instance--you may want to correct this!You are missing some Documentum indexes-contact Support!

Here is the corresponding email message:Return-Path: <dmadmin@bigcat>X-UIDL: 827349620.001Date: Wed, 20 Mar 1996 11:18:54 -0800From: dmadmin@bigcat (Documentum 2.0)To: stevex@tigerSubject: Event FraggedTables has occurredon DBWarning.Doc(090000018006ee33) by dm20

DOCBASE: test1EVENT: FraggedTablesNAME: DBWarning.DocSENT BY: dmadminTASK NAME: event

MESSAGE:You have 18 fragmented tables in your DBMS instance--you may want to correct this!



Dm_LDAPSynchronizationThe dm_LDAPSynchronization tool finds the changes in the user and group informationin an LDAP directory server that have occurred since the last execution of the tool andpropagates those changes to the repository. If necessary, the tool creates default foldersand groups for new users. If there are mapped user or group properties, those are alsoset.

The tool can:• Import new users and groups in the directory server into the repository• Rename users in the repository if their names changed in the directory server• Rename groups in the repository if their names changed in the directory server• Inactivate users in the repository that if they were deleted from the directory server.When using iPlanet, you must enable the changelog feature to use the inactivationoperation. Instructions for enabling the changelog feature are found in the vendor’siPlanet Administration Guide.

The behavior of the tool is determined by the property settings of the dm_ldap_configobject. The tool has four arguments that you can use to override the property settingscontrolling which operations the tool performs. These are listed in Table 56, page 480.

The dm_LDAPSynchronization tool requires the Java method server. Ensure that theJava method server in your Content Server installation is running.

The dm_LDAPSynchronization tool generates a report that is saved in the repository in/System/Sysadmin/Reports/LDAPSynchronization.

The tool is installed in the inactive state. After it is activated, it is executed once a dayat 4 a.m. by default. Before you set it to the active state, you must define the ldapconfig object for the repository. For instructions about defining the set-up values, referto Defining the set-up values, page 333.

Arguments




Table 56. dm_LDAPSynchronization arguments


-deactivate_user_option

Boolean FALSE Set to TRUE, directs the jobto inactivate users in therepository that have beendeleted from the directoryserver.

Setting this overrides thedeactivate_user_optionproperty in the ldap configobject.

-full_sync Boolean FALSE Set to TRUE, this directs thejob to retrieve all entries fromthe LDAP directory that satisfythe search criteria. FALSEcauses the job to import intothe repository only new orupdated LDAP entries.

-import_mode string(7) all Controls whether the jobimports users, groups, or bothinto the repository. Validvalues are: users, groups, andall.

Setting this overrides theimport_mode property in theldap config object.





-rename_group_option

Boolean FALSE Set to TRUE, directs the jobto rename groups in therepository if their names havechanged in the directory server.

Setting this overrides therename_group_optionproperty in the ldap configobject.

-rename_user_option

Boolean FALSE Set to TRUE, directs the job torename users in the repositoryif their names have changed inthe directory server.

Setting this overrides therename_user_option propertyin the ldap config object.

-source_directory dm_all_directories

Controls which LDAP serversare synchronized when the jobruns.

If not set, all LDAP serversassociated with the serverconfig object are synchronized.If set to particular LDAPservers, only those servers aresynchronized.

Explicitly specifying LDAPservers in -source_directory ,page 482, describes how specifymultiple servers individually.

-window_interval integer 1440 Execution window for the tool.Refer to The window interval,page 450 for a completedescription.



Executing dm_LDAPSynchronization manually

You can execute the dm_LDAPSynchronization tool manually from the command line.The syntax isjava com.documentum.ldap.LDAPSync -docbase_name repositoryname-user_name superuser_login -method_trace_level integer -full_sync true

where repositoryname is the name of the repository, superuser_login is the login for aSuperuser, and integer is the required trace level for the method.

Explicitly specifying LDAP servers in -source_directory

Use the LDAP server’s object name to identify the server in the -source_directoryargument. If you want to identify multiple servers, use the following syntax:ldap_config_obj_name+ldap_config_obj_name{+ldap_config_obj_name}

where ldap_config_object_name is the object name value of the ldap config object forthe LDAP directory server. For example:ldap_engr1+ldap_engr2+ldapQA

DmcleanThe Dmclean tool automates the dmclean utility. The utility scans the repository fororphaned content objects, ACLs, annotations (dm_note objects), and aborted workflows.The utility also scans for the workflow templates created by the SendToDistributionListcommand (a Documentum Desktop command that routes a document to multipleusers concurrently) and left in the repository after the workflow completed. The utilitygenerates a script to remove these orphans. (For detailed information about the dmcleanutility, refer to Chapter 7, Content Management.) The Dmclean tool performs dmclean’soperations and (optionally) runs the generated script.

When the agent exec program invokes the script, the tool generates a report showingwhat content objects, content files, ACLs, notes and workflow templates wouldbe removed upon execution of the generated script. The status report is saved in/System/Sysadmin/Reports/DMClean.

Note: If the tool was run against the content at a remote distributed site, the report namewill have the site’s server config name appended. For example, if London is a remotesite, its report would be found in /System/Sysadmin/Reports/DMCleanLondon.

Whether the generated script runs is controlled by the tool’s clean_now argument.This argument is set to TRUE by default. If you set it to FALSE, the script is



not run, and you will have to run it manually to remove the orphan objects.The script is stored in %DOCUMENTUM\dba\log\hexrepositoryid\sysadmin($DOCUMENTUM/dba/log/hexrepositoryid/sysadmin).

The Dmclean tool is installed in the inactive state.

Arguments


Table 57. Dmclean arguments


-clean_content Boolean TRUE Controls whether the toolsearches for orphaned contentobjects. Set to FALSE ifyou do not want to includecontent objects in the dmcleanoperation.

-clean_note Boolean TRUE Controls whether the toolsearches for orphaned noteobjects (annotations). Set toFALSE if you do not want toinclude notes in the dmcleanoperation.

Note: Even if the setting isTRUE, the tool never removesa note whose object ID isrecorded in an audit trail entry(a dm_audittrail object).

-clean_acl Boolean TRUE Controls whether the toolsearches for orphaned ACLs.Set to FALSE if you do not wantto include ACLs in the dmcleanoperation.




-clean_now Boolean TRUE Controls whether the toolremoves the orphaned objects.The dmclean utility generatesa script to clean the repository.Setting clean_now to TRUEautomatically executes thescript as part of the job.

-clean_wf_template

Boolean TRUE Controls whether the toolremoves old workflowtemplates created whenusers executed theSendToDistributionList menucommand from a Documentumclient menu.

-clean_aborted_wf Boolean FALSE Controls whether the toolremoves aborted workflowsand all the workflows’associated runtime objects(packages, work items, and soforth) from the repository.

-clean_castore Boolean FALSE Controls whether the toolincludes orphaned contentwith expired retention datesin EMC Centera storage areasin the operation. T means thatexpired, orphaned content inEMC Centera storage areas isincluded in the operation.





Guidelines

If you are using distributed content, Dmclean requires the default storage area fordm_sysobjects to be the distributed store.

How often you run Dmclean will depend on• Your business rules• The size of the repository• The amount of storage capacityTypically, including notes and ACLs in the operation noticeably increases the executiontime of the tool, so you may want to reset these arguments to FALSE on some runs.

If you prefer to review what and how much will be deleted before executing the script,set the clean_now argument to FALSE. (You will have to execute the script manuallyafter inspection.)

Report sample

Here is a sample of a Dmclean report:DMClean Report For DocBase testdocAs Of 5/14/2002 11:58:46

Arguments for the dmclean method:Unused annotation objects will be cleaned up...Unused internal ACL objects will be cleaned up...Unused SendToDistributionList workflow templateobjects will be cleaned up...Orphaned content objects will be cleaned up...Generated DMClean script will be executed...

The trace level is set to 0...DMClean utility syntax: apply,c,NULL,DO_METHOD,METHOD,S,dmclean

Executing DMClean...All Clean contents were successfully removed.Generated script from the DMClean method:----- StartC:\Documentum\dba\log\000003e8\sysadmin\080003e8800005d6.batoutput ------------------------# Opening document base testdoc...# Total shared memory size used: 1554112 bytes# Making /System cabinet.# /System cabinet exists.# Making /Temp cabinet.# /Temp cabinet exists.# Making /System/Methods folder.# /System/Methods folder exists.# Making /System/FileSystem folder.



# /System/FileSystem folder exists.# Making /System/DataDictionary folder.# /System/DataDictionary folder exists.# Making /System/Procedures folder.# /System/Procedures folder exists.# Making /System/Procedures/Actions folder.# /System/Procedures/Actions folder exists.# Making /System/Distributed References folder.# /System/Distributed References folder exists.# Making /System/Distributed References/Linksfolder.# /System/Distributed References/Links folderexists.# Making /System/Distributed References/Checkoutfolder.# /System/Distributed References/Checkout folderexists.# Making /System/Distributed References/Assembliesfolder.# /System/Distributed References/Assemblies folderexists.# Making /System/Distributed References/Workflowfolder.# /System/Distributed References/Workflow folderexists.# Making /System/Distributed References/VDM folder.# /System/Distributed References/VDM folder exists.# Making docbase config object.# Making server config object.## Documentum, Inc.## dmclean cleans up orphan content, annotation,# internal ACL, and unused SendToDistributionList# workflow template objects. Instead of immediately# destroying the orphan content objects, dmclean# generates an API script, which can# be used for verification before cleanup actually# happens.# This is done in this manner because deleted content# objects by mistake are difficult to recover.# dmclean, however, cleans up all unused annotations# and internal ACLs.# To remove orphan content objects after verification,# do the following in iapi:## % iapi <DOCBASE> -U<USER> -P<PWD># API> @<SCRIPT_NAME># API> quit## Starting to clean up unsed content objects...# Content object 060003e880002100 has parent# count of zero.apply,c,060003e880002100,DESTROY_CONTENTgetmessage,cclose,c,q0# Content object 060003e880002101 has parent



# count of zero.apply,c,060003e880002101,DESTROY_CONTENTgetmessage,cclose,c,q0# Content object 060003e880002105 has parent# count of zero.apply,c,060003e880002105,DESTROY_CONTENTgetmessage,cclose,c,q0# Content object 060003e88000210c has parent# count of zero.apply,c,060003e88000210c,DESTROY_CONTENTgetmessage,cclose,c,q0# Content object 060003e880002114 has parent# count of zero.apply,c,060003e880002114,DESTROY_CONTENTgetmessage,cclose,c,q0# Content object 060003e880002119 has parent# count of zero.apply,c,060003e880002119,DESTROY_CONTENTgetmessage,cclose,c,q0# Count of objects with zero parent count was: 6# Content cleanup complete.# Starting to clean up unused subcontent objects...# SubContent cleanup complete.# Starting to Remove unused annotations...# Total number of annotations removed: 0# Starting to clean up unsed internal ACLs...# Total number of ACLs removed: 0# Internal ACL clean up complete.# Starting to Remove unused SendToDistributionList# workflow templates...# Total number of SendToDistributionList workflow# templates removed: 0------- EndC:\Documentum\dba\log\000003e8\sysadmin\080003e8800005d6.bat output ------------------------Destroying DMClean script with ID 090003e880002907...Report End 5/14/2002 11:59:16

DmlescanThe Dmfilescan tool automates the dmfilescan utility. This utility scans a specific storagearea or all storage areas for any content files that do not have associated content objectsand generates a script to remove any that it finds. The tool executes the generated scriptby default, but you can override the default with an argument. (For detailed informationabout the dmfilescan utility, refer to Using dmfilescan, page 270.)



Dmfilescan also generates a status report that lists the files it has removed. The report issaved in the repository in /System/Sysadmin/Reports/DMFilescan.

Note: If the tool was run against the content at a remote distributed site, the report namewill have the site’s server config name appended. For example, if London is a remotesite, its report would be found in /System/Sysadmin/Reports/DMFilescanLondon.

Dmfilescan is installed in the inactive state.

Arguments

Table 58, page 488, lists the arguments for the tool. Refer to the description of thedmfilescan utility in Using dmfilescan, page 270, for instructions on specifying valuesfor the -from and -to arguments.

Table 58. Dmlescan arguments


-s storage_name string - Specifies a target storagearea. If this argument is notincluded, all storage areas arescanned.

-from directory_path string - Starting subdirectory for thescan operation.

Refer to Identifying thesubdirectories of the scannedstorage areas, page 271 forinformation about using thisargument.

-to directory_path string - Ending subdirectory for thescan operation.

Refer to Identifying thesubdirectories of the scannedstorage areas, page 271 forinformation about using thisargument.




-scan_now Boolean TRUE Controlswhether the generatedscript is executed. TRUE (thedefault) executes the generatedscript. Set this to FALSE ifyou want to execute the scriptmanually.


-window_interval integer 120 Execution window for the tool.Refer toThe window interval,page 450 for a completedescription.

-force_delete Boolean FALSE Controls whether orphan filescreated within 24 hours of thejob’s execution are deleted.Refer to the Guidelines fordetails.

-no_index_creation Boolean FALSE Controls whetherdmfilescan creates anddestroys the indexes ondmr_content.data_ticket anddmr_content.other ticket orassumes they exist.

T (TRUE) means that the utilityassumes that the indexes existprior to the start of the utility. F(FALSE) means the utility willcreate these indexes on startupand destroy them at the finish.

Refer to Using the-no_index_creation argument,page 272 for details of use.

-grace_period integer 168 Defines the grace period forallowing orphaned content filesto remain in the repository. The




default is 168 hours (1 week),expressed as hours. The jobremoves orphaned files whoseage exceeds 1 week or the valuedefined in the -grace_periodargument.

The integer value for thisargument is interpreted ashours.

Guidelines

Typically, if you run the Dmclean tool regularly, it is not necessary to run the Dmfilescantool more than once a year. By default, the tool removes all orphaned files from thespecified directory or directories that are older than 24 hours. If you wish to removeorphaned files younger than 24 hours, you can set the -force_delete flag to T (TRUE).However, this flag is intended for use only when you must remove younger files toclear diskspace or to remove temporary dump files created on the target that were notremoved automatically. If you execute Dmfilescan with -force_delete set to T, makesure that there are no other processes or sessions creating objects in the repository atthe time the job executes.

If you are using distributed content, dmfilescan requires the default storage area fordm_sysobjects to be the distributed store.

Report sample

The following is a sample of a Dmfilescan report.DMFilescan Report For DocBase boston2As Of 9/17/96 11:08:54 AMGenerated DMFilescan script will be executed...The trace level is set to 5...

DMFilescan utility syntax: apply,c,NULL,DO_METHOD,METHOD,S,dmfilescanExecuting DMFilescan...Executing DMFilescan script...sh /u106/dm/dmadmin/dba/log/00000962/sysadmin/0900096280012800.bat>/u106/dm/dmadmin/dba/log/00000962/sysadmin/0900096280012800.txtGenerated script from the DMFilescan method:



----- Start/u106/dm/dmadmin/dba/log/00000962/sysadmin/0900096280012800.bat output------------------------#!/bin/sh -x## Documentum, Inc.## This script is generated by dmfilescan for later# verification and/or clean-up. This script is in# trace mode by default. To turn off the trace mode,# remove the '-x' in the first line.## To see if there are any content objects referencing# a file reported below, use the following query# (executed in idql):## % idql <docbase> -U<user> -P<pwd># 1> select r_object_id from dmr_content# 2> where storage_id = '<storage_id>' and data_ticket =# <data_ticket># 3> go## If there are no rows returned, then this is an# orphan file.## Opening document base boston2...# Making distributed object_id map.# Making /System cabinet.# /System cabinet exists.# Making /Temp cabinet.# /Temp cabinet exists.# Making /System/Methods folder.# /System/Methods folder exists.# Making /System/FileSystem folder.# /System/FileSystem folder exists.# Making docbase config object.# Making server config object.# Document base boston2 opened. Starting filescan...# Building indexes for content lookups ...# Checking store filestore_01...# Checking store replica_filestore_01...# Checking store replicate_temp_store...# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/01'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/02'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/03'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/04'



# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/05'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/06'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/07'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/08'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/09'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/0a'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/0b'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/0c'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/0d'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/0e'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/0f'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/10'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/11'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/12'# Reading directory '/u127/dm/data/boston2/content_storage_01/00000962/80/00/13'# Reading directory '/u127/dm/data/boston2/replica_content_storage_01/00000962'# Reading directory '/u127/dm/data/boston2/replica_content_storage_01/00000962/80'# Reading directory '/u127/dm/data/boston2/replica_content_storage_01/00000962/80/00'# Reading directory'/u127/dm/data/boston2/replica_content_storage_01/00000962/80/00/01'# Reading directory'/u127/dm/data/boston2/replica_content_storage_01/00000962/80/00/02'# Reading directory'/u127/dm/data/boston2/replica_content_storage_01/00000962/80/00/03'# Reading directory'/u127/dm/data/boston2/replica_content_storage_01/00000962/80/00/09'# Reading directory'/u127/dm/data/boston2/replica_content_storage_01/00000962/80/00/0a'# Reading directory'/u127/dm/data/boston2/replica_content_storage_01/00000962/80/00/0c'# Reading directory'/u127/dm/data/boston2/replica_content_storage_01/00000962/80/00/07'



# Reading directory '/u127/dm/data/boston2/temp_replicate_store/00000962'# Directory /u127/dm/data/boston2/temp_replicate_store/00000962 is empty# 0 orphan files were found## Cleaning up content indexes ...------- End /u116/dm/dmadmin/dba/log/00000962/sysadmin/0900096280012800.bat output------------------------Destroying DMFilescan result file with ID 0900096280012800...Report End 9/17/96 11:09:54 AM

File ReportThe File Report tool assists you in restoring deleted repository documents. It generates areport that lists all documents in the repository and their corresponding content files.Using that report in conjunction with a file system backup, you can restore the contentfile of a deleted document. (Refer to Using a report to restore a document, page 494,for instructions on restoring a document.)

If a document must be recreated, these reports identify which files must be restored torebuild the document. The system administrator matches lost documents to the filenames so that the content files can be recovered. This feature is especially useful forrestoring a single document (or a small set of documents) to a previous state, whichcannot be done from database backups.

The File Report tool, as installed, runs a full report once a week against all file storageareas in the repository. It is possible to run incremental reports and reports that onlyexamine a subset of the storage areas for the repository. For instructions on setting theseup, refer to Creating incremental or partial-repository reports, page 494.

Note: File Report only provides a mechanism for restoring the document content. Thedocument metadata must be restored manually.

File Report saves the generated report to /System/Sysadmin/Reports/FileReport.

The File Report tool is installed as inactive.

Guidelines

Set up the File Report schedule on the same interval as the file system backups. Forexample, if nightly backups are done, also run File Report nightly and store the resultingreport with the backups.



We recommend scheduling nightly incremental reports and generating full repositoryreports on a less frequent basis (weekly or biweekly).

If your repository is so large that creating full reports is not practical or generatescumbersome files, set up multiple jobs, each corresponding to a different storage area.

Usage notes

This section describes two procedures for using file reports:• Creating new file report jobs to create incremental reports or reports for a subset of

storage areas.• Using file reports to recover a document

Creating incremental or partial-repository reports

A File Report job creates an incremental report if its -incremental_report argument isset to TRUE. Incremental reports only include documents that have changed since thelast File Report was run.

If you include the -storage_area argument, the job generates a report on the documentsin the specified storage area.

If you include the -folder_name argument, the job generates a report on documents inthe specified folder.

Including both the -storage_area and -folder_name arguments generates a report onthose documents in the specified folder that are also stored in the given storage area.

To create a job that generates incremental reports or only reports on some storage areas,copy an existing File Report job object and set its properties and arguments as needed.Provide a new name for the copy that identifies it meaningfully.

Creating jobs and job sequences, page 145, provides instructions for creating new jobs,and the Documentum System Object Reference Manual contains a description of the dm_jobobject’s properties. You can create or copy a job using Documentum Administrator.

Using a report to restore a document

The following procedure describes how to use a report to restore a document.



To restore a document to the repository:1. Find the last backup file report with the document listed in it.

2. Find the name(s) of the content file(s) which comprise the document.

3. Restore the named files from your file system backups to the original storage area.This restores the content files to the storage area directory. This does not restore thedocuments to the repository. Until the files are imported back into the repository,they are treated as orphaned content files and will be removed by the next invocationof the dm_clean utility.If you wish, you can move these files out of the storage area directories to a moreappropriate work area in order to import them into the repository.

4. Use the restored content files to recreate the repository documents.The best way to do this is to use a Documentum client to recreate the object metadataand then use a DFC session on the server machine to restore the content.If you need to restore renditions of the document pages manually, use anaddRendition method.You can restore documents that have only one content file using the client’s Importfunction if the content files are directly accessible by the client. Because the contentfiles restored from file system backups are written to the server storage areas, youmust either directly access those directories from the client or copy the restored filesto a network disk and import them from there.If the document has multiple pages, use DFC methods to restore it.

Arguments

Table 59, page 495, lists the arguments for the tool.

Table 59. File Report arguments


-folder_namefolder_path

string - Identifies a folder path onwhich to run the report. Maybe used in conjunction with the-storage-area argument.




-incremental_report

Boolean FALSE When set to TRUE, the reportis run incrementally. Anincremental report only reportsdocuments modified since thelast time the job ran. (A fullreport is generated on the firstexecution of the job).

-storage_areastorage_name

string - Identifies a storage area onwhich to run the report. Usethe storage area’s name. If thisargument is not set, the reportruns against all storage areas inthe repository.

-output_device string - Identifies a file to which towrite the report data. Thespecification must be in theformat:

directory_path/file_name

If the file already exists, data isappended to it.

Use this option when you wantto write directly to a tape driveor other device.

If not set, the report file is savedto: System/Sysadmin/Reports/FileReport

-report_renditions Boolean TRUE When set to TRUE, renditionfiles are reported as well asthe primary format files. Setto False if you do not wish toreport renditions.




-sort_results Boolean TRUE When set to TRUE, thefile report is sorted byfolder_path/object_name.

Because this option requires adatabase sort of the entire dataset returned, you may need totune your database’s sort/tempspace parameters if you usethis option.


-queueperson string - Identifies the user who receivesInbox and email notificationsfrom the tool.

Report sample

Each line of a File Report contains the following information:• Document object_id• Document’s folder_path and object_name• Document owner• Document modification date• Document version• Content format• Content page number• Content file nameThe following sample report describes a two-page Word document.100015b4800001b5 /roger/research/newproject_1 roger4/26/95 19:07:22 1.3 msw6 0

/u120/install/dmadmin/data/rogbase2/content_storage_01/000015b4/80/00/01/49.doc100015b4800001b5 /roger/research/newproject_1 roger4/26/95 19:07:22 1.3 msw6 1

/u120/install/dmadmin/data/rogbase2/content_storage_01/000015b4/80/00/01/4a.doc



The following sample report describes a single-page Word document with a PDFrendition.090015b4800004f1 /roger/research/newproject_2roger 6/16/95 20:00:47 1.7 msw6 0

/u120/install/dmadmin/data/rogbase2/content_storage_01/000015b4/80/00/02/52.txt090015b4800004f1 /roger/research/newproject_2 roger6/16/95 20:00:47 1.7 pdf 0

/u120/install/dmadmin/data/rogbase2/content_storage_01/000015b4/80/00/02/6e.pdf

Group RenameThe Group Rename tool renames repository groups. This tool works in conjunction withDocumentum Administrator. To rename a group, you must use the Groups pages inDocumentum Administrator to identify the group and its new name. DocumentumAdministrator offers you two options for actually executing the rename operation:• Running the Group Rename tool immediately after you identify the new name• Queuing the operation until the next scheduled execution of the Group Rename toolYou cannot use a set method to change a group name. You must go throughDocumentum Administrator and either a manual or automatic Group Rename executionto change a group name.

The Group Rename tool generates a report that lists the changes made to therepository objects for the group rename. The report is saved in the repository in/System/Sysadmin/Reports/GroupRename.

The tool is installed in the inactive state.

Arguments

The Group Rename tool has no arguments.

Index Agent StartupThe dm_FTIndexAgentBoot job starts index agents associated with a Content Serverwhen the Content Server starts up. You do not need to run the job manually. Do notmodify the dm_FTIndexAgentBoot job. Modifying the job is not supported.



Log PurgeThe Log Purge tool deletes old log files. Table 60, page 499, lists the log files deletedby Log Purge.

Table 60. Files deleted by the Log Purge tool

Log file or report Location

Server log files Documentum Server installation log location

dmbasic method server Documentum Server installation log location

Connection broker log files Documentum Server installation log location

Agent Exec log files Documentum Server installation log location

Session log files Documentum Server installation log location

Result log files Temp cabinet

Job log files Temp cabinet

Job reports /System/Sysadmim/Reports folder

Lifecycle log files Documentum Server installation log location

Method server log files Documentum Server installation log location,MethodServer subdirectory

Result log files are generated by the execution of methods when the method’sSAVE_RESULTS argument is set. Result log files are stored in Temp/Result.method_name.

Job log files are generated when a job is run. (The job log file for tools contains the job’strace file and the text of its report.) Job log files are stored in Temp/Jobs/job_name/log_file.

The lifecycle log files are generated when a lifecycle operation such as promote ordemote occurs. The files are named bp_transition_*.log or bp_schedule_*.log, dependingon the operation. They are stored in %\DOCUMENTUM%\dba\log\repository_id\bp($DOCUMENTUM/dba/log/repository_id/bp).

Files are considered old and are deleted if they were modified prior to a user-definedcutoff date. By default, the cutoff date is 30 days prior to the current date. For instance, ifyou run Log Purge on July 27, all log files that were modified before June 28 are deleted.You can change the cutoff interval by setting the -cutoff_days argument for the tool.(Refer to Arguments , page 500, for instructions.)

Log Purge generates a report that lists all directories searched and the files that weredeleted. The report is saved in the repository in /System/Sysadmin/Reports/LogPurge.

Note: If the tool is run at a remote distributed site, the report name has the site’s serverconfig name appended. For example, if London is a remote site, its report is found in/System/Sysadmin/Reports/LogPurgeLondon.



The Log Purge tool is installed in the inactive state.

Arguments


Table 61. Log Purge arguments


-cutoff_days integer 30 Controls what logs aredeleted. All logs older thanthe specified number of daysare deleted.


-window_interval integer 120 Execution window for thetool. Refer to The windowinterval, page 450 for acomplete description.

Guidelines

Your business rules will determine how long you keep old log files and result log files.However, we recommend that you keep them at least 1 month as you may need them todebug a problem or to monitor the result of a method or job.

We recommend that you run this tool daily. This will ensure that your repository neverhas log files older than the number of days specified in the cutoff_days argument.

Report sample

The following is a sample of a Log Purge report. Its start_date property is set to June 3,1996. The cutoff_days argument is set to 30 so that all logs older than 30 days will be



deleted. The report looks for server and connection broker logs, session logs, and resultlogs from method objects and job objects (older than 30 days) and destroys them.LogPurge Report For DocBase boston2As Of 7/25/96 7:18:09 PMParameters for removing Logs:------------------------------ Inbox messages will be queued to boston2- Logs older than 30 days will be removed...

Looking for server and connection broker logs in the loglocation...Log Location: logLog Location File Path: /u106/dm/dmadmin/dba/logChanging directory to server log location:/u106/dm/dmadmin/dba/logLooking for session logs...The top-level session log directory is:/u106/dm/dmadmin/dba/log/00000962Changing directory to:/u106/dm/dmadmin/dba/log/00000962/boston2Removing /u106/dm/dmadmin/dba/log/00000962/boston2/01000962800008beRemoving /u106/dm/dmadmin/dba/log/00000962/boston2/01000962800008e0Removing /u106/dm/dmadmin/dba/log/00000962/boston2/0100096280000904Removing /u106/dm/dmadmin/dba/log/00000962/boston2/0100096280000e28Removing /u106/dm/dmadmin/dba/log/00000962/boston2/0100096280000e72Removing /u106/dm/dmadmin/dba/log/00000962/boston2/0100096280000ed7Changing directory to:/u106/dm/dmadmin/dba/log/00000962/dmadminRemoving /u106/dm/dmadmin/dba/log/00000962/dmadmin/01000962800008b9Removing /u106/dm/dmadmin/dba/log/00000962/dmadmin/01000962800008baRemoving /u106/dm/dmadmin/dba/log/00000962/dmadmin/01000962800008b7Removing /u106/dm/dmadmin/dba/log/00000962/dmadmin/01000962800008b8Changing directory to:/u106/dm/dmadmin/dba/log/00000962/tuser3Removing /u106/dm/dmadmin/dba/log/00000962/tuser3/01000962800008fdChanging directory to:/u106/dm/dmadmin/dba/log/00000962/tuser1Changing directory to:/u106/dm/dmadmin/dba/log/00000962/agentexecRemoving /u106/dm/dmadmin/dba/log/00000962/agentexec/agentexec.log.save.06.11.96.09.43.37Changing directory to:/u106/dm/dmadmin/dba/log/00000962/tuser4Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/01000962800008feRemoving /u106/dm/dmadmin/dba/log/00000962/tuser4/



0100096280000900Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/0100096280000902Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/0100096280000944Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/0100096280000947Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/0100096280000948Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/0100096280000949Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/010009628000094aRemoving /u106/dm/dmadmin/dba/log/00000962/tuser4/010009628000094dRemoving /u106/dm/dmadmin/dba/log/00000962/tuser4/010009628000094eRemoving /u106/dm/dmadmin/dba/log/00000962/tuser4/0100096280000955Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/trace.tmpChanging directory to:/u106/dm/dmadmin/dba/log/00000962/tuser2Removing /u106/dm/dmadmin/dba/log/00000962/tuser2/0100096280000e73Changing directory to:/u106/dm/dmadmin/dba/log/00000962/sysadminChanging directory to:/u106/dm/dmadmin/dba/log/00000962/tuser5Looking for result logs from dm_method objects...Destroying Result.users_logged_in objectDestroying Result.users_logged_in objectDestroying Result.dmclean objectDestroying Result.dmclean objectDestroying Result.dmclean objectDestroying Result.dmclean objectDestroying Result.users_logged_in objectDestroying Result.users_logged_in objectLooking for result logs from dm_job objects...Destroying 06/01/96 11:40:27 boston1 objectDestroying 05/31/96 11:40:41 boston1 objectDestroying 06/02/96 11:40:30 boston1 objectDestroying 06/03/96 11:40:15 boston1 objectDestroying 06/04/96 11:40:03 boston1 objectDestroying 06/19/96 11:40:00 boston1 objectDestroying 06/20/96 11:40:55 boston1 objectDestroying 06/22/96 11:40:32 boston1 objectDestroying 06/21/96 11:40:34 boston1 objectDestroying 06/24/96 11:40:10 boston1 objectDestroying 06/23/96 11:40:24 boston1 objectDestroying 06/25/96 11:40:07 boston1 objectDestroying 06/13/96 11:40:08 boston1 objectDestroying 06/16/96 11:40:18 boston1 objectDestroying 06/14/96 11:40:28 boston1 objectDestroying 06/15/96 11:40:27 boston1 objectDestroying 06/17/96 11:40:12 boston1 objectDestroying 06/18/96 11:40:07 boston1 object



Destroying 06/12/96 11:40:06 boston1 objectDestroying 06/11/96 11:40:11 boston1 objectDestroying 06/09/96 11:40:46 boston1 objectDestroying 06/08/96 11:40:03 boston1 objectDestroying 06/10/96 11:40:29 boston1 objectDestroying 06/06/96 11:40:01 boston1 objectDestroying 06/07/96 11:40:55 boston1 objectDestroying 06/05/96 11:40:02 boston1 objectDestroying 05/29/96 11:40:06 boston1 objectDestroying 05/30/96 11:40:49 boston1 object

End of Log Purge ReportReport End 7/25/96 7:19:13 PM

Queue ManagementThe Queue Management Tool deletes dequeued Inbox items. Whenever an item isqueued to a user’s Inbox, an object of type dmi_queue_item is created for that queueditem. When users forward or otherwise remove an item from their Inboxes, thecorresponding dmi_queue_item object is marked dequeued, but it is not removedfrom the repository. If these dequeued items are not removed, the tables for thedmi_queue_item type grow quite large, and performance degrades when users accesstheir Inboxes. The Queue Management tool automates the task of removing theseunneeded dmi_queue_item objects.

The cutoff_days and custom_predicate arguments determine which dmi_queue_itemsare removed. The cutoff_days argument specifies the age of the objects you want todelete. The custom_predicate argument is applied to those items meeting the agerequirement, allowing you to delete all or only some of them. For example, the toolcould delete all dequeued dmi_queue_items that are older than 30 days and werequeued to a specific user.

The tool generates a status report that provides you with a list of the deleted dmi_queue_items. The report is saved in the repository in /System/Sysadmin/Reports/QueueMgt.

If there is an error in the tool’s execution, an email and Inbox notification is sent to theuser specified by the -queueperson argument.

The Queue Management tool is installed in the inactive state.

Arguments




Table 62. Queue Management arguments



string - Defines a WHERE clausequalification for the querythat selects dequeued itemsfor deletion.

The qualification must bea valid qualification andmust work against thedmi_queue_item object. Forexample, a valid qualificationis "event=’APPROVED’" or"name=’dmadmin’".

Refer to the Content ServerDQL Reference Manual forcomplete information aboutWHERE clause qualifications.

-cutoff_days integer 90 Defines a minimum age, indays, for dequeued items. Alldequeued dmi_queue_itemsolder than the specifiednumber of days and that meetthe specified qualification aredeleted.

To include all dequeued itemsin the search, set this value tozero (0).



Note: The tool creates a base qualification that contains two conditions:



• delete_flag = TRUE• dequeued_date = value (computed using cutoff_days argument)Any qualification you add is appended to the base qualification.

Guidelines

Dequeued items are the result of moving objects out of an inbox. Objects are placed ininboxes by workflows, event notifications, archive and restore requests, or explicit queuemethods. Objects are moved out of an inbox when they are completed or delegated.

You must decide if there are any reasons to keep or maintain dequeued items. Forexample, you may want to keep dequeued items for auditing purposes. If so, leave thistool inactive or set the cutoff_days argument to a value that will save the dequeueditems for a specified length of time.

After you have made your decisions, formulate a scheduling plan.

Note: The first time you execute the Queue Management tool, it may take a long time tocomplete if dequeued items have never been deleted before.

Report sample

Here is a sample of the report generated by the Queue Management tool.QueueMgt Report For DocBase boston2As Of 7/26/96 5:09:00 PMParameters for removing dequeued items:---------------------------------------- Inbox messages will be queued to dmadmin- No items dequeued before 7 days will be removed...- The custom predicate is:name='tuser5'

Looking for dequeued items to delete...Destroying queue item with ID 1b00096280000603Destroying queue item with ID 1b000962800002e4Destroying queue item with ID 1b00096280000304Destroying queue item with ID 1b00096280000324Destroying queue item with ID 1b000962800003445 dequeued items deleted...

End of Queue Management ReportReport End 7/26/96 5:09:00 PM



Remove expired retention objectsThe Remove Expired Retention Objects (RemoveExpiredRetnObjects) tool removesobjects from the repository whose content, stored in an EMC Centera storage area, hasan expired retention date. The tool does not remove the actual content files or theassociated content objects.

The tool invokes the CHECK_RETENTION_EXPIRED administration method todetermine which SysObjects to remove from the repository. By default, the tool operatesonly on objects stored in EMC Centera storage areas that require a retention date. Youcan also direct the tool to operate on EMC Centera storage areas that allow but donot require a retention date by setting the INCLUDE_ZERO_RETENTION_OBJECTSargument. The tool never includes objects stored in EMC Centera storage areas that donot allow retention periods. Refer to the Guidelines for more information.

After the tool runs the method to find the objects, it uses a destroy method to removethem from the repository.

The tool generates a status report that provides you with a list of the deletedobjects. The report is saved in the repository in /System/Sysadmin/Reports/RemoveExpiredRetnObjects. For each deleted object, the report lists the followingproperties:• r_object_id• object_name• a_storage_type• r_creation_date• retention_date

The retention_date property is a computed property.The tool is installed in the inactive state.

Arguments




Table 63. Remove Expired Retention Objects arguments


-query qualification string - Identifies which objects areselected for possible removal.

This is a DQL where clausequalification.

-include_zero_retention_objects

Boolean F (FALSE) Setting this to T (TRUE)directs the job to considerobjects stored in an EMCCentera storage area thatallows but does not require aretention period.



Guidelines

An EMC Centera or NetApp SnapLock storage area can have three possible retentionperiod configurations:• The storage area may require a retention period.

In this case, the a_retention_attr name property is set and the a_retention_attr_req isset to T.

• The storage area may not allow a retention period.

In this case, the a_retention_attr name property is not set and the a_retention_attr_reqis set to F.

• The storage area may allow but not require a retention period.

In this case, the a_retention_attr name property is set , but the a_retention_attr_req isset to F.



By default, the method does not include objects whose content has a 0 retention periodbecause the assumption is that such content is meant to be kept forever. However, ina storage area that allows but does not require a retention period, a 0 retention periodcan be result from two possible causes:• The user deliberately set no retention period, and consequently, the server set the

retention period to 0• The user specified a retention date that had already elapsed. When this occurs,

the server sets the retention period to 0.Because the meaning of 0 is ambiguous in such storage areas, the tool supports theINCLUDE_ZERO_RETENTION_OBJECTS argument to allow you to include contentwith a zero retention in storage areas that allow but do not require a retention period.

If you set INCLUDE_ZERO_RETENTION_OBJECTS to T, when the tool examinesobjects in storage areas that allow but do not require a retention period and it willremove from the repository any object with an expired or zero retention period. thetool does not remove the actual content files or associated content objects. (You mustrun dmclean to remove those.)

Refer to the Content Server DQL Reference Manual for further information about theunderlying method.

Report sample--- Start C:\Documentum\dba\log\00002710\sysadmin\RemoveExpiredRetnObjectsDoc.txt report output ----RemoveExpiredRetnObjects Report For DocBase dctm52As Of 2/26/2004 15:39:10

RemoveExpiredRetnObjects utility syntax:apply,c,NULL,CHECK_RETENTION_EXPIRED,QUERY,S,'a_storage_type = ''destroy_test3''',INCLUDE_ZERO_RETENTION_OBJECTS,B,TExecuting RemoveExpiredRetnObjects...Object 090027108000c910 destroyed successfully.Object 090027108000c911 destroyed successfully.# of objects with expired retention that matchedthe condition: 2# of successfully destroyed: 2# of objects not destroyed : 0Report End 2/26/2004 15:39:14--- End C:\Documentum\dba\log\00002710\sysadmin\RemoveExpiredRetnObjectsDoc.txt report output ---



Rendition ManagerThe Rendition Manager tool removes unwanted renditions of versioned documents.A rendition is a copy of a document’s content in a different format than the original.Renditions, like the original content files, are stored in storage areas. Over time,unneeded renditions from previous versions of documents can take up noticeableamounts of disk space. (For information about renditions, refer to Content ServerFundamentals.)

The tool’s arguments define which renditions are removed. The tool can delete renditionsbased on their age, format, or source (client- or server-generated). The tool removesthe content objects associated with unwanted renditions. The next execution of theDmclean tool automatically removes the renditions’ orphaned content files (assumingthat Dmclean’s clean_content argument is set to TRUE).

Note: Renditions with the page modifier dm_sig_template are never removed byRendition Manager. These renditions are electronic signature page templates; theysupport the electronic signature feature available with Trusted Content Services.

The report generated by the tool lists the renditions targeted for removal. The report issaved in the repository in /System/Sysadmin/Reports/RenditionMgt.

The Rendition Manager tool is installed in the inactive state.

Arguments

Table 64, page 509, describes the arguments for the Rendition Management tool.

Table 64. Rendition Management arguments


-keep_slabels Boolean TRUE Indicates whether you wish tokeep renditionswith symboliclabels. When this is TRUE,the -keep_current argumentis ignored because CURRENTis a symbolic label.




-keep_current Boolean TRUE Indicates whether youwish to keep renditions ofdocuments with the symboliclabel CURRENT. When thisis TRUE, the CURRENTversion is always kept even if-keep_slabel is set to FALSE.

-keep_keep_flag Boolean TRUE Controls whether contentobjects with a renditionproperty value of 3 aredeleted by the tool. T (TRUE)instructs the tool to not deletethe objects.

The default value is F(FALSE), meaning the contentobjects are not deleted.

Note: The rendition propertyin a content object is setto 3 when a rendition isadded to content with thekeepRendition argument inthe addRendition method setto T (TRUE).

-keep_esignature Boolean TRUE Controls whether renditionswith the page modifierdm_sig_source are removed.

T (TRUE) means to keep thoserenditions. F (FALSE) meansto remove those renditions.

-cutoff_days integer 180 The maximum age, in days,of renditions that you wantto keep. All renditions olderthan the specified numberof days are considered fordeletion.




-server_renditions string all Specifies which server-basedrenditions to remove. Validvalues are:

allnone

or a list of formats

If a list of formats is specified,the format names must beseparated by single spaces.

The default is all.

-client_renditions string none Specifies which clientrenditions to remove(includes the renditionsadded using an addRenditionmethod). Valid values are:

allnone

or a list of formats

If a list of formats is specified,the format names must beseparated by single spaces.

The default is none.

-report_only Boolean TRUE Indicates whether to generateonly a report and not deleterenditions. Set this to FALSEif you want to actually deletethe renditions in addition togenerating a report.






Guidelines

The RenditionManagement tool removes all renditions that meet the specified conditionsand are older than the specified number of days. For example, if you execute this toolon July 30 and the -cutoff_days argument is set to 30, then all renditions created ormodified prior to June 30 are candidates for deletion. On July 31, all renditions createdor modified before July 1 are removed.

We recommend that you run this tool with the -report_only argument set to TRUE firstto determine how much disk space renditions are using and what type of renditions arein the repository. With -report_only set to TRUE, you can run the tool several times,changing the other arguments each time to see how they affect the results.

We recommend that you have a thorough knowledge of how and when renditions aregenerated before removing any. For example, client renditions, such as those addedexplicitly by an Addrendition method, may be difficult to reproduce if they are deletedand then needed later. Content Server renditions are generated on demand by the serverand are generally easier to reproduce if needed.

To ensure that your repository never has rendition files older than the number of daysspecified in the -cutoff_days argument, run this tool daily.

Note: The first time you execute the Rendition Management tool, it may take a long timeto complete if the old renditions have never been deleted before.

Report sample

Here is a sample of the Rendition Management’s report.RenditionMgt Report For DocBase boston2



As Of 7/27/96 3:57:01 PMParameters for removing renditions:------------------------------------ Inbox messages will be queued to dmadmin- No renditions accessed in the last 0 days willbe removed...- Renditions of documents having symbolic labelswill be removed...- Renditions for the current version will NOTbe removed...- This will generate a report only; no renditionswill be removed...- The following client renditions are candidatesfor removal:

1) mactext- The following server renditions are candidatesfor removal:

1) crtext

NOTE: This is a report only - no renditions will beremoved

Querying for renditions...Object NameOwner Name FormatAccess DateRendition TypeRenditionMgtdmadmincrtext07/27/96 15:44:31serverRenditionMgtdmadmincrtext07/27/96 15:45:31serverRenditionMgtdmadmincrtext07/27/96 15:45:31serverteststatus2boston2crtext07/24/96 18:40:23serverSwapInfodmadmincrtext07/11/96 16:16:16serverDBWarningdmadmincrtext07/12/96 18:31:11serverfoo717bbbdmadmincrtext07/24/96 20:48:46serverContentWarningdmadmincrtext07/18/96 18:01:19server......SwapInfodmadmincrtext07/27/96 13:20:47serverRenditionMgtdmadmincrtext07/27/96 15:48:09serverrend722 dmadminmactext07/02/96 11:00:11client/externalrend722dmadminmactext07/02/96 11:02:13client/externalrendzz2dmadminmactext07/02/96 11:05:04client/externalrendyy2dmadminmactext07/02/96 12:16:10client/externalrendww2dmadminmactext07/02/96 12:27:05client/externalfoor717atuser4mactext07/17/96 17:48:25client/externalfoor725atuser5mactext07/25/96 12:05:07client/externalReport Summary:---------------The Docbase has a total of 39,216 kbytes of content.54 renditions were reported.The renditions reported represent 82 kbytes of contentor 0.21%End of Rendition Management ReportReport End 7/27/96 3:57:10 PM



State of the Repository ReportThe State of the Repository Report tool generates a report to help you troubleshootrepository problems. A partial list of the information included in the report is:• The property values in the docbase config object• Server initialization information from the server.ini file• The directory paths defined by the location objects in the server config object• Version numbers of your server, RDBMS, and operating systemThe report is saved in the repository in /System/Sysadmin/Reports/StateOfDocbase.

The State of the Repository tool is installed in the active state.

Arguments

Table 65, page 514, describes the tool’s argument.

Table 65. State of the Repository arguments



Report sample

Here is a sample report from the State of the Repository tool. The example shows allof the sections in the tool’s report, but truncates entries in some sections in the interestsof space.StateOfDocbase Report For Docbase dm_master As Of 4/12/1999 09:26:32

Docbase Configuration:Description:The Test RepositoryFederation Name:<dm_master is not in a Federation>Docbase ID:22000Security ModeaclFolder Security:OnAuthorization Protocol:<Not defined>Database:SQLServerRDBMS Index Store:<Not defined>Mac Access Protocol:none



Server Configuration:Server Name:dm_masterServer Version:4.0 Win32.SQLServer7Default ACL:Default ACL of UserHost Name:bottae1Install Owner:dmadminInstall Domain:bottae1Operator Name:dm_masterAgent Launcher:agent_exec_methodCheckpoint Interval:300 secondsCompound Integrity:On - Server enforces integrity for virtual documentsTurbo Backing Store:filestore_01Rendition Backing Store:<Not defined>Web Server Location:BOTTAE1Web Server Port:80Rightsite Image:/rs-bin/RightSit

Server Locations:events_locationD:\DOCUMENTUM\share\data\eventscommon_locationD:\DOCUMENTUM\share\data\commontemp_locationD:\DOCUMENTUM\share\templog_locationD:\DOCUMENTUM\dba\logsystem_converter_location D:\DOCUMENTUM\product\4.0\convertuser_converter_location<Not defined>verity_locationD:\DOCUMENTUM\product\4.0\verityuser_validation_location <Not defined>assume_user_locationD:\DOCUMENTUM\dba\dm_assume_user.exechange_password_locationD:\DOCUMENTUM\dba\dm_change_password.exesignature_chk_locD:\DOCUMENTUM\dba\dm_check_password.exestage_destroyer_location<Not defined>

Set Information:

CLASSPATH=C:\PROGRA~1\DOCUME~1\DFCRE40\lib\dfc.jar;C:\PROGRA~1\DOCUME~1\Classes;C;\Netscape\ldapjava\packagesCOLORS=white on blueCOMPUTERNAME=BOTTAE1ComSpec=C:\WINNT\system32\cmd.exeCVSROOT=godzilla.documentum.com:/docu/src/masterCVS_SERVER=cvs1-9DM_HOME=D:\DOCUMENTUM\product\4.0DOCUMENTUM=D:\DOCUMENTUMHOMEDRIVE=C:HOMEPATH=\LOGONSERVER=\\BOTTAE1NUMBER_OF_PROCESSORS=1OS=Windows_NTOs2LibPath=C:\WINNT\system32\os2\dll;Path=D:\DOCUMENTUM\product\4.0\bin;C:\PROGRA~1\DOCUME~1\DFCRE40\bin;D:\DOCUMENTUM\product\3.1\bin;C:\WINNT\system32;C:\WINNT;c:\program files\maestro.nt;C:\PROGRA~1\DOCUME~1\Shared;c:\SDK-Java.201\Bin;c:\SDK-Java.201\Bin\PackSign;c:\Winnt\Piper\dll;c:\Program Files\DevStudio\SharedIDE\bin;c:\Program Files\DevStudio\SharedIDE\bin\ide;D:\MSSQL7\BINN;c:\cvs1.9;c:\csh\bin;c:\csh\samples;C:\DOCUME~1\RIGHTS~1\product\binPATHEXT=.COM;.EXE;.BAT;.CMDPROCESSOR_ARCHITECTURE=x86PROCESSOR_IDENTIFIER=x86 Family 5 Model 2 Stepping 5, GenuineIntelPROCESSOR_LEVEL=5



PROCESSOR_REVISION=0205PROMPT=$P$GSystemDrive=C:SystemRoot=C:\WINNTTEMP=C:\TEMPTMP=C:\TEMPUSERDOMAIN=BOTTAE1USERNAME=dmadminUSERPROFILE=C:\WINNT\Profiles\dmadminwindir=C:\WINNT

Registered tables in the Repository:

Table NameTable OwnerOwner:Group:World Permits

adm_turbo_sizedbo 1:1:1dm_federation_logdbo 15:7:3dm_portinfodbo 1:1:1dm_queuedbo 1:1:1

Number of Documents by Type:

Document Type Countdmi_expr_code 74dm_method 66dm_document 44dm_folder 31dm_job 29dm_location 14dm_registered 14dm_procedure 10dm_cabinet 6dm_script 3dm_smart_list 2dm_business_pro 1dm_docbase_config 1dm_mount_point 1dm_outputdevice 1dm_query 1dm_server_config 1Total: -------------

299

Number of Documents by Format:

Document Format Count

crtext 11mdoc55 9maker55 5<NO CONTENT> 2msw8template 2vrf 2wp6 2excel5book 1excel8book 1excel8template 1



ms_access7 1ms_access8_mde 1msw6 1msw8 1powerpoint 1ppt8 1ppt8_template 1ustn 1Total: -------------

44

Number of Documents by Storage Area:

Storage Area Count

filestore_01 40dm_turbo_store 4Total: -------------

44

Content Size(KB) by Format:

FormatLargestAverageTotal

mdoc5515885772crtext 10115436text19621254vrf 192119238maker553722114

Content Size(KB) by Renditions:

FormatLargestAverageTotal

Content Size(KB) Summary:

filestore_01Largest Content: 196Average Content: 31Total Content: 2,092

dm_turbo_storeLargest Content: 8Average Content: 5Total Content: 34

------------------------GTotal Content: 2,127GTotal Rendition: (0.00% of total content)

Number of Users and Groups:Named Users 4Groups 2

ACL Summary:Number of ACLs: 33Number of Internal ACLs: 29Number of External System ACLs: 4Number of External Private ACLs:



Report End 4/12/1999 09:26:54

Swap InfoNote: The Swap Info tool is not installed if Content Server is running on an HPUXmachine.

The Swap Info tool uses operating system commands to retrieve information aboutswap space usage and availability. The tool generates a report but does not issuewarnings because there is no realistic way to determine if the swap space is too low asthis determination has too many variables. The status report is saved in the repositoryin /System/Sysadmin/Reports/SwapInfo.

Note: If the tool was run at a remote distributed site, the report name will have the site’sserver config name appended. For example, if London is a remote site, its report wouldbe found in /System/Sysadmin/Reports/SwapInfoLondon.

The Swap Info tool is installed in the active state.

Arguments


Table 66. Swap Info arguments






Report sample

The format of the report generated by Swap Space Info varies by operating system. Hereis a sample of a report run against the Solaris operating system:SwapInfo Report For DocBase boston2As Of 7/26/96 4:00:59 PMSummary of Total Swap Space Usage and Availability:

total: 59396k bytes allocated + 49216k reserved =108612k used, 287696k availableSwap Status of All Swap Areas:swapfile dev swaplo blocks free/dev/dsk/c0t3d0s1 32,25 8 717688 626640Report End 7/26/96 4:00:59 PM

ToolSetupToolSetup is an installation utility for the system administration tools. The tools areinstalled as part of the installation procedure, and under typical circumstances, runningthis utility is not needed. This utility is not implemented as a job.

However, if needed, you can rerun ToolSetup as often as needed, to install new versionsof the software or until all tools are installed at all sites in a multiple-site configuration.Running ToolSetup does not affect previously installed system administration toolsor their argument values.

You must run ToolSetup from the primary site (where the RDBMS resides). To installtools in component sites, use the setupdist utility.

You can run Toolsetup from the command line or using Documentum Administrator.

To run ToolSetup from the command line:1. At the primary site, log in to the %DOCUMENTUM%\install\admin

($DOCUMENTUM/install/admin) directory.

2. Execute the following command for the primary site:dmbasic -ftoolset.ebs -eToolSetup - -<><current_path>

Update StatisticsThe Update Statistics tool generates current statistics for the RDBMS tables owned bythe repository owner. Generating statistics is always useful, particularly after you



perform load operations or if table key values in the underlying RDMBS tables are notnormally distributed.

When you run the tool against an Oracle or Sybase database, the tool uses a file thatcontains commands to tweak the database query optimizer. For Oracle, the file isnamed custom_oracle_stat.sql. For Sybase, it is named custom_sybase_stat.sql. Thefile is stored in %DOCUMETNUM %\dba\config\repository_name ($DOCUMETNUM/dba/config/repository_name). You can add commands to this file. However, do so withcare. Adding to this file affects query performance. If you do add a command, you canuse multiple lines, but each command must end with a semi-colon (;). You cannot insertcomments into this file.

The -dbreindex argument controls whether the method also reorganzes database tablesin addition to computing statistics. For SQL Server and DB2, you can set the argument toeither READ or FIX. Setting it to READ generates a report on fragmented tables but doesnot fix them. Setting it to FIX generates the report and fixes the tables. (In either case, thereport is included in the overall job report.)

For Sybase, the -dbreindex argument is only effective if set to FIX, to reorganize thetables. Setting it to READ does not generate a report on Sybase. If you include the-dbreindex argument set to FIX, the repository owner (the account under which the toolruns) must have sa role privileges in the database.

The -dbreindex argument has no effect on a Oracle database.

The tool generates a report that is saved in the repository in System/Sysadmin/Reports/UpdateStats. The exact format of the report varies for each database.

The Update Statistics tool is installed in the active state, running once a week. Becausethis tool can be CPU and disk-intensive, it is recommended that you run the tool duringoff hours for database use. Consult with your RDBMS DBA to determine an optimalschedule for this tool.

Arguments




Table 67. Update Statistics arguments


-dbreindex string READ Controls whether the toolactually updates statistics oronly reports on RDBMS tablesthat need updating.

READ generates only thereport. This setting is validonly for SQL Server and DB2databases.

FIX generates the report andupdates the tables. Thissetting is valid on SQL Server,DB2, and Sybase databases.However, on Sybase, it onlyfixes the tables. A report is notgenerated.

This argument is not availablefor Oracle databases.

-server_name string(32) - Name of the database server.

This is a required argumenton SQL Server and Sybase.It is set for the job whenthe administration toolsare installed in repositoriesrunning against a SQL Serveror Sybase database.





Guidelines

Run this tool after you perform large loading operations.

When the job is run with -dbreindex set to READ and the statistics need updating, thereport will say:-dbreindex READ. If rows appear below, the correspondingtables are fragmented.Change to -dbreindex FIX and rerun if you want to reindexthese tables.

When the job is run with -dbreindex set to FIX, the report will say:-dbreindex FIX. If rows appear below, the correspondingtables have been reindexed.Change to -dbreindex READ if you do not want to reindexin the future.

Report sample

The Update Statistics report tells you when the tool was run and which tables wereupdated. The report lists the update statistics commands that it runs in the order inwhich they are run. Here is a sample of the report:Update Statistics Report:

Date of Execution: 06-04-96

update statistics dmi_object_typegoupdate statistics dm_type_sgoupdate statistics dm_type_rgoupdate statistics dm_type_rgoupdate statistics dmi_index_sgo. . .End of Update Statistics Report

User Chg Home DbThe UserChgHomeDb tool changes a user’s home repository. This job works inconjunction with Documentum Administrator. To change a user’s home repository,you must connect to the repository using Documentum Administrator and make the



change through the Users pages. Documentum Administrator gives you two options forperforming the change:• Execute the UserChgHomeDb tool immediately after you save the change• Queue the change, to be performed at the next scheduled execution of

UserChgHomeDb.You cannot change a user’s home repository using a set method. When a user’s homerepository changes, the change must be cascaded to several other objects that makeuse of it.

The UserChgHomeDb tool generates a report that lists the objects changed by theoperation. The report is saved in the repository in /System/Sysadmin/Reports/UserChgHomeDb.

The User Chg Home Db tool is installed in the inactive state.

Arguments

The User Chg Home Db tool has no arguments.

User RenameThe User Rename tool changes a user’s repository name. This job works in conjunctionwith Documentum Administrator. To change a user’s name, you must connect to therepository using Documentum Administrator and make the change through the Usersscreens. Documentum Administrator gives you two options for performing the change:• Execute the User Rename tool immediately after you save the change• Queue the change, to be performed at the next scheduled execution of User Rename.You cannot change a user’s name using the Set method. When a user’s name changes, thechange must be cascaded to many other objects that make use of it.

The User Rename tool generates a report that lists the objects changed by the operation.The report is saved in the repository in /System/Sysadmin/Reports/UserRename.

The User Rename tool is installed in the inactive state.

Arguments

The User Rename tool has no arguments.



Report sample

This sample report was generated when the tool was run in Report Only mode.Job: dm_UserRenameReport For Repository example.db_1;As Of 3/6/2000 12:00:27 PM

==============3/6/2000 12:00:28 PM===============Reporting potential changes in repository example.db_1when renaming user 'dm_autorender_mac' to 'test'.

The following user rename options were specified:Execution Mode: Report OnlyChecked out Objects: UnlockWARNING: There are 15 sessions currently open. It isrecommended that user rename is performed in singleuser connection mode.

================== DM_USER OBJECT ================Object type : dm_userObject id : 1100162180000103Name : dm_autorender_macpropertys referencing user dm_autorender_mac: user_name-----------------------------------------------------==== ACL Objects referencing user dm_autorender_mac ===-----------------------------------------------------Object type : dm_aclObject id : 450016218000010cName : dm_450016218000010cpropertys referencing user dm_autorender_mac:owner_name-----------------------------------------------------**** Number of ACL objects affected: 1

===== Alias Set Objects referencing user dm_autorender_mac**** Number of Alias Set objects affected: 0

===== Dm_user object. Default ACL of user object isreferencing dm_autorender_mac-----------------------------------------------------Object type : dm_userObject id : 1100162180000103Name : dm_autorender_macpropertys referencing user dm_autorender_mac: acl_domain-----------------------------------------------------====== Sysobjects referencing user 'dm_autorender_mac',which are not locked**** Number of sysobjects affected: 0

====== Sysobject referencing user 'dm_autorender_mac',which are locked (all the objects in this list will beunlocked and modified)**** Number of sysobjects affected: 0

====== Sysobjects locked by user 'dm_autorender_mac' ==(all the objects in this list will be unlocked)**** Number of sysobjects affected: 0



====== Routers referincing user dm_autorender_mac. ===**** Number of router objects affected: 0

====== Workflow objects referincing userdm_autorender_mac.**** Number of dm_workflow objects affected: 0

====== Activity objects referincing userdm_autorender_mac.**** Number of dm_activity objects affected: 0

====== Workitem objects referincing userdm_autorender_mac.**** Number of dmi_workitem objects affected: 0

====== Groups referincing user dm_autorender_mac. ===-----------------------------------------------------Object type : dm_groupObject id : 1200162180000100Name : docupropertys referencing user dm_autorender_mac:users_names[2]-----------------------------------------------------**** Number of group objects affected: 1

====== dmi_queue_item objects referincing userdm_autorender_mac.**** Number of dmi_queue_item objects affected: 0

====== dmi_registry objects referincing userdm_autorender_mac.**** Number of dmi_registry objects affected: 0

====== The following dm_registered objects have table_ownerproperty referencing user dm_autorender_mac. The scriptwill not update the objects. You have to modify them manualy.

====== The following dm_type objects have owner_nameproperty referencing user dm_autorender_mac. The script will not update the objects. You have to modify themmanualy.

====== The following dmi_type_info objects have acl_domainproperty referencing user dm_autorender_mac. The scriptwill not update the objects. You have to modify them manually.

--------3/6/2000 12:00:28 PM--------

Version ManagementThe Version Management tool removes unwanted versions of documents from therepository. This tool automates the destroy and prune methods. (Refer to Content Server



Fundamentals for a discussion of how versioning works.) The tool removes only therepository object. It does not remove content files associated with the object. To removecontent files, use the Dmclean tool, described in Dmclean , page 482.

The arguments you define for the tool determine which versions are deleted. Forexample, one argument (keep_slabels) lets you choose whether to delete versions thathave a symbolic label. Another argument (custom_predicate) lets you define a WHEREclause qualification to define which versions are deleted. (Refer to the Content ServerDQL Reference Manual for instructions on writing WHERE clauses.)

The Version Management tool generates a status report that is saved in the repository in/System/Sysadmin/Reports/VersionMgt.

The Version Management tool is installed in the inactive state.

Arguments


Table 68. Version Management arguments


-keep_slabels Boolean TRUE Indicates whether youwish tokeep versions of documentswith symbolic labels. Thedefault is TRUE.


string - Defines a WHERE clausequalification for the querythat selects versions fordeletion.

The qualification mustbe a valid qualification.Refer to the Content ServerDQL Reference Manual forinformation about WHEREclause qualifications.




-cutoff_days integer 180 The maximum age, in days, ofthe versions that you want tokeep. All versions older thanthe specified number of daysare considered for deletion. Ifyou set this flag, you cannotset the -keep_latest flag.The two flags are mutuallyexclusive.

-keep_latest integer - Directs the tool to keep thespecified number of versionsdirectly derived from eachend node of a version branch.If you set this flag, you cannotset the -cutoff_days flag.The two flags are mutuallyexclusive.

-report_only Boolean TRUE Indicates whether to generateonly the report. Set this toFALSE to actually removeversions.



Guidelines

We recommend that you have a thorough knowledge of what prior versions meanfor your business requirements. If you need to keep all versions to satisfy auditingrequirements, do not run this tool at all. Individual users or departments may also haveneeds and requirements for older versions. Needs for disk space may also affect thedecisions about how many older versions to keep.



Run this tool initially with the -report_only argument set to TRUE to determine howmuch disk space versions are using and how many versions are in the repository. With-report_only set to TRUE, you can run the report several times, changing the otherarguments each time to see how they affect the results.

If you are using the -cutoff days argument to ensure that your repository never hasonly versions older than a specified number of days, run this tool daily. If you areusing -keep_latest argument to keep only a specified number of versions, you can runthis tool less frequently. The frequency will depend on how often new versions aregenerated (thereby necessitating the removal of old versions to keep the number ofversions constant).

You can use this tool for one-time events also. For example, after a project is completed,you might remove all older versions of the project’s documentation. (You must set thearguments appropriately for such occasions and reset them after the job is finished.)

Note: The first execution of the tool may take a long time to complete if the old versionshave never been deleted before.

Report sampleVersionMgt Report For DocBase boston2As Of 9/12/96 11:33:33 AMParameters for deleting versions:------------------- Inbox messages will be queued to boston2- Keep the 3 most recent versions of each versiontree...- Documents having symbolic labels will NOT bedeleted...- This will generate a report and delete theversions...- The custom predicate is:object_name='ver911c'

- The server is enforcing compound integrity(the compound_integrity property in the Server

Config object is set to true).

Querying for versions...Object Name Owner Name Modify Date Version Labelsver911c tuser1 09/12/96 11:19:30 1.7.1.2ver911c tuser1 09/12/96 11:18:49 1.7.1.0ver911c tuser1 09/11/96 16:18:46 1.3.1.1ver911c tuser1 09/11/96 16:18:37 1.3.1.0ver911c tuser1 09/11/96 16:07:40 1.5ver911c tuser1 09/11/96 16:07:39 1.4ver911c tuser1 09/11/96 16:07:37 1.1ver911c tuser1 09/11/96 16:07:35 1.0Report Summary:---------------The Docbase has a total of 21,986 kbytes of content.8 versions were removed.



The versions removed represented 12 kbytes of contentor 0.05%The documents contents are now orphaned. Use theDmclean system administration tool to actually removethe contents.

Tool maintenance and troubleshootingThe tool suite typically requires very little maintenance after you define executionschedules and arguments for the tools.

Instructions for setting the scheduling properties are found in Activating and schedulingadministration tools, page 453.

Changing the default settings

The jobs that make up the tool suite are installed with default property values that maynot be appropriate for your environment. You may want to change the default settingsof a job after you have:• Examined report results• Determined warning thresholds that are appropriate for your site• Defined a staggered execution schedule for the tools• Defined qualifying arguments for the destructive toolsThe easiest way to change the properties for a tool’s job is using DocumentumAdministrator. However, you can also use DQL to change a tool’s settings.

The server always passes the standard arguments to the tools. The methods associatedwith the tools use the job_id argument to obtain the remaining tool-specific argumentsfrom the job object. Do not reset this argument for tools.

Using DQL

To view a tool’s properties, use the SELECT statement to retrieve the property values inwhich you are interested.

To change a tool’s properties, use the UPDATE...OBJECT statement. To ensure that youupdate the correct job object, qualify your query with a condition that uniquely identifiesthe job you want to change.

For information about these statements, refer to theContent Server DQL Reference Manual.



Using the tool trace log les

If an error occurs during the execution of a tool, the queueperson is notified by Inboxand email messages. Generally, the message indicates a failure in the method and directsyou to the appropriate trace log file. The trace log files are stored in the Temp cabinet asResult.method name. For example, the log file for the Queue Management tool is calledResult.dm_QueueMgt. Examine the log files to determine the cause of the failure. Atrace log file is generated whenever a tool is executed.

Viewing the tool reports

You can view the tool reports using Documentum Administrator or by opening therepository folder in which they are contained. The reports provide historical accounts ofyour repository environment and should be examined regularly so that you can respondin a timely fashion to any problems or administrative needs that the tools uncover.

To view the reports directly in the repository, open the Sysadmin folder in the Systemcabinet. The reports are in a subfolder called Reports.


Chapter 12Logging and Tracing Facilities

This chapter discusses the tracing and logging facilities supported by Content Server and DFC. Itincludes the following topics:• Introduction, page 531• Content Server logging and tracing, page 531• DFC logging, page 536• DFC tracing, page 536

IntroductionEMC Documentum supports robust tracing and logging facilities for both Content Serverand DFC operations, to ensure that you can obtain helpful information when needed.

The logging facilities record information generated automatically by Content Server orDFC. This includes error, warning, and informational messages. Logging operations thatlog the error, warning, and informational messages occur automatically.

The tracing facility records information that is explicitly requested by a user. Thatis, trace information is recorded only if a user, such as a system administrator, or anapplication, through a specific method call, requests tracing. Sysadmin or Superuserprivileges are required to turn tracing on and off.

Content Server logging and tracingContent Server logging and tracing provides information about Content Serveroperations. Content Server records logging information and tracing information, witha few exceptions, in the following files:


Logging and Tracing Facilities

• Repository log file

Content Server records information about root server activities in this file. This isalso sometimes referred as the Content Server log file.

• Session log files

A session log file records all informational, warning, error, and fatal error messagesand, by default, all SQL commands generated from DQL commands.

Note: It is possible, though not recommended, to turn off recording of the SQLcommands.

Session log files are stored in %DOCUMENTUM%\dba\log\hex_repository_id\username ($DOCUMENTUM/dba/log/hex_repository_id/username), wherehex_repository_id is the repository ID expressed as a hexadecimal value and usernameis the account under which the session is running. The server creates a separatesession log for each new connection.

The exceptions that do no record their log and trace information in these files are a fewContent Server features. These exceptions, such as jobs, that record their tracing andlogging information in files that are specific to those features.

Starting and stopping Content Server tracing operations

There are several ways to start and stop tracing for Content Server operations:• From the server startup command line• With a IDfSession.setServerTraceLevel• With a SET_OPTIONS administration method• With a MODIFY_TRACE administration method

Note: MODIFY_TRACE is used only to start or stop tracing full-text operations. Forinformation about this method, refer to the Documentum DQL Reference Manual.

The way you choose to initiate tracing will depend on what you are tracing. Each optioncontrols a slightly different set of tracing functionality.

Starting and stopping tracing from the startup command line

You can initiate tracing a variety of operations from the Content Server startup commandline. To start tracing at server start-up, specify the trace flags for the options with the -ooption on the command line. The name of the option must immediately follow the -o.No space is allowed between the -o and the option name. On Windows platforms, addthe -o option to the command line by editing Content Server’s service entry.



Table 69, page 533, lists the trace flags that you can use with the -o option at serverstart-up and the tracing information each provides. The generated trace information isrecorded in the repository log file.

Table 69. Server start-up trace options

Option name Description

debug Session shutdown, change check, launch and forkinformation

docbroker_trace Connection broker information

i18n_trace Session locale and client code page usage

lock_trace Windows locking information

net_ip_addr IP addresses of client and server for authentication

nettrace Turns on RPC tracing (traces Netwise calls, connectionID, client host address, and client host name)

rpctrace Turns on tracing of RPC calls.

sqltrace SQL commands sent to the underlying RDBMS forsubsequent sessions, including the repository session IDand the database connection ID for each SQL statement.

This option is turned on by default when a server starts.

ticket_trace Traces import and export operations for login ticket keysand operations using single-use login tickets

trace_authentication Detailed authentication information

trace_complete_launch UNIX process launch information

trace_workflow_agent Trace messages generated by the workflow agent

To stop tracing from the command line, you must remove the trace flag from the servercommand line and then stop and restart the server.

Using setServerTraceLevel

The setServerTraceLevel method is defined for the DFC IDfSession interface. Themethod takes two arguments, a trace level, defined as an integer value, and a facilityname. Table 70, page 534, lists the possible trace levels, and Table 71, page 534, liststhe facilities that you can specify.



Table 70. Trace level severity values

Severity level Meaning

0 No messages, tracing is turned off. Use this value toturn off tracing for the specified facility.

1 Level 1 trace messages




8 Dump and load object information

10 Timing information

The severity levels are additive. For example, if you specify tracing level 10, you alsoreceive all the other messages specified by the lower levels in addition to the timinginformation.

Table 71. Valid facilities for setServerTraceLevel

Facility Description

ALL Traces all available trace facilities

DM_CONTENT Traces content operations. The information isrecorded in the session log file.

DM_DUMP Traces dump operations. The information is recordedin the session log file.

DM_LOAD Traces load operations. The information is recordedin the session log file.

DM_QUERY Traces query operations. The information is recordedin the session log file.

SQL_TRACE Traces generated SQL statements. The informationis recorded in the session log file.

Tracing for this facility is turned on by default.Turning it off is not recommended by DocumentumTechnical Support.

DM_SYSOBJECT Traces SysObject operations. The information isrecorded in the session log file.



Using SET_OPTIONS

The SET_OPTIONS administration method turns on or off a wide range of ContentServer tracing options, including tracing EMC Centera and NetApp SnapLock storagearea operations, digital shredding operations, and connection broker information, forexample. For a complete list of the trace options available for SET_OPTIONS, refer to itsreference information in the Content Server DQL Reference Manual.

The method can be executed from Documentum Administrator or using the DQLEXECUTE statement or an IDfSession.apply method.

Although not recommended by Documentum Technical Support, you can useSET_OPTIONS to turn off SQL tracing.

Turning tracing on and off using SET_OPTIONS affects only new sessions. Currentsessions are not affected.

Examples of server tracing

Here is a server log excerpt for DM_LOAD tracing:Fri Aug 14 16:02:27 1998 569000 [DM_LOAD_I_PROGRESS]info:"For load object 310007b680000101 in phase 2, processed 54 of 66 objects;last object processed was 090007b680000238"Fri Aug 14 16:02:27 1998 710000 [DM_LOAD_I_PROGRESS]info:"For load object 310007b680000101 in phase 2, processed 55 of 66 objects;last object processed was 060007b680000118"Fri Aug 14 16:02:27 1998 720000 [DM_LOAD_I_PROGRESS]info:"For load object 310007b680000101 in phase 2, processed 56 of 66 objects;last object processed was 270007b680000165"

The following example shows a log file excerpt for query tracing. The example assumesthat the following query is issued:SELECT "user_os_name" FROM "dm_user" WHERE "user_name"='zhan'

Here is the corresponding server log:Fri Aug 14 15:31:29 1998 608000 [DM_QUERY_T_SELECT_COMPLETE]info:"SELECT statement semantic checking and setup is complete."Fri Aug 14 15:32:20 1998 942000 [DM_QUERY_T_SYNTAX_BEGIN]info:"Begin syntactic parse (call yacc)."Fri Aug 14 15:32:20 1998 942000 [DM_QUERY_T_SYNTAX_COMPLETE]info:"Syntactic parse is complete."Fri Aug 14 15:32:20 1998 942000 [DM_QUERY_T_SELECT_BEGIN]info:"Begin SELECT statement."Fri Aug 14 15:32:20 1998 942000 [DM_QUERY_T_SQL_SELECT]info:"SELECT statement generated by the query is:select all dm_user.user_os_name from dm_user_sp dm_user where(dm_user.user_name='zhan').Begin Database processing."



Fri Aug 14 15:32:22 1998 434000 [DM_QUERY_T_SELECT_COMPLETE]info:"SELECT statement semantic checking and setup is complete."

Determining which tracing options are turned on

To determine whether a particular Content Server tracing option is on turned on, usean IDfSession.isServerTraceOptionSet method. This method takes as an argument thename of the option. For example, if you wish to determine if the docbroker_trace tracingoption is turned on, you would specify that option name as the argument to the method.

You cannot specify a facility name with the isServerTraceOptionSet method.

DFC loggingDFC logging is controlled by the log4j.properties file. The location of the generatedlog file is defined in the log4j.properties file. The default location defined in the file is${user.dir}/documentum/logs/documentum.log.

Refer to the standard Java documentation for information about the keys that may beset in this file, to control logging.

If you wish to record debug information generated by specific packages or classes, it isrecommended that you direct that information to the DFC trace file, rather than the log4jlog file. Instructions are found in Directing categories to the trace file, page 547.

DFC tracingDFC supports a set of tracing configuration options that allow you to obtain desiredtrace information about DFC operations, formatted in a manner most helpful to you.For example, you can turn on tracing for individual users or individual threads andspecify which methods to trace. You can also configure characteristics of the trace filesuch as how timestamps within the file are formatted or how method entrances andexits are recorded.

All DFC tracing is controlled by entries in a properties file. The entries are dynamic. Youcan add, remove, or change a tracing key entry and the change is effective immediately.It is not necessary to stop and restart DFC or the application.



The logger and logging appender

Entries in the trace log file are recorded by a logger and its associated loggingappender created by DFC when you initiate tracing. The configuration of the appenderdetermines some characteristics of the log file, such as its file name and its maximumsize. Configuring the logging appender, page 537, describes the entries that configurethe appender.

Enabling tracing

Before you actually start tracing, it is recommended that you set the keys in dfc.propertiesthat configure the logger and define what you want to trace. If you do not set these, thetracing facility is initialized with the default values. The keys that configure the loggingappender are described in Configuring the logging appender, page 537. The keys thatdefine what to trace are described in Defining what is traced, page 542.

To initialize the DFC tracing facility and start tracing, set the dfc.tracing.enable key totrue:dfc.tracing.enable=true

This key is false by default.

Conguring the logging appender

The configuration of the logging appender controls the name and location of the tracefile and its format. Table 72, page 537, lists the configuration options for the appender.

Table 72. Logging appender conguration options

Option Key Description

File name prefix dfc.tracing.file_prefix Defines the base name ofthe trace file. Refer to Tracefile names, page 539, fordetails about choosing abase name.

The default value isdfctrace.




Location of file dfc.tracing.dir Identifies the directory inwhich to store the trace file.

If unset, the file is stored inthe directory identified by${dfc.data.dir}/logs.

Valid values for thisproperty are any validdirectory path. Setting thisproperty is recommended.

Creation mode dfc.tracing.file_creation_mode

Controls whether traceinformation is logged inone file or multiple files.Defining file creationmode, page 539, describesthis in detail.

Maximum file size dfc.tracing.max_file_size Defines the maximum sizeof a trace file before it isrolled over. Valid valuesare any string accepted bylog4j as MaxFileSize.

If an integer value isspecified with no unit ofmeasure, the integer valueis interpreted as bytes.

The default is 100MB.

Maximum number ofbackups for the file

dfc.tracing.max_backup_index

Defines the number ofback-up files the loggerwill retain for the logfile. When the maximumnumber is reached, theoldest backup is destroyedwhen a new back-up iscreated.




Valid values are anypositive integer. Thedefault value is 1.

Date format for timestamp dfc.tracing.date_format Defines a date format ifdfc.tracing.timing_style,in dfc.properties, is set todate. Refer to Definingthe timestamp format,page 540, for completeinformation about settingdfc.tracing.timing_styleand its interaction withdfc.tracing.date_format inthe dfc.properties file.

Trace le names

Trace log file names have the following format:file_prefix[.identifier].timestamp.log

The file prefix is prepended to the beginning of the name of each trace file generatedby DFC. For example, if you are recording all information in one log file, the name ofthe file is in the format:file_prefix.timestamp.log

The default value for the file prefix is dfctrace. You can define a different prefix bysetting the dfc.tracing.file_prefix key:dfc.tracing.file_prefix=value

An identifier is included in the file name only if you are generating log files for individualusers or threads. The identifier is the user name if the logs are being generated forindividual users, or the thread name if logs are being generated for individual threads.

The timestamp records when the file was created.

Dening le creation mode

The dfc.tracing.file_creation_mode key controls whether the log entries are recorded inone log file or several. By default, the default value for this key is standard, which means



that all DFC trace entries are recorded in one log file. Table 73, page 540, lists the validvalues for this key and the effects of each on log file creation.

Table 73. Valid values for dfc.tracing.le_creation_mode

Value Description

standard All log entries are recorded in one log file.This is the default.

thread DFC creates a log file for each threadthat has trace data to log. The log file foreach thread is named using the followingformat:

file_prefix.threadname.timestamp.log

Tracing by thread is only recommended ifyou also set the dfc.tracing.thread_name_filter key.

user DFC creates a log file for each user thathas trace data to log. The log file for eachuser is named using the following format:

file_prefix.username|default.timestamp.log

If the specific user cannot be determinedfor a particular call, the trace for thatcall is logged in a separate log file, withusername specified as ’default’.

Tracing by user is only recommended ifyou also set the dfc.tracing.user_names_filter key.

Dening the timestamp format

Each entry in a log file has a timestamp. If the file is recorded in compact mode, there aretwo columns for the timestamp. The first column records the entry time and the secondcolumn records the duration of the method call—the difference between method entryand method exit time. If the log file is recorded in standard mode, there is one columnfor the timestamp in the entry. The value recorded is either the entry time or the exittime, depending on whether the log entry is recording the method’s entry or exit.



By default, timestamps are expressed in seconds. You can configure the timestampdisplay. It is controlled by the dfc.tracing.timing_style key. Table 74, page 541, describesthe valid values for dfc.tracing.timing_style.

Table 74. Valid values for dfc.tracing.timing_style

Value Description

nanoseconds The timestamp values are those returned by a call toSystem.nanoTime().

These values may or may not actually havenanosecond granularity, depending on theunderlying operating system. The values cannot becorrelated to absolute time.

milleseconds The timestamp values are those returned by a call toSystem.currentTimeMillis().

milleseconds_from_start The timestamp is recorded as the number ofmilliseconds from the start of the JVM process.

seconds The timestamp values are displayed as the numberof seconds from the start of the process. The valueis a float.

This is the default timing style.

date The timestamp values are displayed as a date string.The default format is:

yyyy/MM/dd-HH:mm:ss.S

(Refer to the Javadocs for the SimpleDateFormat classfor details.)

The date setting may only be used if dfc.tracing.modeis set to standard. If you set dfc.tracing.timing_styleto date and the mode is compact, the timing styledefaults to milliseconds.

If the timing style is set to date, you can alsoset dfc.tracing.date_format and optionally,dfc.tracing.date_format_width, to define an alternatedate format. Defining a date format, page 542,describes how to define an alternate format.



Dening a date format

If you have set dfc.tracing.timing_style to date, you may also set dfc.tracing.date_formatand dfc.tracing.date_column_width. Use the dfc.tracing.date_format property to definea format for the dates entered in the trace files that is different from that defaultformat. The format you specify must conform to the syntax supported by the Java classjava.text.SimpleDateFormat.

The default column width allotted to dates in the trace file entries is 14. If theformat you specify in dfc.tracing.date_format is wider than 14 characters, setdfc.tracing.date_column_width to the required number of characters. You can set this toany positive integer value.

Dening what is traced

There are a variety of keys that you can use to define what is traced and to set a few moreoptions for the format of the file. You can, for example, configure how methods aretraced, whether trace information is placed in one file or broken out into multiple files bythread or user, and define maximum number of users or threads to trace.

Conguring method tracing

The following keys control method tracing:• dfc.tracing.max_stack_depth• dfc.tracing.mode• dfc.tracing.method_name_filter

Dening maximum stack depth to trace

The dfc.tracing.max_stack_depth key controls the depth of tracing into the DFC call stack.The default value for this key is 1, meaning only the first level of method calls is traced.

To change the default, reset the property to the desired depth. The first method call ina stack is considered to have a depth level of 1. So, for example, suppose you havean application like the following:call methodA (stack depth=1)

methodA calls methodB (stack depth=2)methodB calls methodC (stack depth=3)

methodC calls methodD (stack depth=4)



If you want to trace calls in the stack to the third invocation, where methodB callsmethodC, you set:dfc.tracing.max_tracing_depth=3

Setting max_stack_depth to 3 causes DFC to record the calls to methodA, methodB, andmethodC in the log file. The call to methodD is not traced because that is the fourth levelof depth, and tracing depth level is set to 3.

Setting the key to -1 means that the traced stack depth is unlimited.

Specifying method entry and exit tracing

The dfc.tracing.mode key controls how method entry and exit is recorded in the log file.There are two possible values for mode: compact and standard.

In compact mode, DFC adds one line to the file that records both entry and exit andreturn value for a method. The methods are logged in the order of method entrance. Incompact mode, DFC buffers in memory the log entries for a sequence of method callsuntil the topmost method returns.

If you set mode to standard, DFC creates one line in the file for a method’s entry andone line for a method’s exit. In standard mode, the log entries for exit record the returnvalues of the methods.

The default is setting is compact.

Identifying which packages, classes, and methods to trace

The dfc.tracing.method_name_filter[n] key identifies the packages, classes, and methodsor any combination of these to be traced. The key is a repeating key, which means youcan put multiple entries for the key into the dfc.properties file. Each entry has one value,identifying a package, class or method to be traced. Like repeating repository properties,each dfc.tracing.method_name_filter entry is referenced using a square-bracketedinteger, with the first entry beginning with zero.

For example, if you want to include three entries for this key, they would be:dfc.tracing.method_name_filter[0]=valuedfc.tracing.method_name_filter[1]=valuedfc.tracing.method_name_filter[2]=value

The value is one or more string expressions that identify what to trace. The syntax of theexpression is:([qualified_classname_segment][*]|*)[.[method_name_segment][*]()]

The asterisk is a wild card.

Here are some examples of values for this key and what tracing results from each:



• This example traces all methods on DfPersistentObject and any lower level callsmade within the context of those methods:com.documentum.fc.client.DfPersistentObject

• This example traces the DfPersistentObject.save() method and all lower-level calls.com.documentum.fc.client.DfPersistentObject.save()

• This example traces all methods on all classes whose package name starts with“com.documentum.fc.client”.com.documentum.fc.client*

• This example traces the save method on all classes in the packagecom.documentum.fc.client where the class name starts with DfP.com.documentum.fc.client.DfP*.save()

• This example traces all methods whose name begins with “do” for all classeswhose package is either com.documentum.fc.client or “sub-package” ofcom.documentum.fc.client.com.documentum.fc.client.*.do*()

• This example traces the method setString() on any DFC class in any package.*.setString()

Tracing users by name

When you want to trace only particular users, set the dfc.tracing.user_name_filterkey to identify those users. The key is a repeating key, which means you can putmultiple entries for the key in the file. Each entry specifies one regular expression thatidentifies a user or users to be traced. Like repeating properties in the repository, eachdfc.tracing.user_name_filter entry is referenced using a square-bracketed integer, withthe first entry beginning with zero.

For example, if you want to include three entries for this key, they would be:dfc.tracing.user_name_filter[0]=expressiondfc.tracing.user_name_filter[1]=expressiondfc.tracing.user_name_filter[2]=expression

The expression is a regular expression, using the syntax for a regular expression asdefined in the Java class java.util.regex.Pattern.

When this property is set, DFC traces activities of the users whose login names(dm_user.user_login_name) match the specified expression. The log entries will containthe user name.

Note: If you want to completely separate out various user entries, you can usedfc.tracing.file_creation_mode to create a separate log file for each user. Refer toDefining file creation mode, page 539, for details.



The dfc.tracing.user_name_filter key is not set by default, which means that all usersare traced.

The tracing output may not include all DFC calls made by a particular user. For somecalls, it is not possible to identify the user. For example, most methods on the DfClientinterface are unrelated to a specific session or session manager. Consequently, whentracing is constrained by user, these method calls are not traced.

When tracing by user, DFC cannot identify the user until one of the following occurs:• A method call on an object that derives from IDfTypedObject (if the session

associated with that object is not an API session)• A method call that takes an IDfSession or IDfSessionManager• Amethod call that returns an IDfSession or IDfSessionManagere• An IDfSessionManager method call that sets or gets an IDfLoginInfo object

Tracing threads by name

To trace specific threads, set the dfc.tracing.thread_name_filter key. The key is arepeating key, which means you can put multiple entries for the key into the file.Each entry has one value, identifying a thread or threads to be traced. Like repeatingrepository properties, each dfc.tracing.thread_name_filter entry is referenced using asquare-bracketed integer, with the first entry beginning with zero.

For example, if you want to include three entries for this key, they would be:dfc.tracing.thread_name_filter[0]=expressiondfc.tracing.thread_name_filter[1]=expressiondfc.tracing.thread_name_filter[2]=expression

Each dfc.tracing.thread_name_filter entry is set to a regular expression that identifies athread or threads you want to trace. The regular expression must use the syntax for aregular expression defined in the Java class java.util.regex.Pattern.

The key is not set by default, which means that all methods in all traced threadsare traced by default. Setting the key is primarily useful for standalone DFC-basedapplications that may spawn DFC worker threads.

Note: You can use dfc.tracing.file_creation_mode to further sort the entries for eachthread into separate files. For information, refer to Defining file creation mode, page 539.

Including the session ID

Log entries are identified, by default, with the user name associated with the operationbeing logged. You may also want each entry to include a session ID. To direct DFC to



include session information, set the dfc.tracing.include_session_id property to true. Theproperty is false by default. Setting it to true causes DFC tracing to add the session IDand the identity hash code of the associated session manager to the log entries. Thesession ID is in the form sn; for example, s1 and s2.

Tracing RPC calls

There are two keys that control tracing of RPC calls:• dfc.tracing.include_rpc_count• dfc.tracing.include_rpcsThe dfc.tracing.include_rpc_count is a Boolean key. If it is set to true, DFC adds anadditional column to each log file entry that records the current RPC call count for theassociated session. The logged value is “N/A” if DFC cannot determine the session. Ifthe mode is set to compact, the logged RPC count is the count at the time the methodexits. The default value for the key is false.

The dfc.tracing.include_rpcs key is a Boolean key. When set to true, DFC includes aseparate line in the trace file for each RPC call that is executed. The default for thiskey is false.

Including stack trace for exceptions

By default, the DFC tracing facility only logs exception names and messages. Typically,the stack trace can be determined from the trace file. However, in some circumstances,you may want to obtain an exact stack trace for an exception. To do so, set thedfc.tracing.print_exception_stack property to true.

Setting this property to true causes the tracing facility to log the entire stack trace forthe exception. The stack trace is recorded immediately following the line that logs theexit of the method that caused the exception. The trace is indented and prefixed withexclamation marks.

The default value for this property is false. Setting this property to true is onlyrecommended when the exact stack trace is important and you think that someexceptions are not being logged by the DFC tracing facility.

Setting verbosity

Verbosity determines what set of classes are traced. The default verbosity setting, false,traces a standard set of classes. If verbosity is set to true, an additional set of classes is



traced. These additional classes are low-level classes. Tracing these classes adds onlylimited additional information to the file, but adds many additional entries, possiblyslowing the system noticeably. Turning on verbose mode is only recommended whensuggested by Support.

To turn on additional verbosity, set the following key to true:dfc.tracing.verbosity=true

To return to standard verbosity levels, set the key to false:dfc.tracing.verbosity=false

Directing categories to the trace le

In a log4j.properties file, you can define categories as the target of logging operations. ForDFC, a category specification would typically be a class or package. It is recommendedthat if you want tracing information, particularly at the DEBUG level, for a DFC class orpackage, that you record that information in the trace file generated by the dfc.propertiestracing facility rather than the log4j log file.

To enable that redirection, use the following dfc.properties keys:• dfc.tracing.log.category• dfc.tracing.log.level• dfc.tracing.log.additivityThe dfc.tracing.log.category key identifies the category you want to trace in the DFCtrace log file. The key is a repeating key, which means you can put multiple entries forthe key into the file. Each entry has one value, identifying a category to be traced. Likerepeating repository properties, each dfc.tracing.log.category entry is referenced using asquare-bracketed integer, with the first entry beginning with zero. For example:dfc.tracing.log.category[0]=class_or_package_namedfc.tracing.log.category[1]=class_or_package_name

The dfc.tracing.log.level indicates the level of tracing you wish to use. Thedfc.tracing.log.level key defaults to DEBUG if not specified. The dfc.tracing.log.additivitykey is the additivity setting for the category. The dfc.tracing.log.additivity key defaultsto false if not specified.

The dfc.tracing.log.level and dfc.tracing.log.additivity keys are also repeating keys,and the values across one index position in the entries for the keys are the settings forcategory identified at the corresponding index position in dfc.tracing.log.category.



Interactions of tracing specications

The actual entries in the trace log files are the intersection of all the dfc.tracing key valuesyou have set. For example, if you set dfc.tracing.max_depth to 4 and dfc.tracing.modeto thread, DFC records method calls to a depth of 4 invocations and sorts the entriesby thread into separate log files.

Log le entry format

Trace information is recorded in the log files in the following format:timestamp [method_duration] [threadname]<username|sessionID|session_mgr_id> (RPCs=count) [entry_exit_designation]stack_depth_indicator qualified_class_name@object_identity_hash_code.method(method_arguments) ==>return_value|exception

Note: Bolded characters appear in the log entry; they are not used to indicate optionalitems or choices.

Table 75, page 548, describes the items found in entries.

Table 75. Log entry components

Component Description

timestamp Timestamp of the entry. Its format is dependent on thetracing configuration, as defined by dfc.tracing.timing_style.

method_duration The total length of time to execute the method. This value isonly included if dfc.tracing.mode is set to compact.

threadname Name of the thread associated with the entry.

username Name of the user associated with the entry.

sessionID Identifies the session associated with the entry. This is onlyincluded if dfc.tracing.include_session_id is set to true.

session_mgr_id The hash code identity of the session managerassociated with the entry. This is only included ifdfc.tracing.include_session_id is set to true.

RPCs=count Total number of RPC calls at the time the entry was logged.This is only included if dfc.tracing.include_rpc_count is setto true.



Component Description

entry_exit_designation Keyword that identifies source of the log entry. Thekeyword is only included if the dfc.tracing.mode isstandard. Valid values are:

• ENTER, meaning the entry records a method entry• EXIT, meaning the entry records a method exit• !EXC!, meaning the entry records a call that results inan exception

• RPC_ENTER, meaning the entry records an RPC callentry

• RPC_EXIT, meaning the entry records an RPC call exit

stack_depth_indicator Indicates the depth of call stack tracing. The stack depthindicator is a series of dots (for example, ...).

qualified_class_name Fully qualified name of the class being traced

object_identity_hash_code Hash code of the object on which the method is being called.If the method is static, this element does not appear in thelog entry.

method Name of the method being traced

method_arguments Arguments to the specified method

return_value The value returned by the method. This is included ifdfc.tracing.mode is COMPACT or if the entry records themethod’s exit.

exception The exception name and message, if any, of the exceptionthrown by the method.

The values in each column in an entry are separated by spaces, not tabs.

Trace le examples

Here are some examples of trace files generated by various combinations of propertysettings. Note that due to space limitations on the page, the individual entries areline-wrapped in the examples.

Example 12-1. Settings are: dfc.tracing.enable=true

1158701543173 <user1> [Thread-0] [ENTER].............com.documentum.fc.client.DfTypedObject@28821120.getData()1158701543173 <user1> [Thread-0] [EXIT].............com.documentum.fc.client.DfTypedObject@28821120.getData==>



com.documentum.fc.client.impl.typeddata.ITypedData@150ed68

Example 12-2. Settings are: dfc.tracing.enable=true; dfc.tracing.timing_style=millis_from_start

1141125 <user4> [Thread-5] [EXIT]........com.documentum.fc.client.impl.session.Session@4889213.incrementReferenceCountIfNonZero ==> 2

Example 12-3. Settings are: dfc.tracing.enable=true; dfc.tracing.thread_name_lter=Thread[45]

1158718491103 <user4> [Thread-4] [ENTER]..........com.documentum.fc.client.DfTypedObject@25700470.getData()1158718491103 <user4> [Thread-4] [EXIT]..........com.documentum.fc.client.DfTypedObject@25700470.getData==> com.documentum.fc.client.impl.typeddata.ITypedData@618b081158718491150 <user5> [Thread-5] [EXIT]..........com.documentum.fc.impl.util.io.MessageChannel@15999328.readSocket==> <void>1158718491166 [Thread-5] [EXIT]..........com.documentum.fc.impl.util.io.MessageChannel@15999328.readLength ==> 18

Example 12-4. Settings are: dfc.tracing.enable=true; dfc.tracing.include_rpc_count=true;dfc.tracing.include_session_id=true

1158702906324 <user5|s4|SM@25116828> [Thread-6] [ENTER] (RPCs=3269)....com.documentum.fc.client.impl.connection.docbase.DocbaseConnection@17535609.waitForCorrectTransactionContext()


Appendix A

Consistency Checks

This appendix describes the consistency checks executed by the Consistency Checker administrativetool. The checks are sorted into tables that describe the checks on a particular area of the repository.The tables are:• User and group checks, page 552• ACL checks, page 553• SysObject checks, page 554• Folder and cabinet checks, page 555• Document checks, page 556• Content object checks, page 557• Workflow checks, page 557• Object type checks, page 558• Data dictionary checks, page 559• Lifecycle checks, page 560• Object type index checks, page 561• Method object consistency checks, page 561Each table includes the following information:• Consistency check number

Each consistency check has a unique number. When an inconsistency is reported, the reportincludes the consistency check number and some information about the particular inconsistency.For example:WARNING CC-0001: User docu does not have a default group

• Description


Consistency Checks

• Severity level

The consistency checker script reports inconsistencies with one of two severity values: Warningor Error.

— A check produces a warning for a referential integrity inconsistency. For example, you wouldsee a warning if a check found a document referencing an author who no longer exists in therepository. You should fix such problems, but they do not threaten repository operations.

— A check produces an error for inconsistencies requiring immediate resolution. Theseinclude object corruption problems, such as missing _r table entries or missing entries in admi_object_type table, and type corruption.

User and group checksThese consistency checks apply to users and groups.

Table 76. Consistency checks for users and groups

Consistency check number Consistency checkdescription

Severity

CC-0001 Check for userswho belongto a group that does notexist

Warning

CC-0002 Check for userswho belongto groups that are not indm_user

Warning

CC-0003 Check for userswho are notlisted in dmi_object_type

Error

CC-0004 Check for groupsthat are not listed indmi_object_type

Error

CC-0005 Check for groups thatbelong to groups that donot exist

Warning

CC-0006 Check for groupsbelonging to supergroupsthat do not exist

Warning


Consistency Checks


Severity

CC-0081 Check for groups withdisconnected super groups

Warning

CC-0082 Check for groups withdisconnected subgroups

Warning

ACL checksThese consistency checks apply to ACLs.

Table 77. Consistency checks for ACLs


Severity

CC-0007 Check for ACLs containingusers who do not exist inthe repository

Warning

CC-0008 Check for ACLs which aremissing dm_acl_r entries

Error

CC-0009 Check for sysobjects whoseacl_domain is set to a userwho does not exist in therepository

Warning

CC-0010 Check for sysobjects thatbelong to users who do notexist in the repository

Warning

CC-0011 Check for sysobjects thatare set to ACLs that do notexist

Warning

CC-0012 Check for ACL objects withmissing dm_acl_s entry

Error

CC-0013 Check for ACL objectswith r_accessor_permitvalues that are missingr_accessor_name values

Error


Consistency Checks


Severity

CC-0014 Check for ACL objectswith r_accessor_namevalues that are missingr_accessor_permit values

Error

CC-0015 Check for ACL objects withr_is_group values that aremissing r_accessor_permitvalues

Error

CC-0016 Check for ACL objects withr_is_group values that aremissing r_accessor_namevalues

Error

CC-0017 Check for ACL objects withr_accessor_name valuesthat are missing r_is_groupvalues

Error

CC-0018 Check for ACL objects withr_accessor_permit valuesthat are missing r_is_groupvalues

Error

SysObject checksThese consistency checks apply to SysObjects.

Table 78. Consistency checks for SysObjects


Severity

CC-0019 Check for sysobjects thatare not referenced indmi_object_type

Error

CC-0020 Check for sysobjects thatpoint to non-existentcontent

Warning


Consistency Checks


Severity

CC-0021 Check for sysobjects thatare linked to non-existentfolders

Warning

CC-0022 Check for sysobjects thatare linked to non-existentprimary cabinets

Warning

CC-0023 Check for sysobjects thatreference non-existenti_chronicle_id

Warning

CC-0024 Check for sysobjects thatreference non-existenti_antecedent_id

Warning

CC-0025 Check for sysobjects withdm_sysobject_s entry butmissing dm_sysobject_rentries

Error

CC-0026 Check for sysobjects withdm_sysobject_r entries butmissing dm_sysobject_sentries

Error

Folder and cabinet checksThese consistency checks apply to folders and cabinets.

Table 79. Consistency checks for folders and cabinets


Severity

CC-0027 Check for folders withmissing dm_folder_rentries

Error

CC-0028 Check for folders that arereferenced in dm_folder_rbut not in dm_folder_s

Error


Consistency Checks


Severity

CC-0029 Check for dm_folderobjects that arenot referenced indmi_object_type

Error

CC-0030 Check for dm_folderobjects that are missingdm_sysobject entries

Error

CC-0031 Check for folders withnon-existent ancestor_id

Warning

CC-0032 Check for cabinetobjects that are missingdm_folder_r table entries

Error

CC-0033 Check that cabinet objectsare not referenced indmi_object_type

Error

CC-0034 Check for folderobjects that are missingdm_sysobject_r entries

Error

CC-0035 Check for folder objectswith null r_folder_path

Error

Document checksThese consistency checks apply to documents.

Table 80. Consistency checks for documents


Severity

CC-0036 Check for documents witha dm_sysobject_s entry butno dm_document_s entry

Error


Consistency Checks


Severity

CC-0037 Check for documents withmissing dm_sysobect_sentries

Error

CC-0038 Check for documents withmissing dmi_object_typeentry

Error

Content object checksThese consistency checks apply to content objects.

Table 81. Consistency checks for content objects


Severity

CC-0039 Check for content objectsreferencing non-existentparents

Warning

CC-0040 Check for content withinvalid storage_id

Warning

CC-0041 Check for content objectswith non-existent format

Warning

Workow checksThese consistency checks apply to workflows.

Table 82. Consistency checks for workows


Severity

CC-0042 Check for dmi_queue_itemobjects with non-existentqueued objects

Warning


Consistency Checks


Severity

CC-0043 Check for dmi_workitemobjects that referencenon-existent dm_workflowobjects

Warning

CC-0044 Check for workflowobjects with missingdm_workflow_s entry

Error

CC-0045 Check for dmi_packageobjects with missingdmi_package_s entries

Error

CC-0046 Check for dmi_packageobjects that referencenon-existent dm_workflowobjects

Warning

CC-0047 Check for workflowobjects with non-existentr_component_id

Warning

CC-0048 Check for dmi_workitemobjects with missingdmi_workitem_s entry.

Error

Object type checksThese consistency checks apply to object types.

Table 83. Consistency checks for object types


Severity

CC-0049 Check whether anydm_type objectsreference non-existentdmi_type_info objects

Error


Consistency Checks


Severity

CC-0050 Check whether anydmi_type_info objectsreference non-existentdm_type objects

Error

CC-0051 Check whether any typeshave corrupted propertypositions

Error

CC-0052 Check whether any typeshave invalid propertycounts

Error

Data dictionary checksThese checks apply to the data dictionary.

Table 84. Consistency checks for the data dictionary


Severity

CC-0053 Check whetherany duplicatedmi_dd_attr_info objectsexist.

Error

CC-0054 Check whetherany duplicatedmi_dd_type_info objectsexist

Error

CC-0055 Check whether anydmi_dd_attr_info objectsare missing an entry indmi_dd_common_info_s

Error

CC-0056 Check whether anydmi_dd_type_info objectsare missing an entry indmi_dd_common_info_s

Error


Consistency Checks


Severity

CC-0057 Check whether anydmi_dd_attr_info objectsare missing an entry indmi_dd_attr_info_s

Error

CC-0058 Check whether anydmi_dd_type_info objectsare missing an entry indmi_dd_type_info_s

Error

CC–0078 Check whether any datadictionary objects referencenon-existent default policyobjects

Error

Lifecycle checksThese checks apply to document lifecycles.

Table 85. Consistency checks for lifecycles


Severity

CC-0059 Check for anydm_sysobject objectsthat reference non-existentdm_policy objects

Warning

CC-0060 Check for any policyobjects that referencenon-existent types inincluded_type

Warning

CC-0061 Check for any policyobjects with missingdm_sysobject_s entries

Error

CC-0062 Check for any policyobjects with missingdm_sysobject_r entries

Error


Consistency Checks


Severity

CC-0063 Check for any policyobjects with missingdm_policy_r entries

Error

CC-0064 Check for any policyobjects with missingdm_policy_s entries

Error

Object type index checksThese consistency checks apply to object type indexes.

Table 86. Consistency checks for object type indexes


Severity

CC-0073 Check for dmi_indexobjects that point tonon-existent types

Warning

CC-0074 Check for types withnon-existent dmi_indexobject for _s table

Warning

CC-0075 Check for types withnon-existent dmi_indexobject for _r table

Warning

CC-0076 Check for indexes withinvalid property positions

Warning

Method object consistency checksThese consistency checks apply to method objects.


Consistency Checks

Table 87. Consistency checks for method objects


Severity

CC-0077 Check for methods usingjview rather than Java

Warning


Appendix B

IDQL and IAPI

This appendix describes the Interactive DQL (IDQL) and IAPI utilities. The utility is useful if youwant to test short scripts or perform short, small tasks in the repository. The IAPI utility allows youto execute Docbasic scripts.

The appendix includes the following topics:• Using IDQL, page 563• Using IAPI, page 568

Using IDQLThe IDQL utility is an interactive tool that lets you enter ad hoc DQL queries againsta repository. IDQL is also a useful as a tool for testing and other tasks that support anapplication or installation because it allows you to run scripts and batch files.

IDQL is included and installed with Content Server. It is found in %DM_HOME%\bin($DM_HOME/bin). Copy the utility’s executable (idql32.exe or idql) from the bindirectory to a directory you can access or copy it to your local machine.

If you copy it to your local machine, you must also copy the client library (DMCL) toyour local machine if it is not already there. If you have any of Documentum’s desktopclients or Developer Studio installed on your machine, then you have a copy of theDMCL also. However, the DMCL is not installed with the Web-based clients.

Starting IDQL

You can start the utility from the operating system prompt or an icon. To start the utilityfrom the operating system prompt, use the following syntax:

On Windows:


IDQL and IAPI

idql32 [-n] [-wcolumnwidth][-Uusername|-ENV_CONNECT_USER_NAME][-Pos_password|-ENV_CONNECT_PASSWORD][-Ddomain]repository|-ENV_CONNECT_DOCBASE_NAME [-Rinput_file][-X][-E][-Ltrace_level][-zZ][-Winteger][-Ksecure_mode]

On UNIX:idql [-n] [-wcolumnwidth][-Uusername|-ENV_CONNECT_USER_NAME][-Pos_password|-ENV_CONNECT_PASSWORD][-Ddomain]repository|-ENV_CONNECT_DOCBASE_NAME [-Rinput_file][-X][-E][-Ltrace_level][-zZ][-Winteger][-Ksecure_mode]

The order of the arguments on the command line is not important.

If you created an icon for the utility, double-click the icon and enter your name andpassword. To invoke the utility with additional command line arguments, use the icon’sProperties to add the arguments to the command line before you double-click the icon.

Table 88, page 564, describes the command line arguments.

Table 88. IDQL command line arguments


-n Removes numbering and the prompt symbolfrom input files. This argument is usedprimarily for scripts.

-wcolumnwidth Sets the screen width for output. The defaultwidth is 80 characters.

-Uusername

or

-ENV_CONNECT_USER_NAME

Identifies the user who is starting the session.You can include the user name on thecommand line with the -U flag, or you canuse the -ENV_CONNECT_USER_NAMEargument, which directs the system to lookfor the user name in the environment variableDM_USER_NAME.

-Pos_password

or

-ENV_CONNECT_PASSWORD

Identifies the user’s operating systempassword. You can include the password onthe command line with the -P flag, or youcan use the -ENV_CONNECT_PASSWORDargument, which directs the system to lookfor the password in the environment variableDM_PASSWORD.

If the user does not specify a password, theutility prompts for the password. If the userenters the -P flag without the password, IDQL


IDQL and IAPI


uses the default password, NULL. Passwordsare case sensitive.

-Ddomain Identifies the user’s domain.

repository

or

-ENV_CONNECT_DOCBASE_NAME

Identifies the repository. You caninclude the repository name on thecommand line, or you can use the-ENV_CONNECT_DOCBASE_NAMEargument, which directs the system to lookfor the repository name in the environmentvariable DM_DOCBASE_NAME.

-Rinputfile Specifies the name of an input file containingDQL queries. This is an optional argument.

-X Allows prompt for domain.

-E Turns on echo.

-Ltrace_level Turns tracing on for the session. trace_level canbe any of the valid trace levels described inthe Trace method description.

-zZ Specifies Windows NT Unified Logon. Thisoption overrides any user name and passwordspecified on the command line.

-Winteger

or

-winteger

Sets the maximum column width whendisplaying results. integer is interpreted asnumber of bytes. The default is 2000 bytes.

Any value which exceeds the maximum rowwidth is truncated when displayed.

-Ksecure_mode Defines the type of connection you want toestablish.

Valid values are:

• secure• native• try_secure_first• try_native_first

The default is native. For an explanation of thevalues, refer to Defining the secure connectiondefault for connection requests, page 166.


IDQL and IAPI

After you start IDQL, the utility returns with its prompt. The IDQL utility has anumerical prompt that begins with 1 and increments each time you press the carriagereturn or Enter key to move to a new line on your display.

The IDQL commands

IDQL recognizes the commands listed in Table 89, page 566.

Table 89. IDQL commands

Command Description

go Executes a DQL statement and clears the query buffer.

clear Clears the query buffer.

quit Exits the utility.

describe Provides a description of a specified object type orregistered table. The syntax formats for this commandare:

describe [type] type_name

describe table table_name

@scriptfile Executes the specified script.

shutdown Issues a Shutdown method that shuts down theContent Server gracefully. You must be a superuseror system administrator to use this command. Whenshutdown is complete, the utility exits.

trace Turns on tracing for the current session. By default,tracing is set to level 5.

-Winteger

or

-winteger

Sets the maximum column width when displayingresults. integer is interpreted in bytes. The default is2000 bytes.

Setting this affects the results display for all statementsissued after this command.

Each command must be entered on a separate line. A command cannot appear on thesame line as a query, nor can two or more commands appear on one line.


IDQL and IAPI

Entering queries

Enter a query by typing it at the IDQL prompt. The following IDQL session showstwo queries typed at the prompt:1> BEGIN TRAN2> go3> SELECT *4> FROM Engineering5> WHERE Engineer LIKE 'Smith, %'6> go

The query processor interprets semicolons (;) as statement terminators and ignoreseverything that follows the semicolon on the line.

When you enter a query, IDQL places the query in a buffer. You can then execute thequery or clear the buffer.

The go command executes a query. Each go command can execute only one query. Youcannot execute multiple queries with one go command.

There are two ways to execute queries in a batch using IDQL:• Use the input file option in the IDQL command line.• Use the @scriptfile command.The input file is a file that contains queries. You must place a go command after eachquery in the file, and you must terminate the file with a quit command.

The results of each query are returned to standard output by default.

The @scriptfile command executes a specified script, which can include DQL queries.Like an input file, queries in the script must be separated by go commands. You are notrequired to use a quit command to terminate a script executed with @scriptfile.

Clearing the buffer

The following excerpt enters a query and then clears it from the buffer:1> SELECT *2> FROM Engineering3> WHERE Engineer LIKE 'Smith, %'4> clear

Entering comments

To enter a comment in an IDQL session, start the comment line with \\ or -- .


IDQL and IAPI

Stopping IDQL

To close an IDQL session, enter the quit command at the IDQL prompt.

Using IAPIThe IAPI utility is a tool that you can use to execute Docbasic scripts. This utilityis included and installed with Content Server. It is found in %DM_HOME%\bin($DM_HOME/bin).

Starting IAPI

You can start the utility from the operating system prompt or an icon. To start the utilityfrom the operating system prompt, use the following syntax:

On Windows:iapi32 [-Uusername|-ENV_CONNECT_USER_NAME][-Pos_password|-ENV_CONNECT_PASSWORD] [-Llogfile] [-X][-E][-V-][-Q] repository|-ENV_CONNECT_DOCBASE_NAME [-Rinputfile][-Ftrace_level][-Sinit_level][-Iescape_character][-zZ][-Winteger][-Ksecure_mode]

On UNIX:iapi [-Uusername|-ENV_CONNECT_USER_NAME][-Pos_password|-ENV_CONNECT_PASSWORD] [-Llogfile] [-X][-E][-V-][-Q] repository|-ENV_CONNECT_DOCBASE_NAME [-Rinputfile][-Ftrace_level][-Sinit_level][-Iescape_character][-zZ][-Winteger][-Ksecure_mode]

The order of the arguments on the command line is not important.

If you created an icon for the utility, double-click the icon and enter your name andpassword. To invoke the utility with additional command line arguments, use the icon’sProperties to add the arguments to the command line before you double-click the icon.

Table 90, page 569, describes the command line arguments.


IDQL and IAPI

Table 90. IAPI command line arguments


-Uusername

or

-ENV_CONNECT_USER_NAME

Identifies the user who is starting the session.You can include the user name on thecommand line with the -U flag or you canuse the -ENV_CONNECT_USER_NAMEargument, which directs the system to lookfor the user name in the environment variableDM_USER_NAME.

-Pos_password

or

-ENV_CONNECT_PASSWORD

Identifies the user’s operating systempassword. You can include the password onthe command line with the -P flag, or youcan use the -ENV_CONNECT_PASSWORDargument, which directs the system to lookfor the password in the environment variableDM_PASSWORD.

If the user does not specify a password, theutility prompts for the password.

-Llogfile Directs the server to start a log file for thesession. You must include the file name withthe argument. You can specify a full path.

-X Allows prompt for domain.

-E Turns on echo.

-V- Turns verbose mode off. The utility runs inverbose mode by default. If you turn verbosemode off, the system does not display the IAPIprompt, error messages, or any responsesto your commands (return values or statusmessages).

You can also change modes from the IAPIprompt (refer toIAPI commands, page 571).

-Q Directs the utility to provide a quickconnection test. The utility attempts to connectand exits with a status of zero if successful ornon-zero if not. It provides error messages ifthe attempt is not successful.


IDQL and IAPI


repository

or

-ENV_CONNECT_DOCBASE_NAME

Identifies the repository. You caninclude the repository name on thecommand line, or you can use the-ENV_CONNECT_DOCBASE_NAMEargument, which directs the system to lookfor the repository name in the environmentvariable DM_DOCBASE_NAME.

-Rinputfile Identifies an input file containing APImethods.

-Ftrace_level Turns tracing on for the session. trace_level canbe any of the valid trace levels described in theTrace method description.

-Sinit_level Defines the connection level established whenyou start the API session. Valid init levels andtheir meanings are:

api, which opens an API session. User mustissue an explicit Connect to start a session.

connect, meaning undetermined

standard, which opens a session

-Iescape_character Defines an escape character for certainsymbols such as a forward slash (/).

-zZ Specifies Windows NT Unified Logon. Thisoption overrides any user name and passwordspecified on the command line.

-Winteger

or

-winteger

Sets the maximum column width whendisplaying results returned from a queryentered with a ? command. integer isinterpreted as number of bytes. The defaultis 2000 bytes.

Any value which exceeds the maximum rowwidth is truncated when displayed.

-Ksecure_mode Defines the type of connection you want toestablish.

Valid values are:

• secure• native• try_secure_first


IDQL and IAPI


• try_native_first

The default is try_native_first. For anexplanation of the values, refer toDefiningthe secure connection default for connectionrequests, page 166.

When you issue the iapi command, the system returns a status message that tells you itis connecting you to the specified database. This is followed by a message giving you thesession ID for your session and then the utility’s prompt (API>).

IAPI commands

The IAPI commands affect how the IAPI utility functions. These commands do not affectthe repository. The utility accepts the commands listed in Table 91, page 571.

Table 91. IAPI commands

Command Description

$logfile Outputs to the specified file

@scriptfile Reads input from the specified file

%scriptfile Outputs a script

-V[+|-] Turns verbose mode on (+) or off (-).

By default, verbose mode is on. If you turnverbose mode off, the system does not displaythe IAPI prompt, error messages, or anyresponses to your commands (return valuesor status messages).

-Winteger

or

-winteger

Sets the maximum column width whendisplaying results returned from a queryentered with a ? command. integer isinterpreted in bytes. The default is 2000 bytes.

Setting this affects the results display for allmethods issued after this command.

? Allows you to enter a query or collection IDand formats the output as a table.

The ? command allows you to enter a DQL SELECT statement in IAPI. When used with aSELECT statement, the command is the equivalent of a Readquery method. The syntax is:


IDQL and IAPI

API>?,c,select_query_string

For example:API>?,c,select r_object_id, object_name from dm_document

The results are formatted in a table-like block. For example:r_object_idobject_name-----------------------090015c38000013Bfoo.txt090015c3800002e4spam.html090015c3800001c2fah.txt

You can also use the ? command to retrieve a collection’s content in one block. Forexample, suppose you issue a readquery method, which returns a collection:API>readquery,c,select r_object_id, object_name from dm_document...API>q0

Instead of using a Next method to retrieve each row of the collection, you can use ? toretrieve them all at once:API>?,c,q0...r_object_idobject_name-----------------------090015c38000013Bfoo.txt090015c3800002e4spam.html090015c3800001c2fah.txt

Entering method callsNote: This use of IAPI is deprecated, as the DMCL that was the primary API for ContentServer in versions prior to Documentum 6 is deprecated in Documentum 6.

Call methods directly from the IAPI prompt by typing the method name and itsarguments as a continuous string, with commas separating the parts. For example, thefollowing command creates a new folder:API> create,s0,dm_folder

If any parameter value contains a comma, you must enclose that parameter in singlequotes. For example, the following command creates a new document and assigns ita content file:API> create,s0,dm_documentAPI> setfile,s0,last,'/home/janed/temp.doc,1',text

The name of the content file is in single quotes because it contains a comma.

When the method completes, the utility displays the return value. For example, theCreate method returns the object ID of the newly created object. So if you issue the


IDQL and IAPI

Create command shown in the previous example, the utility displays the object ID ofthe new folder:API> create,s0,dm_folder. . .0b6385F20000561B

When you execute a method that assigns a value to an attribute, you do not specifythe value as part of the command syntax. Instead, IAPI prompts you for that value.For example, the following exchange sets the name of the folder object created in theprevious example:API> set,s0,last,object_nameSET> cake_recipes. . .OK

The keyword last refers to the last created, fetched, checked in/out, or retrieved objectID (in this case, the folder ID).

Entering comments

Enter a comment in an IAPI session by preceding it with the pound sign (#). This isuseful when you want to use scripts with IAPI.

Quitting an IAPI session

To exit from IAPI, enter quit at the IAPI prompt:IAPI> quit


IDQL and IAPI


Appendix C

Archiving scripts

This appendix contains sample scripts to support the archiving functionality. You must edit thesegeneric scripts before running to them to localize them for your installation. Contact DocumentumProfessional Services or Documentum Developer support for assistance to customize these scripts.

The dql Script## dm_archive.dql - initialize methods for the dmarchive# utility.# This file was created by user, roger,# on Thu Nov 3 21:26:00 PST 1994 using# the utility ./tools/dm_archive.gen## This script creates the methods used by the archive utility# "dmarchive".# These methods will be called if they exist and are intended# to allow the archive facility to be customized to move the# archive dumpfiles to an offline storage medium until needed# by restore actions.## post_archive - Called after each archive action, its# intention is to allow the created archive dumpfile to be# moved from the archive directory to offline storage# location.##The method invokes a script with two arguments:## $1 - The name of the new archive dumpfile (path included)# $2 - The number of objects dumped by the archive operation.## pre_restore - Called prior to each restore action, its# intention is to# allow the requested archive dumpfile to be restored to# the archive directory from any offline storage area it# may have been moved to by the post_archive method.## The method invokes a script with one arguments:


Archiving scripts

## $1 - The name of requested archive dumpfile, including the# filesystem path. It must be restored to its original# filesystem directory.## post_restore - Called after each restore action, its#intention is to allow the archive dumpfile to be removed# from the archive directory since its use is now complete.## The method invokes a script with one arguments:## $1 - The name of requested archive dumpfile, including the# filesystem path. It must be restored to its original# filesystem directory.#

create dm_method objectset object_name = 'post_archive',set method_verb = '/u31/docbase/roger/dba/post_archive',set timeout_min = 30,set timeout_max = 1000,set timeout_default = 1000,set launch_direct = false,set launch_async = false,set trace_launch = false,set run_as_server = truego

create dm_method objectset object_name = 'pre_restore',set method_verb = '/u31/docbase/roger/dba/pre_restore',set timeout_min = 30,set timeout_max = 1000,set timeout_default = 1000,set launch_direct = false,set launch_async = false,set trace_launch = false,set run_as_server = truego

create dm_method objectset object_name = 'post_restore',set method_verb = '/u31/docbase/roger/dba/post_restore',set timeout_min = 30,set timeout_max = 1000,set timeout_default = 1000,set launch_direct = false,set launch_async = false,set trace_launch = false,set run_as_server = truego

The dm_archive_start scriptThis script starts a dmarchive process.


Archiving scripts

#!/bin/sh# dm_archive_start - start archive program for repository## This file was created by user, roger,# on Wed Nov 2 16:06:47 PST 1994 using# the utility dm_setup_archive## This script should normally be run by the repository operator# user.## This script may be modified if desired to alter the archive# behavior by adding the following flags to the startup# options below:## -U<username>- Run as specified user (eg. repository operator# name)## -queue_name <name>- Specify alternate inbox queue on# which requests are made.## -do_archive_evnts - Specify that program should only# handle archive requests (not restore requests). Implies# thatrestore requests will be handled by another method or a# different invocation of this program.## -do_restore_events - Specify that program should only# handle restore requests (not archive requests). Implies# that archive requests will be handled by another method# or a different invocation of this program.##

logfile=/u31/docbase/roger/dba/log/dmarchive.rogbase.logdmarchive docbase_name -P -archive_dir /tmp/archive-verbose >> $logfile &

The post_archive scriptThis script is meant to be run after an archive request is completed, to remove the dumpfile from the archive directory and place it in permanent storage.

The Windows version:@echo offremrem Id$remrem post_archive - Called after each archive action,rem its intention is torem allow the created archive dumpfile to be moved from therem archive directory to offline storage location.remrem The post_archive script is invoked with two arguments:rem


Archiving scripts

rem %1 - The name of the new archive dumpfile (path included)rem %2 - The number of objects dumped by the archive operation.rem Primarily provided so that the dumpfile can berem destroyed rather than saved if the object count isrem zero, which occurs when an archive is given whichrem specifies only documents already archived.remremrem This script is provided as a mechanism for automatically movingrem archive dumpfiles to an offline storage arearem following an archive invocation.remrem Each archive operation produces an archive dumpfile in therem Archive Staging Directory and then removes the archivedrem document content from the repository storage areas.rem The archive dumpfile must be saved as it is the onlyrem mechanism for restoring the removed content if the documents arerem needed sometime later.remremrem It is suggested that the archive dumpfiles be periodically movedrem out of the Archive Staging Directory and placedrem on some offline storage media such as a tapes or optical devices.remremrem This can be done by periodically backing up the Archive Stagingrem Directory to tape, and then removing the backed up archiverem dumpfiles. On NT, here is a BackUp utility under the Administrativerem Tools program folder. Alternatively, this can be done via arem third-party backup software that provides a commandrem line interface.remrem NOTE THAT ONCE A DUMPFILE IS REMOVED from the Archive Stagingrem Directory, procedures must be put in place to retrieverem that dumpfile if a restore request is made on an archivedrem document. The restore procedure requiresrem that the dumpfile be placed back in the Archive Staging Directory inrem order to re-load the archived content. rem See the pre_restore scriptrem for more information on these requirements.remremrem The archive methods (post_archive, pre_restore, and post_restorerem scripts) are called as a mechanism for automating the processrem of moving archive dumpfiles in and out of the staging area.remremrem The post_archive method is called after each archive operationrem and allows for the newly-created dumpfile to berem automatically moved to the offline storage device.rem A simple example of this would be to add the shellrem commands at the end of this script to copy the new dumpfile to arem backup device:remremremrem echo ": post_archive: Saving %filename%" >> \temp\archive.logrem ... backup command to transfer dumpfile to a tape or another


Archiving scripts

rem disk ...rem if successful erase %filename%remremremrem Default post_archive implementation:remrem This default script does not attempt to move dumpfiles out of therem staging directory, but it does check for and remove emptyrem archive files.remremset filename="%1"set object_count="%2"remrem If no objects were dumped in the specified archive operation, thenrem delete the created dumpfile rather than saving it. Unusedrem dumpfiles like this are created if an archive requestrem specifies only documents which are already fully archived.remremrem This is often done purposefully to move offline a set of previouslyrem archived documents which have since been restored. Therem archive request takes them offline, but does not actuallyrem dump the documents since they have already been archived.remremif %object_count% NOT = "0" goto the_endecho ": post_archive: Deleting unneeded %filename%" >> \temp\archive.logerase /f /q %filename%exitthe_end:echo ": post_archive: Called with dumpfile %filename%" >>\temp\archive.logexit

The UNIX version:#!/bin/sh#$Id: post_archive,v 1.1 1994/11/03 00:29:47 roger Exp $## post_archive - Called after each archive action, its intention is to allow thecreated archive dumpfile to be moved from thearchive directory to offline storage location.

## The post_archive script is invoked with two arguments:#

# $1 - The name of the new archive dumpfile (path included)# $2 - The number of objects dumped by the archive# operation.# Primarily provided so that the dumpfile can be destroyed# rather than saved if the object count is zero, which occurs# when an archive is given which specifies only documents# already archived.### This script is provided as a mechanism for automatically


Archiving scripts

# moving archive dumpfiles to an offline storage area# following an archive invocation.## Each archive operation produces an archive dumpfile in# the Archive Staging Directory and then removes the archived# document content from the repository storage areas. The# archive dumpfile must be saved as it is the only mechanism# for restoring the removed content if the documents are# needed sometime later.## It is suggested that the archive dumpfiles be# periodically moved out of the Archive Staging Directory and# placed on some offline storage media such as a tapes or# optical devices.## This can be done by periodically backing up the Archive# Staging Directory to tape via a standard unix utility# (tar, cpio ..) or your favorite third-party backup# software, and then removing the backed up archive# dumpfiles.## NOTE THAT ONCE A DUMPFILE IS REMOVED from the Archive# Staging Directory, procedures must be put in place to# retrieve that dumpfile if a restore request is made on an# archived document. The restore procedure requires that the# dumpfile be placed back in the Archive Staging Directory in# order to re-load the archived content. See the pre_restore# script for more information on these requirements.## The archive methods (post_archive, pre_restore, and# post_restore scripts) are called as a mechanism for# automating the process of moving archive dumpfiles in and# out of the staging area.#

## The post_archive method is called after each archive# operation and allows for the newly-created dumpfile to be# automatically moved to the offline storage device. A# simple example of this would be to add the shell commands# at the end of this script to copy the new dumpfile to a tape# device:## echo "‘date‘: post_archive: Saving $filename" >> /tmp# /archive.log# tar -rf /dev/rmt0 $filename# status=$?# if [ $status = 0 ]# then# rm $filename# fi#

######################################################################

## Default post_archive implementation:## This default script does not attempt to move dumpfiles


Archiving scripts

# out of the staging directory, but it does check for and# remove empty archive files.#

######################################################################

filename="$1"object_count="$2"

## If no objects were dumped in the specified archive# operation, then delete the created dumpfile rather than# saving it. Unused dumpfiles like this are created if an# archive request specifies only documents which are already# fully archived.## This is often done purposefully to move offline a set of# previously archived documents which have since been# restored. The archive request takes them offline, but does# not actually dump the documents since they have already# been archived.#

if [ $object_count = "0" ]thenecho "‘date‘: post_archive: Deleting unneeded $filename" >> /tmp/archive.logrm $filenameexit 0

fi

echo "‘date‘: post_archive: Called with dumpfile $filename" >> /tmp/archive.logexit 0

The pre_restore scriptThe Windows version:@echo offrem $Id: pre_restore.bat,v 2.1 1995/11/13 23:27:56 kinnard Exp $remrem pre_restore - Called prior to each restore action, itsrem intention is to allow the requested archive dumpfile to berem restored to the archive directory from any offline storagerem area it may have been moved to by the post_archive method.rem The pre_restore script is invoked with one argument:remrem 1 - The name of requested archive dumpfile, includingrem the filesystem path. It must be restored to its originalrem filesystem directory.remremrem This script is provided as a mechanism for automatically restoringrem archive dumpfiles from their offline storage arearem so that their archived content can be retrieved by a restorerem operation.rem


Archiving scripts

rem Each archive operation produces an archive dumpfile in the Archiverem Staging Directory and then removes the archived documentrem content from the repository storage areas. The archive dumpfilerem must be saved as it is the only mechanism for restoringrem the removed content if the documents are neededrem sometime later.remrem It is suggested that the archive dumpfiles be periodically moved outrem of the Archive Staging Directory and placed on somerem offline storage media such as a tapes or optical devices.remremrem This can be done by periodically backing up the Archive Stagingrem Directory to tape via a standard unix utility (tar, cpio ..)rem or your favorite third-party backup software, and then removingrem the backed up archive dumpfiles.remrem The archive methods (post_archive, pre_restore, and post_restorerem scripts) are called as a mechanism for automating therem process of moving archive dumpfiles in and out of therem staging area.remrem NOTE THAT ONCE A DUMPFILE IS REMOVED from the Archive Stagingrem Directory, procedures must be put in place to retrieve thatrem dumpfile if a restore request is made on an archived document.rem The restore procedure requires that the dumpfile be placedrem back in the Archive Staging Directory in order to re-loadrem the archived content.remrem When the dmarchive program is run, it requires that the archiverem dumpfiles which contain needed content data either be alreadyrem accessible in the Archive Staging directory at the timerem the restore request is seen, or that they be automaticallyrem restored by the invocation of the pre_restorerem method.remrem The pre_restore method is called once for each needed archiverem dumpfile prior to a restore operation. Upon exit the specifiedrem dumpfile must be available in the Archive Staging Directoryrem for the restore load operation in order for the restorerem request to proceed.remrem A simple example of the pre_restore function would be to add therem shell commands at the end of this script to copy the dumpfilerem back from the tape device to which it was written by therem post_archive method:remrem if [ ! -f $filename ]rem thenrem echo "‘date‘: pre_restore: Restoring $filename" >>rem /tmp/archive.logrem tar -xf /dev/rmt0 $filenamerem firemremremrem Default pre_restore implementation:


Archiving scripts

remrem This default script does not attempt to restore dumpfiles to therem staging directory; it merely checks their existence.remremrem

set filename="%1"echo ": pre_restore:Requested file:%filename%" >> \temp\archive.logif not exist %filename% goto not_existexit

not_exist:echo ": pre_restore: Warning: %filename% does not exist." >> \temp\archive.logfiexit

The UNIX version:#!/bin/sh#$Id: pre_restore.bat,v 1.1 1994/11/13 23:27:56 kinnard Exp $#

# pre_restore - Called prior to each restore action, its# intention is to allow the requested archive dumpfile to be# restored to the archive directory from any offline storage# area it may have been moved to by the post_archive method.##The pre_restore script is invoked with one argument:#

# $1 - The name of requested archive dumpfile, including# the filesystem path. It must be restored to its# original filesystem directory.## This script is provided as a mechanism for automatically# restoring archive dumpfiles from their offline storage# area so that their archived content can be retrieved by a# restore operation.## Each archive operation produces an archive dumpfile in# the Archive Staging Directory and then removes the archived# document content from the repository storage areas. The# archive dumpfile must be saved as it is the only mechanism# for restoring the removed content if the documents are# needed sometime later.## It is suggested that the archive dumpfiles be periodically# moved out of the Archive Staging Directory and placed on# some offline storage media such as a tapes or optical# devices.## This can be done by periodically backing up the Archive# Staging Directory to tape via a standard unix utility (tar,# cpio ..) or your favorite third-party backup software, and# then removing the backed up archive dumpfiles.## The archive methods (post_archive, pre_restore, and# post_restore scripts) are called as a mechanism for# automating the process of moving archive dumpfiles in and


Archiving scripts

# out of the staging area.

## NOTE THAT ONCE A DUMPFILE IS REMOVED from the Archive# Staging Directory, procedures must be put in place to# retrieve that dumpfile if a restore request is made on an# archived document. The restore procedure requires that# the dumpfile be placed back in the Archive

#

# Staging Directory in order to re-load the archived# content. When the dmarchive program is run, it requires# that the archive dumpfiles which contain needed content# data either be already accessible in the Archive Staging# directory at the time the restore request is seen, or that# they be automatically restored by the invocation of the# pre_restore method.## The pre_restore method is called once for each needed# archive dumpfile prior to a restore operation. Upon exit# the specified dumpfile must be available in the Archive# Staging Directory for the restore load operation in order# for the restore request to proceed.## A simple example of the pre_restore function would be to# add the shell commands at the end of this script to copy# the dumpfile back from the tape device to which it was# written by the post_archive method:#

# if [ ! -f $filename ]# then# echo "‘date‘: pre_restore: Restoring $filename" >> /tmp/# archive.log# tar -xf /dev/rmt0 $filename# fi#

######################################################################

#

# Default pre_restore implementation:## This default script does not attempt to restore dumpfiles to the staging

directory; it merely checks their existence.#

######################################################################

filename="$1"

echo "‘date‘: pre_restore: Requested file: $filename" >> /tmp/archive.logif [ ! -f $filename ]thenecho "‘date‘: pre_restore: Warning: $filename does not exist." >>/tmp/archive.log

fi

exit 0


Archiving scripts

The post_restore scriptThe Windows version:@echo offrem $Id: post_restore.bat,v 2.1 1995/11/13 23:29:06 kinnard Exp $remrem post_restore - Called after each restore action, its intention isrem to allow the archive dumpfile to be removed from the archive directoryrem since its use is now complete.remrem The post_restore script is invoked with one argument:remrem %1 - The name of the archive dumpfile (path included)remrem This script is provided as a mechanism for automatically managingrem archive dumpfiles that are transitioned between therem Archive Staging Directory and offline storage during archiverem and restore operations.remrem If the post_archive and pre_restore methods are automatically usedrem copy archive dumpfiles to offline storage and back then this methodrem can be used to automatically clean up files used in restorerem operations.remrem If the method of offline storage for archive dumpfiles is such thatrem copies of the dumpfiles are created in restore operations,rem and if the particular dumpfile on which the current restore wasrem just performed has already been copied to offline storage,rem then this routine can safely remove that dumpfile fromrem the Archive Staging Directory as it is no longer needed.remrem If your configuration does not automatically copy all archiverem dumpfiles to offline storage, be careful that you do not modifyrem this routine to accidentally delete an archive dumpfile thatrem has not been saved yet!remrem Tip: If restore requests are handled frequently, it may make senserem to not automatically delete them after each restore operation,rem but to leave them around for a little while in case a secondrem restore operation is requested which needs the same dumpfile.rem This script could be altered to only delete files which haverem been resident for a set amount of time.remremremrem Default post_restore implementation:remremset filename="%1"echo ": post_restore: Restored file: %filename%" >> \temp\archive.logexit

The UNIX version:#!/bin/sh#$Id: post_restore,v 1.1 1994/11/03 00:29:49 roger Exp $


Archiving scripts

## post_restore - Called after each restore action, its# intention is to allow the archive dumpfile to be removed# from the archive directory since its use is now complete.## The post_restore script is invoked with one# argument:## $1 - The name of the archive dumpfile (path included)## This script is provided as a mechanism for automatically# managing archive dumpfiles that are transitioned between# the Archive Staging Directory and offline storage during# archive and restore operations.## If the post_archive and pre_restore methods are being# used to automatically copy archive dumpfiles to offline# storage and back then this method can be used to# automatically clean up files used in restore operations.## If the method of offline storage for archive dumpfiles is# such that copies of the dumpfiles are created in restore# operations, and if the particular dumpfile on which the# current restore was just performed has already been# copied to offline storage, then this routine can safely# remove that dumpfile from the Archive Staging Directory as# it is no longer needed.## If your configuration does not automatically copy all# archive dumpfiles to offline storage, be careful that you# do not modify this routine to accidentally delete an# archive dumpfile that has not been saved yet!## Tip: If restore requests are handled frequently, it may# make sense to not automatically delete them after each# restore operation, but to leave them around for a little# while in case a second restore operation is requested# which needs the same dumpfile. This script could be# altered to only delete files which have been resident for a# set amount of time.#

######################################################################

## Default post_restore implementation:#

######################################################################


Archiving scripts

filename="$1"

echo "‘date‘: post_restore: Restored file: $filename" >> /tmp/archive.logexit 0


Archiving scripts


Appendix D

High-Availability Support Scripts

EMC Documentum provides a set of scripts that monitor processes to determine whether a givenprocess is running or stopped. These scripts are installed when a Content Server installation iscreated. The scripts can be programmatically invoked from any commercial system management andmonitoring package. This appendix describes the scripts and which processes they affect.

• Monitoring scripts, page 589• Processes not requiring a script , page 591

Monitoring scriptsMonitoring scripts are provided for Content Server, the connection broker, the Javamethod server, and for the Index Agent.

The scripts must be run as the Documentum Content Server installation owner. Eachscript returns success (the monitored process is running) as 0 or failure (the monitoredprocess is stopped) as a non-zero value.

Table 92, page 589, lists the processes that have monitoring scripts, the script names, andtheir locations and command-line syntax.

Table 92. Monitoring Scripts

Process Script Syntax and Location

Content Server ContentServer-Status

A Java program in the server-impl.jar file.

The command line syntax is:

java com.documentum.server.impl.utils.ContentServerStatus-docbase_name xxxx -user_name



Process Script Syntax and Location

On UNIX, the return value is recorded in thevariable $?. On Windows, the return value isrecorded in %ERRORLEVEL%.

Connectionbroker

dmqdocbroker Located in %DM_HOME%\bin ($DM_HOME/bin)

The syntax is:

%DM_HOME%\bin\dmqdocbroker -thost_name -c ping

or

$DM_HOME/bin/dmqdocbroker -thost_name -c ping

host_name is the name of the machine hostingthe connection broker.


Java methodserver

TestConnection A Java program in the server-impl.jar file.

On UNIX, the command line syntax is:

java TestConnection host port servlet

On Windows, the command line syntax is:

java TestConnection host port

host is the Java Method Server (JVM)host machine; port is the port the JVMis using; and servlet is the value indm_server_config.app_server_name thatrepresents the JVM.


Index Agent IndexAgentCtrl A Java program in the server-impl.jar file.

The command line syntax is:

java com.documentum.server.impl.utils.IndexAgentCtrl -docbase_name



Process Script Syntax and Locationrepository_name -user_name user_name-action status

repository_name is the name of a repositoryserved by the agent and user_name is the useraccount with which to connect to the repository.

Processes not requiring a scriptThe following processes do not require a separate script:• dmbasic method server• ACS server• Workflow agentContent Server monitors these processes. If any of these proceses stops, Content Serverrestarts it automatically.




Appendix E

Populating and Publishing the DataDictionary

This appendix describes how to modify the data dictionary by adding or removing information,including locale files. It also describes how to publish the data dictionary. The appendix includesthe following topics:• Populating the data dictionary, page 593• Data dictionary population script, page 594• Publishing the data dictionary information, page 606

Populating the data dictionaryWhen you configure a repository, by default the procedure automatically populates thedata dictionary with default information for one locale and sets the name of the localein the dd_locales property of the docbase config object.

To add a new locale, use the population script provided by Documentum. To add to orchange the locale information for installed data dictionary locales, you can use:• The population script provided by Documentum• The DQL CREATE TYPE or ALTER TYPE statementUsing the population script automatically records a new locale in the dd_localesproperty if needed.

Only some of the data dictionary information can be set using a population script.(Summary of settable data dictionary properties, page 597, describes the data dictionaryproperties that you can set in a population script.) The information that you can not setusing the population script must be set using the DQL statements. Additionally, youmust use DQL if you want to set data dictionary information that applies only whenan object is in a particular lifecycle state.

Using DQL statements, page 606, discusses using DQL to populate the data dictionary.


Populating and Publishing the Data Dictionary

For a description of the default data dictionary files provided with Content Server, referto Default files provided by EMC Documentum, page 606.

Data dictionary population scriptThe data dictionary population script, dd_populate.ebs, is a Docbasic script that reads aninitialization file. The initialization file contains the names of one or more data files thatdefine the data dictionary information you want to set. (Refer to Executing the script,page 605, for instructions on executing the script.)

Note: Documentum provides an initialization file and data files that populate the datadictionary with the default settings for Documentum object types. For information aboutthese, refer to Default files provided by EMC Documentum, page 606.

The initialization le

You can name the initialization file any name you like, but it must have a .ini extension.The structure of the initialization file is:[DD_FILES]<non-NLS data dictionary data file 1><non-NLS data dictionary data file 2>. . .<non-NLS data dictionary data file n>

[NLS_FILES]<NLS data dictionary data file 1><NLS data dictionary data file 2>. . .<NLS data dictionary data file n>

The non-NSL data dictionary files contain the data dictionary information that is notspecific to a locale.

The NLS data dictionary files contain the information that is specific to a locale.

You can include any number of data files in the initialization file. Typically, there is onefile for the non-NLS data and an NLS data file for each locale. You can reference the datafiles by name or full path specification. If you reference a data file by name only, thedata file must be stored in the same directory as the population script or it must be in%DM_HOME%\bin ($DM_HOME/bin).



The data les

The data files are text files. You can create them with any text editor. There are twokinds of data files:• Non-NLS• NLSIn the non-NLS data files, the information you define is applied to all locales. In thesefiles, you define the information that is independent of where the user is located. Forexample, you would set a property’s is_searchable or ignore_immutable setting in anon-NLS-sensitive file.

In an NLS data file, all the information is assumed to apply to one locale. In these files,you identify the locale at the beginning of the file and only the dd type info and dd attrinfo objects for that locale are created or changed. For example, if you set the label textfor a new property in the German locale, the system sets label_text in the new property’sdd attr info object in the German locale. It will not set label_text in the property’s ddattr info objects for other locales.

If you do set NLS information in a non-NLS data file, the server sets the NLS informationin the session’s current locale.

If you include multiple NLS files that identify the same locale, any duplicate informationin them overwrites the information in the previous file. For example, if you includetwo NLS data files that identify Germany (de) as the locale and each sets label_textfor properties, the label text in the second file overwrites the label text in the first file.Unduplicated information is not overwritten. For example, if one German file setsinformation for the document type and one sets information for a custom type calledproposals, no information is overwritten.

Note: Future upgrades of Content Server may overwrite any changes you make to thedata dictionary information about Documentum object types. To retain those changes,use a separate data file to create them. You can then re-run that data file after theupgrade to recreate the changes.

File structure

Each data file consists of sections headed by keywords that identify the object type and,if you are defining information for a property, the property. Additionally, an NLS filemust identify the locale at the beginning of the file.

To specify the locale in an NLS file, place the following key phrases as the first linein the file:• LOCALE=locale_name CODEPAGE=codepage_name



locale_name is defined as a string of up to five characters. When the locale is defined in afile, the server resets the current session locale to the specified locale and the informationin that data file is set for the given locale.

codepage_name is the name of the code page appropriate for the specified locale. Table 93,page 596, lists the code pages for the data files provided with Content Server.

Table 93. Codepages for the data dictionary les provided with Content Server

Data file locale Codepage

en (English) ISO_8859-1

es (Spanish) ISO_8859-1

fr (French) ISO_8859-1

it (Italian) ISO_8859-1

de (German) ISO_8859-1

sv (Swedish) ISO_8859-1

ja (Japanese) Shift_JIS

ko (Korean) EUC-KR

zh (Chinese) MS936

ru (Russian) Windows-1251

pt (BrazilianPortuguese)

Windows-1252

To define information for an object type, the format is:TYPE=type_name<data dictionary property settings>

To define information for a property, the format is:TYPE=type_nameproperty=property_name<data dictionary property settings>

If you want to define information for multiple properties of one object type, specify thetype only once and then list the properties and the settings:TYPE=type_nameproperty=property_name<data dictionary property settings>{property=property_name<data dictionary property settings>}

The setting for one data dictionary property settings must fit on one line.

The next section, Summary of settable data dictionary properties, page 597, lists the datadictionary properties that you can set in data files. Examples of data file entries, page602, shows some examples of how these are used in a data file.



Summary of settable data dictionary properties

Data dictionary information is stored in the repository in internal object types. Whenyou set data dictionary information, you are setting the properties of these types. Someof the information applies only to object types, some applies only to properties, andsome can apply to either or both.

Table 94, page 597, lists and briefly describes the data dictionary properties that youcan set using a population script.

Table 94. Settable data dictionary properties using population script

property name Reference in script as: Which level NLS-specific?Yes or no

Comments

ignore_immutable

IGNORE_IMMUTABLE

property No None

allowed_search_opsdefault_search_opsdefault_search_arg

ALLOWED_SEARCH_OPSDEFAULT_SEARCH_OPDEFAULT_SEARCH_ARG

property No If allowed_search_ops isset, you must setdefault_search_ops.

Default_search_arg,if set, must be set toone of the allowed_search_ops.

read_only READ_ONLY property No None

is_hidden IS_HIDDEN property No None

is_required IS_REQUIRED property No None

not_nullnot_null_msgnot_null_enf

NOT_NULLREPORT=stringENFORCE=string

property Yes Setting not_null setsthe not_null datadictionary propertyto TRUE.

Including REPORT(not_null_msg)or ENFORCE(not_null_enf) isoptional. If youinclude both,REPORT mustappear first.

Valid values forENFORCE are




Comments

application anddisable.

map_data_stringmap_display_stringmap_description

MAPPING_TABLEVALUE=integerDISPLAY=stringCOMMENT=string

property Yes The key phraseMAPPING_TABLEmust appear beforethe keywords thatset the values for themapping table.

COMMENT isoptional.

VALUE andDISPLAY must beset. Set each oncefor each value thatyou want to map.(Refer to Examplesof data file entries,page 602 for anexample.)

life_cycle LIFE_CYCLE= integer Object type No Valid values are:

ValueMeaning1Currently in use2For future use3Obsolete

label_text LABEL_TEXT Object typeproperty

Yes None

help_text HELP_TEXT Object typeproperty

Yes None

comment_text COMMENT_TEXT Object typeproperty

Yes None

is_searchable IS_SEARCHABLE Object typeproperty

No None




Comments

primary_keyprimary_key_msgprimary_key_enf

If defined at type level:

PRIMARY_KEY=keyREPORT=stringENFORCE=string

If defined at propertylevel:

PRIMARY_KEYREPORT=stringENFORCE=string

Object typeproperty

Yes If the primary keyconsists of oneproperty, you candefine the key ateither the propertyor type level. Atthe type level, youmust name theproperty in key.If you define thekey at the propertylevel, naming theproperty is notnecessary.

If the primary keyconsists of multipleproperties, youmust specify thekey at the typelevel. Provide acomma-separatedlist of the propertiesin key.

Including REPORT(primary_key_msg)or ENFORCE(primary_key_enf)is optional. Ifyou include both,REPORT mustappear first.

Valid values forENFORCE areapplication anddisable.




Comments

unique_keyunique_key_msgunique_key_enf

If defined at type level:

UNIQUE_KEY=keyREPORT=stringENFORCE=string

If defined at propertylevel:

UNIQUE_KEYREPORT=stringENFORCE=string

Object typeproperty

Yes If the unique keyconsists of oneproperty, you candefine the key ateither the propertyor type level. Atthe type level, youmust name theproperty in key.If you define thekey at the propertylevel, naming theproperty is notnecessary.

If the unique keyconsists of multipleproperties, youmust specify thekey at the typelevel. Provide acomma-separatedlist of the propertiesin key.

Including REPORT(unique_key_msg)or ENFORCE(unique_key_enf)is optional. Ifyou include both,REPORT mustappear first.

Valid values forENFORCE areapplication anddisable.




Comments

foreign_keyforeign_key_msgforeign_key_enf

At the type level:

FOREIGN_KEY=keyREFERENCES=type(attr)REPORT=stringENFORCE=string

At the property level:

FOREIGN_KEY=type(attr)REPORT=stringENFORCE=string

Object typeproperty

Yes Refer to Settingforeign keys, page601 following thistable for details ofdefining this key.

Setting foreign keys

Like other keys, you can set a foreign key at either the type level or the property level.

If you set the key at the type level, you must identify which property of the typeparticipates in the foreign key and which property in another type is referenced by theforeign key. The key phrase FOREIGN_KEY defines the property in the object typethat participates in the foreign key. The keyword REFERENCES defines the propertywhich is referenced by the foreign key. For example, suppose a data file contains thefollowing lines:TYPE=personnel_action_docFOREIGN_KEY=user_nameREFERENCES=dm_user(user_name)

These lines define a foreign key for the personnel_action_doc subtype. The key says thata value in personnel_action_doc.user_name must match a value in dm_user.user_name.

To define the same foreign key at the property level, the data file would include thefollowing lines:TYPE=personnel_action_docproperty=user_nameFOREIGN_KEY=dm_user(user_name)

REPORT and ENFORCE are optional. If you include both, REPORT must appear beforeENFORCE. Valid values for ENFORCE are:• application



• disable

Examples of data le entries

Here is an excerpt from a data file that sets non-NLS data dictionary information:#set property level information for user_name propertyTYPE=dm_userproperty=user_nameIS_REQUIREDDEFAULT_SEARCH_OP=contains

#set property level information for dm_documentTYPE=dm_documentproperty=acl_domainIGNORE_IMMUTABLEproperty=acl_nameIGNORE_IMMUTABLEproperty=titleIS_REQUIREDDEFAULT_SEARCH_OP=containsproperty=subjectDEFAULT_SEARCH_OP=containsproperty=authorsIS_REQUIRED

This excerpt is from a data file that defines data dictionary information for the Englishlocale.#This sets the locale to English.LOCALE = enCODEPAGE = ISO_8859-1

# Set property Information for dm_userTYPE = dm_userproperty = alias_set_idLABEL_TEXT = User Alias Set ID

# Set property Information for dm_groupTYPE = dm_groupproperty = alias_set_idLABEL_TEXT = Group Alias Set ID

# Set property Information for dm_processTYPE = dm_processproperty = perf_alias_set_idLABEL_TEXT = Performer Alias Set ID

# Set property Information for dm_workflowTYPE = dm_workflowproperty = r_alias_set_idLABEL_TEXT = Performer Alias Set ID

# Set property Information for dm_activityTYPE = dm_activityproperty = resolve_type



LABEL_TEXT = Alias Resolution TypeMAPPING_TABLEVALUE = 0DISPLAY = DefaultCOMMENT = Default ResolutionVALUE = 1DISPLAY = Package-basedCOMMENT = Resolution based on packagesVALUE = 2DISPLAY = Previous Performer-basedCOMMENT = Resolution based on last performer onlyproperty = resolve_pkg_nameLABEL_TEXT = Alias Resolution Package

# Set property Information for dm_sysobjectTYPE = dm_sysobjectproperty = a_effective_labelLABEL_TEXT = Effective Labelproperty = a_effective_dateLABEL_TEXT = Effective Dateproperty = a_expiration_dateLABEL_TEXT = Expiration Dateproperty = a_effective_flagLABEL_TEXT = Effective Flagproperty = a_publish_formatsLABEL_TEXT = Publish Formatsproperty = a_categoryLABEL_TEXT = Categoryproperty = language_codeLABEL_TEXT = Language Codeproperty = authorsFOREIGN_KEY = dm_user(user_name)REPORT = The author is not found in the repository.ENFORCE = application

# Set property information for dmr_containmentTYPE = dmr_containmentproperty = a_contain_typeLABEL_TEXT = Containment Typeproperty = a_contain_descLABEL_TEXT = Containment Description

# Set property Information for dm_assemblyTYPE = dm_assemblyproperty = path_nameLABEL_TEXT = Path Name

# Set property Information for dm_relationTYPE = dm_relationproperty = r_object_idLABEL_TEXT = Object IDproperty = relation_nameLABEL_TEXT = Relation Nameproperty = parent_idLABEL_TEXT = Parent IDproperty = child_idLABEL_TEXT = Child IDproperty = child_labelLABEL_TEXT = Child Label



property = permanent_linkLABEL_TEXT = Permanent Linkproperty = order_noLABEL_TEXT = Order Numberproperty = effective_dateLABEL_TEXT = Effective Dateproperty = expiration_dateLABEL_TEXT = Expiration Dateproperty = descriptionLABEL_TEXT = Description

This final example sets some constraints and search operators for the object types andtheir properties.TYPE = TypeCPRIMARY_KEY = Attr2, Attr3REPORT = The primary key constraint was not met.ENFORCE = application

UNIQUE_KEY = Attr2, Attr3REPORT = The unique key constraint was not met.ENFORCE = application

FOREIGN_KEY = Attr1REFERENCES = TypeA(Attr1)REPORT = TypeC:Attr1 has a key relationship with TypeA:Attr1ENFORCE = disable

IS_SEARCHABLE = TrueTYPE = TypeCproperty = Attr1ALLOWED_SEARCH_OPS = =,<,>,<=,>=,<>, NOT, CONTAINS, DOES NOT CONTAINDEFAULT_SEARCH_OP = CONTAINSDEFAULT_SEARCH_ARG = 3TYPE = TypeDLIFE_CYCLE = 3PRIMARY_KEY = Attr1REPORT = Attr1 is a primary key.ENFORCE = disableLABEL_TEXT = label t TypeDHELP_TEXT = help TypeDCOMMENT_TEXT = com TypeDIS_SEARCHABLE = TrueUNIQUE_KEY = Attr1REPORT = Attr1 is a unique key.ENFORCE = applicationFOREIGN_KEY = Attr1REFERENCES = TypeC(Attr1)REPORT = Attr1 has a foreign key relationship.TYPE = TypeEproperty = Attr1IGNORE_IMMUTABLE = TrueNOT_NULLENFORCE = applicationALLOWED_SEARCH_OPS = CONTAINS, DOES NOT CONTAINDEFAULT_SEARCH_OP = CONTAINSDEFAULT_SEARCH_ARG = 22READ_ONLY = TrueIS_REQUIRED = TrueIS_HIDDEN = TrueLABEL_TEXT = property 1



HELP_TEXT = This property identifies the age of the user.COMMENT_TEXT = You must provide a value for this property.IS_SEARCHABLE = FalseUNIQUE_KEYFOREIGN_KEY = TypeB(Attr1)REPORT = This has a foreign key relationship with TypeB:Attr1ENFORCE = applicationFOREIGN_KEY = TypeC(Attr2)REPORT = This has a foreign key relationship with TypeC:Attr2ENFORCE = application

Executing the script

The population script is named dd_populate.ebs and is found in%\DOCUMENTUM%\product\version\bin ($DOCUMENTUM/product/version/bin).

To execute the script:1. Change to the %\DOCUMENTUM%\product\version\bin ($DOCUMENTUM/

product/version/bin) directory.

2. Enter the following command line at the operating system prompt:dmbasic -f dd_populate.ebs -e Entry_Point -- <repository_name><username> <password> <ini_filename>

repository_name is the name of the repository.username is the name of the user executing the script. The user must have Sysadminor Superuser privileges.password is the user’s password.ini_filename is the name of the initialization file that contains the data files. This canbe a full path specification or only the file name. If you include just the file name, thefile must be in the same directory as the population script.

Populating a Japanese locale on a Korean host or aKorean locale on a Japanese host

To populate the Japanese data dictionary locale on a Korean host or the Korean datadictionary locale on a Japanese host, connect to Content Server from a Windowscomputer in the desired locale and run the data dictionary population script fromthat computer. For example, to install the Japanese data dictionary information ina repository on a Korean host, connect to the repository from a Japanese Windowscomputer and run the script from the Japanese computer.



Default les provided by EMC Documentum

EMC Documentum provides the following data dictionary files with Content Server:• dd_populate.ebs

dd_populate.ebs is the script that reads the initialization file.• data_dictionary.ini

data_dictionary.ini is the default initialization file.• data files

The data files contain the default data dictionary information for Documentum objecttypes and properties. They are located in %DM_HOME%\bin ($DM_HOME/bin).There is a file for each supported locale. The files are named with the followingformat:data_dictionary_localename.txt

where localename is the name of the locale. For example, the data file for the Germanlocale is named data_dictionary_de.txt.

Using DQL statements

Use the DQL CREATE TYPE and ALTER TYPE statements to set data dictionaryinformation if:• You cannot add the information using a population file• The information applies only when an object is in a particular lifecycle state• You want to add or change information for a single object type or propertyThe DQL statements allow you to publish the new or changed information immediately,as part of the statement’s operations. If you choose not to publish immediately, thechange is published the next time the Data Dictionary Publisher job executes. You canalso use the publish_dd method to publish the information. (For information aboutpublishing, refer to Publishing the data dictionary information, page 606.)

For details about using these statements, refer to the Content Server DQL Reference Manual.

Publishing the data dictionary informationInformation in the data dictionary is stored in internal object types and must bepublished before applications or users can access it. Publishing creates the dd commoninfo, dd type info, and dd attr info objects that applications and users can query. After



you add or change information in the data dictionary, the information must be publishedbefore the changes are accessible to users or applications.

Publishing can occur automatically, through the operations of the Data DictionaryPublisher job, or on request, using the publishDataDictionary method or the PUBLISHkeyword.

The data dictionary publisher job

The Data Dictionary Publisher job publishes changes to the data dictionary. Each timethe job runs, it publishes:• Changes to previously published data dictionary information• Previously unpublished data dictionary information, such as information added to a

previously published locale or information for a new localeThe job uses the value of the resync_needed property of dd common info objects todetermine which data dictionary objects need to be republished. If the property is set toTRUE, the job automatically publishes the data dictionary information for the object typeor property represented by the dd common info object.

To determine what to publish for the first time, the job queries three views:• dm_resync_dd_attr_info, which contains information for all properties that are not

published• dm_resync_dd_type_info, which contains information for all object types that are

not published• dm_dd_policies_for_type, which contains information for all object types that have

lifecycle overrides definedThe Data Dictionary Publisher job is installed with the Documentum tool suite.

The publishDataDictionary method

The publishDataDictionary method publishes the data dictionary information. Youcan use the method to publish the entire data dictionary or just the information for aparticular object type or a particular property. For information about using this method,refer to the Javadocs.



The PUBLISH key phrase

PUBLISH is a key phrase in the DQL CREATE TYPE and ALTER TYPE statements.If you include PUBLISH when you execute either statement, the server immediatelypublishes the new or changed information and any other pending changes for theparticular object type or property.

For example, if you include PUBLISH when you create a new object type, the serverimmediately publishes the data dictionary for the new object type. If you includePUBLISH in an ALTER TYPE statement, the server immediately publishes theinformation for the altered object type or property and any other pending changes forthat type or property.

If you do not include PUBLISH, the information is published the next time one of thefollowing occurs:• The Publish_dd method is run to update the entire dictionary or just that object

type or property• The Data Dictionary Publisher job runs.• An API method is executed to obtain data dictionary information about the changed

object type or property.


Appendix F

System Events

This appendix lists and describes the system events recognized by Content Server. You can registermost of these events for auditing. You can also use an IDfSysobject.registerEvent method to register toreceive an Inbox notification for any of the DFC, workflow, or lifecycle events.

Those events which cannot be registered for auditing or notification are noted in their descriptions.

This appendix has the following topics:• dm_default_set event, page 609• DFC events, page 610• Workflow events, page 615• Lifecycle events, page 618• Events sent to the fulltext user, page 619

dm_default_set eventThis event name represents a set of events that are audited by default. Table 95, page 609,lists the events in that default set.

Table 95. Events represented by the dm_default_set event


docbase config

Note: Thedm_default_setevent is registeredagainst the docbaseconfig object;however, it causesauditing of the

dm_archive dm_checkin dm_restore

dm_assemble dm_checkout dm_save

dm_bp_attach dm_destroy dm_setfile

dm_bp_demote dm_freeze dm_signoff

dm_bp_promote dm_link dm_unfreeze


System Events


listed events fordm_documentobject type and itssubtypes.

dm_bp_resume dm_lock dm_unlink

dm_bp_suspend dm_mark dm_unlock

dm_branch dm_prune

DFC eventsTable 96, page 610, lists the events arising from DFC methods. (Events arising frommethods that are specific to workflows are listed separately in Table 97, page 615.)

Table 96. Events arising from DFC methods

Event Target object type Event description Trigger

dm_all (or all) 0 or omitted

dm_sysobject

All All auditable events in repository

Any event on any Sysobject or thespecified Sysobject

dm_add_dynamic_group

dm_group Add To DynamicGroup

Execution of an IDfSession.addDynamicGroups call

dm_adddigsigna-ture

dm_sysobject Add DigitalSignature

Execution of the addDigitalSigna-ture method.

addDigitalSignature methods arealways audited. It is not possibleto unregister this event.

dm_addesignature dm_sysobject Add ElectronicSignature

Execution of the addEsignaturemethod.

addEsignature methods are alwaysaudited and the entries are alwayssigned by Content Server.It is notpossible to modify this behavior.

dm_addesigna-ture_failed

dm_sysobject Add ElectronicSignature Failed

An attempt to execute theaddEsignature method failed.These failures are always audited.It is not possible to modify thisbehavior.


System Events


dm_addnote dm_sysobjectdm_process

Add Note Addition of a note to a SysObject.

When the target object is a processobject, the SysObject is in aworkflow package.

dm_addrendition dm_sysobject Add Rendition Addition of a rendition to an object.

dm_addretention dm_sysobject Add Retention Object placed under control of aretention policy

dm_appendpart dm_sysobject Apend to VirtualDocument

Addition of a component to avirtual document

dm_archive dm_sysobject Archive Objects Execution of an archive method

dm_assemble dm_sysobject Assemble VirtualDocument

Execution of assemble method

dm_assume dm_user Assume User Execution of Assume method

dm_audit all object types Audit Event Execution of method to register forauditing

Registrations for auditing arealways audited. It is not possibleto unregister this event.

dm_authenticate dm_user Authenticate User Execution of an authenticatemethod

Executing an authenticate methodalso generates a dm_connectmethod if the authenticationrequires a repository connection.

dm_branch dm_sysobjectdm_retainer

Branch Version Execution of a branch method

dm_checkin dm_sysobjectdm_retainer

Checkin Object Checking in an object

dm_checkout dm_sysobjectdm_retainer

Checkout Object Checking out an object


System Events


dm_connect dm_user Logon Establishing a repositoryconnection

Note: An authenticate methodmay also establish a repositoryconnection, which will generate adm_connect event in addition tothe dm_authenticate event.

dm_destroy dm_sysobjectdm_acldm_userdm_groupdm_retainer

Destroy Object Execution of a destroy method

dm_disassemble dm_sysobject DisassembleVirtual Document

Execution of a disassemble method

dm_disconnect dm_user Logoff Terminating a repositoryconnection

dm_fetch dm_sysobjectdm_retainer

Fetch Object Fetching an object from therepository

dm_freeze dm_sysobject Freeze Object Execution of a freeze method

dm_getfile dm_sysobject View/Export Occurs when a document isviewed or exported or when the agetContent and getPath method isexecuted.

dm_getlogin dm_user Get Login Execution of a getLoginTicketmethod

dm_insertpart dm_sysobject Insert into VirtualDocument

Execution of an insertPart method

dm_install dm_policydm_processdm_activity

Install Execution of an install method

dm_invalidate dm_processdm_activity

Invalidate Execution of an invalidate method

dm_kill not applicable Kill Session Execution of a Kill method

Note: You cannot audit a Killmethod that flushes the cache.

dm_link dm_sysobject Link To Execution of a link method

dm_lock dm_sysobject Lock Object Execution of a lock method


System Events


dm_logon_failure dm_user Logon Failure User attempts to start a repositoryconnection using invalidcredentials.

dm_mark dm_sysobject Add Version Label Execution of a mark method

dm_move_content dmr_content Move Content Execution of a MIGRATE_CONTENT administration method

dm_prune dm_sysobjectdm_retainer

Prune Versions Execution of a prune method

dm_purgeaudit dm_audittraildm_audittrail_acldm_audittrail_group

Purge Audit Execution of a destroy method orPURGE_AUDIT administrationmethod to remove audit trailentries

Purging an audittrail entry isalways audited. It is not possible tostop auditing this event.

dm_readonlysave dm_sysobject no eventdescriptionprovided

Generated when Content Serverchanges a property value of animmutable object.

This event is generatedautomatically for the fulltextuser.

dm_remove_dynamic_group

dm_group Remove FromDynamic Group

Execution of an IDfSession.removeDynamicGroups call

dm_removecon-tent

dm_sysobject Remove Content Execution of a removeContentmethod

dm_removenote dm_sysobjectdm_process

Remove Note Execution of a removeNote method

dm_removepart dm_sysobject Remove fromVirtual Document

Execution of a removePart method

dm_removerendi-tion

dm_sysobject Remove Rendition Execution of one of theremoveRendition methods

dm_removereten-tion

dm_sysobject Remove Retention Object removed from control of aretention policy

dm_restore dm_sysobject Restore Object Execution of a restore method


System Events


dm_save dm_sysobjectdm_acldm_groupdm_userdm_retainer

Save Object Execution of a save method.

Note: For new objects, ContentServer stores the value ’Create’ inthe audit trail attribute string_1.For existing objects, the value inthe attribute is ’Save’.

dm_saveasnew dm_sysobjectdm_acldm_retainer

Copy Object Execution of a saveAsNew method

dm_setfile dm_sysobject Set Content Execution of the followingmethods:

appendContent appendFilebindFile iInsertFile insertContentsetContent setPath

dm_setoutput dm_process Setoutput Execution of a Setoutput method.

dm_setretention-status

dm_retainer Set RetentionStatus

Change to status of a retainerobject.

dm_signoff dm_sysobject Signoff Execution of a signoff method

signoff methods are alwaysaudited. It is not possible to stopthis auditing.

dm_unaudit all object types Unaudit Event Removing an auditing registration.

Methods that remove (unregister)an audit registration are alwaysaudited. It is not possible to stopthis auditing.

dm_unfreeze dm_sysobject Unfreeze Object Execution of an unfreeze method

dm_uninstall dm_policydm_processdm_activity

Uninstall Execution of an uninstall method

dm_unlink dm_sysobject Unlink From Execution of an unLink method

dm_unlock dm_sysobject Cancel Checkout Execution of a cancelCheckOutmethod

dm_unmark dm_sysobject Remove VersionLabel

Execution of an unMark method


System Events


dm_updatepart dm_sysobject Update in VirtualDocument

Execution of an updatePart method

dm_validate dm_policydm_processdm_activity

Validate Execution of a validate method

Workow eventsTable 97, page 615, lists the events specific to workflows. Note that several API eventslisted in the previous table are also applicable to workflows.

Table 97. Workow events


dm_all_workflow dm_process (or notincluded)

All Workflow Events All events onworkflows generatedfrom the specifiedprocess object or allevents in the repository

Note: This does notinclude dm_validate,dm_install,dm_invalidate, anddm_uninstall events.

dm_abortworkflow dm_process Abort Workflow Aborting a workflow

dm_addattachment dm_process Add Attachment An attachment isadded to a runningworkflow or workitem.

dm_addpackage dm_process Add WorkflowPackage

Execution of anaddPackage method

dm_autotransactivity dm_process Automatic WorkflowActivity Transition

An automatic activitytransition occurs


System Events


dm_changedactivityinstancestate

dm_process Change WorkflowActivity to Failed State

An automatic activitychanges state becausethe error handling flagis set to zero and thework item returns anon-zero value.

dm_changepriority-workitem

dm_process Change WorkitemPriority

The priority value of awork item is changedat runtime.

dm_changestateactiv-ity

dm_process Change WorkflowActivity State

An activity instancechanges state to a stateother than failed orchanges state due to anautomatic transition.

dm_changestatepro-cess

dm_process Change WorkflowTemplate State

A process definitionchanges state

dm_changestatework-flow

dm_process Change WorkflowState

A workflow changesstate by amethod otherthan a save, execute, orabort.

dm_changeworkflowsupervisor

dm_process Change WorkflowSupervisor

Execution of aSetsupervisor method

dm_completed-workitem

dm_process Complete Workitem Execution of aComplete method

dm_createworkflow dm_process Create Workflow A workflow is created.

dm_delegated-workitem

dm_process Delegate Workitem A work item isdelegated.

dm_finishworkflow dm_process Finish Workflow A workflow isterminated.

dm_pauseworkitem dm_process Pause Workitem A work item is paused.


System Events


dm_portselect dm_process Select Workflow Port Selection of outputports by a user orContent Server uponcompletion of anactivity.

Note: This event is nottriggered if the activityhas a transition type ofprescribed.

dm_pseudocomplet-edworkitem

dm_process Pseudo_CompleteWorkitem

A work item is markedas pseudo-completedby Content Server

dm_removeattach-ment

dm_process Remove Attachment An attachment isremoved from aworkflow or workitem

dm_removepackage dm_process Remove WorkflowPackage

A package is removedfrom a workflow

dm_repeatworkitem dm_process Repeat WorkflowWork Item

A work item isrepeated.

dm_resumeworkitem dm_process Resume Workitem A work item isresumed.

dm_save_workqueue Not applicable Not applicable Generated when aworkqueue objectis saved by theWorkqueue SBO.

It is not possible toregister for this event.

dm_save_workqueuepolicy

Not applicable Not applicable Generated when aworkqueue policyobject is saved by theWorkqueue SBO.

It is not possible toregister for this event.

dm_selectedworkitem dm_process Select Workitem A work item isacquired.

dm_startworkflow dm_process Start Workflow A workflow is started.


System Events


dm_startedworkitem dm_process Start Workitem A work item isgenerated.

dm_suspended-workqueuetask

dm_process Suspend WorkqueueTasks

A task on a workqueueis suspended.

dm_unsuspended-workqueuetask

dm_process UnsuspendWorkqueue Tasks

A task on a workqueueis unsuspended.

dm_wf_autodelegate_failure

dm_process Auto Delegation Failed Automatic delegationof an activity failed.

Lifecycle eventsTable 98, page 618 lists the events specific to lifecyles.

Table 98. LIfecycle events


dm_bp_attach dm_sysobjectdm_retainer

Attach Lifecycle Attaching a lifecycle toan object

dm_bp_demote dm_sysobjectdm_retainer

Demote from LifecycleState

Demoting an objectfrom a lifecycle state

dm_bp_promote dm_sysobjectdm_retainer

Promote to LifecycleState

Promoting an object toa lifecycle state

dm_bp_resume dm_syobjectdm_retainer

Resume Lifecycle Resuming an object’ssuspended lifecycle

dm_bp_suspend dm_sysobjectdm_retainer

Suspend Lifecycle Suspending an object’slifecycle


System Events

Events sent to the fulltext userThe following events are generated automatically for the dm_fulltext_user user:• dm_checkin• dm_destroy• dm_move_content• dm_readonlysave• dm_save


System Events


Appendix G

Plug-in Library Functions for ExternalStores

This appendix describes the C functions that you must implement to support Content Serveroperations through the plug-in. The following functions are described:• General recommendations , page 621• dm_close_all, page 622• dm_close_content, page 622• dm_deinit_content, page 622• dm_init_content, page 623• dm_open_content, page 623• dm_plugin_version, page 625• dm_read_content, page 625

General recommendationsCall dm_init_content once when the plug-in is loaded. Call dm_plugin_version onceafter the plug-in is loaded.

Use dm_open_content once for each getFile or getContent operation. Usedm_read_content multiple times to read the content in 16k blocks.

Use dm_close_content once for each dm_open_content call.

Use dm_close_all once in a session, and call dm_deinit_content once before the plug-in isunloaded.

You can find sample code for a plug-in the unsupported directory.


Plug-in Library Functions for External Stores

dm_close_allThe dm_close_all function is called by the plug-in when a session is terminated. Thefunction is called to let the plug-in library cleanup any internal data structure(s) forthe specified session.

The function definition is:void dm_close_all (long session)

Table 99, page 622, lists its arguments.

Table 99. dm_close_all arguments


session Identifies the terminated session.

dm_close_contentThe dm_close_content function is called by the plug-in to perform internal cleanup. Thisfunction is called after the read operation for the supplied handle is completed or or ifthe read operation is interrupted. The function returns a boolean value.

The function definition is:BOOL dm_close_content (long handle)

Table 100, page 622, describes the argument for the function.

Table 100. dm_close_content arguments


handle Identifies the read request.

dm_deinit_contentThe dm_deinit_content function performs global internal cleanup operations. Thefunction is called just before the server or client unloads the plug-in library, to let theplug-in perform any global internal cleanup operations.

The function definition is:void dm_deinit_content(void)



dm_init_contentThe dm_init_content function initializes internal data structures. This is the first functioncalled by Content Server after the plug-in library is loaded.

The function definition is:BOOL dm_init_content (long maxsession,int mode)

Table 101, page 623, describes the arguments to this function.

Table 101. dm_init_content arguments


maxsession Contains the maximum number of concurrent sessions.

mode Indicates who is invoking the plug-in. The only valid value is0, indicating the server.

The function returns a positive value for successful initialization. A negative return valueforces the server to unload the plug-in library. This function should return a positivevalue when called multiple times within the same address space.

dm_open_contentThe dm_open_content function retrieves content.

The function definition is:BOOL dm_open_content ( long session, char *other_args,char *token, char *store_object_id, void *callback,long *handle, long errcode)

Table 102, page 623, describes the arguments for the function.

Table 102. dm_open_content arguments


session Indicates the session that needs to retrieve the content.

other_args Indicates the other_args supplied when executing a Mountmethod. NULL for the dm_extern_url, dm_extern_free storagetypes and when the ’token’ specified in a Setpath operation isan absolute path.

token Is the path-translated token for which to retrieve the content.




store_object_id Indicates the external storage object ID.

callback Is a function pointer that can be called by the plug-in libraryto retrieve an attribute value for the supplied external storageobject ID.

handle Identifies the read request. Filled in on initiaization andpassed for subsequent read operations.

errcode Contains error code in case of failure.

The plug-in DLL or shared library returns a positive value for successful initializationand fills in a value for the handle. For subsequent read operations for this token, thehandle value is passed. In case of failure, the plug-in fills in an error code in errcode.

This function is called when the server or client needs to retrieve the content for the token.

The handle enables the plug-in to be a multi-threaded application with each threadservicing a particular read request, with a dispatching mechanism based on the handlevalue. For example, for dm_extern_file store objects, other_args is the root path.

For client side plug-in configurations, if the Mount method has not been issued,the other_args parameter is a pointer to the directory location represented by thedef_client_root attribute.

For server side plug-in configurations, other_args points to the directory represented bythe a_location value for the current sever configuration. If no a_location is configuredfor the current server configuration, it points to the directory represented by thedef_server_root attribute.

The call back function (which is part of server and client) is of the form:char *dmPluginCallback (long session, char *store_object_id, char *attr_name, int position)

The call back function returns an attribute value in string form. The value for the positionparameter should be zero when requesting an attribute value for an single-valuedattribute and should be zero or greater for multi-valued attributes.

When this callback function is called for DM_TIME datatype attribute values, thereturned string format is mm/dd/yyyy hh:mi:ss.

Plug-in libraries can define the function pointer type as follows:typedef char * (*DCTMPLUGINCALLBACK)(long, char *,char *,int)

Cast the callback parameter to DCTMPLUGINCALLBACK before calling by reference.

Advanced plug-ins may start performing the actual read asynchronously and startcaching the content for performance reasons.



dm_plugin_versionThe dm_plugin_version function enables backward compatibility for enhancement infuture releases. This function is called once immediately after the plug-in is loaded intothe process address space. The plug-in protocol version is 1.0. Therefore, the plug-inmust set ’major’ to 1 and ’minor’ to 0.

The definition of this function is:void dm_plugin_version(unsigned int *major, unsigned int *minor)

Table 103, page 625, describes the arguments to the function.

Table 103. dm_plugin_verson arguments


major Set to 1.

minor Set to 0.

dm_read_contentThe dm_read_content function requires the plug-in to return the content data into thelocation pointed to by buffer supplied.

The definition of this function is:long dm_read_content ( long handle, char *buffer,long buffer_size, long *more_data, long *errcode)

Table 104, page 625, describes the arguments to this function.

Table 104. dm_read_content arguments


handle Identifies the read request.

buffer Contains the location to return the content data; filled withzeros when there is no more content to be read or end-of-fileis reached.

buffer_size Contains the buffer size (16k).

more_data When positive, indicates more reading is required.

errcode Contains error code in case of failure.

The function returns the number of bytes read and filled into buffer.



The plug-in must maintain its own internal bookkeeping to start reading from the nextbyte after the previous read.


Index

Aa_archive property, 280a_content_attr_name

dm_storage_strategy setting, 253a_content_static property, 245a_current_status property, 144a_default_retention_date property, 247,

257a_last_return_code property, 144a_next_invocation property, 151a_retention_attr_name property, 248, 257a_retention_attr_required property, 247,

257a_silent_login property, 351a_storage_params property, 224a_storage_type property, 230

dm_turbo_store value, 224accepting server broadcasts, 193access control entries

described, 369access control lists, see ACLsaccess permission ACL entries, 370access restriction ACL entries, 370acl_class property, 379acl_domain property, 381acl_name property, 381acl_update_threshold (server.ini key), 98ACLs

ACL object overview, 369acl_domain property, 381acl_name property, 381acl_update_threshold (server.ini

key), 98adding entries, 384aliases in, 379audit trail entries, interpreting, 413caching, 100

changingobject name, 379owners, 379type default, 74

consistency checks, 553constraint on aliases, 380creating, 380

default, 383default, assigning, 383default, defining, 381deleting

external, 385from repository, 385internal, 76, 385

described, 360entries, described, 369entry evaluation, 374evaluation for object owners, 375external, 378folder default, 382internal, 378macl_security_disabled property, 377modifying, 384multiple entries for one user, 376naming conventions, 379object name, 381object types, assigning to, 382orphaned, 76owner of, 381owner_xpermit_default (server.ini

key), 101private, 379public, defined, 379removing entries, 384removing orphans, 482specifying server-level default, 383system, defined, 379TCS license and evaluation, 374templates, 379Trusted Content Services license

and, 380, 384


Index

type default, 382user default, 382using dmclean to delete, 385

ACS servers, 86activating

administration jobs, 453jobs after loading, 60

Active Directorymode requirements, 342user_namemapping requirement, 336

addDigitalSignature methodauditing, 391

addDynamicGroup method, 311addESignature method

tracing, 427Addesignature method

auditing, 391parameters passed by, 425

admingroup group, 302, 310Administration Encryption Key, see AEK

(Administration Encryption Key)administration methods

MIGRATE_CONTENT, 259PURGE_AUDIT, 416RECOVER_AUTO_TASKS, 125

administration, serverContent Server Manager, 32Documentum Administrator, 32DQL, 32DQL statements, 33privileges required, 31tool suite, 33tools, 446

AEK (Administration Encryption Key)audit trail entries and, 394backing up, 431described, 430determining existence, 433passphrase, changing, 434putting in shared memory, 432sharing among products, 430single-repository distributed

configurations, 431agent exec process, 148

behavior modification, 154database_refresh_interval (server.ini

key) and, 154described, 85, 449disabling all jobs, 153

jobs in polling cycle, settingmaximum, 154

log file location, 155max_concurrent_jobs, 154override_sleep_duration, 154polling interval, default, 86, 154removing log files, 499tracing, turning on, 155

agent_exec_method method, 85agent_launcher property, 85, 153alias sets

creating, 72deleting, 72described, 71modifying, 72

aliasesACL template use, 379dm_dbo, 73mounted directories, 66repository owner, 73use constraint in ACLs, 380

_all_users_names (computedproperty), 311

allow_trusted_login (dfc.propertieskey), 166

ALTER TYPE statement for modifyingtypes, 74

annotationsdmclean argument for, 483removing orphans, 482

annotations, removing orphans, 76API (Application Program Interface)

IAPI utility, 568append_to_body property, 424application access control tokens

dfc.machine.id key (dfc.propertiesfile), 439

enabling use, 439retrieval from storage, enabling, 440strorage location, 443token files, 441troubleshooting, 444

application codes, 364application events, 388, 393

audit trails, viewing, 396application permission ACL entries, 371application restriction ACL entries, 372application server, see JBoss application

serverapplication_access_control property, 439


Index

applicationsapplication events, auditing, 393application permits in ACLs, 371application restrictions in ACLs, 372archive method, 278authentication plug-ins,

specifying, 347connection brokers and, 199enabling/disabling client caching, 178file extensions, 258firewalls and, 194is_private property, usage, 308Mount method, 243objects, controlling, 361plugin authentication, using, 347private and public groups, 307restore method, 278shutting down servers with, 119URLs, using, 234

approved_clients_only property, 169archive directory, 282archive tool

archive directory, choosing, 285described, 280generated dump record, 281generated load record, 282repository operator, 284verbose option, 281

Archive tool, 454archiving

archive directory, choosing, 285archive tool, 280content files, moving, 262content used in many documents, 283generated dump record, 281generated load record, 282overview, 277post_archive procedure, 283post_restore procedure, 283pre_restore procedure, 283re-archiving restored documents, 286repository operator, 284setting up, 285strategies, 283

arguments passed to methods, 151ascii property, 236ascii property for blob store type, 217aspects

dump operations and, 51asset_class property, 70

assume user program, 315assume_user_location property, 315attachments

package control and, 80Audit Management tool, 456

privileges to run, 416Audit method, 394

auditing execution of, 391audit trail

defined, 388audit trail entries

lifecycle, 404querying/retrieving, 397removal, auditing of, 391removing, 456signatures, verifying, 415signing, 394

audit trailscommon use properties, 397generic properties, 397interpreting, 397removing, 416viewing, 396

audit trial entriesACLs, 413groups, 413workflow, 405

audit_old_values property, 388auditing, 387

addDigitalSignature method, 391Addesignature method, 391application events, 393Audit Management tool, 456Audit method auditing, 391audit trail, 388audit trail entries

querying/retrieving, 397audit trail entries, signing, 394audit trails

interpreting, 397removing, 416

audit trails, viewing, 396common use properties, 397compound documents, 417conflicting registrations,

resolving, 395default auditing, 391distributed configurations, 416dm_default_set event, 392dm_purgeaudit events, 391


Index

dmi_registry objects and, 393events, 387failed logins, 392IDfAuditTrailManager interface, 396privileges to stop, 396property values, 388signatures, verifying, 415Signoff method, 391system events, 393Unaudit method auditing, 391

audittrail attrs objectsremoving, 416

auth config objects, 322auth_protocol property, 318

unix_domain_used setting, 322authentication, 328

See also user authenticationauth_protocol property, 318authentication plug-ins, 314CA SiteMinder Policy Server, 315dm_check_password file, 316domain-required mode, 318domains, affect of, 317failed attempts, limiting, 356failure auditing, 392no-domain required mode, 318password checking program,

creating, 319plug-in modules

described, 346server domain, 108trusted logins, 351unified login, 351UNIX default mechanism, 316UNIX users in domains, 320user names, 108user, options, 313user_login_name property, 290Windows default mechanism, 317

authentication modulesplug-in idientifiers, 347

authenticatonin-line passwords, using, 351

auto_request_forward (dfc.propertieskey), 191

automatic activitiesexecution

configuring, 123disabling, 124

recovering work items on ContentServer failure, 125

automatic operationsauditing failed authentication, 392file clean up, 176file extensions, 258

Bbackslashes, in repository connection

file, 156base_url property, 238basic user privileges, 291bind_type property, 334binding modes for LDAP, 334blob storage areas

ascii property, 217, 236content location, identifying, 224described, 217maximum content size, 217naming rules, 236setting up, 236

bp_schedule_*.log files, 499bp_transition_*.log files, 499broadcasts, connection brokers

accepting, 193

CC-clip buffer size, for Centera stores, 214C-clip buffer, setting size, 252CA certificates, installing, 340CA SiteMinder

plug-in authentication module, 348CA SiteMinder Policy Server, 315ca store object type, 212cabinets

consistency checks, 555Create Cabinet user privilege, 292creating, 43default ACL, 383defined, 42editing, 43home, 43permissions to modify/delete, 44private, 43public, 43user default, 298

cache config objectsautomating validation, 182


Index

client check interval, setting, 181creating, 179server check interval, setting, 180

cache_element_queries property,setting, 179

cache_element_types property,setting, 179

cachesdatabase_referesh_interval server.ini

key, 104dump process, 55persistent client, 177

CD-ROM files, external storage and, 220certdb_location property, 335certificate authorities

obtaining, 340obtaining list of, 345

certificate databasecontents, listing, 345installing, 340location of, 335

certutil utility, 340change password program, 316change_location permission, 366change_owner permission, 366change_password_location property, 316change_permit permission, 367change_state permission, 367checkpoint interval

described, 114setting, 116

checkst_client_version property, 168cleaning up file storage areas, 266client caches

flushing, 181client caching

enabling/disabling, 178client capability setting, 299client configuration

connection pooling, 172local areas

disk space limit, 176file clean up, 176file naming conventions, 177purgeLocalFiles method, 177

search_order (dfc.properties key), 191short date formats, 175short date formats, defining, 175

client local areachanging location, 176

client local areasdisk space limit, setting, 176file clean up, 176file naming conventions, 177local_purge_on_diskfull

(dfc.properties key), 176purgeLocalFiles method, 177

client platformdefined, 162

client rights objectscreating, 168

client_check_interval property, 181client_pcaching_change property, 182client_pcaching_disabled property, 178client_session_timeout (server.ini

key), 103clients, 201

client_session_timeout (server.inikey), 103

connection brokers and, 190defined, 162finding connection brokers, 200getDocbrokerMap method, 200

cluster environmentsupd_last_chg_time_from_db

(server.ini key), 102code page requirements

user names, 290code pages

authentication modules, use in, 350default settings, 87dump and load requirements, 48

collectionsKill method and, 120

commas, in repository connection file, 156comments

IAPI format, 573IDQL format, 567

commit_read_operations (server.inikey), 99

common arearemoving files from, 122

compound documentsauditing, 417

computed properties_all_users_names, 311

concurrent_sessionslogin tickets and, 173

concurrent_sessions, setting value inserver.ini file, 103


Index

Config Audit privileges, 396Config Audit user privileges, 293configuration

changing server configuration, 109DocBrokers, 196objects, 29overview, 27, 29session config objects, 174

connect_retry_interval (dfc.properties), 167

connected users, viewing, 34connection broker

monitoring status, script for, 590connection broker locator object

described, 189connection brokers

adding additional, 196api config properties for, 201auto_request_forward (dfc.properties

key), 191clients and, 190communicating with, 114configuration options, 189, 191defining targets in server config, 115deleting server information, 201failover, 164, 191finding, 200firewalls and, 194Getcdocbrokermap method, 189getDocbaseMap method, 200getServermap method, 200information about, 200initialization file, 192invoking initialization file, 193load balancing, 164, 191log files, 79number of, 188overview, 187projection targets, 114removing log files, 499requesting information from, 199restricting server access, 193security, 192, 198server shutdown notification, 120servers and, 85, 189setting checkpoint interval for

servers, 116setting keep_entry interval for

servers, 116shutdown security, 193

specifying for sessions, 163specifying IP address for, 192starting, 195stopping, 197stopping multiple, 199translating IP addresses, 194

connection modeserver-side, setting, 110

connection poolingdmbasic method server, 130enabling, 172

connection requestsgethostbyaddr (server.ini key), 100

connection stringsDB2, 97MS SQL Server, 97Oracle, 96Sybase, 97

connection strings for EMC Centeraclusters, 249

connection strings, for EMC Centera storestorage areas, 248

connectionsconcurrent_sessions setting, 103

Consistency Checker tooldescribed, 459report sample, 460

consistency checking rulesoverriding, 183

consistency_checker.ebs, 460content assignment policies

administering, 229behavior on error, configuring, 227,

276creating, 225described, 225DFC cache for, 227, 277enabling/disabling, 276enforcement, 226logging use, 275repository representation, 227storage algorithm, 228

content compression, 206constraint on use in distributed

stores, 207dump files, for, 55

content directoriescreating, 65

content duplication checkingbehavior, 209


Index

constraint on use in distributedstores, 209

filestores, in, 209hash format, 210Macintosh constraint, 209supporting properties, 209

content filesaccessing in load operations, 55archiving content used in many

documents, 283archiving/restoring overview, 277auditing movement, 263automatic file extensions, 258clean up in local areas, 176clean up in repository, 76compression in EMC Centera storage

areas, 213compression in NetApp SnapLock

storage areas, 217compression in storage, 206content assignment policies, 225content migration policies, 260Content Warning tool, 468default storage algorithm, 229deleting from EMC Centera storage

area, 265digital shredding, 211dos_extension property and, 68dump files and, 54dumping encrypted, 54file extensions in storage, 237File Report tool, 493hash values, 210moving, 259naming convention in local areas, 177naming conventions in file stores, 233r_content_hash property, 210removing from EMC Centera

storage, 268removing from server common

area, 122removing orphan files, 266, 487retention of, 231storage algorithm

primary, 229renditions, 231

storage options, 204storing in turbo store, 257use_extensions property, 234, 258

content migration policies

configurable arguments, 261described, 260log file location, 262

Content Migration Thread option, 259content objects

consistency checks, 557defined, 223i_content_id property and, 266is_archived property, 280is_offline property, 280r_content_hash property, 210removing orphans, 266, 482set_file property, 280turbo storage and, 218

Content Replication toolarguments, 466described, 465report sample, 467

Content Serveragent exec process, 85, 449audit trails

interpreting, 397auditing

application events, 393privileges to stop, 396

auditing, default, 391changing configuration, 109code page, 87common area, removing file from, 88common area, removing files

from, 122communicating with connection

brokers, 189configuration, 84configuration requirements for

additional, 112connecting to by host name, 165connecting to by name, 165connecting to specific server on

specific host, 165connection brokers and, 85connection strings

DB2, 97MS SQL Server, 97Oracle, 96Sybase, 97

data dictionarypopulating, 593

database connection string, 96


Index

database_refresh_interval (server.inikey), 104

default_acl, setting, 383defining projection targets, 114, 116deleting from connection broker

list, 201described, 84distinct_query_results (server.ini

key), 104failover, 121getServerMap method, 200historical session cutoff, 100history_cutoff (server.ini key), 100history_sessions (server.ini key), 100index_store (server.ini key), 99internationalizaton, 87java.ini file, 134LDAP connection credentials, 334LDAP directory servers, multiple, 342listener queue length,

configuring, 118load balancing, 121max_ftacl_cache_size (server.ini

key), 100monitoring status, script for, 590moving executable (UNIX), 109notifying connection broker of

shutdown, 120parent and session servers, 84proximity values, defining, 117removing server logs, 499removing session logs, 499restarting, 111server.ini file, 88server_startup_sleep_time key, 106sessions, shutting down, 120setting checkpoint interval, 116setting keep_entry interval, 116shutting down, 118specifying listening address, 98standard arguments passed to

jobs, 449start_index_agents (server.ini

key), 107starting, 88starting additional, 112threads, 84tracing options, 532version number, 514

viewing historical sessions, 100Content Server Manager, 32Content Servers

secure connection mode, setting, 110content storage areas

moving files, 259Content Storage Services license, 225content type

parent_id property, 223storage_id property, 223

Content Warning tooldescribed, 468percent_full argument, 469report sample, 469

content_dupl_pref property, 210content-file servers

failover limitation, 122content_hash_mode property, 210ContentServerStatus script, 590copying

objects, folder security and, 363Create Cabinet user privilege, 292Create full-text events tool

report sample, 474Create Group user privilege, 292Create method, 65Create Type user privilege, 292CREATE...GROUP (statement), 308CREATE...OBJECT (statement)

creating format objects, 69creating jobs with, 149creating location objects, 65

CREATE...TYPE (statement), 73createAudit() method, 394creating

blob storage areas, 236default ACLs, 383directories, 65dump record object, 50format objects, 69jobs, 149linked storage areas, 239location objects, 64method objects, 143object types, 72objects, folder security and, 363repositories, 39

creating full-text events, 470custom ACLs. See internal ACLs, 378


Index

Ddata dictionary

consistency checks, 559Data Dictionary Publisher job, 607Data Dictionary Publisher tool, 475data files supplied with Content

Server, 606dd_populate.ebs, 594, 605 to 606default files, 606initialization file, 606initialization file format, 594populating, 593

data file format, 595settable properties with

population file, 597setting foreign keys, 601

populating Japanese/Koreanlocales, 605

populating using DQL, 606PUBLISH keyword, 608publishDataDictionary method, 607publishing, 606

data dictionary data filesdescribed, 595examples, 602settable properties, 597structure of, 595using multiple, 595

Data Dictionary Publisher, 607Data Dictionary Publisher tool, 475data ticket number, 234data_dictionary.ini, 606data_store (server.ini key), 99database connection strings

DB2, 97described, 96MS SQL Server, 97Oracle, 96Sybase, 97

Database Space Warning tool, 476database_conn server.ini key, 96database_name server.ini key, 97database_owner server.ini key, 96database_refresh_interval (server.ini

key), 154date formats, short, 175dates

storage, configuring, 45time zone adjustment, 45

DB2database connection strings, 97object type table location, 45object type tables

device, defining, 94uninstalling repository, affects of, 100

dcf_edit utility, 156dd_locales

setting, 44dd_populate.ebs, 606

described, 594executing, 605

deactivatingjobs, 153jobs during load, 60

default ACLsassigning to objects, 383cabinet, 383changing type default, 74creating, 383default_acl property and, 383described, 381folder, 382specifying at server level, 383type default, 382user, 382

default storage algorithm for content, 229default values

changing default group, 304public and private groups, 307storage area for types, 74

default_acl property, 383default_app_permit property, 364default_folder property, 298default_retention_days property, 247, 257default_storage property

format object property, 230type info object property, 230

default_storage property, for formats, 70deferred object update queue, setting

size, 107deferred update process, 107deferred_update_queue_size (server.ini

key), 107delete_object permission, 367deleting

ACLs, 385dequeued items, 503format objects, 71groups, 309


Index

log files, 499objects, folder security and, 363properties from types, 75renditions, 509users, 304

delimiterssignature page defaults,

changing, 421dequeued items, deleting, 78, 503Destroy method

automating with version managementtool, 525

folder security and, 363DFC (Documentum Foundation

Classes, 537See also DFC tracingtrace file location, default, 538trace file size, default, 538

DFC (Documentum FoundationClasses), 168, 536See also DFC tracing; privileged DFCcontent assignment policy

enforcement, 226determining tracing status, 536dump and load interfaces, 49log files, 536trace file naming, 539tracing, 536user privileges, setting, 303

DFC eventsaudit trail entries, 398

DFC tracingdates, defining alternate format, 542dates, defining column width, 542default file location, 538default file size, 538determining activation status, 536dfc.tracing.file_creation_mode, 544dfc.tracing.thread_name_filter, 545enabling, 537exception stacks, printing, 546file_creation_mode, defining, 539log4j.properties and, 537logger, 537logging appender, 537method calls, 542method entry and exit, 543RPC calls, tracing, 546session information, including, 545

specitying package, class, method totrace, 543

timestamp format, setting, 540trace file format, 548trace file names, 539users, filtering by name, 544verbosity level, 546

dfc.config.check_interval key, 162dfc.data.umask (dfc.properties), 175dfc.keystore file, 171dfc.machine.id key, 439dfc.privilege.enable key, 170dfc.properties

connect_retry_interval, 167dfc.session.max_count key, 167dfc.tracing.print_exception_

stack, 546directory specifications, 163max_connect_retries, 167modifying, 163secure_connect_default, 166

dfc.properties fileconnection brokers, specifying, 163described, 162dfc.config.check_interval key, 162dfc.data.umask, 175dfc.session.pool.enable key, 172dfc.storagepolicy,ignore_rule_error

key, 276dfc.tokenstorage.dir key, 440, 443dfc.tokenstorage.enable key, 440dfc.tracing.date_column_width, 542dfc.tracing.date_format, 542dfc.tracing.enable, 537dfc.tracing.file_creation_mode, 539,

544dfc.tracing.include_rpc_count, 546dfc.tracing.include_rpcs, 546dfc.tracing.include_session_id, 545dfc.tracing.method_name_filter, 543dfc.tracing.mode, 543dfc.tracing.thread_name_filter, 545dfc.tracing.timing_style, 540dfc.tracing.user_name_filter, 544dfc.tracing.verbosity, 546dfcfull.properties file, 162enable_persistence d key, 178extern_store_content_static key, 245force_coherency_check key, 183keu format, 162


Index

local_clean_on_init key, 177local_diskfull_limit key, 176local_purge_on_diskfull key, 176max_stack_depth, 542search_order key, 191write_interval key, 183.write_max_attempts key, for Centera

stores, 253write_max_attempts key, for EMC

Centera stores, 253dfc.session.pool.enable (dfc.

properties), 172dfc.tokenstorage.dir key, 440, 443dfc.tokenstorage.enable key, 440dfc.tracing.date_column_width, 542dfc.tracing.date_format, 542dfc.tracing.enable, 537dfc.tracing.file_creation_mode, 539dfc.tracing.include_rpc_count, 546dfc.tracing.include_rpcs, 546dfc.tracing.include_session_id, 545dfc.tracing.timing_style, 540dfcfull.properties file, 162digital shredding

described, 211digital signatures, 427dir_user_sync_on_demand property, 328directories

archive, 282creating, 65dfc.data.umask (dfc.properties), 175format objects and, 39fulltext index objects and, 39location objects and, 38mount point objects and, 39mounted drive aliases, 66storage objects and, 39temp, 78umask server.ini key, 101, 109

directory pathsarchive dump file, 280content in file stores, 223, 233dump file, 59State of the Repository Report

tool, 514directory specifications, in

dfc.properties, 163disabling

content assignment policies, 276policy engine (DFC), 276

disk space managementContent Warning tool, 468Database Space Warning tool, 476Swap Info tool, 518

distinct_query_resultsserver.ini key, 104

DistOperations job, 447distributed content

dmclean tool and, 485dmfilescan tool and, 490

distributed environment and site-specifictool reports, 451

distributed environmentssignatures, verifying, 415

distributed repositoriesauditing in, 416

distributed storage areascreating, 236described, 218load operations and, 60valid component types, 218

distributed store storage typer_component property, 224

distributed storescomponents, replacing, 274

DM_ARCHIVE event, 278dm_Archive job, 454dm_AuditMgt job, 456dm_audittrail_acl objects, 392dm_audittrail_group objects, 392dm_auth_config objects, 322dm_autorender_mac user, 41dm_autorender_win31 user, 41dm_bpm_inbound_user user, 41dm_browse_all group, 294dm_browse_all_dynamic group, 294dm_check_password file, 316dm_CheckCacheConfig method, 182dm_ConsistencyChecker, 459dm_ContentReplication job, 465dm_ContentWarning job, 468dm_create_cabinet group, 295dm_create_group group, 295dm_create_type group, 295dm_create_user group, 295dm_crypto_boot utility, 432dm_crypto_change_passphrase

utility, 434dm_crypto_create

troubleshooting AEK with, 433


Index

DM_CRYPTO_FILE environmentvariable, 430

dm_dbo alias, 73dm_DBWarning job, 476DM_DEBUG_ESIGN_METHOD

environment variable, 427dm_default_set event, auditing, 392dm_DMClean job, 482dm_DMFilescan job, 487dm_domain_conv script, 319DM_ENCR_PASS prefix, 353dm_encrypt_password utility, 354dm_error utility, 34dm_FileReport job, 493dm_FTCreateEvents, 470dm_fulltext_index_user, 41DM_GROUP_LIST_LIMIT environment

variable, setting, 79dm_GroupRename tool, 498DM_HOME_CURRENT environment

variable, 88, 109dm_job_sequence objects, 147dm_launch_docbroker, 195dm_LDAPSynchronization job, 479

activating, 341behavior on first run, 344choosing LDAP servers, 327described, 325indexed LDAP properties, use of, 334LDAPSynchronizationDoc.txt

file, 337on-demand execution, 328properties set, 326 to 327trace files, 345

dm_LDAPSynchronization tool, 479dm_LogPurge job, 499dm_mediaserver user, 41dm_move_content event, 263dm_MoveContent

configurable arguments, 261dm_MoveContent job

described, 260dm_netegitry, 349DM_PLUGIN prefix, 347dm_QueueMgt job, 503dm_relation_ssa_policy objects, 227dm_RenditionMgt job, 509DM_RESTORE event, 278dm_retention_managers group, 294dm_retention_users group, 294

dm_run_dependent_jobsbehavior, 147

dm_run_dependent_jobs methodarguments, 159introduced, 146return values, 147

dm_save eventsload operations and, 60

DM_SERVER trace facility, 211dm_shutdown_repository script

creating server_specific, 113shutting down servers with, 119

dm_ssa_policy objects, 227dm_start_repositoryname script

oclean argument, 88starting servers with, 88

dm_StateofDocbase job, 514dm_stop_docbroker utility, 198dm_storage_strategy, a_content_attr_

name value, 253dm_store type

r_status property, 264dm_superusers group, 294dm_superusers_dynamic group, 294dm_SwapInfo job, 518dm_sysadmin group, 295dm_UpdateStats job, 519dm_UserChgHomeDb job, 522dm_UserRename job, 523dm_VersionMgt job, 525dmauthplug.h header file, 350dmauthplug.lib (dmauthplug.a) file, 350dmbasic executables, 138dmbasic method server

connection pooling, 130described, 130enabling, 135log files, removing, 499worker threads, configuring, 136

dmclean utilityarguments, 267deleting internal ACLs, 385described, 266 to 267Dmclean tool, 482EMC Centera storage areas and, 268EXECUTE syntax, 268executing generated script, 269external storage and, 219generated script sample, 269standalone syntax, 269


Index

dmdocbroker.exe, 195dmfilescan utility

arguments, 270described, 266, 270Dmfilescan automated tool, 487EXECUTE syntax, 273executing generated script, 274external storage and, 219-force_delete argument, 272generated script example, 273index use, 272standalone syntax, 273subdirectories to scan,

identifying, 271dmi_audittrail_attrs

privileges to query, 397dmi_queue_item objects, removing, 78dmqdoccbroker script, 590dmtkgen utility

arguments, 441output file, 441output file, naming, 443

DO_METHOD procedures, 129See also methodscreating method objects, 143Java method server and, 131post_archive, 283post_restore, 283pre_restore, 283tracing, 133

do_method servlet, 131DocApps

dump operations and, 64dumping limitation, 51

docbase config objectdd_locales, setting, 44described, 38wf_package_control_enabled

property, 80docbase config objects

check_client_version property, 168macl_security_disabled property, 377oldest_client_version property, 168security_mode property, 362

docbase configurationtrust_by_default property, 437trusted_docbases property, 437

docbase_id server.ini key, 96docbase_name server.ini key, 96Docbasic

java guidelines, 137tool suite implementation, 449

Docbasic argument length, maximum, 137docbroker locator object

getDocbrokerMap method, 201DOCBROKER_CONFIGURATION

section, 196DocBrokers

configuration, 196docu group, 61documents

a_archive property, 280archiving/restoring overview, 277consistency checks, 556defining signature page templates

for, 423re-archiving restored documents, 286restoring, 495restoring from archive, 286restoring from archive with surrogate

get, 287retention of, 231setting up archiving, 285

Documentumcreating repositories, 39repository security levels, 362security overview, 359tool suite, 446user privileges, 291

domain controller maps, 322domain-required mode

converting to, 319described, 318

domainsauth_protocol property, 318authenticating in, 317authenticating UNIX users in, 314,

320authentication, 108dm_domain_conv script, 319proximity values and, 118

dos_extension property, 68DQL (Document Query Language)

auditing and, 393creating method objects, 144distinct_query_results (server.ini

key), 104format object deletion, 71format object modification, 70


Index

NOFTDQL hint and distinct_query_results server.ini key, 104

type modification procedures, 74DROP TYPE (statement), 76dump and load

table permits, affect on, 387dump files

code pages and, 48content files and, 54

dump object record object, 49dump record objects

described, 49dum_operaton property, 51include_content property, 55specifying

predicate property, 53predicate2 property, 53type property, 52

dumpingcompressing content, 55content files, 55DocApps limitation, 51dump_operation property, 51external storage, 219full_docbase_dump, 51job objects, 60non-restartable, 56objects under retention, 50objects with aspects, 51partial, 51repositories, 48, 64sample script, 57script, sample for full dump, 57script, use of, 56selecting objects, 53specifying object types, 52troubleshooting, 59, 64Web Publisher repositories, 48

duplicate rows in queries, 104duplicating repositories with dump and

load, 48dynamic groups, 361

dm_browse_all_dynamic, 294dm_superusers_dynamic, 294is_dynamic_default property, 308membership default, setting, 310

Eelectronic mail notifications

disabling, 105electronic signatures

append_to_body property, 424customizing, 417max_signatures property, 424signature creation methods,

creating, 425signature page templates,

creating, 427tracing, 427

electronic signoffregistering for notification, 429

embedded blobs, configuring, 251embedded blobs, in EMC Centera storage

described, 214EMC Centera clusters, connection strings

for, 249EMC Centera host machines, clock

requirements, 255EMC Centera profiles

required permissions, 249EMC Centera storage areas

a_storage_params property, 224C-clip buffer size, 214C-clip buffer, setting size, 252ca store object type, 212Centera profiles, permissions

required, 249configuration options, 212connection string, setting, 248content assignment policies, 225content compression, 213content, removing, 268deleting content from, 265dfc.content.castore.write_max_

attempts key, 253dfc.content.castore.write_sleep_

interval key, 253embedded blob use, configuring, 251embedding or linking content, 214expired objects, removing, 506Linux platform, 212machine clock requirements, 255Macintosh computers, 212memory map interface use, 215memory map interface, configuring

use, 254retention periods, 213retention policies and, 248


Index

retention requirements,configuring, 247

setting up, 245single-instancing, overriding, 215, 253socket connections, configuring

maximum, 215, 254write attempts, configuring, 214, 253

EMC Centera storage hostsFP_OPTION_BUFFERSIZE

configuration parameter, 253EMC Centerastorage areas

Centera clusters, supporting, 249EMC RSA Plug-in for Documentum, 315enable_persistence key, 178encrypted content files

dumping, 54encrypted passwords, 352encrypted storage areas, 206encryption

DM_ENCR_PASS prefix, 353dm_encrypt_password utility, 354keys, described, 429passwords, 352passwords, discontinuing for, 353resolving compromised keys, 275utilities, described, 432

encryptPassword method, 353enforce_four_digit_year key, 104ENV_CONNECT_DOCBASE (iapi/idql

argument), 565, 570ENV_CONNECT_PASSWORD (iapi/idql

argument), 565, 569ENV_CONNECT_USER_NAME

(iapi/idql argument), 564environment variables

DM_CRYPTO_FILE, 430DM_DEBUG_ESIGN_METHOD, 427DM_GROUP_LIST_LIMIT, 79DM_HOME_CURRENT, 88, 109

error messagesdm_error utility, 34

evaluation, of ACL entries, 374event notifications

use_group_address (server.inikey), 102

eventsapplication events, auditing, 393auditing, 387defined, 387dm_signoff notification, 429

full-text indexing, used by, 619kinds of, 388notification, disabling, 105system events, 393system-defined, 609user-defined, 387

exceptions, tracing in DFC, 546execute_proc permission, 367execution agents

choosing, 132default, 132described, 130performance, 132security issues, 133

expiration date of jobs, 151expiration_date property, 151explicit transactions

caching objects and, 184EXPORT_TICKET_KEY administration

method, 436exportTicketKey (DFC method), 436extended characters, in LDIF files, 301extended object-level permissions

described, 366viewing, 367

extended restriction ACL entries, 371extended user privileges, 293

permissions to grant/revoke, 302extern file storage areas

described, 220extern_store_content_static

(dfc.properties key), 245external ACLs

defined, 378deleting, 385name format, 381

external applicationsdedicated servers, 38Docbasic argument length,

maximum, 137jobs and, 149URLs, using, 234

external file store storage areasexample of use, 242

external free storage areascreating, 244defined, 220

external password checking, withLDAP, 330

external storage


Index

a_content_static property, 245CD-ROM files, 220content dump not allowed, 219content load not allowed, 219extern_store_content_static

dfc.properties key), 245external free stores, 220external URL stores, 220optimizing retrieval performance, 245renditions and, 220replication constraint, 219

external storage areasdescribed, 219setting up, 242types of, 219

external URL storage areascreating, 244defined, 220

externded permissionsowner_xpermit_default (server.ini

key), 101extra_directory_config_id property, 327,

329

Ffail-over mechanisms

multiple service names in server.inifile, 98

failed_auth_attempt property, 306, 356failover

connection brokers, 164, 191Content Server, 121content-file server limitation, 122

failover_ldap_config_ids property, 331failover_use_interval property, 331federations

LDAP authentication and, 328LDAP directory servers and, 325

file extensionsimplementing automatic use, 258in storage areas, 237

file formats, 67See also formatsformat objects and, 67

file naming conventions in client localareas, 177

File Report tool, 493file store keys

resolving compromised, 275

file store storage areasautomatic file extensions, 258base_url property, 238content assignment policies, 225content compression, 206content duplication checking, 209creating, 237described, 205digital shredding, 211encrypted, 206file store keys, resolving

compromised, 275is_public property, 206location_name property, 223moving, 264private access, 206public access, 206use_extensions property, 234, 258

file systemslinked stores and, 221Windows NT and, 238

file systems, external storage and, 220file_system_path property

character constraint, 65filename_modifier property, 70files

dfc.data.umask (dfc.properties), 175dump, moving, 59removing from server common

area, 88temporary, 78umask server.ini key, 101, 109

filestore_01 storage area, 233filters, for LDAP, 334firewalls, 194folder default ACL, 382folder security

changing, 364defined, 362 to 363

folder_security property, 364folders

consistency checks, 555creating, 43defined, 42editing, 43permissions to modify/delete, 44

force_coherency_check key, 183foreign keys

setting, 601format obects


Index

format_class property, 68format objects

adding, 69creating, 69default_storage property, 230deleting, 71described, 67dos_extension property, 68modifying, 70obtaining list of, 69repository configuration, 39rich media formats, 69

format_class property, 68formats

formats.csv file, 68internal ACL names, 379obtaining list of, 69rich media, 69

formats.csv, 68fragmentation, table, 476FTDQL

distinct_query_results server.inikey, 104

full-text indexingACL caching, 100creating events, 470event generation, stopping during

load operations, 61events used by, 619format_class property, 68job reports, 451load operations and, 60reindexing a repository, 470starting index agents, 107use_estimate_search (server.ini

key), 108fulltext index objects

repository configuration, 39FUNCTION_EXTENT_SIZE server.ini file

section, 95FUNCTION_SPECIFIC_STORAGE

server.ini section, 94

Ggenerate_event load operations

parameter, 61getDocbaseMap method, 200getDocbrokerMap method, 201gethostbyaddr (server.ini key), 100

getServerMap method, 200GRANT (statement), 302Group Rename tool, 498group_admin property, 309group_global_unique_id property, 327group_table_permit property, 386groups

adding, 307audit trail entries, interpreting, 413changing default, 304consistency checks, 552Create Group user privilege, 292deactivated users, adding, 309deleting, 309docu, 61dynamic, 361email notifications for,

configuring, 102group_global_unique_id

property, 327is_dynamic_default property, 361is_private property, 308LDAP synchronization, 325membership setting, for dynamic

groups, 308modifying, 309naming restrictions, 308obtaining count of members, 311obtaining list of, 311obtaining list of members, 311ownership, assigning, 307ownership, changing, 309private, 307privileged, 294properties

mapping LDAP attributes to, 335required LDAP mappings, 336

properties set by synchronization, 327public, 307querying, 311renaming, 498required group entries in ACLs, 372required group set ACL entries, 373Saveasnew defaults, 101system-created, 41

Hhierarchy, repository, 42history_cutoff (server.ini key), 100


Index

history_sessions (server.ini key), 100home cabinet, 43home repositories, changing, 522host (server.ini key), 98host machine

connecting to specific, 165dm_crypto_boot, running after

restart, 432TCP/IP service name in server.ini

file, 98version number, 514

HTTP_POST administration methodadding servlet for, 123

Ii_contents property, 212i_contents_id property, 266i_crypto_key property, 431IAPI (utility)

commands for, 571comments, entering, 573executing methods, 572exiting, 573

identifiers, 347See also plug-in identifiers

IDfAuditTrailManager interface, 396IDfDumpRecord interface, 49IDfLoadRecord interfacee, 49IDmMethod interface, 142IDQL (utility)

buffer, clearing, 567commands, 566idql command syntax, 563queries, entering, 567quiting, 568starting, 563

ignore_client_domain key, 104ignore_rule_errors (dfc.properties

key), 276IMPORT_TICKET_KEY administration

method, 436importTicketKey (DFC method), 436inactivating

administration jobs, 453jobs, 153

inboxesarchive and restore requests, 280deleting dequeued items from

repository, 503

index agentmonitoring status, script for, 591

index positions, 54index_store (server.ini key), 99IndexAgentCtrl script, 591indexes (type), specifying location, 99indexes, for dmfilescan, 272information

connection broker, 199format objects, 67server startup file, 38State of the Repository Report

tool, 514tool reports, 530

initialization filesconnection broker

format, 192invoking, 193

server.ini, 88installations

described, 28repository security levels, 362security overview, 359user privileges, 291

internal ACLsdeleting, 385described, 378names, 379object names and, 381

internationalizationContent Server, 87dump and load requirements, 48group names, 308plug-in authentication module code

page, 350short date formats, 175short date formats, defining, 175user names, 290, 296

IP addressesfor connection brokers, 192specifying in server.ini, 98translating, 194

is_archived property, 280is_dynamic property, 361is_dynamic_default property, 308, 310,

361is_inactive property, 153is_offline property, 280is_private property, 308is_public property, 206


Index

JJapanese locales

populating on Korean host, 605Java method server, 131

described, 131implementing methods for, 141method object requirements, 143monitoring status, script for, 590servlets, adding, 123shutdown.sh script, 131starting/stopping, 131storage location for methods, 143

java methodsexecution agents for, 132guidelines, 137

Java methodsimplementing, 141storage location, 143

Java security policy files, modifying, 170java.ini file, 134java.ini file, location, 138JBoss, 131JBoss application server, 86

binaries, location of, 126starting and stopping, 126

job reports, full–text indexing and, 451job sequences

candidates for inclusion, 150creating, 150dcf_edit utility, 156described, 146dm_run_dependent_jobs method

execution, 159execution, 147failure recovery, 158name of, 147repository connection file, 148, 155repository representation, 147return codes, defining, 144return values, 147status report, described, 158tool suite and, 453

jobs, 146, 446See also job sequences; tool suitea_next_invocation, 151activating/inactivating, 153admingroup group and, 302agent exec process, 85, 148, 154, 449content migration policies, 260

creating, 149creating full-text events, 470Data Dictionary Publisher, 607described, 146disabling all, 153dm_Archive, 454dm_AuditMgt, 456dm_ConsistencyChecker, 459dm_ContentReplication, 465dm_ContentWarning, 468dm_DBWarning, 476dm_DMClean, 482dm_DMFilescan, 487dm_FileReport, 493dm_FTCreateEvents, 470dm_GroupRename, 498dm_LDAPSynchronization, 341, 479dm_LogPurge, 499dm_MoveContent, 260dm_QueueMgt, 503dm_RenditionMgt, 509dm_StateofRepository, 514dm_SwapInfo, 518dm_UpdateStats, 519dm_UserChgHomeDb, 522dm_UserRename, 523dm_VersionMgt, 525dumping/loading, 60expiration_date property, 151is_inactive property, 153job reports, full–text indexing

and, 451maximum concurrent, setting, 154maximum executions, 151passing standard arguments, 151queueperson argument for tools, 450records migration, 262removing log files, 499reports, viewing, 451return codes for jobs in sequence, 144run_interval property, 151run_mode property, 151run_now property, 152scheduling, 150server time, use in scheduling, 151standard arguments passed, 449start_date property, 151tool suite implementation, 449tool suite log files, 452validating cached data, 182


Index

Kkeep_entry_interval, 116keepSLabel argument, 77keys

server.ini file, 89keystore file

configuring shared file, 172keytool utility

passwords, 171keywords

PUBLISH, 608Kill method, 120Korean locales

populating on Japanese host, 605

LLDAP attribute mappings

benefits, 324defining, 335examples, 338repository storage of, 337

LDAP authenticationpassword checking program,

creating, 341ldap config objects

bind_type property, 334deleting, 342federations and, 328mapping storage properties, 337multiple, using, 332retry_count property, 330retry_interval property, 330retry_interval, configuring, 343set-up values, defining, 333

LDAP directory serverdeleting users, effect of, 306dm_LDAPSynchronization tool, 479

LDAP directory serversActive Directory

mode requirements, 342user_name mapping, 336

attributes, mapping to properties, 335authentication, see user authenticationcertificate authorities, 340certutil utility, 340Changepassword constraint, 324choosing for authentication, 329choosing for synchronization, 327connection retry configuration, 330

deleting from repository, 342dm_LDAPSynchronization job, 325federations and synchronization, 325implementing, 332integrating entries with

repository, 324LDAP_RECONNECT_INCREMENT_

SECOND environmentvariable, 343

LDAP_RECONNECT_TIME_SECONDS environmentvariable, 343

ldapconfig.cnt file, 334LDAPSynchronizationDoc.txt

file, 337multiple config objects, using, 332multiple Content Servers, use

with, 342multiple, using, 325overview, 314property mapping

guidelines, 337required mappings, 336rules for, 336

retry_interval, configuring, 343search bases/filters, 334secondary servers, 330secure connections

configuring, 335described, 330

set-up values, defining, 333synchronization

activating job, 341behavior on first run, 344groups, 325on-demand, described, 328users, 325

usagebenefits, 324constraints, 324

use with repository, 323LDAP synchronization, see LDAP

directory serversLDAP synchronization on demand

described, 328LDAP users

authentication overview, 329changing LDAP directory server, 344on-demand synchronization, 328property mappings, required, 336


Index

user_global_unique_id property, 327user_login_domain property, 327user_source property, 327

LDAP, securecertificate authorities, obtaining, 340certutil utility, 340

ldap_config_id property, 327, 329LDAP_RECONNECT_INCREMENT_

SECONDS environment variable, 343LDAP_RECONNECT_TIME_SECONDS

environment variable, 343ldapcertdb_loc location object, 335ldapconfig.cnt file, 334ldapsearch utility, 346LDIF files

described, 300extended characters and, 301

legacy files, external storage for, 220lifecycles

audit trail entries, interpreting, 404consistency checks, 560log files, removing, 499

limitskeep entry interval, 116RDBMS timeout, 106table fragmentation, 476

link_location property, 224linked storage areas

content location, identifying, 224creating, 239described, 221

linking, folder security and, 363Linux platform, 212listener_queue_length (server.ini

key), 118load balancing, 38, 121

connection brokers, 164, 191load object record objects, 49load operations

full-text indexing and, 60generate_event parameter, 61indexing-related events, turning

off, 61load record objects, 49loading

accessing content files, 55code pages and, 48content not allowed into external

storage, 219DocApps and, 64

job objects, 60new repositories, 61 to 62preload utility, 62registered tables, 61repositories, 48, 64troubleshooting, 64Web Publisher repositories, 48

local_clean_on_init (dfc.propertieskey), 177

local_dir, changing, 176local_diskfull_limit (dfc.properties

key), 176local_purge_on_diskfull (dfc.properties

key), 176locales

adding, 593dd_locales, setting, 44

locales, supported, 87location objects

creating, 64 to 65repository configuration, 38security_type property, 65State of the Repository Report

tool, 514location_name property, 223log files

connection broker, 79content assignment policy use,

for, 275Content Server, 79DFC (Documentum Foundation

Classes), 536removing for repository cleanup, 78server, 121session, 78

Log Purge tool, 499logger, for DFC tracing, 537

logging appender, configuring, 537logging appender, 537logging appender, configuring, 537login failure, auditing, 391login ticket key

exporting and importing, 436resetting, 436

login tickets, 107backwards compatibility, 173restricting use of global, 438revoking in repository, 438server cache size, setting, 173troubleshooting, 438


Index

validity period, defining, 437validity period, setting, 173

login_ticket_timeout property, 173, 437logs

lifecycle, 499removing files, 499tool job files, 452

MMacintosh

external storage and, 219Windows NT servers and, 238

Macintosh computers, 212Macintosh files

storage constraint, 209mail_notification (server.ini key), 105map_attr property, 337map_attr_type property, 338map_rejection property, 338map_val property, 338map_val_type property, 338mapping rules for LDAP property

mappings, 336max_auth_attempt property, 306, 356max_connect_retries (dfc.properties), 167max_count (dfc.properties key), 167max_ftacl_cache_size (server.ini key), 100max_iterations property, 151max_login_ticket_timeout property, 437max_nqa_string (server.ini key), 101max_sessions_heap_size (server.ini

key), 101max_signatures property, 424max_stack_depth, 542max_storage_info_count (server.ini

key), 105Maximum Content Migration Threads

value, 260maximums

age of renditions, 510age of versions, 527blob storage size, 217concurrent jobs, 154concurrent sessions, 103connection broker projection

targets, 116dump cache size, 55failed authentication attempts, 356history sessions, 100

job executions, 151predicate property, 53

Media Servernew repositories and, 40

Media Transformation Servicesnew repositories and, 40

memorydump cache, 56login tickets, 107max_sessions_heap_size (server.ini

key), 101memory map interface, using, 254messages

dump and load, 64from tools, 452session log file, 532

method execution queue, 130method objects

consistency checks, 561creating, 143jobs passing standard arguments, 151

method serverjava.ini file, 134method object requirements, 140method_server_enabled (server.ini

key), 105method_server_threads (server.ini

key), 105method_server_enabled (server.ini

key), 105method_server_threads (server.ini

key), 105methods

defined, 129executing automatically, 146executing on demand, 145execution agents

choosing, 132described, 130performance, 132

execution queue, 130IAPI execution, 572IDmMethod interface, 142implementing, 136output, recording, 140property settings for Content

Server, 140property settings for dmbasic method

server, 140


Index

property settings for Java methodserver execution, 143

removing results files, 499security issues, 133storing content, 129success_return_codes, setting, 144success_status, setting, 144tracing, 133

Microsoft Performance Monitor tool, 33MIGRATE_CONTENT administration

method, 259auditing, 263memory map interface use, 215

minimum valuesage of audit trails, 458age of dequeued items, 504

modifyingACLs, 384format objects, 70groups, 309server config objects, 109types, 75users, 303

monitoring scripts, 589Mount method, 243mount point objects

alias drive letters and, 66repository configuration, 39

mount pointscreating, 66

movingcontent through archive, 280contents through restoring, 281dump files, 59, 282objects, folder security and, 363repositories, 48

MS SQL Serverdatabase connection strings, 97database_name server.ini key, 97

Nnaming conventions

ACLS, 379archive dump files, 281blob storage areas, 236data ticket values, 234file extensions, 237files in client local areas, 177log purge reports, 499

storage area sudirectories, 272storage objects, 63user objects, 290win_preferred_alias, 67

native and secure connection modesetting, 111

native connection mode setting, 111NetApp SnapLock storage areas

a_storage_params property, 224content assignment policies, 225content compression, 217retention periods, 216retention policies and, 257retention requirements,

configuring, 256setting up, 255

network service names, 112no-domain required mode, 318NOFTDQL hint, 104None user privilege, 292notifications

disabling, 105number (quantity of)

concurrent sessions, 103connection brokers, 188historical sessions, 100login tickets, 107

numbersdata ticket, 234docbase_id, 96port, for connection brokers, 187proximity values, 117

Oobject replication

external store constraint, 219object type indexes

consistency checks, 561object type tables

alternate locations for (Oracle orDB2), 45

object typesACLs, assigning, 382consistency checks, 558default_storage property, 230dm_create_cabinet group, 295dm_create_group group, 295dm_create_type group, 295dropping from repository, 76


Index

modifiying, 73privileges to modify/create, 72

object-level permissionsbasic permissions, 365described, 364extended permissions, 366table permits and, 387

objectsapplication control of, 364application-level control of, 361creating and folder security, 363deffered object update, queue

size, 107deleting and folder security, 363dump object record, 49dump record, 49format, 39fulltext index, 39load object record, 49load record, 49location, 38mount point, 39moving and folder security, 363owner access evaluation, 375storage, 39superuser access to, 376

oldest_client_version property, 168operator_name property

described for archive tool, 284tool messages and, 450

Oracledatabase connection strings, 96database_name server.ini key, 97dm_dbo alias, 73object type table location, 45object type tables

size, defining, 95tablespace, defining, 94

Oracle Intranet Directoryproperties, indexing, 334

orphan content files, 76orphaned annotations, 76owner_table_permit property, 386owner_xpermit_default (server.ini

key), 101

Ppackage_control property, 80packages

component names, controlling useof, 80

parallel content migration, 259parent server

described, 84parent_id property, 223pass_standard_argument property, 151passphrases, changing, 434password checking program

creating, 319requirements, 320

password checking program, creating forLDAP, 341

passwordschange constraint with LDAP, 324changing encrypted, 354connection broker shutdown, 193encrypted, 352server authentication, 108stopping encrypted use, 353

performanceauditing and, 456blob storage areas, 217dmclean and dmfilescan, 266dump operations, 55inboxes and, 503large archive files, 283load balancing, 38turbo storage, 218type indexes, 44

performance of queries, 79permissions

base object-level, 364extended object level, 366multiple entries for single user,

resolving, 376required for Centera profile, 249

permits, registered tables, 362persistent client caches

cache config objects, creating, 179cached objects backup, 183client_pcaching_change property, 182client_pcaching_disabled

property, 178described, 177forcing currency checks, 183troubleshooting, 184

persistent client cachingclient check interval, setting, 181enabling/disabling, 178


Index

flushing a cache, 181server check interval, setting, 180

persistent object cacheautomatic back up, 183

PKI credentialsaccessing, 171location, 171

plug-in authentication moduleimplementing custom, 349

plug-in authentication modulesCA SiteMinder, 348code page, defining, 350described, 346dmauthplug.h file, 350dmauthplug.lib file, 350identifiers, 347identifying to server, 347RSA, 348trace files, 351

plug-in identifiersCA SiteMInder, 349defining, 347

policy engine (DFC)disabling, 276

policy engine, content assignmentpolicies, 226

port number for connection brokers, 187post_archive (DO_METHOD

procedure), 283post_restore (DO_METHOD

procedure), 283pre_restore (DO_METHOD

procedure), 283precedence, LDAP directory server, 324predicate property, 53predicate2 property, 53preload utility, 62preserve_existing_types (server.ini

key), 106primary content

storage algorithm, 229private

ACLscreating, 380

ACLs, defined, 379cabinets, 43file store storage areas, 205groups, 307

private file stores, 206privileged delete

required EMC Centera profilepermission, 249

privileged DFCalias, defining, 172approved_clients_only property, 169client rights objects, 168dfc.keystore file, 171disabling, 170enabling, 169Java security policy files and, 169 to

170role groups used by, 295

privileged groups, 294role groups used by DFC, 295

privileges, see user privilegesprograms

shutting down servers with, 119projection properties for connection

broker, 115projection targets, 114properties

adding to types, 74auditing

initiating, 388changing on signature page

template, 420default access permissions, 73deleting, 74deleting from types, 75dump record, 49index position, 54lengthening string, 75load object, 49mapping to LDAP attributes, 324max_nqa_string (server.ini key), 101object and ACL connection, 380permissions and, 365values in State of the Repository

Report tool, 514property mappings for LDAP,

examples, 338proximity values

defining, 117projection_proxval property, 115

Prune methodautomating with version management

tool, 525folder security and, 363repository cleanup, 77

public


Index

cabinets, 43file store areas, 205groups, 307

public ACLsdefined, 379

PUBLISH keyword, 608publishDataDictionary method, 607publishing

data dictionary, 607Purge Audit privileges, 416Purge Audit user privileges, 293PURGE_AUDIT administration

method, 416auditing, 391

purgeLocalFiles method, 177

Qqueries

distinct_query_results (server.inikey), 104

duplicate rows in results, 104query performance, 79queue items, deleting unwanted, 78Queue Management tool, 503queueperson

tool argument, 450tool errors, 530

Rr_component property, 224r_content_hash property, 210r_gen source property, 394r_is_public property, acl_update_

threshold and, 98r_normal_tz property, 45r_status property, 264RDBMS

connection timeout, 106Database Space Warning tool, 476finding fragmented tables, 476locks, releasing, 99login name, 290setting table permits, 386table permits, 386updating table statistics, 519version number, 514

rdbms_connect_retry_timeout key, 106records migration jobs, creating, 262

RECOVER_AUTO_TASKS administrationmethod, 125

registered tablesaffects of loading operations, 61setting table permits, 386table permits, 386user_db_name and, 290

reindexing repositories, 470rejecting server broadcasts, 193Relate permit level and relationships, 366relation ssa policy objects, 227relationships

permissions for, 366Remove Expired Retention Objects

tool, 506removeDynamicGroup method, 311removing

aborted workflows, 77dequeued items, 503log files, 499renditions, 509

Rendition Management tool, 509renditions

external storage and, 220removing old, 77, 509storage algorithm, 231turbo storage and, 218

replica_filestore_01 storage area, 233replicate_temp_store storage area, 233reports (tool suite), 451repositories

activating LDAP synchronizationjob, 341

addingformat objects, 69groups, 307users, 295

AEK described, 430AEK passphrase, changing, 434AEK, backing up, 431application access control tokens,

configuring, 439approved_clients_only property, 169audit trails

interpreting, 397removing, 416

auditing, 387application events, 393

auditing, default, 391changing user home, 522


Index

cleaning up, 76client_pcaching_disabled

property, 178connecting to, 165content storage options, 204creating, 39creating cabinets/folders, 43database_owner in server.ini, 96dd_locales, setting, 44default_app_permit, 364defined, 37deleting

ACLs, 385dequeued items, 503format objects, 71groups, 309orphaned objects, 76users, 304

dmbasic method server,described, 130

docbase config object, 38dumping and loading, 48, 64dumping complete, 51dumping partial, 51enabling dmbnasic method

server, 135encryption key, 431getDocbaseMap method, 200groups, system-created, 41Java method server, described, 131LDAP directory server, adding, 332LDAP directory servers and, 323, 325limiting access using client

version, 168listing format objects, 69loading, 59loading from dump file, 62loading new, 61locales, adding, 593login ticket keys, managing, 436login tickets, configuring, 437macl_security_disabled property, 377method execution agents, 130methods, implementing, 136modifying

format objects, 70groups, 309users, 303

moving, 48multiple Content Servers, 85

name in server.ini, 96object defining configuration, 38object types

modifying, 73objects in new repository, 41obtaining list of groups in, 311organization, 42properties supporting LDAP

mappings, 337query performance, 79repository identifier in server.ini, 96restoring documents, 495sample dump script, 57security

folder security setting, 364starting connection brokers, 196State of the Repository tool, 514storage areas, configuration

options, 222synchronizing with directory

servers, 325trust mode, configuring, 437uninstalling, 33uninstalling DB2, affects of, 100user privileges

basic, 291extended, 293

usersrenaming, 304

users, adding multiple, 299users, system-created, 41Web Publisher, 48workflow package control,

configuring, 80repository configuration

audit_old_values property, 388login_ticket_cutoff property, 438

repository connection filecreating and maintaining, 155

repository connection file, for jobsequences, 148

repository encryption key, 431repository name, changing, 523repository operator

archive tool and, 284tool messages and, 450

repository sessionschanging configuration, 174connection brokers, specifying, 163connection pooling, configuring, 172


Index

dfc.session.pool.enable (dfc.properties), 172

max_count (dfc.properties key), 167session config objects, 174SSL default, setting, 166UNIX constraint on number of, 168

require_ticket property, 234required group ACL entries

aliases, constraint on use, 380described, 372

required group set ACL entriesaliases, constraint on use, 380described, 373

RESET_TICKET_KEY administrationmethod, 436

resetTicketKey (DFC method), 436respository connection file

commas and backslashes,escaping, 156

dcf_edit utility, 156respository sessions

requests for, configuring, 167restoring content files through archive

and restore, 277restrict_su_ticket_login property, 438restricted_folder_ids property, 298results log files, deleting, 499retainer objects

dump operations and, 50retentention storage areas

EMC Centera, 212retention periods

defined in EMC Centera storageareas, 213

defined in NetApp SnapLock storageareas, 216

retention policies, 231dm_retention_managers group, 294dm_retention_users group, 294dump operations and, 50EMC Centera store retention periods

and, 248NetApp SnapLock store retention

periods and, 257retention requirements

configuring for EMC Centerastores, 247

configuring for NetApp SnapLockstores, 256

retry_count property, 330

retry_interval property, 330return codes, for jobs in sequence, 144REVOKE (statement), 302rich media formats

format objects, 69richmedia_enabled property, 70roles, for privileged DFC, 295root certificate authority

obtaining, 340RPC calls, tracing, 546RSA Access Manager, see EMC RSA

Plug-in for DocumentumRSA plug-in modules, 348RSA plugin, see EMC RSA Plug-in for

Documentumrun_interval property, 151run_mode property, 151run_now property, 152

SSaveasnew method, 363

default group assignment and, 101saveasnew_retain_source_group

server.ini key, 101schedules, changing tool, 453scripts

archive, 282ContentServerStatus, 590dmclean, 266dmfilescan, 270dmqdocbroker, 590IndexAgentCtrl, 591preload utility, 62sample repository dump, 57TestConnection, 590

search bases, for LDAP, 334search_order (dfc.properties key), 191secondary LDAP servers, 330secure connection default, setting, 166secure connection mode

resetting, 110secure connection mode setting, 111secure connections

LDAP and, 330secure LDAP

certicate database location, 335setting up, 335

secure_connect_default (dfc.properties), 166


Index

secure_connect_property, 111security

ACL caching, 100ACL naming conventions, 379acl objects, 369ACLs, creating, 380application access control tokens,

enabling use, 439application control of SysObjects, 364auditing, 387changing

ACL object name, 379ACL owner name, 379

connection broker shutdown, 193connection brokers and, 198Create Cabinet (user privilege), 292Create Type (user privilege), 292default ACLs, 381deleting ACLs, 385digital signatures, 427electronic signatures,

customizing, 417execution agents, for methods, 133folder, 362 to 363granting/revoking user

privileges, 301modifying ACLs, 384overview, 359repository security levels, 362secure connections with LDAP, 330-security argument, 88signing audit trail entries, 394Superuser (user privilege), 292Sysadmin (user privilege), 292table permits, 386user privileges, 291

security_mode property, 362security_type property, 65SELECT (statement)

finding users with, 308server common area

removing files from, 88server config objects

changing, 109connection broker projection

properties, 115described, 85modifying, 110operator_name property and archive

tool, 284

setting checkpoint_intervalproperty, 116

setting keep_entry_intervalproperty, 116

server configurationapplication access control tokens,

enabling, 439global login tickets, restricting

superuser use, 438login_ticket_timeout property, 437max_login_ticket_timeout

property, 437server log files

deleting, 499described, 121trace messages, 532

server. ini filestart_index_agents key, 107

server_check_interval property, 180server_config_name key, 106server.ini

method_server_enabled, 105server.ini file

acl_update_threshold, 98changing, 110comment character, 89commit_read_operations key, 99connection broker entries, 93data_store key, 99database_conn key, 96database_name key, 97database_owner key, 96database_refresh_interval, 104defaulted keys, 103deferred_update_queue_size, 107defining projection targets, 116described, 84, 88docbase_id key, 96docbase_name key, 96enforce_four_digit_year key, 104gethostbyaddr key, 100history_cutoff key, 100history_sessions key, 100ignore_client_domain, 104index_store key, 99mail_notification key, 105max_sessions_heap_size, 101max_storage_info_count key, 105preserve_existing_types, 106


Index

saveasnew_retain_source_groupkey, 101

server_config_name key, 106service key, 98State of the Repository Report

tool, 514upd_last_chg_time_from_db key, 102use_estimate_search, 108use_group_address key, 102validate_database_user key, 102

server_login_ticket_version (server.inikey), 174

SERVER_STARTUP server.ini filesection, 89

server_startup_sleep_time key, 106service (server.ini key), 98service name

connection broker, 197server, 112

services file, 196servlets

adding to Java method server, 123session config objects

described, 174session log files

deleting, 499described, 532dump and load messages, 64

session servers, 84session threads, 84sessions

client_session_timeout (server.inikey), 103

dfc.properties file, 162max_sessions_heap_size (server.ini

key), 101modifying configuration, 174session config object, 174trusted logins, disabling, 166viewing historical, 100

set_file property, 280SET_OPTIONS

trace_method_server flag, 133Setup program, 33shared libraries

plug-ins, 220shared memory, login tickets, 107Shift_JIS

NEC extensions, 88short date formats, 175

described, 175UNIX defaults, 175Windows default, 175

shutdown method, 120shutting down

connection broker, requiringpasswords for, 193

connection brokers, 197servers, 118sessions, 120

signature creation methodcustom, creating, 425parameters passed to, 425tracing, 427

signature page templateadding/removing properties, 420appearance, modifying, 422append_to_body property, 424changing delimiters, 421default, described, 418document types, defining for, 423number of signatures,

configuring, 424signature page templates

creating, 427signature requirement support

simple signoffs, customizing, 428signature validation programs

customizing, 428signature_chk_loc property, 429signatures

audit trail entries, on, 394digital, 427verifying in distributed

environment, 415Signoff method

auditing, 391signoffs, simple

customizing, 428signature_chk_loc property, 429validation program, customizing, 428

single-repository configurationssignatures, verifying, 415

single-repository distributedconfigurationsAEK requirements, 431

sizeblob storage areas, 217

sleep interval (workflow agent)changing, 124


Index

sorting query results, 104space, reclaiming

in repositories, 77ssa policy objects, 227ssl_mode property, 335ssl_port property, 335standard arguments for jobs, 151, 449start_date property, 151start_index_agents (server.ini key), 107starting

additional Content Servers, 112connection brokers, 195Content Servers, 88, 111

startup.sh script, 131State of the Repository tool, 514statistics

updating, 519statistics, updating, 79stopping

connection brokers, 197jobs, 153servers, 118

storage algorithmprimary content, 229renditions, 231

storage algorithmsDFC policy engine, 228

storage areasblob set up, 236cleaning up, 266configuration options, summary, 222default, 232determining state, 264distributed store components,

replacing, 274EMC Centera, 212, 245file stores, creating, 237file stores, moving, 264filestore_01, 233full-text indexing and, 223moving files, 259naming conventions in file stores, 233naming conventions,

subdirectories, 272NetApp SnapLock, 255removing orphan files, 487replica_filestore_01, 233replicate_temp_store, 233setting offline/online, 263shared memory, 105

streaming_storage_01, 233thumbnail_storage_01, 233types, 74types of, 204use_extensions property, 237

storage typesblob store, 217distributed store, 218file store, 205linked store, 221turbo storage, 218

storage_id property, 223storeage objects

repository configuration, 39streaming content files

storage area default, 233URLs, format, 234

streaming_storage_01 storage area, 233string properties, lengthening, 75subcontent objects, 218success_return_codes property, 144success_status property, 144Superuser privilege

access permissions for, default, 293Superuser privileges

dm_superusers group, 294dm_superusers_dynamic group, 294

Superuser user privilegeadmingroup group and, 302dumping repositories, 48granting and revoking, 302loading repositories, 48

Superuser user privileges, 292superusers

ACL entry evaluation and, 376global login tickets, restricting use

of, 438Swap Info tool, 518Sybase

database connection strings, 97database_name server.ini key, 97dm_dbo alias, 73

Sysadmin privilegesdm_sysadmin group, 295

Sysadmin user privilege, 292SysObjects

a_storage_type property, 230access permission levels, 364application-level control, 364consistency checks, 554


Index

determining associated ACL, 381i_contents_id property, 266owner access evaluation, 375superuser access to, 376

system ACLscreating, 380defined, 379

system administrationtool suite, 33

System cabinetload operation and, 61location objects in, 64mount point objects in, 64tool reports in, 530

system events, 387 to 388, 393audit trails, viewing, 396

system-defined events, 609

Ttable permits

affects of loading operation, 61described, 362, 386dump and load, effect of, 387object-level permissions and, 387setting, 386

tablesfinding fragmented, 476updating statistics, 519

tablespacesidentifying, 99

targets, connection broker projection, 114TCP/IP service name in server.ini file, 98Temp cabinet

load operations and, 61tool trace logs, 530

template ACLs, 379creating, 380

TestConnection script, 590threads, session and Content Server, 84threads, tracing, 545thumbnail files

URLs, format, 234Thumbnail Server

new repositories and, 40thumbnail_storage_01 storage area, 233ticket_multiplier server.ini key, 107, 173tickets, number in shared memory, 107time zones, date storage and, 45timeouts, 437

See also validity periodsconnection to RDBMS, 106

tool suiteactivating/inactivating a tool, 453agent exec process and, 449Archive, 454Audit Management, 456Consistency Checker, 459Content Replication, 465Content Warning, 468create full-text events, 470Data Dictionary Publisher, 475Database Space Warning, 476dm_LDAPSynchronization, 479Dmclean, 482Dmfilescan tool, 487email messages, 452File Report, 493Group Rename, 498implementation, 449inactivating a tool, 453job log files, 452job reports, viewing, 451job sequences, using, 453Log Purge, 499overview, 33, 446Queue Management, 503queueperson argument, 450Remove Expired Retention

Objects, 506Rendition Management, 509reports, 451running on demand, 454schedule recovery, 450scheduling window, 450State of the Repository, 514Swap Info, 518tool schedules, setting, 453ToolSetup (install utility), 519Update Statistics tool, 519UserChgHomeDb, 522UserRename, 523Version Management, 525window_interval argument, 450

ToolSetup tool, 519trace files, 537

See also DFC tracingLDAP synchronization jobs, 345plug-in authentication modules, 351

trace_method_server flag, 133


Index

tracingcontent duplication checking and

prevention, 211Content Server options, 532DFC operations, 536DFC trace file format, 548job execution, 155LDAP authentication failover, 332method execution, 133rejected LDAP entries, 337workflow agent, 124

transactionsKill method and, 120loading and, 60server shutdown and, 120session server and, 120

translating IP addresses for connectionbrokers, 194

troubleshootingContent Server Manager, 33dump and load, 64peristent client caches, 184process monitoring scripts, 589repository dump operation, 59

trust_by_default property, 437Trusted Content Services

ACL evaluation and, 374ACLs, creating, 380ACLs, modifying, 384

trusted login, disabling, 166trusted logins, 351trusted logons, 318trusted_docbases property, 437turbo storage

described, 218renditions of content, 218setting up, 257size constraints, 218

turbo storage areascontent location, identifying, 224

type default ACL, 382type indexes

creating, 44type info object type

default_storage property, 230TYPE_EXTENT_SIZE server.ini file

section, 95TYPE_SPECIFIC_STORAGE server.ini

section, 94types, 72

See also user-defined typesadding properties, 74changing, 74Create Type user privilege, 292creating, 73default ACL, 382default ACL, changing, 74dropping properties, 75lengthening string properties, 75privileges to modify/create, 72removing from repository, 76specifying index location, 99

Uumask, see dfc.data.umask (dfc.properties)umask server.ini key, 101, 109Unaudit method

auditing execution of, 391unified login, enabling, 351uninstalling a repository, 33UNIX

constraint on number of sessions, 168UNIX clients

short date format, 175unlinking, folder security and, 363upd_last_chg_time_from_db (server.ini

key), 102Update Statistics administration tool, 79Update Statistics tool, 79, 519update_access_ date server.ini key, 107updating table statistics, 519URLs

base_url property, 238format, 234

use_estimate_search (server.ini key), 108use_extensions property

appending extension, 234file extensions and, 237setting up storage area, 258

use_group_address (server.ini key), 102Useacl method, 383user authentication

auth_protocol property, 318authentication name, 296authentication plug-ins, 314CA SiteMinder, 315certutil utility, 340dm_check_password file, 316domain-required mode, 318


Index

domains, affect of, 317failed attempts, limiting, 356failover, 331failover for LDAP, 330failover tracing, 332LDAP and federations, 328LDAP directory servers, 314LDAP options, 330LDAP synchronization job, 341no-domain required mode, 318options, 313password checking program,

creating, 319plug-in modules

described, 346secure LDAP

setting up, 335trusted logins, 351unified login, 351UNIX default mechanism, 316UNIX users against domain, 314UNIX users in domains, 320user_login_namee property, 290user_os_domain property, 318user_os_name property, 290Windows default mechanism, 317

user default ACL, 382user names

code page requirements, 290, 296overview, 290user_db_name property, 290user_login_name property, 290user_name property, 290user_os_namee property, 290

user privilegesaudit records, viewing and, 396basic, list of, 291Create Cabinet, 292Create Group, 292Create Type, 292described, 291, 362dm_create_cabinet group, 295dm_create_group group, 295dm_create_type group, 295dm_create_user group, 295extended, list of, 293GRANT statement, 302None, 292permissions to grant/revoke, 301REVOKE statement, 302

setting, 297, 302User Renametool, 304user type default ACL, 382user_address property, 296user_auth_case key, 108user_auth_target key, 108user_db_name property, 290, 298user-defined properties

adding, 74dropping, 75

user-defined typesadding properties, 74allowed supertypes, 72changing, 74changing default acl, 74creating, 72lengthening string properties, 75removing from repository, 76

user_global_unique_id property, 327user_login_doamin property, 327user_login_name property, 290, 296, 329user_name property, 290, 296user_os_domain property, 318user_os_name property, 290user_password property, 351user_privileges property, 302user_source property, 323, 327user_state property, 305 to 306user_validation_location property, 316user_xprivileges property, 302UserChgHomeDb tool, 522UserRename tool, 523users, 327, 336

See also LDAP usersACL entry evaluation and, 374activating, 306adding, 295adding multiple, 299authenticating, 108client capability, 299configuring for Windows NT domain

authentication, 323consistency checks, 552deactivated, adding to groups, 309deactivating or locking, 305default ACL, defining, 297default folder, defining, 298deleting, 304dm_create_user group, 295email address, 296


Index

extended privileges, 293granting/revoking privileges, 301home repository, changing, 522in-line password authentication, 351inactivating automatically, 306LDAP authentication, 328, 330LDAP authentication failover, 330LDAP synchronization, 325login failure, auditing, 391modifying, 303name properties, 290privileges, 291, 362properties

mapping LDAP attributes to, 335properties set by synchronization, 327renaming, 304, 523restricting folder access, 298system-created, 41tracing in DFC, 544user_db_name, setting, 298viewing connected, 34

utilitiescertutil, for ldap, 340dm_crypto_boot, 432dm_crypto_change_passphrase, 434dm_crypto_create, 433dm_encrypt_password, 354dm_error, 34dm_launch_docbroker, 195dm_stop_docbroker, 198dmclean, 266, 269dmdocbroker.exe, 195dmfilescan, 266dmtkgen, 441preload, 62

Vvalidate_database_user server.ini key, 102validate_user location object, 316.validation.interval (dfc.properties

key), 277validity periods, for login tickets

defining, 437verbosity, in DFC tracing, 546verifyAudit method, 415verifyESignature method

tracing, 427Version Management tool, 525

version numbers in State of the RepositoryReport tool, 514

versionsremoving outdated, 77Version Management tool, 525

View Audit user privileges, 293

Wwait_for_connect_timeout server.ini

key, 108Web Publisher repositories

dump and load operations notsupported, 48

web.xml file, trace parameter, 134wf_agent_worker_threads property, 124wf_package_control_enabled

property, 80wf_sleep_interval property, 124window_interval argument, 450Windows clients

short date format, 175Windows domain

authenticating in, 317Windows NT

file systems, 238Macintoshes and, 238

work itemsemail notification, disabing, 105recovering claimed work items, 125

worker sessions (workflow agent)changing number of, 124

workflow agentconfiguring, 123disabling, 124sleep interval, changing, 124tracing, 124worker sessions, changing

number, 124workflow definitions

package_control property, 80workflow methods, return values, 137,

141workflows

audit trail entries, interpreting, 405consistency checks, 557dmclean and, 267package name control, configuring, 80removing aborted workflows, 77


Index

use_group_address (server.inikey), 102

workflow agent, 123world_table_permit property, 386write_interval key, 183

write_max_attempts (dfc.propertieskey), 253

write_sleep_interval (dfc.propertieskey), 253
