OpenText™ Documentum™ Server

Administration and Configuration

Guide

This guide describes how to configure and administer

Documentum Server.

EDCCS200200-AGD-EN-01
OpenText™ Documentum™ Server
Administration and Configuration Guide
EDCCS200200-AGD-EN-01
Rev.: 2020-Mar-07
This documentation has been created for software version 20.2.
It is also valid for subsequent software versions as long as no new document version is shipped with the product or is
published at https://knowledge.opentext.com.

Open Text Corporation

275 Frank Tompa Drive, Waterloo, Ontario, Canada, N2L 0A1

Tel: +1-519-888-7111
Toll Free Canada/USA: 1-800-499-6544 International: +800-4996-5440
Fax: +1-519-888-0677
Support: https://support.opentext.com
For more information, visit https://www.opentext.com

Copyright © 2020 Open Text. All Rights Reserved.

Trademarks owned by Open Text.

One or more patents may cover this product. For more information, please visit https://www.opentext.com/patents.

Disclaimer

No Warranties and Limitation of Liability

Every effort has been made to ensure the accuracy of the features and techniques presented in this publication. However,
Open Text Corporation and its affiliates accept no responsibility and offer no warranty whether expressed or implied, for the
accuracy of this publication.
 Table of Contents

PRE Preface xxvii

i Intended audience ........................................................................ xxvii
ii Revision history ........................................................................... xxvii

1 Administration and Configuration Tools ............................... 29

1.1 Introduction ..................................................................................... 29
1.2 Documentum Administrator .............................................................. 30
1.3 Documentum Server Manager ......................................................... 30
1.3.1 Starting Documentum Server Manager ............................................. 30
1.4 Tool suite ....................................................................................... 31

2 Managing Connection Brokers .............................................. 33

2.1 Connection brokers ......................................................................... 33
2.2 The connection broker initialization file ............................................. 34
2.2.1 Invoking the initialization file ............................................................. 35
2.2.2 Configuring shutdown security (Linux only) ....................................... 35
2.2.3 Restricting server access ................................................................. 35
2.2.4 Certificate-based SSL configuration .................................................. 36
2.2.5 Supported connection broker connection modes ............................... 36
2.2.6 Translating IP addresses ................................................................. 37
2.3 Connection broker projection targets ................................................ 38
2.4 Server proximity .............................................................................. 38
2.5 Restarting a connection broker ......................................................... 39
2.5.1 Restarting a connection broker running as a Windows service ........... 39
2.5.2 Restarting a connection broker that is not running as a Windows
service ........................................................................................... 39
2.5.3 Restarting a connection broker on a Linux platform ........................... 39
2.6 Adding a connection broker for one session ...................................... 40
2.7 Implementing connection broker failover ........................................... 40
2.8 Starting additional connection brokers .............................................. 40
2.9 Shutting down connection brokers .................................................... 42
2.9.1 To stop a connection broker running as a service on Windows: .......... 42
2.9.2 To stop a connection broker started from the Windows command
line: ................................................................................................ 42
2.9.3 To stop a connection broker on a Linux platform: .............................. 42
2.9.3.1 Stopping multiple connection brokers on Linux .................................. 43
2.10 Requesting connection broker information ........................................ 43

EDCCS200200-AGD-EN-01 Administration and Configuration Guide iii

Table of Contents

3 Managing Documentum Servers ............................................ 45

3.1 Documentum Servers ...................................................................... 45
3.2 Starting a server ............................................................................. 45
3.3 Configuring licenses ........................................................................ 46
3.4 Managing Documentum Servers ...................................................... 47
3.4.1 Adding or modifying Documentum Servers ....................................... 48
3.4.2 Duplicating a server configuration object ........................................... 49
3.4.3 Modifying general server configuration information ............................ 49
3.4.4 Creating or modifying connection broker projections .......................... 56
3.4.5 Creating or modifying network locations ............................................ 56
3.4.6 Creating or modifying application servers .......................................... 56
3.4.7 Creating or modifying cached types .................................................. 57
3.4.8 Creating or modifying locations ........................................................ 57
3.4.9 Creating or modifying far stores ....................................................... 58
3.4.10 Moving a server to dormant and active states ................................... 58
3.4.11 Enabling or disabling save operation for a Documentum Server in
dormant state .................................................................................. 59
3.4.12 Projecting active or dormant state of Documentum Server to
connection broker ........................................................................... 59
3.4.13 Viewing server and connection broker log files .................................. 60
3.4.14 Deleting a server configuration object ............................................... 60
3.4.14.1 Confirming object deletion ............................................................... 60
3.4.15 Configuring a server as a process engine ......................................... 60
3.4.16 Disabling a process engine server .................................................... 61
3.4.17 Changing ACL or groups in a HA setup ............................................ 61
3.5 The server.ini file ............................................................................. 61
3.5.1 Modifying the server.ini file .............................................................. 62
3.5.2 SERVER_STARTUP section keys .................................................... 63
3.5.2.1 concurrent_sessions ....................................................................... 82
3.5.2.2 database_refresh_interval ............................................................... 83
3.5.2.3 umask ............................................................................................ 83
3.5.3 DOCBROKER_PROJECTION_TARGET section keys ...................... 84
3.5.4 FUNCTION_EXTENT_SIZE and TYPE_EXTENT_SIZE sections ....... 85
3.6 Managing additional Documentum Servers ....................................... 86
3.7 Managing Documentum Server in a virtual deployment ...................... 87
3.7.1 Overview ........................................................................................ 87
3.7.2 Operational status ........................................................................... 88
3.7.2.1 Privileged group .............................................................................. 94
3.7.3 Monitoring performance ................................................................... 94
3.7.3.1 Using the DFC performance monitoring API ...................................... 95
3.7.4 Using the DFC operational status API ............................................... 96
3.7.5 Restarting Documentum Server components in virtual deployments ... 97

iv OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

3.7.5.1 Overview ........................................................................................ 97

3.7.5.2 Restarting Documentum Server on Windows .................................... 97
3.7.5.2.1 Start connection brokers .................................................................. 98
3.7.5.2.2 Start Documentum Server and repositories ....................................... 98
3.7.5.2.3 Start the JMS application server ....................................................... 98
3.7.5.2.4 Start the index agents ...................................................................... 99
3.7.5.3 Restarting Documentum Server on Linux .......................................... 99
3.7.5.3.1 Start connection brokers .................................................................. 99
3.7.5.3.2 Start Documentum Server and repositories ..................................... 100
3.7.5.3.3 Start the JMS application server ..................................................... 100
3.7.5.3.4 Start the index agents .................................................................... 100
3.8 Server load balancing and failover .................................................. 101
3.9 Shutting down a server .................................................................. 101
3.9.1 Shutting down a server running on Windows ................................... 102
3.9.2 Shutting down a server running on Linux ........................................ 102
3.9.3 Creating a shut-down script ........................................................... 102
3.10 Clearing the server common area .................................................. 103
3.11 Managing the WildFly application server ......................................... 103
3.11.1 Starting and stopping the WildFly application server ........................ 104
3.12 Server log files .............................................................................. 105
3.13 The dm_error utility ....................................................................... 105
3.14 Improving performance on Oracle and PostgreSQL databases ........ 105

4 Managing Repositories ......................................................... 107

4.1 Repositories ................................................................................. 107
4.2 Managing repositories ................................................................... 107
4.2.1 Viewing or modifying the repository configuration ............................ 108
4.2.2 Modifying repository synchronization .............................................. 115
4.2.3 Moving a repository to dormant and active states ............................ 116
4.2.4 Enabling a repository as a global registry ........................................ 117
4.2.5 Repository content ........................................................................ 117
4.2.6 Type indexes ................................................................................ 119
4.2.7 Date values .................................................................................. 119
4.2.8 Moving or duplicating a repository .................................................. 120
4.2.8.1 Supporting object types ................................................................. 120
4.2.8.2 Dumping objects under retention .................................................... 121
4.2.8.3 Aspects and dump operations ........................................................ 121
4.2.8.4 Dumping an entire repository ......................................................... 121
4.2.8.5 Dumping specific objects ............................................................... 121
4.2.8.5.1 Setting the type property ................................................................ 122
4.2.8.5.2 Setting the predicate properties ...................................................... 123
4.2.8.6 Content files and dumping ............................................................. 124

EDCCS200200-AGD-EN-01 Administration and Configuration Guide v

Table of Contents

4.2.8.6.1 Dumping without content ............................................................... 124

4.2.8.6.2 Including content ........................................................................... 125
4.2.8.6.3 Compressing content .................................................................... 125
4.2.8.7 Setting the cache size ................................................................... 125
4.2.8.8 Using non-restartable dump ........................................................... 126
4.2.8.9 Using a script to create a dump file ................................................. 126
4.2.8.9.1 Sample script for a partial repository dump ..................................... 127
4.2.8.10 If the server crashes during a dump operation ................................. 128
4.2.8.11 Moving the dump file ..................................................................... 129
4.2.8.12 Loading a repository ...................................................................... 129
4.2.8.12.1 Refreshing repository objects from a dump file ................................ 130
4.2.8.12.2 Loading job objects ....................................................................... 130
4.2.8.12.3 Loading registered tables ............................................................... 130
4.2.8.12.4 Turning off save event generation during load operations ................ 130
4.2.8.12.5 Loading a new repository ............................................................... 131
4.2.8.12.5 The preLoad utility ......................................................................... 131
.1
4.2.8.12.6 Load procedure for new repositories ............................................... 132
4.2.8.12.7 DocApps ...................................................................................... 133
4.2.8.13 Generating dump and load trace messages .................................... 133
4.2.9 Repository maintenance ................................................................ 134
4.2.10 Checking consistency .................................................................... 136
4.2.10.1 Running the job from a command line ............................................. 136
4.2.10.2 Example report ............................................................................. 136
4.2.11 Changing the repository owner password ....................................... 141
4.3 Adding repositories ....................................................................... 141
4.4 Federations .................................................................................. 142
4.4.1 Creating or modifying federations ................................................... 142
4.4.2 Adding, modifying, or deleting federation members ......................... 144
4.4.3 Deleting Federations ..................................................................... 144
4.4.4 Connecting to the governing repository or a federation member ....... 144
4.4.5 Choosing user subtypes ................................................................ 144
4.4.6 Choosing repository federation members ........................................ 144

5 Managing Sessions ............................................................... 145

5.1 The dfc.properties file .................................................................... 145
5.2 Managing connection requests ....................................................... 146
5.3 Defining the secure connection default for connection requests ........ 146
5.4 Modifying the connection request queue size .................................. 147
5.5 Stopping a session server .............................................................. 147

6 Managing Java Method Servers ........................................... 149

6.1 Java Method Servers .................................................................... 149

vi OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

6.1.1 Viewing Java method server information ......................................... 150

6.1.2 Modifying a Java Method Server configuration ................................ 150
6.1.3 Adding or modifying Associated Content Servers ............................ 152
6.1.4 Viewing active Java method servers ............................................... 152
6.2 Java methods ............................................................................... 154
6.3 Recording Java method output ....................................................... 154
6.4 Deploying Java methods ............................................................... 155
6.5 Adding additional servlets to the Java method server ...................... 155

7 Managing LDAP Servers ....................................................... 157

7.1 LDAP servers ............................................................................... 157
7.1.1 Viewing LDAP server configurations ............................................... 158
7.1.2 Adding or modifying LDAP server configurations ............................. 159
7.1.2.1 LDAP Server Configuration properties ............................................ 160
7.1.2.2 LDAP authentication using Digest-MD5 mechanism ........................ 163
7.1.2.3 LDAP Server Sync & Authentication properties ............................... 163
7.1.2.4 LDAP Nested Groups .................................................................... 165
7.1.2.5 LDAP Server mapping properties ................................................... 165
7.1.2.6 LDAP Server failover properties ..................................................... 167
7.1.3 Mapping LDAP Servers ................................................................. 169
7.1.3.1 Mapping guidelines ....................................................................... 170
7.1.3.2 Using Search Builder ..................................................................... 170
7.1.3.3 Adding or modifying repository property mapping ............................ 170
7.1.4 Configuring secondary LDAP servers ............................................. 171
7.1.5 Changing the binding password ..................................................... 172
7.1.6 Forcing LDAP server synchronization ............................................. 172
7.1.7 Duplicating LDAP configurations .................................................... 172
7.1.8 Deleting LDAP configurations ........................................................ 172
7.1.9 Using LDAP directory servers with multiple Documentum Servers .... 173
7.1.10 LDAP proxy server support ............................................................ 173
7.1.11 Configuring LDAP synchronization for Kerberos users ..................... 173
7.2 LDAP certificate database management ......................................... 174
7.2.1 Viewing LDAP certificates .............................................................. 174
7.2.2 Importing LDAP certificates ............................................................ 174
7.2.3 Using multiple LDAP servers in SSL mode ...................................... 175
7.2.4 Replacing or removing LDAP certificates ........................................ 175

8 Managing MSA for Documentum Services ......................... 177

8.1 Prerequisites ................................................................................ 177
8.2 Creating and associating MSA with Microsoft Windows Server ......... 178
8.3 Removing MSA ............................................................................. 181

EDCCS200200-AGD-EN-01 Administration and Configuration Guide vii

Table of Contents

9 OpenText Directory Services Integration with

Documentum Server ............................................................. 183
9.1 Overview ...................................................................................... 183
9.2 Configuring OTDS integration with Documentum Server .................. 183
9.3 Supported functions ...................................................................... 184
9.4 Configuring OTDS authentication in Documentum Server ................ 185
9.5 OTDS users authentication ............................................................ 186
9.6 Troubleshooting ............................................................................ 186

10 Distributed Content Configuration ...................................... 187

10.1 Network locations .......................................................................... 187
10.1.1 Creating, viewing, or modifying network locations ............................ 188
10.1.2 Copying network locations ............................................................. 190
10.1.3 Deleting network locations ............................................................. 190
10.2 ACS servers ................................................................................. 190
10.2.1 Viewing or modifying the ACS server configuration properties .......... 192
10.2.2 ACS projections and stores ............................................................ 193
10.2.3 Designating connection brokers for an ACS server .......................... 194
10.2.4 Choosing network locations ........................................................... 196
10.3 BOCS servers ............................................................................... 196
10.3.1 Creating, viewing, or modifying BOCS servers ................................ 196
10.3.2 Setting BOCS server security ......................................................... 198
10.3.3 Setting BOCS server communication protocols ............................... 199
10.3.4 Deleting BOCS servers ................................................................. 199
10.4 Configuring distributed transfer settings .......................................... 200
10.5 Messaging server configuration ...................................................... 200

11 User Management .................................................................. 203

11.1 Administering users, groups, roles, and sessions ............................ 203
11.2 Users ........................................................................................... 204
11.2.1 Locating users .............................................................................. 205
11.2.2 Creating or modifying users ........................................................... 205
11.2.3 Creating global users .................................................................... 212
11.2.4 Setting default permissions for folders and cabinets ........................ 212
11.2.5 Importing users ............................................................................. 213
11.2.5.1 Import file format ........................................................................... 216
11.2.6 Deleting users ............................................................................... 218
11.2.7 Reassigning objects to another user ............................................... 218
11.2.8 Changing the home repository of a user ......................................... 218
11.2.9 Activating or deactivating a user account ........................................ 218
11.2.10 Viewing groups, workflows, alias sets, permission sets, and
documents of a user ...................................................................... 219

viii OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

11.2.11 Viewing or deleting change home repository logs ............................ 219

11.2.12 Viewing user reassign logs ............................................................ 219
11.2.13 Reassign reports ........................................................................... 219
11.3 Groups ......................................................................................... 219
11.3.1 Dynamic groups ............................................................................ 221
11.3.2 Privileged groups .......................................................................... 221
11.3.3 Locating groups ............................................................................ 223
11.3.4 Viewing group memberships .......................................................... 223
11.3.5 Creating, viewing, or modifying groups ........................................... 224
11.3.6 Adding users, groups, or roles to a group ........................................ 226
11.3.7 Removing users from a group ........................................................ 226
11.3.8 Deleting groups ............................................................................. 226
11.3.9 Reassigning the objects owned by a group ..................................... 226
11.3.10 Viewing group reassign logs .......................................................... 226
11.4 Roles ........................................................................................... 227
11.4.1 Creating, viewing, or modifying roles .............................................. 227
11.4.2 Adding users, groups, or roles to a role ........................................... 229
11.4.3 Reassigning roles ......................................................................... 229
11.4.4 Deleting roles ................................................................................ 229
11.5 Modules roles ............................................................................... 229
11.5.1 Creating, viewing, or modifying module roles .................................. 230
11.5.2 Reassigning module roles .............................................................. 231
11.5.3 Deleting module roles .................................................................... 231
11.6 Sessions ...................................................................................... 231
11.6.1 Viewing user sessions ................................................................... 232
11.6.2 Viewing user session information ................................................... 232
11.6.3 Viewing user session logs .............................................................. 233
11.6.4 Killing user sessions ...................................................................... 233

12 Security and Authentication ................................................. 235

12.1 Object permissions ........................................................................ 235
12.2 Changing default operating system permits on public directories
and files (Linux only) ..................................................................... 238
12.3 Folder security .............................................................................. 238
12.4 Additional access control entries .................................................... 239
12.5 Default alias sets ........................................................................... 240
12.6 Access evaluation process ............................................................ 240
12.7 Permission sets ............................................................................ 242
12.8 Authenticating in domains .............................................................. 242
12.8.1 No-domain required mode ............................................................. 243
12.8.2 Domain-required mode .................................................................. 243
12.9 Principal authentication ................................................................. 243

EDCCS200200-AGD-EN-01 Administration and Configuration Guide ix

Table of Contents

12.9.1 Client rights domains ..................................................................... 244

12.9.1.1 Creating a client rights domain ....................................................... 244
12.9.1.2 Enabling or disabling a client rights domain ..................................... 245
12.9.1.3 Deleting a client rights domain ....................................................... 245
12.9.1.4 Adding member repositories .......................................................... 245
12.9.1.5 Viewing repository memberships .................................................... 246
12.9.1.6 Removing a member repository from a client rights domain ............. 246
12.10 Privileged clients ........................................................................... 246
12.10.1 Adding privileged DFC clients ........................................................ 247
12.10.2 Configuring privileged client trusted login and trusted server
privileges ...................................................................................... 248
12.10.3 Approving or denying privileged clients ........................................... 248
12.10.4 Deleting a DFC client and certificate ............................................... 249
12.11 Administrator access sets .............................................................. 249
12.11.1 Creating, viewing, or modifying administrator access sets ................ 250
12.11.2 Deleting administrator access sets ................................................. 251
12.12 Managing Authentication Plug-Ins, Signatures, and Encryption Keys 252
12.12.1 Using authentication plug-ins ......................................................... 252
12.12.1.1 Plug-in scope ................................................................................ 252
12.12.1.2 Identifying a plug-in ....................................................................... 252
12.12.1.2. Defining a plug-in identifier ............................................................ 253
1
12.12.1.3 Using the RSA plug-in ................................................................... 253
12.12.1.4 Using the CA SiteMinder plug-in ..................................................... 254
12.12.1.5 Using the CAS plug-in ................................................................... 254
12.12.1.5. Authentication flow using CAS plug-in ............................................ 255
1
12.12.1.5. Custom configurations for CAS plug-in ........................................... 256
2
12.12.1.5. Documentum Server configuration ................................................. 256
2.1
12.12.1.5. LDAP configuration ....................................................................... 257
2.2
12.12.1.6 Implementing a custom authentication plug-in ................................. 258
12.12.1.6. Writing the authentication plug-in ................................................... 259
1
12.12.1.6. Internationalization ........................................................................ 260
1.1
12.12.1.7 Tracing authentication plug-in operations ........................................ 260
12.12.2 Managing encrypted passwords ..................................................... 260
12.12.2.1 Using encryptPassword ................................................................. 261
12.12.2.2 Using clear text passwords ............................................................ 262
12.12.2.3 Changing an encrypted password .................................................. 262

x OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

12.12.3 Implementing signature support ..................................................... 264

12.12.3.1 Using electronic signatures ............................................................ 265
12.12.3.2 Customizing electronic signatures .................................................. 266
12.12.3.2. Configuring the number of allowed signatures ................................. 266
1
12.12.3.2. Creating custom signature creation methods and associated
2 signature page templates ............................................................... 267
12.12.3.2. Publishing dynamic information ...................................................... 269
3
12.12.3.2. Tracing electronic signature operations ........................................... 269
4
12.12.3.2. Setting the Java memory allocation ................................................ 269
5
12.12.3.3 Supporting electronic signatures .................................................... 269
12.12.3.4 Regenerating audit signatures ....................................................... 270
12.12.3.5 Customizing simple signoffs ........................................................... 270
12.12.3.5. Customizing the signature validation program ................................. 271
1
12.12.3.5. Registering for notification ............................................................. 271
2
12.12.3.5. Querying the audit trail for signoffs ................................................. 271
3
12.12.4 Managing encryption keys ............................................................. 272
12.12.4.1 The AEK ....................................................................................... 272
12.12.4.1. Sharing the AEK or passphrase ..................................................... 273
1
12.12.4.1. The AEK and distributed sites ........................................................ 273
2
12.12.4.1. Backing up the AEK ...................................................................... 273
3
12.12.4.2 Repository encryption keys ............................................................ 274
12.12.4.3 Encryption utilities ......................................................................... 274
12.12.4.4 Using dm_crypto_boot ................................................................... 275
12.12.4.5 Using dm_crypto_create ................................................................ 276
12.12.4.6 Changing a passphrase ................................................................. 277
12.12.5 Managing the login ticket key ......................................................... 279
12.12.5.1 Exporting and importing a login ticket key ....................................... 279
12.12.5.2 Resetting a login ticket key ............................................................ 279
12.12.6 Configuring application access control token use ............................ 280
12.12.6.1 Enabling AAC token use by a server .............................................. 280
12.12.6.1. Enabling machine-only AAC tokens ................................................ 280
1
12.12.6.2 Enabling token retrieval by the client library .................................... 280
12.12.6.3 Generating tokens for storage ........................................................ 282

EDCCS200200-AGD-EN-01 Administration and Configuration Guide xi

Table of Contents

12.12.6.3. Naming the output file .................................................................... 284

1
12.12.6.4 Storing tokens generated by dmtkgen ............................................. 284
12.13 Enabling Kerberos Authentication .................................................. 285
12.13.1 Overview ...................................................................................... 285
12.13.1.1 Documentum Kerberos architecture ............................................... 286
12.13.1.2 Procedure to enable Kerberos SSO ................................................ 287
12.13.1.2. Creating Kerberos user accounts ................................................... 288
1
12.13.1.2. Creating Kerberos users in a repository .......................................... 288
1.1
12.13.1.2. Configuring krb5.ini file .................................................................. 288
2
12.13.1.2. Configuring a service principal name of repository and *.keytab file .. 289
3
12.13.1.2. Mapping the SPN of repository to a user name ............................... 290
3.1
12.13.1.2. Creating the *.keytab file for the repository ...................................... 290
3.2
12.13.1.2. Configuring Kerberos for Documentum Server on Linux ................... 292
4
12.13.1.2. Reinitializing Documentum Server .................................................. 293
5
12.14 Enabling SAML Authentication ....................................................... 293
12.14.1 Overview ...................................................................................... 293
12.14.2 Documentum SAML architecture .................................................... 294
12.14.3 Configuring Name ID ..................................................................... 295
12.14.4 Configuring for encrypted assertions .............................................. 295
12.14.5 Troubleshooting ............................................................................ 296

13 Logging and Tracing ............................................................. 297

13.1 Introduction ................................................................................... 297
13.2 Documentum Server logging and tracing ........................................ 297
13.2.1 Tracing from the startup command line ........................................... 298
13.2.2 Using the setServerTraceLevel method .......................................... 299
13.2.3 Using the SET_OPTIONS method .................................................. 300
13.2.4 Examples of server tracing ............................................................ 300
13.2.5 Determining active tracing options .................................................. 301
13.3 DFC logging ................................................................................. 301
13.4 DFC tracing .................................................................................. 301
13.4.1 Enabling DFC tracing .................................................................... 301
13.4.2 Logging appender options ............................................................. 302
13.4.3 Defining file creation mode ............................................................ 303
13.4.4 Defining the trace file timestamp format .......................................... 304

xii OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

13.4.4.1 Defining the date format ................................................................ 305

13.4.5 Configuring method tracing ............................................................ 306
13.4.6 Tracing users by name .................................................................. 307
13.4.7 Tracing threads by name ............................................................... 307
13.4.8 Including the session ID ................................................................. 308
13.4.9 Tracing RPC calls ......................................................................... 308
13.4.10 Including stack trace for exceptions ................................................ 308
13.4.11 Setting verbosity ........................................................................... 309
13.4.12 Directing categories to the trace file ................................................ 309
13.4.13 Log file entry format ...................................................................... 310
13.4.14 Trace file examples ....................................................................... 311

14 Audit Management ................................................................ 313

14.1 Auditing ........................................................................................ 313
14.2 Audit events .................................................................................. 313
14.3 Audit trails .................................................................................... 314
14.4 Audit properties ............................................................................. 314
14.5 Events audited by default ............................................................... 315
14.5.1 Disabling or modifying default auditing ............................................ 316
14.6 Auditing by object type .................................................................. 316
14.7 Auditing by object instance ............................................................ 318
14.8 Auditing by events selected for all objects in the repository .............. 319
14.9 Search audit ................................................................................. 319
14.10 Audit policies ................................................................................ 320
14.10.1 Creating, modifying, or deleting an audit policy ................................ 321
14.10.2 Audit Policy example ..................................................................... 322
14.11 Registering audits ......................................................................... 322
14.12 Adding, modifying, or removing audits ............................................ 323
14.13 Verifying or purging audit trails ....................................................... 323
14.14 Interpreting audit trails of DFC method, workflow, and lifecycle
events .......................................................................................... 324
14.14.1 Audit trails for events generated by non-workflow or lifecycle
methods ....................................................................................... 324
14.14.2 Lifecycle audit trails ....................................................................... 330
14.14.3 Workflow audit trails ...................................................................... 331
14.15 Interpreting ACL and group audit trails ............................................ 338

15 Methods and Jobs ................................................................. 341

15.1 Methods ....................................................................................... 341
15.1.1 Creating or modifying methods ....................................................... 341
15.1.2 Importing method content .............................................................. 345
15.1.3 Running methods .......................................................................... 345
15.1.4 Viewing the results of a method ..................................................... 345

EDCCS200200-AGD-EN-01 Administration and Configuration Guide xiii

Table of Contents

15.1.5 Exporting method content .............................................................. 346

15.1.6 Editing method content .................................................................. 346
15.1.7 Checking in method content ........................................................... 346
15.1.8 Deleting methods .......................................................................... 346
15.2 Method execution agents ............................................................... 346
15.3 Administration methods ................................................................. 347
15.3.1 Viewing administration methods ..................................................... 347
15.3.2 Running administration methods .................................................... 347
15.3.2.1 CAN_FETCH ................................................................................ 348
15.3.2.2 CLEAN_LINKS ............................................................................. 349
15.3.2.3 DELETE_REPLICA ....................................................................... 349
15.3.2.4 DESTROY_CONTENT .................................................................. 349
15.3.2.5 EXPORT_TICKET_KEY ................................................................ 349
15.3.2.6 GET_PATH .................................................................................. 350
15.3.2.7 IMPORT_REPLICA ....................................................................... 350
15.3.2.8 IMPORT_TICKET_KEY ................................................................. 350
15.3.2.9 MIGRATE_CONTENT ................................................................... 350
15.3.2.10 PURGE_CONTENT ...................................................................... 356
15.3.2.11 REPLICATE ................................................................................. 356
15.3.2.12 RESTORE_CONTENT .................................................................. 356
15.3.2.13 SET_STORAGE_STATE ............................................................... 357
15.3.2.14 DB_STATS ................................................................................... 357
15.3.2.15 DROP_INDEX .............................................................................. 358
15.3.2.16 EXEC_SQL .................................................................................. 358
15.3.2.17 FINISH_INDEX_MOVES ............................................................... 358
15.3.2.18 GENERATE_PARTITION_SCHEME_SQL ..................................... 359
15.3.2.19 MAKE_INDEX .............................................................................. 362
15.3.2.20 MOVE_INDEX .............................................................................. 362
15.3.2.21 ESTIMATE_SEARCH .................................................................... 362
15.3.2.22 MARK_FOR_RETRY .................................................................... 363
15.3.2.23 MODIFY_TRACE .......................................................................... 363
15.3.2.24 GET_LAST_SQL .......................................................................... 363
15.3.2.25 LIST_RESOURCES ...................................................................... 364
15.3.2.26 LIST_TARGETS ........................................................................... 364
15.3.2.27 SET_OPTIONS ............................................................................. 364
15.3.2.28 RECOVER_AUTO_TASKS ............................................................ 365
15.3.2.29 WORKFLOW_AGENT_MANAGEMENT ......................................... 366
15.3.2.30 REGEN_EXPRESSIONS .............................................................. 366
15.3.2.31 Administration Methods Results Page ............................................ 367
15.3.2.32 Choosing a file on the server file system ......................................... 368
15.4 Jobs ............................................................................................. 368
15.4.1 Job descriptions ............................................................................ 369

xiv OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

15.4.1.1 ACL replication (dm_ACLReplication) ............................................. 369

15.4.1.2 ACL replication (dm_ACLRepl_repository) ...................................... 369
15.4.1.3 Asynchronous Write (dm_AsynchronousWrite) ................................ 369
15.4.1.4 Audit Management ........................................................................ 370
15.4.1.4.1 Arguments .................................................................................... 371
15.4.1.4.2 Guidelines .................................................................................... 373
15.4.1.4.3 Report sample .............................................................................. 373
15.4.1.5 Consistency Checker .................................................................... 374
15.4.1.5.1 Running the job from a command line ............................................. 374
15.4.1.5.2 Arguments .................................................................................... 374
15.4.1.5.3 Report sample .............................................................................. 375
15.4.1.6 Content Replication ....................................................................... 379
15.4.1.6.1 Arguments .................................................................................... 380
15.4.1.6.2 Report sample .............................................................................. 381
15.4.1.7 Content Warning ........................................................................... 382
15.4.1.7.1 Arguments .................................................................................... 382
15.4.1.7.2 Report sample .............................................................................. 383
15.4.1.8 Data Dictionary Publisher .............................................................. 384
15.4.1.8.1 Arguments .................................................................................... 384
15.4.1.8.2 Report sample .............................................................................. 384
15.4.1.9 Database Space Warning .............................................................. 385
15.4.1.9.1 Arguments .................................................................................... 385
15.4.1.9.2 Report sample .............................................................................. 386
15.4.1.9.3 Inbox and email message samples ................................................. 387
15.4.1.10 Distributed operations (dm_DistOperations) .................................... 387
15.4.1.11 Archive ......................................................................................... 387
15.4.1.11. Arguments .................................................................................... 388
1
15.4.1.11. Guidelines .................................................................................... 389
2
15.4.1.12 Dmclean ....................................................................................... 389
15.4.1.12. Arguments .................................................................................... 390
1
15.4.1.12. Guidelines .................................................................................... 390
2
15.4.1.12. Report sample .............................................................................. 391
3
15.4.1.13 Dmfilescan ................................................................................... 392
15.4.1.13. Arguments .................................................................................... 393
1
15.4.1.13. Guidelines .................................................................................... 394
2

EDCCS200200-AGD-EN-01 Administration and Configuration Guide xv

Table of Contents

15.4.1.13. Report sample .............................................................................. 395

3
15.4.1.14 Fix folder (dm_fixfolder) ................................................................. 397
15.4.1.14. Arguments .................................................................................... 397
1
15.4.1.15 Federation copy (dm_FederationCopy) ........................................... 397
15.4.1.16 Federation export (dm_FederationExport) ....................................... 398
15.4.1.17 Federation import (dm_FederationImport) ....................................... 398
15.4.1.18 Federation status (dm_FederationStatus) ....................................... 398
15.4.1.19 Federation update (dm_FederationUpdate) ..................................... 398
15.4.1.20 File Report .................................................................................... 398
15.4.1.20. Guidelines .................................................................................... 399
1
15.4.1.20. Usage notes ................................................................................. 399
2
15.4.1.20. Creating incremental or partial-repository reports ............................ 399
2.1
15.4.1.20. Using a report to restore a document .............................................. 400
2.2
15.4.1.20. Arguments .................................................................................... 400
3
15.4.1.20. Report sample .............................................................................. 402
4
15.4.1.21 Group Rename ............................................................................. 403
15.4.1.21. Arguments .................................................................................... 403
1
15.4.1.22 Dm_LDAPSynchronization ............................................................ 403
15.4.1.22. Arguments .................................................................................... 404
1
15.4.1.22. Executing dm_LDAPSynchronization manually ............................... 407
2
15.4.1.22. Explicitly specifying LDAP servers in -source_directory .................... 407
3
15.4.1.23 Log Purge ..................................................................................... 408
15.4.1.23. Arguments .................................................................................... 409
1
15.4.1.23. Guidelines .................................................................................... 409
2
15.4.1.23. Report sample .............................................................................. 409
3
15.4.1.24 Queue Management ...................................................................... 411
15.4.1.24. Arguments .................................................................................... 412
1
15.4.1.24. Guidelines .................................................................................... 413
2

xvi OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

15.4.1.24. Report sample .............................................................................. 414

3
15.4.1.25 Remove expired retention objects .................................................. 414
15.4.1.25. Arguments .................................................................................... 415
1
15.4.1.25. Guidelines .................................................................................... 415
2
15.4.1.25. Report sample .............................................................................. 416
3
15.4.1.26 Rendition Manager ........................................................................ 417
15.4.1.26. Arguments .................................................................................... 417
1
15.4.1.26. Guidelines .................................................................................... 420
2
15.4.1.26. Report sample .............................................................................. 421
3
15.4.1.27 SCS log purge (dm_SCSLogPurgeJob) .......................................... 422
15.4.1.28 State of Repository Report ............................................................. 422
15.4.1.28. Arguments .................................................................................... 422
1
15.4.1.28. Report sample .............................................................................. 423
2
15.4.1.29 Swap Info ..................................................................................... 426
15.4.1.29. Arguments .................................................................................... 426
1
15.4.1.29. Report sample .............................................................................. 426
2
15.4.1.30 Update Statistics ........................................................................... 427
15.4.1.30. Arguments .................................................................................... 427
1
15.4.1.30. Guidelines .................................................................................... 429
2
15.4.1.30. Report sample .............................................................................. 429
3
15.4.1.31 Usage tracking (dm_usageReport) ................................................. 429
15.4.1.32 User change home repository ........................................................ 430
15.4.1.32. Arguments .................................................................................... 430
1
15.4.1.33 User Rename ............................................................................... 430
15.4.1.33. Arguments .................................................................................... 431
1
15.4.1.33. Report sample .............................................................................. 431
2
15.4.1.34 Version Management .................................................................... 433
15.4.1.34. Arguments .................................................................................... 433
1

EDCCS200200-AGD-EN-01 Administration and Configuration Guide xvii

Table of Contents

15.4.1.34. Guidelines .................................................................................... 435

2
15.4.1.34. Report sample .............................................................................. 435
3
15.4.1.35 WfmsTimer (dm_WfmsTimer) ........................................................ 436
15.4.2 Creating a job ............................................................................... 436
15.4.3 Changing the schedule of a job ...................................................... 438
15.4.4 Setting the qualifier rules for the remove retention-expired objects
job ............................................................................................... 439
15.4.5 Assigning a method to a job ........................................................... 440
15.4.6 Locating a method for a job ............................................................ 442
15.4.7 Creating, viewing, or modifying SysObject properties ....................... 442
15.4.8 Creating replication jobs ................................................................ 443
15.4.8.1 Selecting the source repository for a replication job ......................... 443
15.4.8.2 Selecting the target repository for a replication job ........................... 444
15.4.8.3 Setting replication job options ........................................................ 444
15.4.8.4 Choosing a replication folder .......................................................... 446
15.4.8.5 Choosing a replication job user ...................................................... 446
15.4.8.6 Choosing a permission set for replica objects .................................. 446
15.4.8.7 Choosing a storage area ............................................................... 446
15.4.8.8 Choosing replication and security modes ........................................ 447
15.4.9 Creating records migration jobs ...................................................... 449
15.4.9.1 Setting the rules of a records migration job ..................................... 450
15.4.9.2 Defining selection criteria for a records migration job ....................... 450
15.4.9.3 Defining version criteria for records migration job ............................ 450
15.4.10 Creating remove expired retention objects jobs ............................... 450
15.4.11 Creating BOCS caching jobs .......................................................... 451
15.4.11.1 Setting BOCS caching rules ........................................................... 451
15.4.12 Creating job sequences ................................................................. 452
15.4.12.1 Providing repository and job information for a job sequence ............. 453
15.4.12.2 Selecting jobs for a job sequence ................................................... 455
15.4.12.3 Setting dependencies for a job sequence ........................................ 455
15.4.13 Running jobs ................................................................................ 455
15.4.14 Viewing the status of a running job ................................................. 456
15.4.15 Viewing job reports ........................................................................ 456
15.4.16 Setting the trace level for a job ....................................................... 456
15.4.17 Viewing job trace logs .................................................................... 456
15.4.18 Deleting jobs ................................................................................. 457
15.4.19 Managing jobs .............................................................................. 457
15.4.19.1 Activating or inactivating a job ........................................................ 457
15.4.19.2 Disabling all jobs ........................................................................... 457
15.4.19.3 Modifying agent exec behavior ....................................................... 457

xviii OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

15.4.19.3. Setting the polling interval .............................................................. 458

1
15.4.19.3. Setting the number of jobs in a polling cycle .................................... 458
2
15.4.19.3. Enabling the high-availability feature .............................................. 458
3
15.4.19.3. Setting the job interval ................................................................... 458
4
15.4.19.3. Turning on tracing for the agent exec process ................................. 459
5
15.4.19.4 Creating and maintaining a repository connection file for job
sequences .................................................................................... 459
15.4.19.4. Specifying the server connect string ............................................... 459
1
15.4.19.4. Commas and backslashes in the entries ......................................... 460
2
15.4.19.4. The dcf_edit utility ......................................................................... 460
3
15.4.19.5 Recovering from a job sequence failure .......................................... 462
15.4.19.6 Interpreting a job sequence status report ........................................ 462
15.4.19.7 Executing dm_run_dependent_jobs independently .......................... 463
15.4.20 Deactivating jobs that fail ............................................................... 464

16 Alias Sets ............................................................................... 465

16.1 Alias sets and aliases .................................................................... 465
16.2 Creating or modifying alias sets ..................................................... 465
16.3 Viewing or removing aliases .......................................................... 466
16.4 Adding or modifying aliases ........................................................... 466
16.5 Deleting alias sets ......................................................................... 467

17 Formats .................................................................................. 469

17.1 Formats ........................................................................................ 469
17.2 Viewing, creating, or modifying formats ........................................... 469
17.3 Deleting formats ............................................................................ 471

18 Types ...................................................................................... 473

18.1 Object type categories and properties ............................................. 473
18.1.1 Type categories ............................................................................ 473
18.1.2 Lightweight object types ................................................................ 474
18.1.3 Type properties ............................................................................. 474
18.2 Managing types ............................................................................ 474
18.3 Creating or modifying types ........................................................... 475
18.4 Selecting a type ............................................................................ 479
18.5 Deleting types ............................................................................... 479
18.6 Viewing assignment policies .......................................................... 479

EDCCS200200-AGD-EN-01 Administration and Configuration Guide xix

Table of Contents

18.7 Converting types to shareable object types ..................................... 480

18.8 Converting types to lightweight object types .................................... 480
18.9 Converting types to shareable and lightweight object types .............. 480

19 Storage Management ............................................................ 481

19.1 Storage management areas ........................................................... 481
19.2 Storage ........................................................................................ 481
19.2.1 File stores ..................................................................................... 483
19.2.1.1 Creating, viewing, or modifying file stores ....................................... 483
19.2.1.2 Configuring NAS file stores ............................................................ 486
19.2.2 Linked stores ................................................................................ 488
19.2.2.1 Creating, viewing, or modifying linked stores ................................... 488
19.2.3 Blob stores ................................................................................... 489
19.2.3.1 Creating, viewing, or modifying blob stores ..................................... 489
19.2.4 Distributed stores .......................................................................... 490
19.2.4.1 Creating, viewing, or modifying distributed stores ............................ 490
19.2.5 External stores .............................................................................. 492
19.2.5.1 Creating, viewing, or modifying external stores ................................ 493
19.2.5.2 Editing a server root location .......................................................... 494
19.2.6 Centera stores .............................................................................. 494
19.2.6.1 Creating, viewing, or modifying Centera stores ................................ 495
19.2.6.2 Defining the storage parameters for a Centera store ........................ 497
19.2.6.3 Defining Centera store content attributes ........................................ 500
19.2.7 NetApp SnapLock stores ............................................................... 500
19.2.7.1 Creating, viewing, or modifying NetApp SnapLock stores ................. 501
19.2.8 Atmos stores ................................................................................ 503
19.2.8.1 Creating, viewing, or modifying Atmos stores .................................. 503
19.2.8.1.1 Managing authentication ................................................................ 503
19.2.8.2 Storing content in Atmos store ....................................................... 504
19.2.9 ViPR stores .................................................................................. 504
19.2.9.1 Creating, viewing, or modifying ViPR stores .................................... 505
19.2.10 OpenStack Swift stores ................................................................. 505
19.2.10.1 Creating, viewing, or modifying OpenStack Swift stores ................... 506
19.2.11 Amazon S3 stores ......................................................................... 507
19.2.11.1 Using the S3 store plugin ............................................................... 508
19.2.11.2 Creating, viewing, or modifying S3 stores ....................................... 510
19.2.11.3 Configuring S3 store properties ...................................................... 511
19.2.11.4 Logging ........................................................................................ 512
19.2.11.5 Troubleshooting ............................................................................ 513
19.2.12 Mount points ................................................................................. 513
19.2.12.1 Creating or modifying mount points ................................................ 514
19.2.13 Locations ...................................................................................... 515

xx OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

19.2.13.1 Creating or modifying locations ...................................................... 515

19.2.14 Plug-ins ........................................................................................ 516
19.2.14.1 Creating or modifying plug-ins ........................................................ 517
19.2.15 Deleting storage areas, locations, mount points, and plug-ins .......... 517
19.2.16 Setting or updating a retention date or retention period .................... 518
19.2.17 Supporting WORM for Data Domain and Isilon stores ...................... 518
19.2.17.1 Enabling WORM ........................................................................... 519
19.2.17.2 Configuring SmartLock containers in Isilon ...................................... 519
19.3 Assignment policies ...................................................................... 519
19.3.1 Viewing a list of assignment policies ............................................... 521
19.3.2 Creating, viewing, or modifying assignment policies ........................ 522
19.3.3 Modifying the permissions of an assignment policy .......................... 523
19.3.4 Custom assignment policy rule examples ....................................... 524
19.3.5 Associating an assignment policy with an object type ...................... 524
19.3.6 Deleting assignment policies .......................................................... 524
19.4 Migration policies .......................................................................... 525
19.4.1 Creating, viewing, or modifying migration policies ............................ 525
19.4.1.1 Configuring a migration policy schedule .......................................... 526
19.4.1.2 Configuring migration policy rules ................................................... 526
19.4.2 Configuring migration policy SysObject information ......................... 528
19.4.3 Viewing migration policy job reports ................................................ 529
19.4.4 Deleting migration policies ............................................................. 529
19.5 Orphaned content objects and files ................................................ 529
19.5.1 The dmclean utility ........................................................................ 530
19.5.1.1 Removing orphaned content from retention type storage areas ........ 532
19.5.1.2 Running dmclean with an EXECUTE statement .............................. 532
19.5.1.3 Running dmclean from the operating system prompt ....................... 532
19.5.2 The dmfilescan utility ..................................................................... 533
19.5.2.1 Running dmfilescan using an EXECUTE statement ......................... 534
19.5.2.2 Running dmfilescan from the operating system prompt .................... 535
19.5.2.3 The generated script ..................................................................... 535
19.5.2.4 Executing the dmfilescan script ...................................................... 536
19.6 Archiving and restoring documents ................................................. 536
19.6.1 How the process works ................................................................. 536

20 InfoArchive Integration with Documentum ......................... 539

20.1 Prerequisites ................................................................................ 539
20.2 Setting up Documentum connector ................................................. 540
20.3 Running archive job using Documentum Administrator .................... 545
20.4 Cleaning archived objects .............................................................. 546

21 Content Delivery .................................................................... 547

21.1 Content delivery services ............................................................... 547

EDCCS200200-AGD-EN-01 Administration and Configuration Guide xxi

Table of Contents

21.2 Locating content delivery configurations ......................................... 547

21.3 Creating or modifying content delivery configurations ...................... 548
21.4 Configuring the advanced properties of a content delivery
configuration ................................................................................. 550
21.5 Configuring replication properties for a content delivery
configuration ................................................................................. 555
21.6 Configuring extra arguments for a content delivery configuration ...... 556
21.7 Deleting content delivery configurations .......................................... 572
21.8 Testing content delivery configurations ........................................... 572
21.9 Duplicating a content delivery configuration .................................... 572
21.10 Deactivating a content delivery configuration ................................... 572
21.11 Publishing objects ......................................................................... 573
21.12 Content delivery configuration results ............................................. 573
21.13 Content delivery logs ..................................................................... 573
21.13.1 Viewing content delivery logs ......................................................... 573
21.13.2 Deleting content delivery logs ........................................................ 574
21.14 Effective labels .............................................................................. 574

22 Indexing Management ........................................................... 575

22.1 Indexing ....................................................................................... 575
22.2 Index agents and xPlore ................................................................ 575
22.3 Starting and stopping index agents ................................................. 576
22.4 Disabling index agents .................................................................. 576
22.5 Enabling index agents ................................................................... 577
22.6 Verifying indexing actions .............................................................. 577
22.7 Viewing or modifying index agent properties ................................... 577
22.8 Managing index queue items ......................................................... 577
22.8.1 Resubmitting individual objects ...................................................... 578
22.8.2 Resubmitting all failed queue items ................................................ 578
22.8.3 Removing queue items by status .................................................... 579
22.8.4 Removing queue items .................................................................. 579
22.8.5 Viewing queue items associated with an object ............................... 579
22.8.6 Creating new indexing queue item .................................................. 579

23 Content Transformation Services Management ................. 581

24 Content Intelligence Services .............................................. 583

25 Resource Management ......................................................... 585

25.1 Understanding Resource Management ........................................... 585
25.2 Managing resource agents ............................................................ 585
25.3 Managing resource properties ........................................................ 586
25.3.1 Monitoring resources ..................................................................... 587
25.3.2 Manual configuration steps for monitoring resources ....................... 587

xxii OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

26 Cabinets, Files, and Virtual Documents .............................. 589

27 API and DQL ........................................................................... 591

27.1 API and DQL ................................................................................ 591
27.2 DQL Editor ................................................................................... 591
27.3 API Tester .................................................................................... 591

28 Search ..................................................................................... 593

28.1 Searches ...................................................................................... 593
28.2 Setting search preferences ............................................................ 593
28.3 Search guidelines ......................................................................... 593
28.4 Running a simple search ............................................................... 594
28.4.1 Further define search terms ........................................................... 594
28.5 Running an advanced search ......................................................... 597
28.6 Search results ............................................................................... 597
28.7 Additional configuration options ...................................................... 597
28.8 Saved searches ............................................................................ 598
28.9 Creating a search template ............................................................ 598

29 Inbox ....................................................................................... 599

30 Workflows, Work queues, and Lifecycles ........................... 601

30.1 Workflows ..................................................................................... 601
30.1.1 Configuring the workflow agent ...................................................... 601
30.1.1.1 Changing the number of worker sessions ....................................... 601
30.1.1.2 Changing the sleep interval ............................................................ 601
30.1.1.3 Changing the system shutdown timeout .......................................... 602
30.1.1.4 Enabling immediate processing of automatic activities ..................... 602
30.1.1.4.1 Skipping workflow task assignment ................................................ 603
30.1.1.5 Tracing the workflow agent ............................................................ 603
30.1.1.6 Disabling the workflow agent .......................................................... 604
30.2 Work queue management .............................................................. 604
30.3 Lifecycles ..................................................................................... 605
30.4 References ................................................................................... 605

31 Performance and Tuning ...................................................... 607

31.1 Common problems with Documentum Server performance .............. 607
31.2 Type caching ................................................................................ 609
31.2.1 Concurrency ................................................................................. 609
31.2.2 Deeper type hierarchy ................................................................... 610
31.3 LDAP synchronization ................................................................... 610
31.3.1 Best throughput formula ................................................................ 610
31.3.2 Throughput and CPU utilization balance ......................................... 611

EDCCS200200-AGD-EN-01 Administration and Configuration Guide xxiii

Table of Contents

31.3.3 Large volume and hierarchy ........................................................... 612

31.3.4 Java Method Server tuning ............................................................ 613
31.3.5 Database tuning ............................................................................ 614
31.4 Intelligent Session Management ..................................................... 615
31.5 Multiple workflows in Linux ............................................................ 617

A System Events ....................................................................... 619

A.1 dm_default_set event .................................................................... 619
A.2 DFC events .................................................................................. 620
A.3 Workflow events ........................................................................... 626
A.4 Lifecycle events ............................................................................ 629
A.5 Events sent to the fulltext user ....................................................... 630

B Populating and Publishing the Data Dictionary ................. 631

B.1 Populating the data dictionary ........................................................ 631
B.1.1 Populating a repository’s data dictionary with a Japanese, Korean,
Simplified Chinese, Russian, or Arabic locale-specific data
dictionary file ................................................................................ 632
B.2 Data dictionary population script ..................................................... 632
B.2.1 The initialization file ....................................................................... 632
B.2.2 The data files ................................................................................ 633
B.2.2.1 File structure ................................................................................. 634
B.2.2.2 Summary of settable data dictionary properties ............................... 635
B.2.2.3 Setting foreign keys ....................................................................... 640
B.2.2.4 Examples of data file entries .......................................................... 641
B.2.3 Executing the script ....................................................................... 643
B.2.4 Populating data dictionary on a repository from a non-English host ... 644
B.2.5 Default files provided by Documentum ............................................ 644
B.2.6 Using DQL statements .................................................................. 645
B.3 Publishing the data dictionary information ....................................... 645
B.3.1 The data dictionary publisher job .................................................... 645
B.3.2 The publishDataDictionary method ................................................. 646
B.3.3 The PUBLISH key phrase .............................................................. 646

C High-Availability Support Scripts ........................................ 647

C.1 Monitoring scripts .......................................................................... 647
C.2 Processes not requiring a script ..................................................... 650

D Consistency Checks ............................................................. 651

D.1 General information ....................................................................... 651
D.2 User and group checks .................................................................. 651
D.3 ACL checks .................................................................................. 652
D.4 SysObject checks ......................................................................... 653
D.5 Folder and cabinet checks ............................................................. 654

xxiv OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Table of Contents

D.6 Document checks ......................................................................... 655

D.7 Content object checks ................................................................... 655
D.8 Workflow checks ........................................................................... 655
D.9 Object type checks ........................................................................ 656
D.10 Data dictionary checks .................................................................. 657
D.11 Lifecycle checks ............................................................................ 657
D.12 Object type index checks ............................................................... 658
D.13 Method object consistency checks ................................................. 659

E Plug-in Library Functions for External Stores .................... 661

E.1 General recommendations ............................................................. 661
E.2 dm_close_all ................................................................................ 661
E.3 dm_close_content ......................................................................... 662
E.4 dm_deinit_content ......................................................................... 662
E.5 dm_init_content ............................................................................ 662
E.6 dm_open_content ......................................................................... 663
E.7 dm_plugin_version ........................................................................ 664
E.8 dm_read_content .......................................................................... 665

F Usage Tracking ...................................................................... 667

F.1 Usage Tracking ............................................................................. 667
F.1.1 Tracking internal user accounts ...................................................... 667
F.1.2 Tracking unique users ................................................................... 668
F.1.3 Tracking login times ...................................................................... 668
F.1.4 Usage tracking and software compliance ........................................ 668

EDCCS200200-AGD-EN-01 Administration and Configuration Guide xxv

Preface
Preface
This guide describes how to configure and administer Documentum Server. This
guide contains administration and configuration information, instructions, and
procedures for a general Documentum installation.

IMPORTANT

Documentum Content Server is now OpenText Documentum Server. OpenText

Documentum Server will be called Documentum Server throughout this guide.

i Intended audience
This guide is written for system and repository administrators. The system
administrator is the person who generally installs and owns the Documentum
installation. Repository administrators are the users who own and are responsible
for one or more repositories. Readers should be familiar with the general principles
of client/server architecture and networking. In addition, they should know and
understand the Windows and Linux operating systems.

ii Revision history
Revision Date Description
April 2020 Initial publication.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide xxvii

Chapter 1

Administration and Configuration Tools

1.1 Introduction
A Documentum installation typically consists of one or more repositories,
Documentum Servers that access the repositories, and clients that access the
repositories through the Documentum Servers.

Documentum Server software manages the repository and provides content

management capabilities. The repository consists of three main components: a file
store containing the content assets, attribute tables within a relational database, and
full-text indexes.

After Documentum Server is installed and running, typical system administration

and configuration tasks include:

• Creating new repositories and maintaining existing repositories, including object

types, methods, jobs, and alias sets
• Configuring, starting, and shutting down servers
• Maintaining connection brokers
• Managing content storage areas and content files
• Administering full-text indexes
• Managing users and groups
• Managing security
• Changing session configurations

The two main tools for administering and configuring Documentum Server are
Documentum Administrator and Documentum Server Manager. Documentum
Administrator is sold separately. It is not included with Documentum Server.

Most administration and configuration tasks are typically done using Documentum
Administrator. Some tasks have to be performed using Documentum Server
Manager or the command line.

This guide provides instructions for administration and configuration tasks using
Documentum Administrator, unless a task can only be accomplished using
Documentum Server Manager or the command line. In that case, the instructions are
provided using Documentum Server Manager or the command line, respectively.
Documentum Administrator User Guide contains the information on using
Documentum Administrator.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 29

Chapter 1 Administration and Configuration Tools

1.2 Documentum Administrator

Documentum Administrator is the primary user interface for administration tasks.
Documentum Administrator is a web-based interface for monitoring, administering,
configuring, and maintaining Documentum repositories from any system running a
web browser.

Documentum Administrator User Guide contains the information and instructions on

the following:

• Logging in to Documentum Administrator

• Using the System Information page
• Determining the Documentum Administrator version
• Using the Preferences menu in Documentum Administrator

1.3 Documentum Server Manager

Documentum Server Manager is an administration tool added to the Windows Start
menu during server installation on Windows platforms. Documentum Server
Manager is typically used to:

• Edit the server.ini file to change the Documentum Server configuration

• Uninstall a repository
• Start the IDQL utility
• Modify connection brokers
• Display connection broker log files
• Invoke the Documentum Server setup program to add or remove server
components
• Invoke the Microsoft Performance Monitor tool
• Create a configuration summary report

1.3.1 Starting Documentum Server Manager

Documentum Server Manager is a Documentum Server administration tool only
available on Windows platforms.

To start Documentum Server Manager

1. Log in to the Windows machine that is running Documentum Server.

2. Select Start > Documentum Server Manager.

The Documentum Server Manager page displays.

30 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 1.4. Tool suite

1.4 Tool suite

Documentum Server includes various tools that automate regular administration
tasks, such as files, monitoring storage space and database tables. The tools are
implemented as jobs and most are installed in an inactive state. Documentum
Administrator provides a graphical interface for defining, modifying, and
monitoring the tools and their associated jobs.

The following table briefly describes the tools that are available. The “Jobs”
on page 368 section contains more information.

Table 1-1: Documentum tool suite

Tool Description
Archive Automates archive and restore operations
between content areas.
Audit Management Deletes audit trail objects.
Consistency Checker Checks the repository for consistency across
a variety of object types.
Content Replication Automates replication of document content
for distributed file stores.
Content Storage Warning Monitors disk space on the devices used to
store content and index files. Queues a
warning message when a disk used for
content and index storage reaches a user-
defined percentage of capacity.
Data Dictionary Publisher Publishes data dictionary information to
make it visible to users and applications.
Database Space Warning Monitors the RDBMS. Queues a warning
message when the RDBMS reaches a user-
defined percentage of capacity.

Note: This tool is not installed for

installations running against Microsoft
SQL Server.
Dm_LDAPSynchronization Determines all changes in the LDAP
directory server information and propagates
the changes to the repository.
Dmclean Automates the dmclean utility, which
removes orphaned content objects, notes,
ACLs, and SendToDistribution workflow
templates from a repository.
Dmfilescan Automates the dmfilescan utility, which
removes orphaned content files from a
specified storage area of a repository.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 31

Chapter 1 Administration and Configuration Tools

Tool Description
Distributed Operations Performs the distributed operations
necessary to manage reference links. This is
an internal job that is installed as part of the
tool suite. Documentum Platform and Platform
Extensions Installation Guide contains more
details.
File Report Utility Provides a report to help restore deleted or
archived document content using file system
backups. This method only applies to
distributed storage areas.
Group Rename Renames a group in the repository.
Index Agent Startup Starts the index agent.
Log Purge Deletes log files for the server, session,
connection broker, and agent and the trace
log files resulting from method and job
executions.
Queue Management Deletes dequeued objects in the
dmi_queue_item tables.
Remove Expired Retention Objects Removes objects with an expired retention
date, if they are stored in a Centera storage
area.
Rendition Management Removes of unwanted document renditions.
State of the Repository Report Provides information about the repository
status.
Swap Info Reports on swap space availability and
usage.
ToolSetup Installs system administration tools.
Update Stats Updates stored statistics on the underlying
RDBMS tables, to aid in query performance.
User Chg Home Db Changes the user home repository.
User Rename Changes a user name in the repository.
Version Management Removes of unwanted document versions.

32 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 2

Managing Connection Brokers

2.1 Connection brokers

The Documentum connection broker is a process that provides client sessions with
connection information, such as IP addresses and port numbers. The connection
brokers that handle a client connection request are defined in the dfc.properties file
of the client. By default, each Documentum Server installation must have one
connection broker. The first connection broker is started as part of the installation
process.

When a client contacts the connection broker, the connection broker sends back the
IP address and port number of the server host. If there are multiple servers for the
repository, the connection broker returns connection information for all of them. The
client 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
particular host, or a particular server on a specified host.

The dfc.properties file contains most of the configuration parameters for handling
sessions. For example, the file contains keys that identify which connection brokers
are used to obtain a session, specify how many sessions are allowed for one user,
and enable persistent client caching. Many keys have default values, but an
administrator or application must explicitly set some of the keys. The “The
dfc.properties file” on page 145 section contains more information on the
dfc.properties file.

The standard connection broker that comes with a Documentum Server installation
can be customized for meet more specific requirements, such as:

• Protection against being shut down by an unauthorized person

• A list of servers that can access the connection broker
• IP listening addresses to run multiple connection brokers
• Connection requests from outside a firewall

These options are configured in the connection broker initialization file. Both, the
dfc.properties file and the connection broker initialization file cannot be modified
using Documentum Administrator.

When Documentum Server is started, it automatically broadcasts information about

itself. Each connection broker that receives the broadcast adds the server to its
registry, or list of known servers. Documentum Server sends the first broadcast
before it is fully initialized, and the connection broker sets the server status to
starting. As soon as Documentum Server is fully initialized and ready to service

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 33

Chapter 2 Managing Connection Brokers

clients, it broadcasts a checkpoint message. The receiving connection brokers update

the server status to open.

Documentum Server broadcasts a checkpoint message at regular intervals. By

default, the checkpoint interval is 5 minutes. If the connection broker does not
receive a checkpoint message, it modifies the server status to presumed down. A
connection broker keeps the entry for a non-broadcasting server for a specified time,
called the keep_retry interval. Both, the checkpoint interval and the keep_retry
interval are specified in the server configuration object, as described in “General
server configuration properties” on page 49.

A connection broker deletes a Documentum Server from its list of known servers
when:

• A server sends a delete me message as a result of a manual shutdown using the

shutdown method.
• A server fails to broadcast a checkpoint message within the expected keep_entry
interval.
For example, a server is not active as a result of a shutdown without a delete me
message, a crash, or when the network between the server and connection broker
fails.
• A server is reinitialized after a change to the projection targets in the server
configuration object that deletes the connection broker from the targets.

2.2 The connection broker initialization file

The connection broker initialization file is an optional connection broker
configuration file. The initialization file can have any valid file name. You can store
the file in any location, but the most convenient place is the same directory in which
the dm_launch_docbroker script is stored.

The initialization file is a plain text file and has the following format:
[SECURITY]
password = string_value
allow_hosts=host_name_list|deny_hosts=host_name_list

[DOCBROKER_CONFIGURATION]
host = host_name|IP_address_string
service = service_name
port = port_number
keystore_file=broker.p12
keystore_pwd_file=broker.pwd
cipherlist=AES128-SHA
secure_connect_mode=native or secure or dual

[TRANSLATION]port=["]outside_firewall_port=inside_firewall_port
{,outside_firewall_port=inside_firewall_port}["]
host=["]outside_firewall_ip=inside_firewall_ip
{,outside_firewall_ip=inside_firewall_ip}["]

Note: The password key in the [SECURITY] section is only valid on Linux
platforms. Connection brokers on Windows platforms do not use the security

34 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 2.2. The connection broker initialization file

password. The port translation strings are enclosed in double quotes when
multiple ports or hosts are specified.

If the initialization file includes a valid service name, the connection broker is started
with the service name. If the initialization file does not provide a service name, but a
valid port number, the connection broker is started using the port number. If a
service name or a port number is not included, the connection broker is started on
port 1489.

2.2.1 Invoking the initialization file

When you start a connection broker, the initialization file is not automatically
invoked. To invoke the file, 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 the
argument on the command line. You can use the Documentum Server Manager to
edit the service entry.

For Linux platforms, the syntax is:

% dm_launch_docbroker -init_file <filename>

If there are other arguments on the command line in addition to the initialization file
argument, the -init_file argument must appear first or it is ignored.

2.2.2 Configuring shutdown security (Linux only)

Defining a security password for a connection broker ensures that only a user who
knows the password can stop the connection broker. Define a password in the
[SECURITY] section with the password key:
[SECURITY]
password=<string_value>

2.2.3 Restricting server access

By default, a connection broker accepts broadcasts from any server. However, you
can configure a connection broker to either:

• Accept broadcasts only from specified servers

• Reject broadcasts from specified servers

To define accepted servers, use the following format in the initialization file:
[SECURITY]
...
allow_hosts=<host_name_list>

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 35

Chapter 2 Managing Connection Brokers

To define rejected servers, use the following format:

[SECURITY]
...
deny_hosts=<host_name_list>

<host_name_list> is a list of the host machines on which the servers reside. Separate
multiple host names by commas. For example:
[SECURITY]
...
deny_hosts=<bigdog,fatcat,mouse>

The options are mutually exclusive. For each connection broker, you can configure
either the accepted servers or the rejected servers, but not both.

2.2.4 Certificate-based SSL configuration

Use these parameters to enable certificate-based SSL:

• keystore_file: Keystore containing the connection broker certificate and private

key
• keystore_pwd_file: File containing the plain-text or encrypted keystore password
• Cipherlist: List of ciphers separated by “:”

Documentum Platform and Platform Extensions Installation Guide contains more

information.

2.2.5 Supported connection broker connection modes

This section lists the supported connection modes for connection broker.

• Native: Connections are in the raw RPC format without any encryption
• Secure: SSL mode is:

– used with anonymous ciphers (ADH:DEFAULT)

– used with certificates
• Dual: Connections are both in the raw RPC format without any encryption and
SSL mode is used with anonymous ciphers (ADH:DEFAULT) and certificates

36 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 2.2. The connection broker initialization file

2.2.6 Translating IP addresses

For security reasons, many enterprises set up firewalls to prevent outside users from
accessing enterprise repositories and file systems.

To allow a user or client application outside the firewall to connect to a repository

inside the firewall, the connection broker initialization file includes a
[TRANSLATION] section. This section redirects a request to a safe IP address and
port name. The section has the following format:
[TRANSLATION]port=["]outside_firewall_port=inside_firewall_port
{,outside_firewall_port=inside_firewall_port}["]
host=["]outside_firewall_ip=inside_firewall_ip
{,outside_firewall_ip=inside_firewall_ip}["]

where

<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,

outside the firewall, wants to connect to repository A. Also suppose the connection
broker that receives the request has the following TRANSLATION section in its
initialization file:
[TRANSLATION]
port=2231=4532
host=2.18.13.211=172.18.23.257

When the connection broker receives the request, it translates 4532 to 2231 and
172.18.23.257 to 2.18.13.211. It sends the values 2231 and 2.18.13.211 back to
application B, which uses them to establish the connection.

If you specify multiple ports or hosts for translation, enclose the translation string in
double quotes. For example:
[TRANSLATION]
port="2253=6452,2254=6754"

To use a [TRANSLATION] section:

1. Define the IP address translation rules in the firewall.

2. Enter the rules in the [TRANSLATION] section of the connection broker

initialization file.

3. Restart the connection broker, specifying the initialization file on the command
line.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 37

Chapter 2 Managing Connection Brokers

2.3 Connection broker projection targets

Active Documentum Servers must regularly broadcast, or project, connection
information to at least one connection broker. Server broadcasts are called
checkpoints. The connection brokers receiving the checkpoints are called connection
broker projection targets.

Connection broker projection targets are defined in the server configuration object.
The Documentum Server installation procedure defines one connection broker
projection target in the server.ini file. The target is the connection broker that is
specified during the installation procedure. When the installation procedure is
complete, the target definition can be moved to the server configuration object.

The “Creating or modifying connection broker projections” on page 56 section

contains more information on modifying connection broker projection targets.

2.4 Server proximity

Documentum Servers send a proximity value to each connection broker projection
target. The proximity value represents physical proximity of the server to the
connection broker. By default, clients connect to the server with the smallest
proximity value since that server is the closest available server. If two or more
servers have the same proximity value, the client makes a random choice between
the servers.

The proximity values should reflect the topology of a Documentum Server

installation. For example, an installation with three servers and one connection
broker, the server closest to the connection broker projects the lowest proximity
value. The server farthest from the connection broker projects the highest proximity
value.

The server proximity value is specified in the network location section of the server
configuration object, as described in “Creating or modifying network locations”
on page 56.

An individual server that has multiple connection broker projection targets can
project a different proximity value to each target. Guidelines for setting proximity
values are:

• Proximity values should have a value of 1 to 999, unless the Documentum

Servers are in a distributed configuration.

• Any server with a proximity value of 9000 to 9999 is considered a Documentum

Server and typically only handles content requests.

• For values from 1001 through 8999, the first digit is ignored and only the last
three digits are used as the proximity value. For example, if for a proximity value
of 8245, clients ignore the 8 and only consider 245 the proximity value.

38 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 2.5. Restarting a connection broker

• On Windows platforms, proximity values of 10,000 and more represent servers

in another domain. Users who want to connect to such servers must specify the
server by name in the Connect command line.

2.5 Restarting a connection broker

On Windows platforms, a connection broker can either be started as a service or
from the command line. On Linux platforms, a connection broker is always started
from the command line.

2.5.1 Restarting a connection broker running as a Windows

service
Double-click Start connection broker in the Documentum group.

This launches the connection broker executable.

Note: The connection broker service name is Documentum Docbroker Service

<connection_broker_name> where <connection_broker_name> is the name of the
connection broker. The default service name is Documentum Docbroker
Service Docbroker.

2.5.2 Restarting a connection broker that is not running as a

Windows service
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

2.5.3 Restarting a connection broker on a Linux platform

1. Log in to 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 the
dm_launch_docbroker utility. The command-line syntax is:
dm_launch_docbroker [-init_file <file_name>] [-host <host_name>] [-service
<service_name>] [-port <port_number>]

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 39

Chapter 2 Managing Connection Brokers

Include the host name and a service name or port number to identify the
connection broker. Otherwise specify an initialization file that includes a
[DOCBROKER_CONFIGURATION] section to identify the connection broker.

2.6 Adding a connection broker for one session

Documentum Administrator obtains connection information from the connection
broker referenced in the dfc.properties file of the Documentum Administrator
installation. You cannot modify the dfc.properties file using Documentum
Administrator. If you have system administrator or superuser privileges, you can
add connection brokers for an active session by storing connection broker
information in a cookie. However, the repositories of that connection broker can
only be accessed during the current session.

Documentum Administrator User Guide contains the instructions on adding a

connection broker for a session.

2.7 Implementing connection broker failover

Failover for connection information requests from a client is implemented by listing
multiple connection brokers in the dfc.properties file. In addition, the value of the
dfc.docbroker.auto_request_forward key in the dfc.properties file must be set to T.

By default, the first connection broker listed in the file handles the connection
request. If that connection broker does not respond within 15 seconds or less, the
request is forwarded to the next connection broker that is listed in the dfc.properties
file. The request is forwarded sequentially until a connection broker responds
successfully or until all connection brokers defined in the file have been tried. If
there is no successful response, the connection request fails.

2.8 Starting additional connection brokers

A repository can have multiple connection brokers. The connection brokers can run
on separate machines or on the same machine. With multiple connection brokers on
the same machine, each connection broker on the machine must use a separate port
or a separate network card.

Configuring a connection broker to use a separate port, requires defining a services

file entry that identifies the service name for the connection broker. The service
name for the connection broker must be unique among the service names.
Alternatively, you can create an initialization file that identifies the service. For
example:
[DOCBROKER_CONFIGURATION]
host=<host_machine_name>
service=<service_name>

or

40 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 2.8. Starting additional connection brokers

[DOCBROKER_CONFIGURATION]
host=<host_machine_name>
port=<port_number>

where <port_number> is the port identified in the new service.

To configure a connection broker to use a separate network card, create an

initialization file for the connection broker. The file must include a
[DOCBROKER_CONFIGURATION] section to identify the IP address of the
network card. Use the following format:
[DOCBROKER_CONFIGURATION]
host=<IP_address_string>
service=<service_name>
port=<port_number>

<IP_address_string> must be in the dotted decimal format (for example,

143.23.125.65).

The service name is the connection broker service name, defined in the host machine
services file. The port number is the port defined in the service. Documentum Platform
and Platform Extensions Installation Guide contains instructions on setting up service
names. If you include a service name, the connection broker is started using that
service. Otherwise, if you include a port number, the connection broker is started
using that port. If you do not include a service 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\<version>\bin\dmdocbroker.exe
[-init_file <filename> ]-host <host_name> -service <service_name>

• On Linux:
dm_launch_docbroker [-init_file <filename>]-host <host_name>
-service <service_name>

Include the host name and a service name or port number to identify the
connection broker. Otherwise, specify an initialization file that includes a
[DOCBROKER_CONFIGURATION] section to identify the connection broker.

2. Modify the projection properties in the server configuration object to add the
new connection broker as a server projection target.

3. Optionally, modify the server.ini file to add the new connection broker as a
server projection target.

4. Reinitialize the server.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 41

Chapter 2 Managing Connection Brokers

2.9 Shutting down connection brokers

The connection broker shutdown procedure varies, depending on whether the
connection broker runs on a Windows platform or Linux platform. The shutdown
procedure also depends on whether the connection broker was started as a service
or from the command line.

If the connection broker was configured with shutdown security, supply the correct
password to shut down the connection broker.

2.9.1 To stop a connection broker running as a service on

Windows:
1. Click Start > Program Files > Documentum > Server Manager.
2. Select the connection broker tab.
3. Select the correct connection broker.
4. Click Stop.

2.9.2 To stop a connection broker started from the Windows

command line:
Close the window in which the connection broker is running.

2.9.3 To stop a connection broker on a Linux platform:

Execute the dm_stop_docbroker utility on the command line:
% dm_stop_docbroker [-P<password>][-B[atch]]
[-N<port_number>][-S<service_name>]

The utility stops the connection broker that is running on the host specified in the
dmshutdown script. That connection broker was specified during the initial server
installation. If you are executing the dm_stop_docbroker utility in interactive mode
(without the -B flag), the utility displays which connection broker it intends to stop
and prompts for a confirmation. If you include the -B flag, the utility does not
prompt for confirmation or display which connection broker it is stopping. The
default for the -B flag is FALSE.

If you have multiple connection brokers on one machine, you can include the -N and
-S arguments to identify a particular connection broker to shut down.

The <password> is the password specified in the connection broker initialization file.
The “Configuring shutdown security (Linux only)” on page 35 section contains more
information on connection broker security. If the connection broker initialization file
contains a password, supply this password to stop the connection broker.

If you cannot use the dm_stop_docbroker utility, you can use the Linux kill
command to stop the connection broker if it was started without security. If you do

42 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 2.10. Requesting connection broker information

not know the process ID for the connection broker, you can obtain it using the Linux
ps command. You cannot use the Linux kill command to stop a connection broker
that was started with security. Only the Linux kill -9 command stops a secured
connection broker.

2.9.3.1 Stopping multiple connection brokers on Linux

If you have multiple connection brokers, stop two or more by editing the
dm_stop_docbroker script before running the dm_stop_docbroker utility. The script
resides in the $DOCUMENTUM/dba directory. The last line in this script contains
the connection broker host name that is stopped when the dm_stop_docbroker
utility runs:
./dmshutdown docbroker -Tlapdog -P$password $@
# lapdog is the host name

To stop multiple connection brokers, add a line one for each host on which a
connection broker resides to the script. For example, connection brokers are running
on hosts named lapdog, fatcat, and mouse. To stop all three connection brokers, 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

If all connection brokers use the same password, the dm_stop_docbroker utility
substitutes the password specified on the command line for $password in the script.
If each connection broker requires a different password, add the password for each
connection broker in the script:
./dmshutdown docbroker -Tlapdog -Pbigbark $@
#lapdog is the host name

./dmshutdown docbroker -Tfatcat -Pmeowmeow $@

#fatcat is the host name

./dmshutdown docbroker -Tmouse -Psqueak $@

#mouse is the host name

2.10 Requesting connection broker information

To obtain information about servers or repositories associated with a particular
connection broker, or which connection broker a client can access, use the following
methods:

• getServermap: Returns information about associated servers for a particular

connection broker.
The IDfDocbrokerClient.getServerMap method returns the non-persistent server
locator object. The server information appears at corresponding index positions
in the repeating properties of the object. For example, the name of the host
machine for the server named in r_server_name[0] is specified in r_host_name[0].

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 43

Chapter 2 Managing Connection Brokers

The process ID is specified in r_process_id[0], and the status is specified in

r_last_status[0].
Documentum Server System Object Reference Guide contains more information
about the server locator object.
• getDocbaseMap: Returns information about associated repositories for a
particular connection broker.
The IDfDocbrokerClient.getDocbaseMap method returns the non-persistent
repository locator object. The repository information appears at corresponding
index positions in the repeating properties. For example, the name of the
repository whose ID is in r_docbase_id[3] is found in r_docbase_name[3] and its
description is found in r_docbase_description[3].
Documentum Server System Object Reference Guide contains more information
about the repository locator object.
• getDocbrokerMap: Returns a list of connection brokers a client can access.
The IDfTypedObject.getDocbrokerMap method returns the non-persistent
docbroker locator object.
The information for a single connection broker appears at corresponding index
positions in the repeating properties. For example, the values at
network_protocol[2], host_name[2], port_number[2], and time_out[2] describe
one connection broker.
The method is also useful when sending a getDocbaseMap or getServerMap
method to a particular connection broker to find the protocol, host name, and
port number values for the connection broker.
Documentum Server System Object Reference Guide contains more information on
the docbroker locator object.
• Query the client config object.
Each client session references a non-persistent client config object for
configuration information. The client object properties are populated from the
keys of the dfc.properties file. Any key value specified in the file is reflected in
the client config object.
The keys in the dfc.docbroker category contain information about the connection
brokers in the properties file is contained in the keys with the category
dfc.docbroker. For example, a dfc.docbroker.host key identifies a connection
broker host and a dfc.docbroker.port key identifies a connection broker port.
The repeating properties of the client config object use the same names as the
keys in the dfc.properties file. For example, connection broker hosts are found in
the dfc.docbroker.host property.

44 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 3
Managing Documentum Servers

3.1 Documentum Servers

A Documentum Server is a process that provides client access to the repository.
Documentum Servers receive queries from clients in the form of DFC methods or
DQL statements and make the actual call to the underlying RDBMS or the file
directories. Every repository must have at least one active Documentum Server. If a
repository does not have an active server, users cannot access that repository.

The default Documentum Server installation starts one Documentum Server for a
repository. However, a repository can have more than one Documentum Server. If a
repository is very active, serving many users, or its users are widely spread
geographically, multiple servers can provide load balancing and enhance
performance. The “Adding or modifying Documentum Servers” on page 48
section more information on adding Documentum Servers to a repository.

Repositories are comprised of object type tables, type indexes, and content files. The
type tables and type indexes are tables in an underlying relational database. The
content files are typically stored in directories on disks in a given installation.
However, content files can also be stored in the database, in a retention storage
system such as Centera or NetApp SnapLock, or on external storage devices.

A full-text index is associated with a particular repository or, in a consolidated

deployment, with all repositories indexed by a xPlore installation. Full-text indexes
enable rapid searching for designated values or strings in content files and property
values.

3.2 Starting a server

Documentum Server can only be started or restarted using Documentum Server
Manager or a startup script.

To restart a server using Documentum Server Manager (Windows):

1. Log into the machine where Documentum Server is installed as the

Documentum installation owner.

2. Navigate to Start > Programs > Documentum > Documentum Server Manager.

3. Click the DocBroker tab, select a connection broker, then click Start.

4. Click the Repository tab, select a repository, then click Start to start
Documentum Server.

5. Click Start > Programs > Administrative Tools > Services.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 45

Chapter 3 Managing Documentum Servers

6. Right-click Documentum Java Method Server in the Services list, then click
Start to start the Java Method Server.

To restart a server using the startup script (Linux):

1. Log into the machine where Documentum Server is installed as the

Documentum installation owner.

2. Start the connection broker by running the $Documentum/dba/dm_launch/

<docbrokerName> script, where <docbrokerName> is the name of the connection
broker.
Change to the $DOCUMENTUM/dba directory.

3. Run the dm_start_<repositoryname> script that references the server to start.

The dm_start_<repositoryname>script checks that a log directory is defined for
the installation, copies any existing log file to a new location, and starts the
server. The script has an optional argument, -oclean, that removes the files in
the server common area if the argument is included it in the command line.

4. Navigate to the $DOCUMENTUM_SHARED/WildFly_directory/server/

startMethodServer.sh and run the startMethodServer.sh script to start the
application server.

3.3 Configuring licenses

Certain Documentum Server and repository features require an additional license.
Documentum Administrator provides a license configuration feature to enable
licenses in existing repositories for the following features or products:

• Collaboration Edition
• Federated Record Services
• Physical Records Management
• Records Manager
• Retention Policy Services

Documentum Administrator User Guide contains the instructions on the following:

• Viewing which licenses are enabled

• Enabling a product of feature license

46 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.4. Managing Documentum Servers

3.4 Managing Documentum Servers

The default Documentum Server installation creates a repository with one server. In
Documentum Administrator, administrators can configure additional servers to run
against a particular repository.

Each Documentum Server is associated with a server configuration object. A server

configuration object is a template for a Documentum Server. A server configuration
is defined by the properties in the associated server configuration object and the
parameters in the server.ini file that is read during server startup. At startup, a
server always reads the CURRENT version of its server configuration object.

All server configuration objects for the current repository are listed on the
Documentum Server Configuration page in Documentum Administrator, as
described in “Server configuration object information” on page 47.

Server configuration objects are stored in the repository System cabinet. You can add
Documentum Servers by creating multiple server configuration objects, as long as
they are uniquely named. You can also modify a server configuration object and
save it as a new object.

Note: Documentum Platform and Platform Extensions Installation Guide contains

information on creating, starting, and stopping a RCS.

Table 3-1: Server configuration object information

Column Description
Name The name of the server configuration object.
Host The name of the host on which the
Documentum Server associated with the
server configuration object is running.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 47

Chapter 3 Managing Documentum Servers

Column Description
Operational Status The current running status and dormancy
status separated by a comma of the
Documentum Server. Valid values are:

Running Status:
• Running
• Unknown

Dormancy Status:
• Dormancy Requested
• Projected Dormancy
• Dormant
• Active
• Invalid

Note: The Operational Status column

will display only the current running
status for Documentum Server
versions prior to 7.0.
Version The version of the server configuration
object.

3.4.1 Adding or modifying Documentum Servers

The Server Configuration list page in Documentum Administrator lists the server
configuration objects of all Documentum Servers for the current repository. Each
Documentum Server has a server configuration object in the repository.

Table 3-2: Server Configuration properties tabs

Tab Description
Info Select the Info tab to view or modify
information on the server host, the platform
on which the server is running, code pages
and locales, and other general information.
Connection Brokers Select the Connection Brokers tab to view or
modify connection broker projections.
Network Locations Select the Network Locations tab to view or
modify the proximity values for the
associated network locations.
App Servers Select the App Servers tab to add an
application server for Java method execution.

48 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.4. Managing Documentum Servers

Tab Description
Cached Types Select the Cached Types tab to specify which
user-defined types are to be cached at server
startup.
Locations Select the Locations tab to view the locations
of certain files, objects, and programs that
exist on the server host file system, including
the assume user program, change password
program, log file.
Far Stores Select the Far Stores tab to view accessible
storage areas and to designate far stores. A
server cannot store content in a far store.
Documentum Platform and Platform Extensions
Installation Guide contains more information
on far stores.

Documentum Administrator User Guide contains the instructions on adding or

modifying Documentum Servers.

3.4.2 Duplicating a server configuration object

You can create a server configuration object using an existing server configuration
object as a template. Create a server configuration object when you run additional
servers against a repository, whether on the same host or a different host.

Documentum Administrator User Guide contains the instructions on duplicating a

server configuration object.

3.4.3 Modifying general server configuration information

You can create or modify the general server information, such as the server host, the
platform on which the server is running, code pages and locales.

Table 3-3: General server configuration properties

Field label Value

Name The name of the initial server configuration
object created. By default, the server
configuration object has the same name as
the repository. When you create a new server
configuration object, you assign it a new
name.
Host Name The name of the host on which the server is
installed. Read-only.
Server Version The version, operating system, and database
of the server defined by the server
configuration object. Read-only.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 49

Chapter 3 Managing Documentum Servers

Field label Value

Process ID The process ID of server on its host. Read-
only.
Install Owner The Documentum installation owner. Read-
only.
Install Domain On Windows, the domain in which the
server is installed and running. Read-only.
Trusted Mode Indicates whether Trusted Content Services
is enabled. Read-only.
Dormancy Status Indicates the dormancy status of
Documentum Server.

Note: The Dormancy Status label is

only visible for 7.0 and later versions of
Documentum Server.
Update Configuration Changes
Re-Initialize Server Select to reinitialize the server after the
server configuration object is saved.
Configuration Changes
Web Server Location The name of the web server host and its
domain. Used by client applications for
creating DRLs.
Web Server Port Identifies the port the web server uses. The
default is 80.
Agent Launcher Defines the method that launches the agent
exec process. The default value is
agent_exec_method.

The agent_exec_method is created when you

install Documentum Server. Its name is
stored in the agent_launcher property of the
server configuration object. It polls jobs that
contain scheduling information for methods.
Jobs are launched by the agent_exec process.

To disable all job execution, leave this field

empty.

Click the Select Agent Launcher Method

link to access the Choose a method page.

50 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.4. Managing Documentum Servers

Field label Value

Operator Name The name for the repository operator if the
repository operator is not explicitly named
on the dmarchive.bat command line or in the
Archive or Request method. This must be
manually configured. The default is the
owner of the server configuration object (the
repository owner).

The repository operator is the user whose

Inbox receives all archive and restore
requests.

Click the Select Operator link to access the

Choose a user page.
Server Cache Size The maximum number of objects allowed in
the server cache. The default is 200.
Client Cache Size The maximum permitted size of the client
cache, expressed as the number of objects.
The default is 50.
Network File Share Indicates whether the server is using
Network File Share for file sharing.
Checkpoint Interval Defines the interval at which the server
broadcasts service information to connection
brokers. The unit of measurement is seconds.
The default is 300 seconds.
Keep Entry Interval Specifies how long each connection broker
keeps a server entry if the connection broker
does not receive checkpoint broadcasts from
the server. This time limit is included in the
broadcast information of server.

By default, the value is 1,440 minutes (24

hours).
Locale Name Indicates the server locale.

The value is determined during server

installation.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 51

Chapter 3 Managing Documentum Servers

Field label Value

Default Client Codepage The default codepage for clients. The value is
determined programmatically and is set
during server installation. In general, it does
not need to be changed.

Options are:
• UTF-8
• ISO_8859-1
• Shift_JIS
• EUC-JP
• EUC-KR
• US-ASCII
• ISO_10646-UCS-2
• IBM850
• ISO-8859-8

Server OS Codepage The code page used by the operating system

of the machine on which the server resides.
The value is determined programmatically
and is set during server installation. In
general, this value is not changed.

Options are:
• UTF-8
• ISO_8859-1
• Shift_JIS
• EUC-JP
• EUC-KR
• US-ASCII
• ISO_10646-UCS-2
• IBM850
• ISO-8859-8

Turbo Backing Store The name of the file store storage area where
the server puts renditions generated by
indexing blob and turbo content. The default
is filestore_01.
Rendition Backing Store The name of the file store storage area where
the server will store renditions generated by
full-text indexing operations.
Modifications Comments Remarks on changes made to the server
configuration object in this version.

52 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.4. Managing Documentum Servers

Field label Value

SMTP Server The name of the computer hosting the SMTP
Server that provides mail services to
Documentum Server.

The value is provided during server

installation.
Workflow Agent Worker Threads The number of workflow agent worker
sessions. The maximum value is 1000. The
default value is 3. Setting this to 0 disables
the workflow agent.
Secure Connect Mode Specifies whether type of connection the
server accepts. Options are:
• Dual: Uses encrypted and non-encrypted
connections.
• Native: Uses non-encrypted connections
only.
• Secure: Uses encrypted connections only.

If you change the mode, you must restart the

server. Re-initializing the server does not
suffice.
Maximum Content Migration Threads Defines a valid value range for the argument
PARALLEL_DEGREE for parallel content
migration when running
MIGRATE_CONTENT administration
method or setting up a migration policy rule.
Valid values are between 1 and 128.

This option requires a Content Storage

Services license that is enabled on the
Documentum Server.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 53

Chapter 3 Managing Documentum Servers

Field label Value

System Shutdown Timeout The time in seconds that the workflow agent
attempts to shut down work items gracefully
after receiving a shutdown command. The
default value is 120 seconds.

When the timeout value expires, the server

takes over and shuts down the workflow
agent. This feature is only applicable for
repositories that use multiple Documentum
Servers.

If the timeout period is exceeded (or is set to

zero), Documentum Server takes over and
shuts down the workflow agent
immediately.

If the timeout period is a negative value,

Documentum Server waits for the workflow
agent threads to complete the automatic
tasks held by workflow agent workers before
shutting down gracefully.
Authorization Settings
Inherit Permission Set From The permission set the server uses for new
objects if a user fails to specify a permission
set for an object or fails to specify that no
default permission set is wanted. Options
are:

A User permission set is defined for a user

when a system administrator, superuser, or
repository owner creates a user. This
permission set can be used as the permission
set for any object created by the user.
Because user objects are not subtypes of
SysObject, the permission set is not used to
enforce any kind of security on the user. A
User permission set can only be used as a
default permission set.

A Type permission set is associated with the

type definition for a SysObject or SysObject
subtype. A Type permission set can only be
used as a default permission set.

A Folder permission set is associated with a

folder or cabinet. If a user wants to change
the properties of a folder or cabinet, modify
the folder or cabinet object itself, or move,
copy, or link an object to the folder, the
server uses the permissions in the associated
permission set to determine whether the user
can perform the requested operation.

54 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.4. Managing Documentum Servers

Field label Value

Default Alias Set The default alias set for new objects. Click
the Select Alias Set link to access the Choose
an alias set page.
Enabled LDAP Servers The LDAP configuration objects for LDAP
servers used for user authentication and
synchronization.

Click the Select link to access the Choose

LDAP Server Configurations page to add
LDAP servers.
Maximum Login Ticket Expiration Time The maximum length of time, in minutes,
that a login ticket generated by the current
server can remain valid. The minimum value
is 1 minute. The maximum value is 43200
minutes (30 days). The default value at
server installation is 43200.
Default Login Ticket Expiration Time The default length of time, in minutes, that a
login ticket generated by the current server
can remain valid. The value must always be
less than or equal to the maximum login
ticket expiration time. The default value is 5
minutes.
Application Access Application access control (AAC) tokens are
encoded strings that may accompany
connection requests from applications. The
information in a token defines constraints on
the connection request. If selected, a
connection request received by this server
from a non-superuser must be accompanied
by a valid application access control token
and the connection request must comply
with the constraints in the token.
Superuser Access When selected, a user with superuser
privileges cannot connect to the server using
a global login ticket.

Documentum Administrator User Guide contains the instructions on modifying general

server configuration information.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 55

Chapter 3 Managing Documentum Servers

3.4.4 Creating or modifying connection broker projections

The connection broker is the intermediary between a client and the server when the
client wants 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 broadcasts information to connection brokers at regular
intervals. The broadcast contains the information maintained by connection brokers
about the server and the repository accessed by the server.

When a client requests a connection to a repository, the connection broker sends the
client the connection information for each server associated with the repository. The
client can then choose which server to use.

Documentum Administrator User Guide contains the instructions on creating or

modifying connection broker projections.

3.4.5 Creating or modifying network locations

A network location identifies locations from which end users connect to
Documentum web clients. Network locations define specific IP address ranges.
Documentum Servers use network locations to determine the content storage
location from which a content file is provided to web client users.

Documentum Administrator User Guide contains the instructions on creating or

modifying network locations.

3.4.6 Creating or modifying application servers

Documentum Server supports application servers in the server configuration object.
The Documentum Server configuration object specifies the name and the URI of the
associated application servers.

Documentum Server supports a wide variety of network-accessible application,

personalization, portal, and e-commerce servers from enterprise vendors such as
BEA, IBM, Microsoft, Oracle, Sun, and SAP. The vendor documentation of the
application server contains more information on how to deploy an application
server.

Documentum Administrator User Guide contains the instructions on creating or

modifying application servers.

56 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.4. Managing Documentum Servers

3.4.7 Creating or modifying cached types

Cached types specify which user-defined types are to be cached at server startup. By
default, no user-defined objects are cached.

Documentum Administrator User Guide contains the instructions on creating or

modifying cached types.

3.4.8 Creating or modifying locations

The Location tab lets you view and modify the locations of files, objects, and
programs on the server hosts file system, including the assume user program,
change password program, and log file.

Table 3-4: Locations page properties

Field label Value

Assume User The location of the directory containing the
assume user program. The default is
assume_user.
Change Password The location of the directory containing the
change password program. The default is
change_password.
Common The location of the common directory. The
default is common.
Events The location of the events directory. The
default is events.
Log The location of the logs directory. The
default is temp.
Nls The location of the NLS directory. The
default is a single blank.
Secure Writer The location of the directory containing the
secure writer program. The default is
secure_common_area_writer.
System Converter The location of the directory containing the
convert.tbl file and the system-supplied
transformation scripts. There is no default for
this field.
Temp The location of the temp directory.
User Converter The full path for the user-defined
transformation scripts. The default is
convert.
User Validation The full path to the user validation program.
The default is validate_user.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 57

Chapter 3 Managing Documentum Servers

Field label Value

Verity 5.3 and later repositories, contains a dummy
value for compatibility with Webtop 5.2.x.
The default value is verity_location.
Signature Check The location of the directory that contains the
signature validation program. The default is
validate_signature.
Authentication Plugin The location of an authentication plug-in, if
used. The default is auth_plugin in
$Documentum/dba/auth.

Documentum Administrator User Guide contains the instructions on creating or

modifying locations.

3.4.9 Creating or modifying far stores

In a distributed content environment, a far store is a storage area remote or
inaccessible from the current Documentum Server, in which the server cannot store
content. Documentum Platform and Platform Extensions Installation Guide contains more
information on distributed content environments.

Documentum Administrator User Guide contains the instructions on creating or

modifying far stores.

3.4.10 Moving a server to dormant and active states

This section describes how to move a server to a dormant state and back to an active
state.

A Documentum Server can be moved to a dormant state only from an active state.
To perform this operation, you should be a member of the
dm_datacenter_managers, a privileged group whose membership is maintained by
superusers. This feature is only applicable for 7.0 and later versions of Documentum
Server.

A Documentum Server can be moved back to an active state only from a dormant
state. To perform this operation, you should be a member of the
dm_datacenter_managers, a privileged group whose membership is maintained by
superusers. This feature is only applicable for 7.0 and later versions of Documentum
Server.

Documentum Administrator User Guide contains the instructions on moving a server to

dormant and active states.

58 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.4. Managing Documentum Servers

3.4.11 Enabling or disabling save operation for a Documentum

Server in dormant state
You can perform the enable or disable save operation for a Documentum Server if
you are a member of the dm_datacenter_managers, a privileged group whose
membership is maintained by superusers. When you enable save operation for a
Documentum Server which is in dormant state, you can perform create and update
operations. By default, save operation is disabled. This feature is only applicable for
7.0 and later versions of Documentum Server.

Caution
To perform any of the view, create, update, or delete operations for a
Documentum Server which is in dormant state, you as a member of the
dm_datacenter_managers group should execute the action Enable Save
Operation, else view, create, update, or delete operations will fail.

Documentum Administrator User Guide contains the instructions on enabling or

disabling save operation for a Documentum Server in dormant state.

3.4.12 Projecting active or dormant state of Documentum

Server to connection broker
The dormancy status of Documentum Server can be projected to Connection Broker.
To perform this operation, you should be a member of the
dm_datacenter_managers, a privileged group whose membership is maintained by
superusers. This feature is only applicable for 7.0 and later versions of Documentum
Server.

Notes

• The Project Dormant Status to Connection Broker and Project Active

Status to Connection Broker menu options are available only for
Documentum Servers which is in active state. These options will not be
available for Documentum Servers which is in dormant state. Therefore, you
always can perform the Project Dormant Status to Connection Broker
operation first followed by Project Active Status to Connection Broker
operation.
• For a WDK application to login to a repository in a dormant state,
dmc_wdk_presets_owner, dmc_wdk_preferences_owner, and
dm_bof_registry users should be a member of dm_datacenter_managers.

Documentum Administrator User Guide contains the instructions on projecting active

or dormant state of Documentum Server to connection broker.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 59

Chapter 3 Managing Documentum Servers

3.4.13 Viewing server and connection broker log files

The server log file records server activities. Server logs provide valuable information
for troubleshooting server or repository problems.

Connection broker logs record information about connection brokers, which provide
connection information to clients.

Note: If you are connected to a secondary server, you see only the server and
connection broker logs for that server.

Documentum Administrator User Guide contains the instructions on viewing server

and connection broker log files.

3.4.14 Deleting a server configuration object

Do not delete the CURRENT version of the server configuration object of an active
server. You can safely delete the CURRENT version of the server configuration
object of a server that is shut down, or old configuration object versions of an active
server. To display old versions of server configuration objects, select the All
Versions filter from the list box on the server configuration object page.

Documentum Administrator User Guide contains the instructions on deleting a server

configuration object.

3.4.14.1 Confirming object deletion

When you delete certain objects from a repository, you must confirm that you want
to delete the object.

Documentum Administrator User Guide contains the instructions on confirming object

deletion.

3.4.15 Configuring a server as a process engine

If the Business Process Manager (BPM) application is installed in a repository and
you have a license for process engines, you can configure a server as a process
engine.

Documentum Administrator User Guide contains the instructions on configuring a

server as a process engine.

60 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

3.4.16 Disabling a process engine server

You can disable a server as a process engine.

To disable a server as a process engine:

1. Using any client, connect to the repository whose server you are disabling as a
process engine.

2. Navigate to the /System/Workflow/Process Engine folder.

3. Ensure that all objects in the folder are displayed.

For example, in Documentum Administrator, select Show All Objects and
Versions from the list box.

4. Delete the object corresponding to the name of the server that is configured as a
process engine.

3.4.17 Changing ACL or groups in a HA setup

In a distributed setup, having several Documentum Servers in HA setup, any
changes to ACL or groups and so on takes some time to reflect the changes in all the
servers. This time depends on the change checker interval. While doing sensitive
operation like deleting a user from a repository, you need to be aware of this to
prevent unauthorized operations during this interval.

3.5 The server.ini file

The server configuration is defined by the server.ini file and the server configuration
object. The server installation procedure creates both files automatically and the files
are called when the server is started.

The properties in the server configuration object provide operating parameters and a
map to the files and directories that the server can access. At startup, a Documentum
Server always reads the CURRENT version of server configuration object.

The server.ini file contains information you provide during the installation process,
including the repository name and the repository ID. That information allows the
server to access the repository and contact the RDBMS server. The server.ini file also
contains the name of the server configuration object.

You can use Documentum Administrator to modify the server configuration object,
as described in “Adding or modifying Documentum Servers” on page 48. However,
the server configuration object pages in Documentum Administrator do not contain
all of the default and optional properties that are defined in the server.ini file. Some
those properties can only be modified in the server.ini file using the Documentum
Server Manager. Typically, only the installation owner can modify the server.ini file.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 61

Chapter 3 Managing Documentum Servers

3.5.1 Modifying the server.ini file

The server.ini file contains configuration information for the server. The file is stored
in the %DOCUMENTUM%\dba\config\<repository> directory ($DOCUMENTUM/
dba/config/<repository>) and is called when the server is started.

The server.ini file has the following format:

[SERVER_STARTUP]
<key>=<value>

[DOCBROKER_PROJECTION_TARGET]
<key>=<value>

[DOCBROKER_PROJECTION_TARGET_<n>] #<n> can be 0-49

<key>=<value>

[FUNCTION_EXTENT_SIZE] #Oracle only

<key>=<value>

[TYPE_EXTENT_SIZE] #Oracle only

<key>=<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.

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

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

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 access this directory.

To modify the server.ini file:

1. Open the server.ini file:

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

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

Manager.
b. Select the Repository tab.
c. Select the repository associated with the server.ini file.
d. Click Edit Server.ini.

2. Edit the properties that you want to change.

62 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

3. Save the file.

4. Stop and restart the server to make the changes take effect.

3.5.2 SERVER_STARTUP section keys

The keys in the [SERVER_STARTUP] section provide repository and the database
access information as well as default operating parameters. The default and optional
keys can be modified using Documentum Server Manager.

“Keys in the SERVER_STARTUP section” on page 63, describes the keys in the
server startup section in alphabetical order.

Table 3-5: Keys in the SERVER_STARTUP section

Key Data type Description

acl_update_threshold integer Optional key. Improves
performance when the
dm_world permission in an
ACL is updated.

If the key is not specified,

Documentum Server updates
the entire dmr_content object
type table. If the key value is
larger than the number of
affected rows, only the
affected rows are updated.
Otherwise, Documentum
Server updates the entire
table.
check_user_interval integer Optional key. The interval, in
seconds, in which
Documentum Server checks
the login status of a user. The
default value is 0, meaning
that the status is only
checked when the user logs
in.
cipherlist string Optional key. Used for
Certificate-based SSL
communication. Specifies the
list of ciphers.
client_session_timeout integer Optional key. Specifies, in
minutes, how long the server
waits for a communication
from a client session before
disconnecting the session.

The default value is 5

minutes.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 63

Chapter 3 Managing Documentum Servers

Key Data type Description

concurrent_sessions integer Optional key. Specifies the
number of connections the
Documentum Server can
handle concurrently. The
default is 100. The
“concurrent_sessions”
on page 82 section contains
more information.
crypto_keyname string Specifies the name of the
AEK key. This can be used in
hosts which have
consolidated repositories
using different AEK keys.
crypto_mode string Mode based on the algorithm
used to generate the AEK
key. Valid values are:
• AES128_RSA1024_SHA3_
384
• AES192_RSA1024_SHA3_
384
• AES256_RSA1024_SHA3_
384
• 3DES_RSA1024_SHA3_38
4
database_conn string The database connection
string, which is used by the
server to connect with the
RDBMS server. This key is
specified during
Documentum Server
installation and is only
required for Oracle
databases.
database_name string The tablespace or database in
the RDBMS. This key is
specified during
Documentum Server
installation and only
required by SQL Server
databases.
database_owner string The RDBMS login name of
the repository owner. This
key is specified during
Documentum Server
installation.
database_password_file string The name of the file that
contains database passwords.

64 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

Key Data type Description

database_user string The RDBMS login name of
the normal database user
with restricted privileges
used during operation mode.

The Documentum Server

chapter in Documentum
Platform and Platform
Extensions Installation Guide
contains more information
about the normal database
user with restricted
privileges.
deferred_update_queue_size integer Optional key. Controls the
size of the deferred object
update record queue. The
default queue size is 1000, the
valid range for this
parameter is 256 to 4096.

Increase the queue size, ff

repository operations
generate a large number of
deferred object updates. If
the queue fills up, the
deferred updates are
performed immediately,
which can impact application
performance.
distinct_query_results Boolean Optional key. Specifies
whether duplicate rows are
included in query results.
Valid values are:
• FALSE: The default value.
Duplicate rows are
included in query results.
• TRUE: Only distinct rows
are returned in query
results.
The NOFTDQL hint
returns only unique
results. If the identical
query is executed in
FTDQL, the key is
ignored and all results of
the query are returned,
including duplicate
results.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 65

Chapter 3 Managing Documentum Servers

Key Data type Description

dm_group_list_limit_temp_t Boolean Optional key. Specifies
bl whether Documentum Server
creates a temporary table that
contains the names of all
groups to which a session
user belongs. Valid values
are:
• TRUE: The SQL generated
for every DQL query
contains a LEFT OUTER
JOIN on the temporary
table. This operation
improves performance
when you execute
multiple queries in the
same session.
• FALSE: The default value.
The SQL generated for
every DQL query
contains a subquery that
fetches the names of all
the groups to which a
session user belongs.
However, if the user is
part of many groups this
subquery becomes
inefficient.

Note: This is
supported only in
administration mode.

66 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

Key Data type Description

dm_left_outer_join_for_acl Boolean Improves performance levels
for session users without
superuser privileges who
belong to large number of
groups.

When you set this variable, it

composes a LEFT OUTER
JOIN from the
dm_sysobject_s table to the
dm_acl_s table on the FROM
clause of the converted SQL
statement. The LEFT OUTER
JOIN returns all entries from
the left table even though an
entry does not have a
matching entry on the right
table. It uses the left table as a
driving table to find the
corresponding entries on the
right table, which guides the
database optimizer to a better
execution plan, thus
improving performance on
SQL Server.
docbase_id integer The repository ID. The
repository ID must be unique
among all the repositories
installed on the system. This
key is specified during
Documentum Server
installation.
docbase_name string The repository name. This
key is specified during
Documentum Server
installation.
db_oracle_dop integer Optional key. Indicates the
degree of parallelism to be
used by the underlying
Oracle database. The index
creation runs faster
depending on the number of
CPUs, table partitioning and
disk fragmentation of the
database. This key is
specified prior to the
Documentum Server
upgrade. The value should
be greater than or equal to 2.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 67

Chapter 3 Managing Documentum Servers

Key Data type Description

db_oracle_index_nologging Boolean Optional key. Helps in faster
insertion and index creation.
Improves performance by
bypassing the writing of the
redo log. This key is specified
prior to the Documentum
Server upgrade. Valid values
are TRUE and FALSE. The
default is TRUE.
db_oracle_online_index Boolean Optional key. Indicates
whether the index is being
created online. During an
online index rebuild, Oracle
takes a snapshot log on the
target table to hold DML
activity, read the table in a
full-table scan (read
consistent), build the new
index and then apply the
changes from the snapshot
log after the index has been
rebuilt. During a regular
index rebuild, an exclusive
lock occurs as the existing
index is read. This key is
designed for scheduled
downtime periods where
there is no DML activity. This
key is specified prior to the
Documentum Server
upgrade. The default is
FALSE.
enable_database_partition Boolean Optional key. This key is
used to enable the
partitioning of the repository.
enforce_four_digit_year Boolean Optional key. Specifies
whether Documentum Server
displays dates using four
digits. Valid values are:
• TRUE: The default value.
Documentum Server
displays the year date
using four digits if the
user does not specify a
date format.
• FALSE: Documentum
Server does not display
the year in four digits by
default.

68 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

Key Data type Description

gethostbyaddr Boolean Optional key. Specifies
whether the Documentum
Server calls the
gethostbyaddr() function
during connection requests to
obtain the host name of the
machine on which a client
application resides. Valid
values are:
• TRUE: The default value.
Documentum Server uses
the gethostbyaddr()
function to obtain the host
name.
• FALSE: Documentum
Server skips the
gethostbyaddr () calls
during connection
requests and uses host
addresses instead.

If a large number of client

machines do not have names,
set the key to FALSE to skip
to achieve better
performance.
history_cutoff integer Optional key. Specifies a cut-
off time for historical sessions
in minutes. For example, if
the history_cutoff value is 15,
the server does not return
any historical session older
than 15 minutes, even if the
maximum number of
sessions defined in
history_sessions has not been
reached.

The default value for

history_cutoff is 240 minutes.
history_sessions integer Optional key. Specifies the
number of maximum timed-
out sessions returned by the
SHOW_SESSIONS function.
Use the apply method or the
EXECUTE statement to run
SHOW_SESSIONS.
Documentum Server DQL
Reference Guide contains more
information.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 69

Chapter 3 Managing Documentum Servers

Key Data type Description

host string The IP address on which the
server listens. The host key
value is specified during
Documentum Server
installation.

Some host machines have

multiple network cards. If
you want Documentum
Server to use a particular
network card on the host
machine, specify the IP
address of the card in this
key before starting the server.
ignore_client_domain Boolean Optional key. Specifies
whether the Documentum
Server ignores the domain
passed by the client during a
connection request. Valid
values are:
• TRUE: The Documentum
Server ignores the client
domain and uses the
domain specified in
user_auth_target attribute
for all user
authentications.
• FALSE: The default value.
The Documentum Server
uses the client domain
passed in a connection
request.
incremental_jms_wait_time_ integer Optional key. Used for
on_failure Documentum Server to
determine the time it should
retry to POST to a previously
failed JMS. By default, the
incremental time interval is
set to 30 seconds. This key is
specified in configuring JMS
for HA only.

Note: This key is not

applicable in
configuring JMS for
HA in the 7.3 and later
releases.

70 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

Key Data type Description

install_owner string This key is not used. The
value in the server
configuration object is used
instead.
jms_max_wait_time_on_failu integer Optional key. Used as a cap
res on wait time so as not to wait
for a long time for the next
retry time. This key is
specified in configuring JMS
for HA only. The default
value for
jms_max_wait_time_on
failures is 1 hr (3600
seconds).

Note: This key is not

applicable in
configuring JMS for
HA in the 7.3 and later
releases.
keystore_file string Optional key. Used for
Certificate-based SSL
communication. Specifies the
connection broker certificate
and private key.
keystore_pwd_file string Optional key. Used for
Certificate-based SSL
communication. Specifies the
plain-text or encrypted
keystore password.
ip_mode string Optional key. Specifies
whether Documentum Server
supports IP addresses in IPv6
format. Valid values are
• DUALSTACK: The
default value.
Documentum Server
accepts both, IPv4 and
IPv6 addresses.
• V4ONLY: Documentum
Server only accepts IPv4
addresses.

Note: IPv6 addresses

should not start with f.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 71

Chapter 3 Managing Documentum Servers

Key Data type Description

kerberos_keytab_path string Optional key. Specifies to
read the kerberos keytab files
from a preconfigured
directory path. If not
specified, it reads from
%DOCUMENTUM%\dba
\auth\kerberos directory.
listener_queue_length integer Optional key. Specifies the
queue for connection
requests. This key is only
used on Windows platforms.

Documentum Server creates

a socket listener for incoming
connection requests. By
default, the maximum
backlog queue value is 200.
The key must be a positive
integer value. Documentum
Server passes the specified
value to the listen ()
Windows Sockets call.
mail_notification Boolean Optional key. Specifies
whether email messages are
sent when a work item or an
event is queued. Valid values
are
• TRUE: The default value.
Email messages are sent.
• FALSE: Users are not
notified.

If no mail server is set for

Documentum Server, it is
recommended you turn off
email sending by setting this
key to FALSE.
max_nqa_string integer Optional key. Defines the
maximum length of a non-
qualifiable string property, in
bytes.

The default is 2000.

If the key is not specified, the

default is the maximum
length allowed by the
underlying relational
database.

72 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

Key Data type Description

max_ftacl_cache_size integer Optional key. Limits the
number of elements cached
per session to process
FTDQL-compliant full-text
queries. Documentum Server
caches ACL information on
objects to evaluate security
on the results returned by
full-text queries.

The default value is -1 (no

limit). If the value is 0, no
security information is
cached. The key can have any
integer value greater than -1.
However, It is recommended
that you do not change the
default value.
max_session_heap_size integer Optional key. Specifies, in
bytes, how much memory a
session can use. The default
value is -1, which means that
the heap grows as necessary
to whatever size the server
machine resources allow, up
to the server addressing
memory limit of 2 GByte.
max_storage_info_count integer Optional key. Defines the
maximum number of storage
areas for which Documentum
Server maintains information
in shared memory. The
default is 100. Valid values
are positive integers from 100
to 65535.

The value does not limit the

number of storage areas. For
example, if the key value is
150, it is possible to create
additional storage areas, but
information for the
additional storage areas is
not maintained in memory.
In a multiserver
environment, all
Documentum Servers must
use the same
max_storage_info_count
value.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 73

Chapter 3 Managing Documentum Servers

Key Data type Description

maxtypes_in_from_clause integer Optional key. Defines the
maximum number of types
in FROM clause increased to
the specified number. If the
key is not specified, the
default value is 50.
method_server_enabled Boolean Optional key. Specifies
whether the Documentum
Server or the Java method
server is used to execute
dm_method objects. Valid
values are:
• TRUE: The default value.
The Java method server
executes dm_method
objects that are
configured to run on the
Java method server. If the
methods are not
configured correctly,
Documentum Server
executes the method
instead.
• FALSE: Documentum
Server executes
dm_method objects.
method_server_threads integer Optional key. Specifies the
maximum number of method
server worker processes 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_sessions property
of the server configuration
object.

The method_server_threads
values are for the dmbasic
method server only and do not
have any impact on the Java
method server.

74 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

Key Data type Description

owner_xpermit_default string Optional key. Specifies
whether object owners are
assigned extended
permissions for an object by
default or have the
permissions that are
explicitly assigned to the
them. Valid values are:
• ACL: Object owners have
only the extended
permissions that are
assigned explicitly and
are not granted extended
permissions by default.
The key value is case-
sensitive and must be
specified in capital letters.
• ALL or No value set:
Object owners are
assigned all extended
permissions by default.
Only the following
sysobjects are secured by
default: dm_job,
dm_job_request,
dm_jms_config,
dm_procedure,
dm_client_rights, and
dmc_module.

This feature is governed

using the
DM_OWNER_CHANGE_AL
LOWED environment
variable. If you set the value
to 0 (for backward
compatibility), users who
does not have the sysadmin
privileges can still change the
ownership.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 75

Chapter 3 Managing Documentum Servers

Key Data type Description

preserve_existing_types Boolean Optional key. Specifies
whether Documentum Server
queries the RDBMS at startup
to determine if the object
type tables are present for all
defined object types. Valid
values are:
• TRUE: The default value.
Documentum Server
preserves existing types
and does not dynamically
destroy and recreate
object type tables for
types that are reported
missing by the RDBMS.
• FALSE: Documentum
Server dynamically
destroys and recreates
object type tables for
types that are reported
missing by the RDBMS.

76 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

Key Data type Description

rdbms_connect_retry_timeou integer Optional key.
t
• Server startup: Specifies
how long the server tries
to connect to the RDBMS.
The server attempts to
connect every 30 seconds
until it is successful or the
time-out limit is reached.
Also note that the server
process sleeps for 30
seconds before every retry
operation. The remaining
time is taken to connect to
RDBMS and so in actual it
takes up 1 minute.
• Server already running: If
the server is already
running and if the
RDBMS connection is lost,
there might be many
internal server sessions
started already and
whenever each of them
tries to connect to
RDBMS, it fails and
retries for 1 second. If the
retry operation fails, then
the server does not stop
as other sessions might be
operating and server does
not know if the RDBMS
failure is intermittent or
not. So, the server does
not give back RDBMS
session for this particular
call while for others it
continues. If the server.ini
value is not set, then for
each session, it will retry
for 10 times (default
timeout value is 5
minutes) before failing.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 77

Chapter 3 Managing Documentum Servers

Key Data type Description

saveasnew_retain_source_gr Boolean Optional key. Specifies which
oup default group is assigned to a
new object created by a
IDfSysObject.saveAsNew
method. Valid values are:
• TRUE: The new object is
assigned to the default
group of the original
(source) object.
• FALSE: The default value.
The new object is
assigned to the default
group of the user who
issues the saveAsNew
method.
server_codepage string UTF-8 is the only allowed
value.
server_config_name string Specifies which server
configuration object is used
to start Documentum Server.
The Documentum Server
installation procedure
assigns the name of the
repository to the server
configuration object
generated for the server.

The default value is the name

of the repository.
server_login_ticket_version integer Specifies the format of the
generated login ticket, for
backwards compatibility.
server_startup_sleep_time integer Specifies the amount of time,
in seconds, that
Documentum Server waits
before trying to connect to
the RDBMS. The time delay
allows the underlying
RDBMS to start before
Documentum Server
attempts to connect.

The default value is 0.

78 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

Key Data type Description

service string The TCP/IP service name for
the Documentum Server.
This key is configured during
Documentum Server
installation. The value is the
service name that appears in
services file of the
Documentum Server host
machine. If a repository has
multiple Documentum
Servers, this name must be
unique for each
Documentum Server.
start_index_agents Boolean Specifies whether
Documentum Server starts
configured index agent
instances at Documentum
Server startup.

The default value is TRUE.

ticket_multiplier integer Specifies the number of login
tickets with server scope
allocated in shared memory.
The number of tickets
allocated by the server is
computed as follows:

#tickets =
concurrent_sessions *
ticket_multiplier

The default value is 10.

truststore_file string Optional key. Used for
Certificate-based SSL
communication. Specifies the
trusted connection broker
certificates.
umask string(4) Optional key. Modifies the
default operating system
permissions assigned to
public directories and files
created by Documentum
Server in the server or
repository installation on
Linux platforms only. The
“umask” on page 83 section
contains more information.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 79

Chapter 3 Managing Documentum Servers

Key Data type Description

update_access_date Boolean Specifies whether the
r_access_date property is
updated in the deferred
update process. Valid values
are:
• TRUE: The default value.
Documentum Server
updates the r_access_date
property as part of the
deferred update process.
• FALSE: Documentum
Server does not update
the r_access_date
property.
upd_last_chg_time_from_db Boolean Optional key. Specifies that
all Documentum Servers in a
clustered environment have
timely access to all changes
in group membership. Valid
values are:
• TRUE: Should only be
used for environments
with multiple
Documentum Servers.
The value should be set to
TRUE for all running
Documentum Servers.
• FALSE: The default value.
use_estimate_search Boolean Specifies whether users can
execute the
ESTIMATE_SEARCH
administration method. The
administration method is
used to fine-tune SEARCH
conditions for queries. Valid
values are:
• TRUE: The default value.
Users can execute the
method.
• FALSE: The method does
not execute.

80 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

Key Data type Description

use_group_address integer Specifies who receives email
notifications when an event
is queued to a group. Valid
values are:
• 0: The default value.
Documentum Server send
email to each group
member.
• 1: Documentum Server
sends email to the groups
address. If the group has
no email address, the
server sends notifications
to each group member.
• 2: Documentum Server
sends email to each group
member and to the group
address.

To reduce the number of

emails sent, it is
recommended you set
use_group_address to 1. This
results in lesser load on the
method server.
user_auth_case string Specifies the case
Documentum Server
converts the user name of the
client before authenticating
the user. Valid values are:
• upper: The user name is
converted to upper case.
• lower: The user name is
converted to lower case.
• NULL: The default value.
The name is authenticated
using the case in which it
was entered by the user.
user_auth_target string Specifies the domain or
default LDAP server that
Documentum Server uses to
authenticate client user
names and passwords on
Windows platforms only.

The default is the domain in

which the server resides.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 81

Chapter 3 Managing Documentum Servers

Key Data type Description

validate_database_user Boolean Specifies whether
Documentum Server
validates that the user
identified in the
database_owner key in the
server.ini file has a valid
operating system user
account. Valid values are:
• TRUE: The default value.
Documentum Server
validates the operating
system user account.
• FALSE: Documentum
Server does not validate
the operating system user
account.
wait_for_connect_timeout integer Specifies how long
Documentum Server waits
for a connection request
before starting to process
other work, such as deferred
updates.

The default value is 10

seconds.

3.5.2.1 concurrent_sessions
The concurrent_sessions key controls the number of connections the server can
handle concurrently. This number must take into account not only the number of
users who are using the repository concurrently, but also the operations those users
are 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,
the operations they are performing, and the number of methods or jobs you execute
regularly, and then modify this value accordingly.

The maximum number of concurrent sessions is dependent on the operating system

of the server host machine. The limit is:

82 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

• 3275 for Windows systems

• 1020 for Linux systems

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

The default value is 1 minute.

3.5.2.3 umask
On Linux platforms, permissions can be expressed as a 3-digit octal number,
representing the permission level for the owner, group owner, and others. For
example, a file created with permissions 700 grants the owner read, write and
execute permission, but the group owner and others get no permissions at all.
Permissions of 644 grants the owner read and write permission, but the group
owner and others only have read permission. Similarly, 640 gives the owner read
and write permission, the group owner read only permission and others get no
permissions.

The umask is also expressed as an octal number and is used to further restrict (or
mask) the permissions when a directory or file is created. For example, if the
requested permissions are 766 and the umask is 22, the actual permissions applied is
744. A bit set in the umask turns off the corresponding bit in the requested
permissions.

Documentum Server uses a umask key in the server.ini file that is separate from the
Linux per-process umask, but applies it in a similar fashion. The Documentum
Server internally refers to permissions with the symbolic names dmOSFSAP_Public,
dmOSFSAP_Private, dmOSFSAP_Public ReadOnly, dmOSFSAP_PrivateReadOnly,
and dmOSFSAP_PublicOpen. “Documentum Server directory and file permissions
on Linux platforms” on page 83 describes the associated permission values.

Table 3-6: Documentum Server directory and file permissions on Linux

platforms

Permission Name Directory Value File Value

dmOSFSAP_Public 755 644
dmOSFSAP_Private 700 600
dmOSFSAP_Public 555 444
ReadOnly
dmOSFSAP_PrivateReadOnl 500 400
y
dmOSFSAP_PublicOpen 777 666

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 83

Chapter 3 Managing Documentum Servers

Note: The umask in the server.ini configuration file only modifies the values
for the dmOSFSAP_PublicOpen permissions. If the umask is not specified in
the server.ini file, the default setting for the dmOSFSAP_PublicOpen
permissions is 777 for directories and 666 for files. Any directories or files that
are publicly accessible outside the Documentum Server are created using this
permission.

3.5.3 DOCBROKER_PROJECTION_TARGET section keys

The [DOCBROKER_PROJECTION_TARGET] and
[DOCBROKER_PROJECTION_TARGET_n] sections define the connection brokers
to which Documentum Server sends connection information. The Documentum
Server installation procedure creates one [DOCBROKER_PROJECTION_TARGET]
section in the server.ini file, which contains access information the first broadcast to
a connection broker. For the first broadcast, the connection broker name provided
during the installation is used as the host key. The proximity key is assigned 1, the
default value. When the Documentum Server is started at the end of the installation
procedure, it projects the connection information to the connection broker specified
in the host key.

Connection broker projection targets are also defined in a set of properties in the
server configuration object. We recommend to use the server configuration
properties to define additional projection targets, instead of the server.ini file.
Modifying the server configuration object allows changing a target without
restarting Documentum Server. If the same projection target is defined in both the
server configuration properties and in the server.ini file, Documentum Server uses
the values for the target in the server configuration properties.

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.

“Server.ini DOCBROKER_PROJECTION_TARGET keys” on page 84 describes the

keys.

Table 3-7: Server.ini DOCBROKER_PROJECTION_TARGET keys

Key Datatype Comments

host string Name of connection broker
host
port integer Port number used by the
connection broker
proximity integer User-defined value that
represents distance of server
from connection broker

84 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.5. The server.ini file

3.5.4 FUNCTION_EXTENT_SIZE and TYPE_EXTENT_SIZE

sections
The [FUNCTION_EXTENT_SIZE] and [TYPE_EXTENT_SIZE] sections specify how
much space is allocated in the RDBMS for the object type tables. They are available
only for Oracle.

“Server.ini FUNCTION_EXTENT_SIZE keys” on page 85, lists the keys for the
FUNCTION_EXTENT_SIZE section.

Table 3-8: Server.ini FUNCTION_EXTENT_SIZE keys

Key Datatype Description

database_ini_ext_large integer Specifies the size of the initial
extent allotted by default to
object types categorized as
large.
database_ini_ext_small integer Specifies the size of the initial
extent allotted by default to
object types categorized as
small.
database_ini_ext_default integer Specifies the size of the initial
extent allotted by default to
object types categorized as
default.
database_next_ext_large integer Specifies the size of the
second extent allotted by
default to object types
categorized as large.
database_next_ext_small integer Specifies the size of the
second extent allotted by
default to object types
categorized as small.
database_next_ext_default integer Specifies the size of the
second extent allotted by
default to object types
categorized as default.

“Server.ini TYPE_EXTENT_SIZE keys” on page 85, lists the keys for the
TYPE_EXTENT_SIZE section.

Table 3-9: Server.ini TYPE_EXTENT_SIZE keys

Key Datatype Comments

database_ini_ext_<typename> integer Replace <typename> with the
name of the object type.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 85

Chapter 3 Managing Documentum Servers

Key Datatype Comments

database_next_ext_<typename integer Replace <typename> with the
> name of the object type.

3.6 Managing additional Documentum Servers

A repository can have more than one Documentum Server. The “Adding or
modifying Documentum Servers” on page 48 section contains information on
adding Documentum Servers to a repository.

Additional Documentum Servers serving a single repository require:

• Unique service names

The service name for each server must be unique within the network connecting
the machines and that service name must be referenced in the service property of
the server.ini file invoked for the server.
• The same trust level
Servers servicing one repository must be all non-trusted servers or all trusted
servers. It is not possible to have trusted and non-trusted servers servicing one
repository.
• Individual server configuration objects and server.ini files
On a Windows host, each server must have its own server configuration object
and server.ini file.
On a Linux host, each server must have its own server configuration object and
server.ini file, and start up script.
• On Windows hosts:
The primary installation account must be in the domain administrators group.
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 start
services for Documentum servers.
• On Linux hosts:

– The installation account of the primary host must have sufficient privilege to
execute 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.

Documentum Platform and Platform Extensions Installation Guide contains more

information on starting additional servers.

86 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.7. Managing Documentum Server in a virtual deployment

3.7 Managing Documentum Server in a virtual

deployment
3.7.1 Overview
To run the Documentum Server effectively in a virtual environment, you must be
able to automate the provisioning, management, and monitoring of Documentum
Server. A virtual environment can be an environment in which virtualized servers,
such as VMware vSphere, are deployed. Managing Documentum Server in a virtual
environment involves programmatically scaling the system up and down to adjust
and balance the system load. In addition, system components must automatically re-
connect to one another when one or more of them are restarted. In a virtual
deployment, Documentum Server can perform the following processes:

• Programmatically and gracefully start or restart the Documentum Server and all
of its components in the correct sequence
• Programmatically and gracefully shut down the Documentum Server and all of
its components in the correct sequence
• Programmatically and gracefully fail over the Documentum Server and all of its
components in the correct sequence
• Monitor the performance of the Documentum Server and all of its components

The first three processes require that the operational status of Documentum Server
and its components be able to be placed into a dormant state. A dormant state
ensures that the transactions of Documentum Server that are in-progress are
completed but that no new transactions are started. The dormant state enables
Documentum Server to be gracefully started, restarted, shut down, or complete
failovers without transactions being lost or the state of Documentum Server
becoming inconsistent.

Figure 3-1 illustrates the interactions between the major Documentum platform
components.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 87

Chapter 3 Managing Documentum Servers

Figure 3-1: Documentum Components

3.7.2 Operational status

When a Documentum Server is in a dormant or dormancy-requested state, the
following occurs:

• No new connections are accepted.

• All existing connections are placed into a read-only mode.
• Its status is projected to its associated connection brokers, which prevent new
connections from being made to it.

Connections can be pooled connections, previously timed-out but reconnected

sessions, and scheduled jobs. When running transactions are completed, they are

88 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.7. Managing Documentum Server in a virtual deployment

placed into a read-only mode. Because some users (such as datacenter

administrators) must be able to perform actions on a dormant Documentum Server,
they can be added to a privileged group. Users in the privileged group can perform
any operations that are allowed with their existing privileges and permissions on a
dormant Documentum Server.

The Java Method Server (JMS) is never placed into a dormant state, because in a JMS
high-availability configuration multiple Documentum Server instances could be
using the same JMS.

“Effects of Operational Status on Documentum Server Platform Components -

Documentum Server” on page 89 describes the effects of the operational status of
Documentum Server platform components.

To make a Documentum Server instance or repository dormant, see “Moving a

server to dormant and active states” on page 58.

To only project a Documentum Server instance as dormant or active, see “Projecting

active or dormant state of Documentum Server to connection broker” on page 59.

Table 3-10: Effects of Operational Status on Documentum Server Platform

Components - Documentum Server

Operational Status Value Documentum Server

ACTIVE 0 Normal operation. It can
accept connections and
process transactions.
DORMANCY_REQUESTED 2 Does not accept new
connection. All existing
connections are placed into a
read-only mode. All
currently running
transactions are completed.
DORMANT 1 Does not accept new
connections. All running
transactions have completed.
PROJECTED_DORMANT N/A Normal operation (including
read/write transactions)
continue for existing
connections.

Table 3-11: Effects of Operational Status on Documentum Server Platform

Components - ACS

Operational Status Value ACS

ACTIVE 0 Normal operation. It can
accept connections and
process transactions.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 89

Chapter 3 Managing Documentum Servers

Operational Status Value ACS

DORMANCY_REQUESTED 2 N/A
DORMANT 1 Does not accept new
connections. All running
transactions have completed.
PROJECTED_DORMANT N/A Normal operation.

Table 3-12: Effects of Operational Status on Documentum Server Platform

Components - Connection Broker

Operational Status Value Connection Broker

ACTIVE 0 Normal operation. It can
accept connections and
process transactions.
DORMANCY_REQUESTED 2 Does not accept projections
from Documentum Server.
Does not provide
Documentum Server or
repository maps.
DORMANT 1 Does not accept projections
from Documentum Server
and ACS. Does not provide
Documentum Server or
repository maps.
PROJECTED_DORMANT N/A Does not allow any new
connections to the
Documentum Server.

Table 3-13: Effects of Operational Status on Documentum Server Platform

Components - Workflow Agent

Operational Status Value Workflow Agent

ACTIVE 0 Normal operation. It can
accept connections and
process transactions.
DORMANCY_REQUESTED 2 All currently running
workflows are halted. Any
running, automatic tasks are
stopped and any of their
acquired work items are
placed into the paused state.
However, dormant work
items of an automatic task
remain in the dormant state.

90 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.7. Managing Documentum Server in a virtual deployment

Operational Status Value Workflow Agent

DORMANT 1 All workflows have been
halted. Any running,
automatic tasks have been
stopped and any of their
acquired work items have
been placed into the paused
state.
PROJECTED_DORMANT N/A Normal operation.

Table 3-14: Effects of Operational Status on Documentum Server Platform

Components - xPlore

Operational Value Index Agent [1] xPlore Deployment [1]

Status
Single Multiple
Repository Repositories
ACTIVE 0 Normal Normal Normal
operation. operation. operation.
DORMANCY_R 2 Behavior is Behavior is Behavior is
EQUESTED identical to that identical to that identical to that
of the of the of the
DORMANT DORMANT DORMANT
operational operational operational
status. status. status.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 91

Chapter 3 Managing Documentum Servers

Operational Value Index Agent [1] xPlore Deployment [1]

Status
Single Multiple
Repository Repositories
DORMANT 1 • For a For a dormant For a dormant
dormant Documentum Documentum
Documentu Server: Server or
m Server: repository, the
• One index
xPlore instances
Only the agent:
in the xPlore
index agents All xPlore deployment
that are instances in remain in
associated the xPlore normal
with that deployment operation.
Documentu are placed
m Server are into an Note:
shut down; off_line Even
whereas the state. when all
index agents
of other • Multiple repositorie
Documentu index agents: s are
m Servers All xPlore dormant,
associated instances in all xPlore
with the the xPlore instances
same deployment in the
repository remain in xPlore
continue to normal deployme
operate operation nt remain
normally. in normal
For a dormant operation.
• For a
dormant repository, all
repository: xPlore instances
in an xPlore
All index deployment are
agents (for all placed into an
Documentu off_line state.
m Servers
associated
with that
repository)
are shut
down.
PROJECTED_D N/A Normal Normal Normal
ORMANT operation. operation. operation.
[1] Only xPlore version 1.3 or later can work with Documentum Server Virtual Deployment
Server.

“Behavior of Dormant Servers in Various Deployments” on page 93 describes the

behavior of dormant servers in the various Documentum Server deployments.

92 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.7. Managing Documentum Server in a virtual deployment

Table 3-15: Behavior of Dormant Servers in Various Deployments

Deployment Dormant Server Instances Behavior

High Availability Single Using the other server
instance, existing sessions
can access the repository in a
read/write mode and new
sessions can be created.
Both Existing sessions can access
the repository in a read-only
mode. New sessions cannot
be created.
Load Balanced Multiple (at least one server Using the other server
instance is active) instances, existing sessions
can access the repository in a
read/write mode and new
sessions can be created. New
sessions are load-balanced
across the active server
instances
All Existing sessions can access
the repository in a read-only
mode. New sessions cannot
be created.
RCS Local Metadata requests are routed
to the remote server. Content
access for non-cached data
might be affected.
Remote The remote server does not
process content requests.
Content access for non-
cached data might be
affected.
Federated Member Push replication as well as
any federation operations
that require the governing
repository are impacted.
Governing Pull replication and any
federation operations that
require the governing
repository are impacted.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 93

Chapter 3 Managing Documentum Servers

3.7.2.1 Privileged group

The name of the privileged group is dm_datacenter_managers. All users in this
privileged group are referred to as privileged users. When a repository is in a dormant
state, all privileged users can connect to the repository in a new session (if required)
and can enable read/write permissions for themselves. Enabling read/write
permissions for privileged users do not allow any more permissions than their
existing privileges and permissions. By default, privileged users are not enabled for
read/write permissions when logging in to a dormant repository.

Note: Members of the dm_datacenter_users group can login in read-only

mode to the system that is in a dormant state. However, if you want all the
users to login in read-only mode to the system that is in a dormant state, set the
environment variable DM_DATACENTER_ALLOW_CONN to <1>.

The “Enabling or disabling save operation for a Documentum Server in dormant

state” on page 59 section contains the information to enable and disable read/write
permissions for privileged users.

3.7.3 Monitoring performance

To manage Documentum Server in a virtual environment effectively, you must be
able to determine when the performance of any of its various components is
unacceptable and then take corrective action. Performance is a measurement of an
action over a specific time period. An example of a performance metric is when
Documentum Server executes twenty transactions within a time period of thirty
minutes.

You can retrieve the following performance metrics for Documentum Server and
JMS servers:

• RPCs

– The total number of RPCs executed in the specified time period

– These execution statistics for RPCs executed during the specified time period:

○ Execution time of the fastest RPC

○ Execution time of the slowest RPC
○ Average execution time of all RPCs
• Transactions

– The total number of transactions executed in the specified time period

– These execution statistics for transactions executed during the specified time
period:

○ Execution time of the fastest transaction

○ Execution time of the slowest transaction

94 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.7. Managing Documentum Server in a virtual deployment

○ Average execution time of all transactions

• Database (Documentum Server only)

– Total size of the tablespace

– Total size of the audit table
– Total number of audit table rows

Note: The DFC Javadoc contains more information on the performance

metrics.

3.7.3.1 Using the DFC performance monitoring API

To implement a new application or add functionality to an existing application that
monitors the performance of Documentum Server in a virtual environment, you use
the methods specified in “Performance Monitoring Tasks” on page 95.

Notes

• After getting a session, you can call all of the performance monitoring
methods, which are implemented in IDfSession.
• Only privileged users can call these methods.
• The DFC Javadoc contains more information and examples on implementing
these methods.

Table 3-16: Performance Monitoring Tasks

Task Description DFC Methods

Starting and stopping the Starts the time period during startGatheringMetric
time period during which to which to collect performance s(java.
collect performance metrics metrics. util.List<java.lang.
String>metricsToGathe
r)
Stops the time period during stopGatheringMetrics(
which to collect performance java.
metrics. util.List<java.lang.
String>metricsToStop)
Retrieving performance Retrieves performance collectMetrics(java.
metrics metrics that have been util.List<java.lang.
collected during the specified String>metricsToColle
time period. ct)

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 95

Chapter 3 Managing Documentum Servers

Task Description DFC Methods

Retrieving the state of Retrieves the execution state listMetricsState()
performance metrics of each of the performance
metrics as follows:
• INITIALIZED - the metric
can be collected, but the
server has not started to
collect it yet
• STARTED - the server has
started to collect this
metric
• STOPPED - the server has
stopped collecting this
metric
Resetting previously set Clears all of the values for resetMetrics()
performance metrics existing performance metrics
and frees all server memory
associated with performance
metrics.

3.7.4 Using the DFC operational status API

The DFC Javadoc contains more information and examples about implementing the
operational status methods.

After getting a session, you can call all of the operational status methods, which are
implemented in IDfSession. Before changing the operational status of a repository,
Documentum Server, or ACS server, check their current operational status.

Figure 3-2 shows the Documentum Server state changes as a result of executing the
different DFC methods.

Figure 3-2: Documentum Server State Changes

96 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.7. Managing Documentum Server in a virtual deployment

3.7.5 Restarting Documentum Server components in virtual

deployments
This chapter discusses how and in which order to reinstall Documentum Server
components in the Windows and Linux virtual deployment environments.

3.7.5.1 Overview
In a virtual deployment, you need to be able to restart applications if a Documentum
Server is being replaced. When you restart applications in a Documentum Server
deployment, restart the following components in the following order:

1. Connection brokers

2. Documentum Server and repositories

• All workflow master and worker threads and processes

• All dmbasic method threads and processes

Note: The Documentum Server repositories are projected to the connection

brokers.

3. The JMS application server. JMS and ACS reconnect.

Note: ACS runs on the same application as JMS.

4. Index agents

Whenever an individual component is restarted:

• All transactions that were running at the time the component was stopped are
restarted.

• No data loss or integrity issues occur.

3.7.5.2 Restarting Documentum Server on Windows

These topics are included:

• Start connection brokers

• Start Documentum Servers and repositories

• Start the JMS application server

• Start the index agents

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 97

Chapter 3 Managing Documentum Servers

3.7.5.2.1 Start connection brokers

On the command line, run:

net start <service>

where <service> is the name of the connection broker service to start.

Example 3-1: Start connection brokers

net start "Documentum Connection Broker Service docbroker2"

An exit status of zero (in %ERRORLEVEL%) indicates that the restart was
successful; a nonzero result indicates that the restart was unsuccessful.

3.7.5.2.2 Start Documentum Server and repositories

On the command line, run:

net start <service>

where <service> is the name of the Documentum Server and repository Windows
service to start.

Example 3-2: Start Documentum Server and repositories

net start "Documentum Repository Service <Repo2>"

An exit status of zero (in %ERRORLEVEL%) indicates that the restart was
successful; a nonzero result indicates that the restart was unsuccessful.

3.7.5.2.3 Start the JMS application server

On the command line, run:

net start <service>

where <service> is the name of the JMS service to start. The default name is
Documentum Java Method Server.

Example 3-3: Start the JMS application server

net start "Documentum Java Method Server"

An exit status of zero (in %ERRORLEVEL%) indicates that the restart was
successful; a nonzero result indicates that the restart was unsuccessful.

98 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.7. Managing Documentum Server in a virtual deployment

3.7.5.2.4 Start the index agents

Ensure that server-impl.jar (in which IndexAgentCtrl.class is contained) is included

in CLASSPATH.

1. On the index agent host, start the application server.

2. On the Documentum Server host, on the command line, run:

Java IndexAgentCtrl -docbase_name <repository_name> -user_name <usser_name> -action
start

where:

• <repository_name> is the name of the repository that the index agent runs
against.
• <usser_name> is the name of a user that has administrator permissions.
An exit status of zero (in %ERRORLEVEL%) indicates that the restart was
successful; a nonzero result indicates that the restart was unsuccessful.

3.7.5.3 Restarting Documentum Server on Linux

These topics are included:

• Start connection brokers

• Start Documentum Servers and repositories
• Start the JMS application server
• Start the index agents

3.7.5.3.1 Start connection brokers

On the command line, run:

$DOCUMENTUM/dba/dm_launch_docbroker [-init_file file_name] [-host host_name]
[-service service_name] [-port port_number]

Include the host name (<host_name>) and a service name (<service_name>) or port
number (<port_number>)to identify the connection broker. Otherwise specify an
initialization file (<file_name>) that includes a [DOCBROKER_CONFIGURATION]
section to identify the connection broker. An exit status of zero (in the $? variable)
indicates that the restart was successful; a nonzero result indicates that the restart
was unsuccessful.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 99

Chapter 3 Managing Documentum Servers

3.7.5.3.2 Start Documentum Server and repositories

On the command line, run:

$DOCUMENTUM/dba/dm_start_<repository>

where <repository> is the name of the repository to start.

Example 3-4: Start Documentum Server and repositories

$DOCUMENTUM/dba/dm_start_<Repo2>"

An exit status of zero (in %ERRORLEVEL%) indicates that the restart was
successful; a nonzero result indicates that the restart was unsuccessful.

3.7.5.3.3 Start the JMS application server

On the command line, run:

$DM_HOME/tomcat/bin/startup.sh

3.7.5.3.4 Start the index agents

Ensure that server-impl.jar (in which IndexAgentCtrl.class is contained) is included

in CLASSPATH.

1. On the index agent host, start the application server.

2. On the Documentum Server host, on the command line, run:

Java IndexAgentCtrl -docbase_name <repository_name> -user_name <usser_name> -action
start

where:

• <repository_name> is the name of the repository that the index agent runs
against.
• <usser_name> is the name of a user that has administrator permissions.
An exit status of zero (in %ERRORLEVEL%) indicates that the restart was
successful; a nonzero result indicates that the restart was unsuccessful.

100 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.8. Server load balancing and failover

3.8 Server load balancing and failover

When an installation has a large number of users or there is a lot of activity in the
repository, multiple Documentum Servers can be used to balance the load. Starting
multiple servers also allows graceful failover if a particular server stops for any
reason.

The Documentum Servers used for load balancing must project identical proximity
values to the connection broker. If the servers have identical proximity values,
clients pick one of the servers randomly. If the proximity values are different, clients
always choose the server with the lowest proximity value.

Sessions cannot fail over to a Documentum Server with a proximity of 9000 or

greater. Documentum Servers with a proximity of 9000 or higher are called content-
file servers. RCS installed at remote, distributed sites are configured as content-file
servers by default. A client session can only fail over to servers that are known to the
connection broker used by that session. For a proper failover, ensure that
Documentum Servers project to the appropriate connection brokers and with
appropriate proximity values.

If a Documentum Server stops and additional servers are running against the
repository with proximity values less than 9000, the client library gracefully
reconnects any disconnected sessions unless one of the following exceptions occurs:

• If the client application is processing a collection when the disconnection occurs,

the collection is closed and must be regenerated again when the connection is
reestablished.
• If there is ongoing transfer between the client and server, the content transfer
must be restarted from the beginning.
• If the client had an open explicit transaction when the disconnection occurred,
the transaction is rolled back and must be restarted from the beginning.
• If the original connection was started with a single-use login ticket or a login
ticket scoped to the original server, the session cannot be reconnected to a
failover server because the login ticket cannot be reused.

3.9 Shutting down a server

On Windows platforms, Documentum Server Manager can be used to shut down
Documentum Server. On Linux, the dm_shutdown_<repository> script or the
shutdown method shuts down Documentum Server. To ensure that Documentum
Server shuts down properly, the Java Method Server should be stopped first, then
stop the repository services and the connection broker.

You must have system administrator or superuser user privileges to stop a server.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 101

Chapter 3 Managing Documentum Servers

3.9.1 Shutting down a server running on Windows

To shut down a server:

1. Navigate to Start > Control Panel > Administrative Tools > Services. Select the
Java Method Server, then click Stop.
2. Navigate to Start > Programs > Documentum > Documentum Server Manager,
click the Repository tab, select the repository, then click Stop.
3. Select the DocBroker tab, select the connection broker, then click Stop.

Caution
On Windows platforms, it is not recommended to use an
IDfSession.shutdown method to shut down the server. The method does
not necessarily shut down all relevant processes.

3.9.2 Shutting down a server running on Linux

On Linux platforms, the dm_shutdown_<repository> script logs into the specified
repository and issues a shutdown request. The script waits 90 seconds before
exiting. If the repository shuts down more quickly, the script exits as soon as the
server is down. This script is useful when you want to shut down the server as part
of a program or application, without human intervention.

You must run the script on the machine where the server resides. To invoke the
script, issue the command:
dm_shutdown_<repository> [-k]

where <repository> is the name of the repository. The -k flag instructs the script to
issue an operating-system kill command to stop the server if the shutdown request
has not been completed in 90 seconds.

3.9.3 Creating a shut-down script

Use the instructions in this section to create a shut-down script for a Documentum
Server running on a Linux host.

To create a script for a new server:

1. Make a copy of an existing dm_shutdown_<repository> script and save the copy

with a new name.
dm_shutdown_<repository> scripts are found in $DOCUMENTUM/dba.
For example:
% cd $DOCUMENTUM/dba
% cp dm_shutdown_engrrepository dm_shutdown_devrepository1

2. In the new copy, edit the line immediately preceding shutdown,c,T by replacing
<repository name>with <repository_name>.<server_config_name>.

102 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.10. Clearing the server common area

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 configuration object that you created for the server.
For example:
./iapi devrepository2.server2 -U$DM_DMADMIN_USER -P -e << EOF

3. Save the file.

3.10 Clearing the server common area

Use the procedures in this section to remove files that are in the server common
area.

To remove all files from the server common area:

1. Stop Documentum Server.

2. Do one of the following:

• On Windows, edit the Documentum Server service to add -oclean to the end
of the command line.
• On Linux, add the -oclean argument in the dm_start_<repositoryname>
command line.

3. Restart the server.

3.11 Managing the WildFly application server

The WildFly binary is bundled with the Documentum Server installation suite. The
application server is installed into the <WildFly_directory> subdirectory of the
Documentum Server installation directory. The default WildFly root directory is:

• $DOCUMENTUM\WildFly_directory on Windows platforms

• $DOCUMENTUM_SHARED\WildFly_directory on Linux platforms

The Documentum Server installation creates a WildFly server instance in the

<WildFlyRoot>\server\<instance name> directory. For example, C:\documentum
\WildFly_directory\server\DctmServer_MethodServer.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 103

Chapter 3 Managing Documentum Servers

3.11.1 Starting and stopping the WildFly application server

The WildFly application server is started automatically after a Documentum Server
installation. However, starting and stopping a Documentum Server does not
automatically start or stop the WildFly application server. The application server
hosts one or more Java applications or processes, such as the method server, the Java
Method Server, ACS server, and the DmMail application.

To start the application server:

On Windows:

1. Navigate to <WildFlyRoot>\server.

2. Execute startMethodServer.cmd or start the Windows service for the server

instance.
For the Java method server, and the server instance hosting the Java method
server, the service name is Documentum Java Method Server. Starting that
service is equivalent to executing startMethodServer.cmd.

On Linux:

1. Navigate to <WildFlyRoot>\server.

2. Execute start MethodServer.sh.

To stop an instance server:

Stopping the server stops all applications running within it.

On Windows:

1. Navigate to <WildFlyRoot>\server.

2. Execute stopMethodServer.cmd or stop the Windows service for the server

instance.
For the Java method server, and the server instance hosting the Java method
server, the service name is Documentum Java Method Server. Stopping that
service is equivalent to executing stopMethodServer.cmd.

On Linux:

1. Navigate to <WildFlyRoot>\server.

2. Execute stopMethodServer.sh.

104 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 3.12. Server log files

3.12 Server log files

Each Documentum Server maintains a log file. By default, the
<serverconfig_name>.log log file is stored in the %DOCUMENTUM%\dba\log
directory, where <serverconfig_name> is the name of the Documentum Server server
configuration object. The default location is defined in the log location object that is
referenced by the log_location property in the server configuration object.

Both, the name and the location of the file can be modified using the -logfile
parameter on the server start-up command line. The server appends to the log file
while the server is running. If the server is stopped and restarted, the file is saved
and another log file started. The saved log files have the following format:

On Windows platforms: <serverconfig_name>.log.save.mm-dd-yy_hh.mi.ss

On Linux platforms: <serverconfig_name>.log.save.mm.dd.yyyy.hh.mi.ss

3.13 The dm_error utility

The dm_error utility returns information about Documentum Server errors. The
utility is run from the command line: dm_error <error_code> Where <error_code> is
the abbreviated text that describes the error. For example,
DM_SERVER_E_NO_MTHDSVR_BINARY.

The utility output of the displays the cause of the error and possible solutions, as
described in the following example:
[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.

3.14 Improving performance on Oracle and

PostgreSQL databases
The performance and throughput of Documentum Server depends to a certain
extend on where the repository content is stored in the underlying database. When a
repository is created, the Documentum Server creates object-type tables and indexes
in the underlying RDBMS in the same tablespace by default. Oracle or PostgreSQL
can be partitioned to store data in different tablespaces. For example, frequently
used data could be stored in a designated tablespace. The size and number of the
extents allotted for each table are determined by default configuration parameters in
the server.ini file. Documentum Platform and Platform Extensions Installation Guide
contains the instructions.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 105

Chapter 4
Managing Repositories

4.1 Repositories
Repositories are comprised of object type tables, type indexes, and content files. The
type tables and type indexes are tables in an underlying relational database. The
content files are typically stored in directories on local disks. Content files can also
be stored in the database, in a retention storage system such as Centera or NetApp
SnapLock, or on external storage devices.

A full-text index is associated with a particular repository or, in a consolidated

deployment, with all repositories indexed by a particular index server installation.
Full-text indexes enable rapid searching for designated values or strings in content
files and property values.

Users access repositories through Documentum Servers. The Documentum Servers

receive queries from clients in the form of Documentum Foundation Classes (DFC)
methods or Documentum Query Language (DQL) statements and make the actual
call to the underlying relational database management system (RDBMS) or the file
directories. Every repository must have at least one active Documentum Server. If a
repository does not have an active server, users cannot access that repository.

Information that about the repository is located in a server startup file. The startup
file is executed whenever the ACS server is started. The information in the startup
file binds the Documentum Server to the repository.

4.2 Managing repositories

The repository is configured on the Administration > Basic Configuration >
Repository page in Documentum Administrator. A repository is represented by a
repository configuration object that defines configuration parameters, such as the
name of the underlying RDBMS, security levels for the repository, and other
operating configuration parameters.

Only users with superuser privileges can view or modify the repository
configuration object of a repository. It is not possible to use Documentum
Administrator to create additional repositories or delete an existing repository.
Adding another repository requires running the Documentum Server installer.

The Repository list page displays the following information:

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 107

Chapter 4 Managing Repositories

Table 4-1: Information on Repository page

Basic Configuration Description

Name The name of the repository configuration
object of the repository.
DBMS The underlying database used for the
repository.
Federation The federation to which the repository
belongs.
Effective Date The effective date of the repository
configuration object. The effective date is
used to manage client query caches.
Dormancy Status The current dormancy status of the
repository. Valid values are:
• Dormancy Requested
• Dormant
• Active
• Invalid

Note: The Dormancy Status column is

only visible for 7.0 and later versions of
repositories.

4.2.1 Viewing or modifying the repository configuration

You can modify some, but not all, of the repository configuration values.

Table 4-2: Repository Configuration Properties

Field Label Value

Database The name of the RDBMS vendor. Read-only.
Repository ID The repository ID number assigned during
installation. Read-only.
Federation Specifies if the repository is a member of a
federation. Read-only.
Security The security mode of the repository. ACL
and None are valid values. None means
repository security is disabled. ACL means
access control lists (permission sets) are
enabled. Read-only.
Index Store The name of the tablespace or other storage
area where type indexes for the repository
are stored.

108 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

Field Label Value

Partitioned Indicates whether the repository is
partitioned. When a repository is created or
updated with partitioning enabled, the
Documentum Server sets the flag to True.

The Partitioned field is:

• Not selectable or changeable.
• Available only in 6.5 repositories.
Crypto Mode Displays the type of cryptography used by
Documentum Server.
Crypto Key Store Indicates the encryption key stored on the
Documentum Server.
Dormancy Status Indicates the dormancy status of repository.

Note: The Dormancy Status label is

only visible for 7.0 and later versions of
repositories.
Update Configuration Changes
Re-Initialize Server Select to reinitialize the server to which you
are connected. This is necessary for changes
to objects to take effect.
Configuration Changes
Folder Security Specifies whether folder security is enabled.
Select to enable folder security. The server
performs the permission checks required by
the repository security level and for some
operations, also checks and applies
permissions on the folder in which an object
is stored or on the objects primary folder.
Rich Media Specifies whether the server processes rich-
media content. This feature only works if
Media Server is installed in the repository. If
you enable the Rich Media feature, you must
re-initialize the server for the changes to take
effect.
Workflow Packages Specifies whether the object names of
workflow package components are
displayed. By default, the object names are
displayed. Select this option to not display
the object names.
Data Dictionary Locales Specifies the locale of the data dictionary.
The default local is en (English). Click Edit to
configure a different locale. The server must
be reinitialized for any changes to be visible.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 109

Chapter 4 Managing Repositories

Field Label Value

Oldest Client Version Specifies which DFC version is used for
chunked XML documents. The value must be
changed manually. If the field is left blank,
the DFC format is compatible with client
versions earlier than the current DFC
version. If a particular DFC version is
specified, clients running an earlier DFC
version cannot access the chunked XML
documents. Set the property value to the
client version number in the format XX.YY,
where X is the major version and Y is the
minor version.
Modifications Comment This field is optional. It can be used to add a
comment about any modifications made to
the repository configuration.
Default Application Permit The default user permission level for
application-controlled objects accessed
through an application that does not own the
object. Valid values are:
• 2: Browse
• 3: Read
• 4: Relate
• 5: Version
• 6: Write
• 7: Delete

The default value is 3, Read permission.

Fulltext Install Locations Specifies the Verity versions installed and
their locations in pre-5.3 repositories.
Content Storage Services Enabled Specifies whether Content Storage Services
were enabled during Documentum Server
installation. If the value is true, Content
Storage Services are enabled.
Minimum Owner Permission Specifies the minimum permission for an
object owner after all ACL rules have been
applied. The permission applies to the entire
repository. Valid values are:
• Browse
• Read
• Relate
• Version
• Write
• Delete

The default value is Browse.

110 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

Field Label Value

Minimum Owner Extended Permission Specifies the minimum owner extended
permissions for an object owner after all ACL
rules have been applied. One or more
extended permissions can be selected. By
default, no extended permission is selected.
Valid values are:
• Execute Procedure
Users with superuser privileges can
change the owner of an item and run
external procedures on certain types.
• Change Location
Allows the object owner to move the
object in the repository.
• Change State
Allows the object owner to change the
state of a lifecycle attached to the object.
• Change Permission
Allows the object owner to modify the
basic permissions associated with the
object.
• Change Ownership
Allows the object owner to change the
object owner.
• Extended Delete
Allows the object owner to delete the
object.
• Change Folder Links
Allows the object owner to link or unlink
the object to a folder.
Authorization Settings

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 111

Chapter 4 Managing Repositories

Field Label Value

MAC Access Protocol The file-sharing software type in use for
Macintosh clients. Valid values are:
• None
• NT
• Ushare
• Double

The default value is None.

If you change the value from NT, Ushare, or

Double to None, existing resource forks are
no longer be accessible.

To change the value from or to NT, Ushare,

or Double, you must first change the value to
None, save the configuration, and then
change it from None to the new value.
Authentication Protocol Defines the authentication protocol used by
the repository.
• On Windows, if set to Domain Required,
it indicates that the repository is running
in domain-required mode.
If a repository is running in domain-
required mode, the login domain value in
the login ticket generated for a user
attempting to log in using an inline
password defaults to the domain of the
superuser even if the user on the login
ticket belongs to a different domain.
Users from a different domain must
specify the their login domain name
when logging into the repository.
If a repository is running in no-domain
required mode, users can login with only
their user name and inline password. It is
also possible to prepend the user name
with a backslash (\). A backslash
specifies an empty domain.
• On Linux platforms, choose between
Linux authentication or Windows domain
authentication.
Cached Query Effective Date Used to manage the client query caches. The
default is NULLDATE.

112 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

Field Label Value

Run Actions As The user account that is used to run business
policy (document lifecycle) actions. Options
are:
• Session User (default)
• Superuser
• Lifecycle Owner
• Named User
If selected, click the Select User link to
access the Choose a user page to select a
user.
Login Tickets Specifies that all other repositories are
trusted and login tickets from all repositories
are accepted by the current repository.
If selected, Allow login tickets from
repositories is not displayed.
Allow login tickets from repositories This field is only displayed if Allow all login
tickets is not selected.

Click Select to access the Choose

Repositories page to designate repositories
whose login tickets are permitted in the
current repository (the trusted repositories).
Designate Login Ticket Expiration Specifies the earliest possible creation date
for valid login tickets. Tickets issued before
the designated date are not valid in the
current repository. Select one of the
following:
• Null date: Specifies that there is no cutoff
date for login tickets in the current
repository. This is the default value.
• Expire login tickets on the following
date and time: Specifies the earliest
possible creation date for valid login
tickets. Use the calendar control to choose
the correct date and time.
Login tickets created before that time and
date cannot be used to establish a
connection. Currently connected users are
not affected by setting the time and date.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 113

Chapter 4 Managing Repositories

Field Label Value

Maximum Authentication Attempts The number of times user authentication can
fail for a user before that user is disabled in
the repository. Authentication attempts are
counted for logins and API methods
requiring the server to validate user
credentials, including the Changepassword,
Authenticate, Signoff, Assume, and Connect
methods.

By default, the installation owner account is

not subject to the failure threshold and is not
disabled when it reaches the maximum
number of attempts. You can modify the
installation owner account from the User
pages.

A value of zero (0) means that the feature is

not enabled.

Requires the server to be reinitialized for

changes to take effect.
LDAP Synchronization On-Demand Used to synchronize LDAP directory users
with the repository between scheduled runs
of the LDAP synchronization job:
• When cleared, LDAP directory users who
do not exist in the repository cannot log
in.
• When selected, if an LDAP directory user
attempts to log in and is found not to
exist in the repository, Documentum
Server searches all active directory
connections for the user. If the user is
found and can be authenticated, the user
is created in the repository.
Privileged Clients Boolean. If selected, indicates that the
repository is accessible to privileged clients
only.

This checkbox is only available if a DFC

client exists in the repository and is
approved to perform privilege escalations.

Documentum Administrator User Guide contains the instructions on viewing or

modifying the repository configuration.

114 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

4.2.2 Modifying repository synchronization

The synchronization options control the behavior of Documentum Offline Client.

Table 4-3: Synchronization properties

Field Label Value

Synchronization Settings For repositories where Offline Client is
enabled. Options are:
• None: no content synchronization to local
machine.
No content is synchronized to the local
machine. This is the default setting for a
repository.
• Basic: 1-way download to local machine
as read only.
Content is downloaded to the local
machine and marked read-only. No
content is uploaded from the local
machine.
• Role-Based: assign sync permissions to
specific repository roles.
Synchronization permissions are based
on specific user roles. Synchronization is
enabled and users can download content.
Whether content can be uploaded
depends on a particular role of user. If
selected, you must designate the
synchronization roles and check-in
settings.
Synchronization Role If you selected role-based synchronization
where Offline Client is enabled, you must
designate the roles. Click the Select users/
groups for offline upload link to access the
Chose a user/group page to select users who
you want to use offline upload.
Check In Settings Select to use the client dialog or the local
settings of user to check content into the
repository. Options are:
• Always Use client dialog to check in
content
• Use User’s local check in setting

Documentum Administrator User Guide contains the instructions on modifying

repository synchronization.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 115

Chapter 4 Managing Repositories

4.2.3 Moving a repository to dormant and active states

This section describes how to move a repository to a dormant state and back to an
active state.

A repository can be moved to a dormant state only from an active state. To perform
this operation, you should be a member of the dm_datacenter_managers, a
privileged group whose membership is maintained by superusers. This feature is
only applicable for 7.0 and later versions of repositories.

Notes

• When a repository is moved to a dormant state, the status of all the

Documentum Servers and ACS servers for this repository will also be moved
to a dormant state.
• In a multiple Documentum Server setup, moving a repository to a dormant
state will move all the configured Documentum Servers to a dormant state.
However, there will be delay in moving the non-connected servers to a
dormant state. This delay is equal to the value of database_refresh_interval
key as specified in server.ini. The database_refresh_interval key defines
how often the main server thread (parent server) reads the repository to
refresh its global caches. You can raise this value but it cannot be lowered.
The default value is 1 minute.
• For a WDK application to login to a repository in a dormant state,
dmc_wdk_presets_owner, dmc_wdk_preferences_owner, and
dm_bof_registry users should be a member of dm_datacenter_managers.

A repository can be moved back to an active state only from a dormant state. To
perform this operation, you should be a member of the dm_datacenter_managers, a
privileged group whose membership is maintained by superusers. This feature is
only applicable for 7.0 and later versions of repositories.

Note: When a repository is moved to an active state, the status of all the
Documentum Servers and ACS servers for this repository will also be moved
to an active state.

Documentum Administrator User Guide contains the instructions on the following:

• Moving a repository to a dormant state

• Moving a repository to an active state

116 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

4.2.4 Enabling a repository as a global registry

Enabling a repository as a global registry after configuration, requires activating the
dm_bof_registry user. The global registry and user credentials can also be
configured in the dfc.properties file.

Documentum Administrator User Guide contains the instructions on enabling a

repository as a global registry.

During the DFC installation on client machines, such as the Documentum

Administrator host, provide the user login name and password for the
dm_bof_registry user. This action updates the dfc.properties file and enables the
DFC installation to contact the global registry.

To modify the dfc.properties file manually:

1. On the DFC host, navigate to $DOCUMENTUM/config (Linux) or

%DOCUMENTUM%\config (Windows).

2. From a command prompt, execute the following command to generate the

encrypted form of the global registry user’s password:
java -cp dfc.jar com.documentum.fc.tools.RegistryPasswordUtils

password_of_user

where password_of_user is the clear-text password of the global registry user.

3. Open the dfc.properties file in a text editor and modify the following attributes:
dfc.globalregistry.repository=global_registry_repository_name

dfc.globalregistry.username=user_login_name

dfc.globalregistry.password=encryped_password_of_user

where encryped_password_of_user is the encrypted password you generated in

step 2.

4. Save the dfc.properties file.

4.2.5 Repository content

The Documentum Server installation program and the scripts that run during
repository configuration automatically create various objects, such as cabinets,
configuration objects, users, and groups.

“Default users created during repository configuration” on page 117 lists the default
users that are created during repository configuration.

Table 4-4: Default users created during repository configuration

User User Privileges Extended User Privileges

repository_owner Superuser None

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 117

Chapter 4 Managing Repositories

User User Privileges Extended User Privileges

installation_owner Superuser None
global registry user None None
dm_bpm_inbound_user None None
dm_autorender_win32 System Administrator None
dm_autorender_mac System Administrator None
dm_mediaserver System Administrator None
dm_fulltext_index_user Superuser None

The configuration program creates a number of default groups. “Default groups

created during repository configuration” on page 118 describes the default groups.
In addition to the default groups, the configuration program also creates a set of
privileged groups.

Table 4-5: Default groups created during repository configuration

Group Members
admingroup installation_owner, repository_owner
docu repository_owner, installation_owner,
dm_autorender_win32, dm_autorender_mac,
dm_mediaserver
queue_admin None.

This is a role group supporting the queue

management feature of Documentum
Process Builder.
queue_manager queue_admin group

This is a role group supporting the queue

management feature of Documentum
Process Builder.
queue_processor queue_manager group

This is a role group supporting the queue

management feature of Documentum
Process Builder.
process_report_admin queue_admin

This is a role group supporting the queue

management feature of Documentum
Process Builder.

118 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

4.2.6 Type indexes

Indexes on the object type tables in the RDBMS enhance the performance of
repository queries. When a repository is configured, the Documentum Server creates
various object type indexes. There are several administration methods for managing
type indexes:

• MAKE_INDEX
The “MAKE_INDEX” on page 362 section contains more information.
• MOVE_INDEX
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
each or you can move the indexes later, using the MOVE_INDEX method.
Indexes that you create can be placed in any directory. The “MOVE_INDEX”
on page 362 section contains more information.
Documentum Platform and Platform Extensions Installation Guide contains more
information on creating a repository with separate tablespaces,
• DROP_INDEX
Removes a user-defined index. It is strongly recommended to not remove any of
the system-defined indexes. The “DROP_INDEX” on page 358 section contains
more information.

Each method can be executed through Documentum Administrator, an apply

method, or the DQL EXECUTE statement.

4.2.7 Date values

By default, Documentum Server stores values as UTC (Coordinated Universal Time)
time in new repositories (Documentum 6 and later), and as the local time in
repositories that are upgraded from versions prior to 6.

The r_normal_tz property in the docbase config object controls how Documentum
Server stores dates in the repository. If the property value is 0, all dates are stored in
UTC time. Otherwise, dates are normalized using the local time of Documentum
Server before being stored in the repository. Offset value is time zone offset from
UTC time, expressed as seconds and it is set by Documentum Server during the
upgrade of existing repositories (repositories upgraded from 5.x versions to later).
For example, if the offset represents the Pacific Standard Time zone, the offset value
is -8*60*60, or -28800 seconds. When the property is set to an offset value,
Documentum Server stores all date values based on the time identified by the time
zone offset.

In a Documentum 6 or later repository, r_normal_tz value is set to 0. In a repository

upgraded from a release earlier than version 6, the r_normal_tz value is set to the
offset that represents Documentum Server local time by Documentum Server and
cannot be changed.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 119

Chapter 4 Managing Repositories

4.2.8 Moving or duplicating a repository

Moving or duplicating a repository requires dump and load operations. Dump and
load operations can be used to:

• Move part of a repository from one location to another.

• Duplicate part of a repository.
Use dump and load operations to create a duplicated repository with a different
name or repository ID than the source repository.

Dump or load operations require superuser privileges. A dump operation creates a

binary file of objects dumped from a repository. If a dumped object has associated
content files, the content files are either referenced by full path or included directly
in the dump file. The load operation loads the objects and content files into another
repository.

Dump files are created by using the session code page. For example, if the session in
which the dump file was created was using UTF-8, the dump file is a UTF-8 dump
file. The repository into which the dump file is loaded must use the same code page
the source repository.

Dump and load operations can be performed manually using either IAPI, Docbasic
scripts, or the IDfDumpRecord and IDfLoadRecord DFC interfaces.

Note: Dump and load operations require additional steps for repositories
where Web Publisher is installed. Documentum Web Publisher Deployment Guide
contains more information.

4.2.8.1 Supporting object types

There are several object types that support dump and load operations:

• Dump Record (dm_dump_record)

A dump record object contains information about a specific dump execution. It
has a property that contains the name of the file with the dumped information
and properties whose values tell Documentum Server which objects to copy into
the specified file.
• Dump Object Record (dmi_dump_object_record)
A dA dump object record object contains information about one specific object
that is copied 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. Its
properties are used by Documentum Server to manage the loading process. It
also has two properties that contain the starting and ending times of the load
operation.
• Load Object Record (dmi_load_object_record)

120 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

A load object record object contains information about one specific object that is
loaded from the dump file into a repository. Load object record objects are used
internally.

Documentum Server System Object Reference Guide contains information on the

properties of these object types.

4.2.8.2 Dumping objects under retention

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

If a retainer object is dumped directly, the object identified in the retainer_root_id

property of the retainer is also dumped. That object can be a single SysObject or a
container, such as a folder. If it is a container, the objects in that container are not
dumped, only the container itself is dumped.

Note: This information does not apply to dump and load operations that are
used to execute object replication jobs.

4.2.8.3 Aspects and dump operations

A dump operation does not dump aspects associated with a dumped object. If
aspects are associated with specific instances of an object type, those aspects must be
created in the target repository. Similarly, if default aspects are defined for an object
type and instances of that type are dumped, the default aspects must be manually
created in the target repository. The aspects must be created in the target repository
before performing the load operation.

4.2.8.4 Dumping an entire repository

Dumping the contents of an entire repository by setting the dump_operation
property of the dump record object to full_docbase_dump is currently not
supported.

4.2.8.5 Dumping specific objects

To dump only specific objects in a repository, set the type, predicate, and predicate2
repeating properties of the dump record object. The type property identifies the type
of object you want to dump and the predicate and predicate2 properties define a
qualification that determines which objects of that type are dumped. Documentum
Server System Object Reference Guide contains a full description of properties of a
dump record object.

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

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

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 121

Chapter 4 Managing Repositories

The ACL associated with a dumped object is also dumped.

4.2.8.5.1 Setting the type property

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

The dump operation dumps objects of the specified type and any of its subtypes that
meet the qualification specified in the predicate. Consequently, it is not necessary to
specify each type by name in the type property. For example, if you specify the
SysObject type, then Documentum Server dumps objects of any SysObject or
SysObject subtype that meets 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 if
objects that are a subtype of the type are dumped.
This means that if a subtype of a specified type has no objects in the repository or
if no objects of the subtype are dumped, the dump process does not dump the
definition of subtype. For example, suppose you have a subtype of documents
called proposal, but there are no objects of that type in the repository yet. If you
dump the repository and specify dm_document as a type to dump, the type
definition of the proposal subtype is not dumped.
This behavior is important to remember if you have user-defined subtypes in the
repository and want to ensure that their definitions are loaded into the target
repository.
• To dump subtype definitions for types that have no objects instances in the
repository or whose objects are not dumped, you must explicitly specify the
subtype in the dump script.
• If you have created user-defined types that have no supertype, be sure to
explicitly include them in the dump script if you want to dump objects of those
types. For example, the following commands will include all instances of
your_type_name:
append,c,l,type
your_type_nameappend,c,l,predicate
1=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. For example, include the following lines in a dump script to dump all
ACLs in the repository (including orphan ACLs):
append,c,l,type
dm_acl
append,c,l,predicate
1=1

122 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

You may want to specify a qualification in the predicate to exclude orphaned

internal ACLs.

• By default, storage area definitions are only included if content associated with
the storage is dumped. If you want to dump the definitions of all storage areas,
even though 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, Documentum Server dumps
only the object (dm_registered) that corresponds to the registered table. The
underlying RDBMS table is not dumped. Use the dump facilities of the
underlying RDBMS to dump the underlying table.

4.2.8.5.2 Setting the predicate properties

You must supply a predicate for each object type you define in the type property. If
you fail 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
the type, such as 1=1.

To dump a subset of the instances of the object type, define a WHERE clause
qualification in the predicate properties. The qualification is imposed on the object
type specified at the corresponding index level in the type property. That is, the
qualification defined in predicate[0] is imposed on the type defined in type[0], the
qualification defined in predicate[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] is
object_name = ‘foo’, then only documents or document subtypes that have an object
name of foo are dumped. The qualification can be any valid WHERE clause
qualification. The Documentum Server DQL Reference Guide contains the description of
a valid WHERE clause qualification.

The predicate property accepts a maximum of 255 characters. If the qualification

exceeds 255 characters, place the remaining characters in the predicate2 property at
the corresponding index level. For example, if the qualification defined for type[0] is
300 characters, you put the first 255 characters in predicate[0] and the remaining 45
in predicate2[0]. When the dump is executed, Documentum Server concatenates
predicate[0] and predicate2[0]. The predicate2 property accepts a maximum of 255
characters also.

Important: If you use the predicate2 property at any index position, you must also set
the predicate2 property at all index positions before the desired position.
Documentum Server does not allow you to skip index positions when setting
repeating properties. For example, 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 index positions to a single blank.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 123

Chapter 4 Managing Repositories

4.2.8.6 Content files and dumping

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

By default, if the content is stored in a file store, Centera storage area, or NetApp
SnapLock storage area, the content is not included in the dump file. You can set the
include_content parameter to include such content. If you are dumping a repository
that has encrypted file store storage areas, you must include the content in the dump
file. Documentum Server decrypts the content before placing it into the dump file.

“Dumping without content” on page 124 describes the default behavior and
requirements for handling dump files without content. “Including content”
on page 125 describes how to include content and the requirements for dump files
with content.

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

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

4.2.8.6.1 Dumping without content

By default, a dump operation on content in file stores, Centera stores, or NetApp

SnapLock stores does not include content. Instead, when an object with content is
dumped, the operation places a reference to the content in the dump file. If the
content is stored in a file system, the reference is a file system path. If the object is
stored in a retention storage system, the reference is the address of content.

When the dump file is loaded into the target repository, any file systems referenced
for content 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_store object at the source repository and must point to the same storage system
used by the source repository.

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

The owner of the target repository must have Read permission in the content storage
areas of the dumped repository when the load operation is executed. The load
operation uses the target repository owner account to read the files in the source
repository and copy them into the target repository.

124 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

4.2.8.6.2 Including content

To include content in a dump file, set the include_content property to T (TRUE) in

the dump record object. If the property is true, when Documentum Server dumps an
object with content, the content is copied into the dump file also. The content must
be stored in a file store, Centera store, or NetApp SnapLock storage area.
Documentum Server cannot copy content from external storage into a dump file.

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

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

4.2.8.6.3 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 to
compress_content = T.

Documentum Server automatically decompresses a compressed dump file during a

load operation.

4.2.8.7 Setting the cache size

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

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

To increase the cache size, set the cache_size argument of the dump_parameter
property to 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 the number of dumped objects increases.

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

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 125

Chapter 4 Managing Repositories

4.2.8.8 Using non-restartable dump

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

A dump operation can only be non-restartable if it is a partial repository dump. Full

repository dump operations are always restartable.

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

restartable=F.

4.2.8.9 Using a script to create a dump file

For dump operations that you execute regularly, we recommend that you write a
script that creates and saves the dump object and checks for errors after the
execution. Using a script avoids re-creating the dump object manually each time you
want to perform the 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, Documentum Server
assumes the path is relative to the root directory of the server. The filename
must be unique within its directory. This means that after a successful load
operation that uses the dump file, you must move the dump file to archival
storage or destroy it so you can 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 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 dump
operation did not return OK, the dump was not successful.
Destruction of the dump object cleans up the repository and removes the dump
object records and state information that are no longer needed.

126 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

4.2.8.9.1 Sample script for a partial repository dump

Note: 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 want to dump only some subset of objects or want to include all ACLs, type
definitions, or storage area definitions, modify the script accordingly.

Here is the script:

create,c,dm_dump_record
set,c,l,file_name
dumpfile name# Supply your own file name.
# This must be a new file
append,c,l,type
dm_sysobject
append,c,l,predicate
1=1
append,c,l,type
dm_assembly
append,c,l,predicate
1=1
append,c,l,type
dm_format
append,c,l,predicate
1=1
append,c,l,type
dm_user
append,c,l,predicate
1=1
append,c,l,type
dm_group
append,c,l,predicate
1=1
append,c,l,type
dmi_queue_item
append,c,l,predicate
1=1
append,c,l,type
dmi_registry
append,c,l,predicate
1=1
append,c,l,type
dm_relation
append,c,l,predicate

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 127

Chapter 4 Managing Repositories

1=1
append,c,l,type
dm_relation_type
append,c,l,predicate
1=1
append,c,l,type
dmr_containment
append,c,l,predicate
1=1
append,c,l,type
dmr_content
append,c,l,predicate
1=1
append,c,l,dump_parameter
cache_size=60 #set cache size
append,c,l,dump_parameter
restartable=F #non-restartable dump
append,c,l,predicate
1=1
save,c,l
getmessage,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, Documentum Server
assumes the path is relative to the root directory of the server. The filename
must be unique within its directory. This means that after a successful load
operation using the dump file, you must move the dump file to archival
storage or destroy it so that you can successfully execute the script later.
• To dump user-defined types that have no supertype, add Append methods
for each to the script:
append,c,l,type
your_type_nameappend,c,l,predicate
1=1

4.2.8.10 If the server crashes during a dump operation

If Documentum 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, the save operation fails. Re-executing the script creates a new dump
record object.
• If the dump operation is restartable, fetch the existing dump object from the
source repository and save it again. Saving the object starts the dump operation.
Documentum Server begins where it left off when the crash occurred.

128 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

4.2.8.11 Moving the dump file

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

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

4.2.8.12 Loading a repository

Loading a repository puts the objects stored in a dump file into the repository. The
dump file header does not indicate the session code page in which the dump file
was created. If you do not know the session code page in use when a dump file was
created, do not load the dump file.

If the dump file does not include the actual content files associated with the objects
you are loading, the operation reads the content from the storage areas of the
dumped repository. 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 source repository.

The load operation generates a dmi_queue_item for the dm_save event for each
object of type SysObject or a subtype that is loaded into the target repository. The
event is queued to the dm_fulltext_index_user user account. This ensures that the
objects are added to the index of target repository. You can turn off this behavior.
The “Turning off save event generation during load operations” on page 130 section
contains the instructions.

Loading a repository is accomplished by creating and saving a load record object.

The act 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 Documentum Server does 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 if you are in an explicit
transaction.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 129

Chapter 4 Managing Repositories

4.2.8.12.1 Refreshing repository objects from a dump file

Generally, when you load objects into a repository, the operation does not overwrite
any existing objects in the repository. However, in two situations overwriting an
existing object is the desired behavior:

• When replicating content between distributed storage areas

• When restoring archived content

In both situations, the content object that you are loading into the repository could
already exist. To accommodate these instances, the load record object has a relocate
property. The relocate property is a Boolean property that controls whether the load
operation assigns new object IDs to the objects it is loading.

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

4.2.8.12.2 Loading job objects

If you dump and load job objects, the load operation automatically sets the job to
inactive in the new repository. This ensures that the job is not unintentionally started
before the load process is finished and it allows you the opportunity to modify the
job object if needed. For example, to adjust the scheduling to coordinate with other
jobs in the new repository.

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

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

4.2.8.12.3 Loading registered tables

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

4.2.8.12.4 Turning off save event generation during load operations

During a load operation, every object of type SysObject or SysObject subtype loaded
into the target repository generates a save event. The event is queued to the
dm_fulltext_index_user. This behavior ensures that the object is added to the target
index of the repository.

The behavior is controlled by the load parameter called generate_event. The

parameter is T by default. If you do not want the load operation to queue save
events to the dm_fulltext_index_user, set the parameter to F for the operation. The
parameter is set in the load_parameter property as:
generate_event=F

130 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

4.2.8.12.5 Loading a new repository

New repositories are not empty. They contain various cabinets and folders created
by 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 cabinet

When you load a dump file into a new repository, these objects are not replaced by
their counterparts 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 of the 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 on the System cabinet, those changes are lost.

To ensure that any changes you have made are not lost, fetch from the source
repository any of the system objects that you have altered and then use the Dump
method to get a record of the changes. For example, if the cabinet of repository
owner was modified, use the 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 necessary changes.

4.2.8.12.5.1 The preLoad utility

Documentum provides a utility that you can run on a dump file to tell you what
objects that you must create in the new repository before you load the dump file.
The utility can also create a DQL script that you can edit and then run to create the
needed objects. The syntax 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 those that have been copied into the dump file.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 131

Chapter 4 Managing Repositories

4.2.8.12.6 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
load operation performs periodic commits to the repository. Documentum
Server does not allow you to save the load record object to start the load
operation if you are in an explicit transaction.

To load a dump file into a new repository:

1. Create the repository.

Notes

• If the repository shares any directories with the source repository, you
must assign the repository an ID that differs from the source repository
ID.
• If the old and new repositories have different owners, ensure that the
new repository owner has Read privileges in the storage areas used by
the old repository if the old repository was not dumped with the
include_content property set to TRUE.
2. Create the necessary storage objects and associated location objects in your new
repository.
Each storage object in your source repository must have a storage object with
the same name in the new repository. The filestore objects in the new repository
must reference location objects that point to actual directories that differ from
those referenced by the location objects in the source repository.
For example, suppose you have a file store object with the name storage_1 in
your source repository that points to the location object named engr_store,
which references 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 name storage_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 the same name. Either option is acceptable.
3. If your storage areas in the source repository had associated full-text indexes,
create corresponding fulltext index objects and their location objects in the new
repository. Note that these have the same naming requirements as the new
storage objects described in “Load procedure for new repositories” on page 132.
4. Create and save the following script:
create,c,dm_load_record
set,c,l,file_name
full_path_of_dump filesave,c,l
getmessage,c

5. Log in as the owner of the installation and use IAPI to execute the script.

132 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

When you start IAPI, connect to the new repository as a user who has Sysadmin
privileges 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
cannot successfully execute the script again if you leave the dump file in
the location where the script created it. Documentum Server does not
overwrite an existing dump file with another dump file of the same
name.
• If Documentum Server crashes during a load, you can fetch the Load
Object and save it again, to restart the process. Documentum Server
begins where it left off when the crash occurred.

4.2.8.12.7 DocApps

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

4.2.8.13 Generating dump and load trace messages

You can activate tracing during dump and load operations to generate trace
messages in the Documentum Server session log.

To activate tracing, use a setServerTraceLevel method.

The trace information includes:

• Whether Documentum 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

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 133

Chapter 4 Managing Repositories

4.2.9 Repository maintenance

Repositories should be cleaned up regularly as part of a maintenance schedule.
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 does not delete the actual content file. This must be done using the
dmclean utility.
• Unwanted document versions and renditions
• Orphaned annotations and internal ACLs
An annotation is orphaned when it is detached from all documents or other
objects to which it was attached.
An internal ACL is orphaned when it is no longer referenced by any object.
• Aborted workflows
A workflow that has been stopped by the execution of an Abort method is an
aborted workflow.
• Old log files

To clean a repository:

1. Perform a complete backup of the repository.

2. Delete unwanted versions of documents.

You can delete only versions created before a certain date or by a certain author
or delete all but the CURRENT version from one or more version trees.

• To delete selected versions of documents, use the DELETE...OBJECT

statement.
Identify the documents to delete by their creation date, modification date, or
some other criteria that you choose. For example, the following statement
deletes all documents that have not been changed since January 1, 2000:
DELETE "dm_document" OBJECTS
WHERE "r_modify_date" < DATE('01/01/2000')

• 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.
An unwanted version is any version that has no symbolic label and that does
not belong to a virtual document. The Javadocs contains information for the
usage of the method.

3. Delete unused renditions.

A rendition is represented in the repository by a content object that points to the
source document and by a content file.

134 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

To delete a rendition (without deleting its source document, first update the
content object for the rendition to remove its reference to the source document.
For example, the following UPDATE...OBJECT statement updates all server-
and user-generated renditions created before January 1, 2000. The updates in
the statement detach the affected renditions from their source documents,
effectively deleting them from the repository.
UPDATE "dmr_content" OBJECTS
SET "parent_count" = 0,
TRUNCATE "parent_id",
TRUNCATE "page"
WHERE "rendition" != 0 AND "set_time" < DATE('01/01/2000')

4. Clean the temp directory by deleting the temporary files in that location.
You can determine the location of the temp directory 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 the inbox of a user, a dmi_queue_item object is
created. When the object is removed, the queue item object is not destroyed, but
it is marked in the repository as dequeued. Use the DELETE...OBJECT
statement to remove dmi_queue_item objects.
For example, the following statement removes all queue items objects that were
dequeued before January 1, 2000:
DELETE "dmi_queue_item" OBJECTS
WHERE "dequeued_date" < DATE('01/01/2000')
AND "delete_flag"=true

6. Run the dmclean utility to remove orphaned content files, orphaned

annotations and ACLs, and aborted workflows. You can execute the Dmclean
administration tool or run the dmclean utility manually. The “Dmclean”
on page 389 section contains more information on the dmclean utility.

7. Delete or archive old server logs, session logs, trace files, and old versions of the
product.
Session logs are located in the %DOCUMENTUM%\dba\log\repository_id
($DOCUMENTUM/dba/log/repository_id) directory.
Documentum Server and connection broker log files are found in the
%DOCUMENTUM%\dba\log ($DOCUMENTUM/dba/log) directory. The
server log for the current server session is named repository_name.log. The log
for the current 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 creation appended to their name.
On Windows, you can use the del command or the File Manager to remove
unwanted session logs, server logs, and connection broker logs. On Linux, use
the rm command.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 135

Chapter 4 Managing Repositories

4.2.10 Checking consistency

Documentum Server provides the Consistency Checker, a tool that scans a
repository and reports any inconsistencies. Inconsistencies typically include type or
object corruptions, objects that reference a user, group, or other object that does no
exist, and so forth. The tool does not fix the inconsistencies. Contact OpenText
Global Technical Services for assistance in correcting errors found by the consistency
checker.

The Consistency Checker tool is a job that can be run from the command line or
using Documentum Administrator. The “Running jobs” on page 455 section
contains more information on running the job in Documentum Administrator.

The job generates a report that lists the checked categories and any inconsistencies
that were found. The report is saved in the /System/Sysadmin/Reports/
ConsistencyChecker directory. If no errors are found, the current report overwrites
the previous report. If an error is found, the current report is saved as a new version
of the previous report. By default, the Consistency Checker job is active and runs
once a day.

Documentum recommends to run this tool on a repository before upgrading the

repository to a new version of the Documentum Server.

4.2.10.1 Running the job from a command line

The Consistency Checker job is implemented as the consistency_checker.ebs script.
To run the script from the command line, enter the following syntax at the
command-line prompt:
dmbasic -fconsistency_checker.ebs -eEntry_Point --repository_name superuser password

where repository_name is the name of the repository that is checked, superuser is

the user name of a repository superuser, and password is the password of the
superuser account.

The results of the checks are directed to standard output.

4.2.10.2 Example report

The following example describes a Consistency Checker report. In this case, the tool
detected five inconsistencies in the Users & Groups section.
Beginning Consistency Checks.....

Repository Name: buzzard

Server Version: 5.1.0.63 Win32.SQLServer
Database: SQLServer

#################################################
##
## CONSISTENCY_CHECK: Users & Groups
##
## Start Time: 09-10-2002 10:15:55
##

136 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

##
#################################################

Checking for users with non-existent group

WARNING 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 to
non-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_user

Checking for users not listed in dmi_object_type
Checking for groups not listed in dmi_object_type
Checking for groups belonging to non-existent groups
Checking for groups with non-existent super groups

##################################################
##
##
## CONSISTENCY_CHECK: ACLs ##
##
## Start Time: 09-10-2002 10:15:55
##
##
##################################################

Checking for ACLs with non-existent users

Checking for ACLs with missing dm_acl_r table entries
Checking for sysobjects with acl_domain set to
non-existent user
Checking for sysobjects that belong to
non-existent users
Checking for sysobjects with non-existent ACLs
Checking for ACL objects with missing dm_acl_s entry
Checking for ACL objects with r_accessor_permit
value but missing r_accessor_name value
Checking for ACL objects with r_accessor_name value
but missing r_accessor_permit value
Checking for ACL objects with r_is_group value but
missing r_accessor_permit value
Checking for ACL objects with r_is_group value but
missing r_accessor_name value
Checking for ACL object with r_accessor_name value
but missing r_is_group value
Checking for ACL object with r_accessor_permit value
but missing r_is_group value

################################################
##
##
## CONSISTENCY_CHECK: Sysobjects
##
##
## Start Time: 09-10-2002 10:15:58
##
##
#################################################

Checking for sysobjects which are not referenced in

dmi_object_type
Checking for sysobjects that point to non-existent
content
Checking for sysobjects that are linked to non-existent
folders
Checking for sysobjects that are linked to non-existent

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 137

Chapter 4 Managing Repositories

primary cabinets
Checking for sysobjects with non-existent i_chronicle_id
Checking for sysobjects with non-existent i_antecedent_id
Checking for sysobjects with missing
dm_sysobject_r entries
Checking for sysobjects with missing
dm_sysobject_s entry

#################################################
##
##
## CONSISTENCY_CHECK: Folders and Cabinets
##
## Start Time: 09-10-2002 10:16:02
##
##
#################################################

Checking for folders with missing dm_folder_r table

entries
Checking for folders that are referenced in dm_folder_r
but not in dm_folder_s
Checking for dm_folder objects that are missing an
entry in dmi_object_type
Checking for dm_folder objects that are missing
corresponding dm_sysobject entries
Checking for folders with non-existent ancestor_id
Checking for cabinet that have missing dm_folder_r
table entries
Checking for cabinets that are missing an entry in
dmi_object_type
Checking for folder objects with missing
dm_sysobject_r entries
Checking 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 entry

but no dm_document_s entry
Checking for documents with missing dm_sysobect_s
entries
Checking for documents with missing dmi_object_type
entry

#################################################
##
##
## CONSISTENCY_CHECK: Content
##
## Start Time: 09-10-2002 10:16:03
##
##
##
#################################################

Checking for content objects that reference

non-existent parents
Checking for content with invalid storage_id
Checking for content objects with non-existent format

#################################################
##

138 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.2. Managing repositories

##
## CONSISTENCY_CHECK: Workflow
##
##
## Start Time: 09-10-2002 10:16:03
##
##
#################################################

Checking for dmi_queue_item objects with non-existent

queued objects
Checking for dmi_workitem objects that reference
non-existent dm_workflow objects
Checking for dmi_package objects with missing
dmi_package_s entries
Checking for dmi_package objects that reference
non-existent dm_workflow objects
Checking for workflow objects with non-existent
r_component_id
Checking for workflow objects with missing
dm_workflow_s entry
Checking for work item objects with missing
dm_workitem_s entry

################################################
##
##
## CONSISTENCY_CHECK: Types
##
## Start Time: 09-10-2002 10:16:04
##
##
################################################

Checking for dm_type objects with a non-existen

t dmi_type_info object
Checking for dmi_type_info objects with a non-existent
dm_type object
Checking for type objects with corrupted property
positions
Checking 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 objects

Checking for duplicate dmi_dd_type_info objects
Checking for any dmi_dd_attr_info objects that are
missing an entry in dmi_dd_common_info_s
Checking for any dmi_dd_type_info objects that are
missing an entry in dmi_dd_common_info_s
Checking for any dmi_dd_attr_info objects that are
missing an entry in dmi_dd_attr_info_s
Checking for any dmi_dd_type_info objects that are
missing an entry in dmi_dd_type_info_s

################################################
##
##
## CONSISTENCY_CHECK: Lifecycles
##
## Start Time: 09-10-2002 10:16:11

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 139

Chapter 4 Managing Repositories

##
#################################################

Checking for sysobjects that reference non_existent

policy objects
Checking for any policy objects that reference
non-existent types in included_type
Checking for any policy objects with missing
dm_sysobject_s entry
Checking for any policy objects with missing
dm_sysobject_r entries
Checking for policy objects with missing dm_policy_r
entries
Checking for policy objects with missing dm_policy_s
entry

################################################
##
##
## CONSISTENCY_CHECK: FullText
##
## Start Time: 09-10-2002 10:16:11
##
################################################

Checking for tdk index objects that point to

non-existent fulltext index objects
Checking for any tdk collect objects that point to
non-existent tdk index objects
Checking for any fulltext index objects that point
to non-existent tdk index objects
Checking for any tdk index objects that point to
non-existent tdk collect objects
Checking for any non-orphaned dmr_content objects
that point to types that do not exist
Checking for any non-orphaned dmr_content objects
that point to non-existent formats
Checking for any dmr_content objects that point to
a non-existent fulltext index
Checking for any fulltext index propertys that are
no longer in dm_type

#################################################
##
##
## CONSISTENCY_CHECK: Indices
##
## Start Time: 09-10-2002 10:16:11
##
#################################################

Checking for dmi_index objects that reference

non-existent types
Checking for types with non-existent dmi_index
object for <type>_s table
Checking for types with non-existent dmi_index
object for <type>_r table
Checking for index objects with invalid property
positions

################################################
##
##
## CONSISTENCY_CHECK: Methods
##
## Start Time: 09-10-2002 10:16:11
##
################################################

Checking for java dm_method objects that reference

jview

140 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.3. Adding repositories

Consistency Checker completed successfully

Total number of inconsistencies found: 5
Disconnected from the server.

4.2.11 Changing the repository owner password

If you need to change the password in the database used by the repository owner
account (also referred to as the database owner account, and listed as
database_owner in the server.ini file), use the following procedure:

1. Shut down the repository.

2. Change the repository owner account password in the database.

3. Edit the dbpasswd.txt file to contain one line with the new password in plain
text.

4. Encrypt the dbpasswd.txt file. From the $DM_HOME/bin directory, use the
command:
dm_encrypt_password -docbase <docbase_name> -rdbms -encrypt
<database_password> -keyname <keyname> [-passphrase <passphrase>]

5. Start the repository.

4.3 Adding repositories

Adding repositories requires creating a repository running the Documentum Server
Manager on Windows platforms or the Documentum Server configuration program
on Linux platforms.

To create a repository on Windows platforms:

1. Start the Documentum Server Manager by selecting Start > Programs >
Documentum > Documentum Server Manager.

2. Click the Utilities tab, then click Server Configuration.

The Documentum Server Configuration Program starts.

3. Click Next and follow the configuration instructions on the screen.

To create a repository on Linux platforms:

1. Start the Documentum Server configuration program.

2. Follow the instructions in the Documentum Server configuration sections to

create new repositories.

Documentum Platform and Platform Extensions Installation Guide contains more

information on pre-installation checklists and the Documentum Server configuration
options.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 141

Chapter 4 Managing Repositories

4.4 Federations
A federation is a set of two or more repositories bound together to facilitate the
management of a multi-repository distributed configuration. Federations share a
common name space for users and groups and project to the same connection
brokers.

Global users, global groups, and global permission sets are managed through the
governing repository, and have the same property values in each member repository
within the federation. For example, if you add a global user to the governing
repository, that user added to all the member repositories by a federation job that
synchronizes the repositories.

One enterprise can have multiple repository federations, but each repository can
belong to only one federation. Repository federations are best used in multi-
repository production environments where users share objects among the
repositories. We do not recommend creating federations that include production,
development, and test repositories, because object types and format definitions
change frequently in development and test environments, and these must be kept
consistent across the repositories in a federation.

The repositories in a federation can run on different operating systems and database
platforms. Repositories in a federation can have different server versions; however,
the client running on the governing repository must be version-compatible with the
member repository in order to connect to it.

To create or modify federations, you do not have to be connected to a repository in

the federation. To add a repository to a federation, your Documentum
Administrator connection broker list must include a connection broker to which the
particular repository projects.

Before you set up a repository federation, read the Documentum Platform and Platform
Extensions Installation Guide.

4.4.1 Creating or modifying federations

Before you create a federation, obtain the user name and password of a superuser
account in each repository.

All repositories in a federation must project to the same connection brokers. When
you create a federation, Documentum Administrator updates the connection broker
projection information in the server configuration object for each member
repository. No manual configuration is necessary.

The repositories in a federation can run on different operating systems and database
platforms. Repositories in a federation can have different server versions; however,
the client running on the governing repository must be version-compatible with the
member repository in order to connect to it.

142 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 4.4. Federations

Table 4-6: Federation properties

Field Description
Info tab
Name Type the name of the new federation.
Make All Governing Repository Users & Select to make all users and groups in the
Groups Global governing repository global users and global
groups.
Active This option is available if you are modifying
an existing federation. To change the status
of an existing federation, select or clear the
Active checkbox.

User Subtypes tab

Add Click Add to add user subtypes.

If there are user subtypes in the repository, a

list of user subtypes is displayed on the
Choose a user subtype page. Select the user
subtypes to propagated to member
repositories.

Members tab
Add Click Add to add member repositories.

Select the repositories that you want to be

member repositories and click Add.

Click Edit to edit a member repository. The

Edit button will be available only after
adding more than one repository.

To remove any member repositories from the

Selected Items list, select them and then click
Remove.
Name The login name of a superuser account that is
configured for the repository.
Password The password of a superuser account this is
configured for the repository.
Skip this member and continue Select this option if you want to skip entering
authentication the name and password at this time.

Documentum Platform and Platform Extensions Installation Guide contains more

information. Documentum Administrator User Guide contains the instructions on
creating or modifying federations.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 143

Chapter 4 Managing Repositories

4.4.2 Adding, modifying, or deleting federation members

You can add or delete federation member repositories using the Members tab on the
Federation Configuration Properties page.

Documentum Administrator User Guide contains the instructions on adding,

modifying, or deleting federation members.

4.4.3 Deleting Federations

Documentum Administrator User Guide contains the instructions on deleting
federations.

You can make a federation inactive by accessing the Info page of the federation and
clearing the Active checkbox.

4.4.4 Connecting to the governing repository or a federation

member
Provide the login information for the governing repository or a federation member.

Documentum Administrator User Guide contains the instructions on connecting to the

governing repository or a federation member.

4.4.5 Choosing user subtypes

On the New Federation Configuration - User Subtypes or Federation
Configuration Properties - User Subtypes page, choose user subtypes to be
propagated to all members of the federation. The type itself must be created in each
repository in the federation. This page ensures that users of that particular subtype
are propagated to the member repositories.

Documentum Administrator User Guide contains the instructions on choosing user

subtypes.

4.4.6 Choosing repository federation members

Select the members of a repository federation. The repositories listed are all
repositories not already in a federation that are known to all the connection brokers
in your preferences. You can sort the list of repositories by repository name or
connection broker.

Documentum Administrator User Guide contains the instructions on choosing

repository federation members.

144 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 5
Managing Sessions

5.1 The dfc.properties file

The dfc.properties file contains most of the configuration parameters that specify
how DFC handles repository sessions. The configuration parameters are stored as a
key and a corresponding value. For example, the dfc.properties file contains keys
that specify which connection brokers are used to obtain a session, how many
sessions are allowed for one user, and enable persistent client caching. Many keys
have default values, but some must be explicitly set by an administrator or
application.

Some of the keys in the file are dynamic that affect open sessions. Changing non-
dynamic keys affects only future sessions. By default, Documentum Server checks
every 30 seconds for changes in the dfc.properties file.

The dfc.properties keys and associated values are described in the dfcfull.properties
file, which is installed with DFC. The keys in the dfc.properties file have the
following format:
dfc.<category>.<name>=<value>

The <category> identifies the functionality, feature, or facility that the key controls.
When adding a key to the dfc.properties file, both the category and the name, in
addition to a value must be specifies. For example:
dfc.data.dir= <value>

dfc.tracing.enable= <value>
dfc.search.ecs.broker_count = <value>

For Documentum web-based products, the dfc.properties file is packaged in the

application WAR file.

For desktop applications and Documentum Server, the dfc.properties file is installed
in the C:\Documentum\Config directory on Windows hosts, and the
$DOCUMENTUM_SHARED/config directory on Linux hosts. The file can be edited
using any text editor.

The dfc.properties file is a standard Java properties file. If a key value has a special
character, use a backslash (\) to escape the character. In directory path
specifications, use a forward slash (/) to delimit directories in the path.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 145

Chapter 5 Managing Sessions

5.2 Managing connection requests

When a client requests a connection, the request is sent to a connection broker,
which returns server connection information to the client. There must be at least one
connection broker identified in the dfc.properties file of the client. If multiple
connection brokers are defined in the file, the system uses the additional connection
brokers for backup or failover.

To specify a connection broker in the dfc.properties file, use the following keys:
dfc.docbroker.host[<n>]=<host_name>|<IP_address> #required
dfc.docbroker.port[<n>]=<port_number> #optional

The [<n>] is a numeric index, where <n> is an integer starting with 1. All keys for a
particular connection broker must have the same numeric index. If there are entries
for multiple connection brokers, DFC contacts the connection brokers in ascending
order based on the numeric index by default.

The <host_name> is the name of the machine on which the connection broker resides.
The <IP_address> is the IP address of the machine.

The port is the TCP/IP port number that the connection broker is using for
communications. The port number defaults to 1489 if it is not specified. If the
connection broker is using a different port, you must include this key.

The following example defines two connection brokers for the client. Because lapdog
is not using the default port number, the port number is also specified in the file:
dfc.docbroker.host[1]=bigdog
dfc.docbroker.port[1]=1489

dfc.docbroker.host[2]=lapdog
dfc.docbroker.port[2]=1491

Only the host specification is required. The other related keys are optional.

If you add, change, or delete the keys of a connection broker, the changes are visible
immediately. You do not have to restart your session.

5.3 Defining the secure connection default for

connection requests
All connections between Documentum Server and a client application are either
secure or native (unsecured) connections. Which option is used for a particular
connection depends on how the server is configured and what sort of connection is
requested by the client application when it attempts to obtain a session. If the
request does not specify what type of connection is requested, the connection type
specified in the dfc.properties file, in the dfc.session.secure_connect_default key, is
used.

There are four possible settings for this key:

• native

146 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 5.4. Modifying the connection request queue size

Only a native connections are allowed. If DFC cannot establish a native

connection, the connection attempt fails.
• secure
Only secure connection are allowed. If DFC cannot establish a secure connection,
the connection attempt fails.
• try_secure_first
A secure connection is preferred, but a native (unsecured) connection is
excepted. DFC attempts to establish a secure connection first. If it cannot, it tries
to establish a native connection. If that also fails, the connection attempt fails.
• try_native_first
A native connection is preferred, but a secure connection is also accepted. DFC
attempts to establish a native connection first. If it cannot, it tries to establish 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 the
secure_connect_default key. Documentum Foundation Classes Development Guide
contains information on how to specify it in an application. For information about
configuring the server default for connections, read the Secure Connect Mode
property in “Modifying general server configuration information” on page 49.

5.4 Modifying the connection request queue size

Documentum Server creates a socket listener for incoming connection requests. By
default, the maximum backlog queue value is 200. The value can be changed on
Windows platforms by modifying the listener_queue_length key in the server.ini
file. The key must be a positive integer value. Documentum Server passes the
specified value to the listen () Windows Sockets call.

5.5 Stopping a session server

A kill method should be used to shut down a session server. Using a kill method
requires system administrator or superuser privileges and the session ID. The
session ID can be obtained using the LIST_SESSIONS or SHOW_SESSIONS
administration method. The Documentum Server DQL Reference Guide contains more
information on the administration methods.

A session can be terminated in one of three ways:

• Default kill
The default kill provides the least disruption to the end user. The targeted
session terminates when it has no more open transactions and no more open
collections. The client remains functional.
• After current request kill

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 147

Chapter 5 Managing Sessions

An after current request kill provides a safe and more immediate means of
terminating a session. If the session is not currently executing a request, the
session is terminated. Transactions can be rolled back and collections can be lost.
• Unsafe kill
An unsafe kill can be used to terminate a session when all other techniques have
failed and should be used with caution. It can result in a general server failure.

148 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 6
Managing Java Method Servers

6.1 Java Method Servers

Documentum includes Java Method Server (JMS), a customized version of WildFly
to execute Documentum Server Java methods. One Java Method Server is installed
with each Documentum Server installation. You can use Documentum
Administrator to modify existing Java Method Servers, but you cannot add new Java
Method Servers from the Documentum Administrator interface. To add a Java
Method Server, you have to run the Documentum Server Configuration Program.
Documentum Platform and Platform Extensions Installation Guide contains more
information on installing multiple Documentum Servers, Java Method Servers, and
the supported JMS failover configurations.

Documentum provides a servlet called DO_METHOD to execute Documentum

Server methods. The compiled servlet code is found in the mthdservlet.jar file
located on the same host as Documentum Server. The file contains the IDmMethod
class. Java Method Server runs as an independent process. The process can be
stopped or started without recycling the Documentum Server. On Windows
platforms, the Java Method Server can be run as a Windows service or as a process.

The method server itself is a Java-based web application. Each time a method is
invoked, the Documentum Server makes an HTTP request passing the name of the
Java class which implements the method along with any specified arguments to a
servlet which knows how to execute the specified method.

Note: The JMS can also be used to execute Java methods that are not associated
with a method object. Use an HTTP_POST administration method to send the
request to the Java method server. Documentum Server DQL Reference Guide
contains information on the administration method.

Documentum Administrator provides a Java Method Server configuration page for:

• Viewing and updating Java Method Servers.

• Associating Documentum Servers with Java Method Servers.
• Viewing the Java Method Server status information in the Documentum Server
memory cache.
• Resetting the Java Method Server information in the Documentum Server
memory cache.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 149

Chapter 6 Managing Java Method Servers

6.1.1 Viewing Java method server information

All available JMS are displayed on the Java Method Server Configuration page.
Users with superuser or system administrator privileges can access the Java Method
Server Configuration page. To access the page, log into a repository and navigate to
Administration > Basic Configuration > Java Method Servers.

Each JMS is represented by a JMS configuration object. The Java Method Server
Configuration page displays information for all JMS configuration objects in the
repository.

Table 6-1: Java method server information

Column Label Description

Name The name of the JMS configuration object.
Is Enabled Specifies whether the Java method server is
enabled or disabled.
Associated Content Servers The Documentum Server with which the JMS
configuration object is associated.

The Tools menu on the Java Method Server Configuration page also provides the
option to view information about all active Java method servers. Select Tools >
Active Java Method Servers List to display the Active Java Method Servers List
page.

6.1.2 Modifying a Java Method Server configuration

Only users with superuser privileges can modify JMS configurations.

Table 6-2: JMS configuration information

Field label Description

Name The name of the JMS configuration.
Enable Enables or disables the JMS.

Select this option to enable the JMS

configuration or deselect to disable the JMS.
Associated Content Servers

150 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 6.1. Java Method Servers

Field label Description

Documentum Server The list of Documentum Servers that is
associated with the JMS configuration.

A JMS configuration can be associated with

one or more Documentum Servers.
Documentum Platform and Platform Extensions
Installation Guide contains more information
on installing multiple Documentum Servers,
Java Method Servers, and the supported JMS
failover configurations.
Documentum Server location Specifies whether the JMS is associated with
a RCS. Valid values are:
• Java Method Server for primary
Documentum Server: The ACS is local.
• Java Method Server for secondary (or
additional) Documentum Server: The ACS is
remote.
Add Click Add to add and associate a
Documentum Server with the JMS
configuration.

The Servlet URL Editor page displays. Select

the Documentum Server and intended
purpose, as described in “Adding or
modifying Associated Content Servers”
on page 152.
Edit Select the Documentum Server and click Edit
to modify the Documentum Server
associated with the JMS configuration.

The Servlet URL Editor page displays.

Modify the intended purpose, as described in
“Adding or modifying Associated Content
Servers” on page 152.
Remove Select the Documentum Server and click
Remove to remove the Documentum Server
from the JMS configuration.
Java Method Server Servlet URLs
Name The name of the Java servlet.
URL The location of the Java servlet.

Documentum Administrator User Guide contains the instructions on modifying a Java

Method Server configuration.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 151

Chapter 6 Managing Java Method Servers

6.1.3 Adding or modifying Associated Content Servers

Use the Associated Content Servers page to add or modify Documentum Servers
that are associated with a Java Method Server.

Documentum Administrator User Guide contains the instructions on adding or

modifying Associated Content Servers.

Table 6-3: Associated Content Servers information

Column Label Description

Documentum Server The name of the Documentum Server
associated with the JMS.

To add a Documentum Server, select the

Documentum Server from the drop-down
list.

The drop-down list displays Documentum

Server that were previously installed on the
host machine using the Documentum Server
Configuration program. Documentum
Platform and Platform Extensions Installation
Guide contains more information on
installing multiple Documentum Servers,
Java Method Servers, and the supported JMS
failover configurations.
Documentum Server location Specifies whether the JMS is associated with
a RCS. Valid values are:
• Java Method Server for primary
Documentum Server: The ACS is local.
• Java Method Server for secondary (or
additional) Documentum Server: The ACS is
remote.

6.1.4 Viewing active Java method servers

All active Java method servers are displayed on the Active Java Method Servers List.

Table 6-4: Active Java method server information

Field label Description

Associated Content Server The Documentum Server with which the JMS
cache is associated.
Last Refreshed Time The last time the Documentum Server JMS
cache was reset.

152 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 6.1. Java Method Servers

Field label Description

Incremental Wait Time on Failure The time Documentum Server waits before
contacting the JMS, if the JMS fails to
respond.

The wait time is doubled each time the JMS

fails to respond until the maximum wait time
is reached.
Maximum Wait Time on Failure The maximum wait time Documentum
Server keeps trying to contact the JMS, if the
JMS fails to respond.
Java Method Server in Use The name of the active Java method server
that was used last time.
Java Method Servers associated with the Documentum Server
Name The name of the JMS configuration object.
Is Enabled Specifies whether the Java method server is
enabled or disabled.
Status The current status of the JMS configuration
object.
Documentum Server location Specifies whether the JMS is associated with
a RCS. Valid values are:
• Java Method Server for primary
Documentum Server: The ACS is local.
• Java Method Server for secondary (or
additional) Documentum Server: The ACS is
remote.
Last Failure Time The last time the JMS failed to respond.
Next Retry Time The next time the Documentum Server tries
to contact the JMS, if the JMS fails to
respond.
Failure Count The number of times the JMS failed to
respond.

Documentum Administrator User Guide contains the instructions on viewing active

Java method servers.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 153

Chapter 6 Managing Java Method Servers

6.2 Java methods

Technically, all Documentum Java methods are simple Java classes. A plain Java
class becomes a Java method if it implements either the IDfMethod or IDmMethod
interfaces. If a program starts a repository session, the program should call an
explicit Disconnect when the session is finished.

Methods are deployed as a BOF module and executed on a Java method server. The
methods must have the following property values:

• 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
name, not the class name.
• The method_type property must be set to Java.
• The use_method_server property must be set to T (TRUE).
• The run_as_server property must be set to T (TRUE).

Notes

• Linux users who are authenticated against a Windows domain cannot

execute methods under their own accounts. All methods executed by such
users must be run with run_as_server set to TRUE.
• Documentum does not provide basic support for resolving problems
encountered when creating or executing custom Java methods or classes. For
help, contact OpenText Global Technical Services.

6.3 Recording Java method output

If the DO_METHOD method is executed on the Java method server, Documentum
recommends to include the IDmMethod interface in the program. The interface
saves the response to the repository in a document. The interface can also be used to
capture error or trace messages from the Java 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 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.

154 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 6.4. Deploying Java methods

*
* @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;
}

6.4 Deploying Java methods

Java methods are developed as self-contained BOF modules. Developing and
deploying a Java method has the following advantages:

• Developers can package and deploy the Java server method implementation in
the same DAR file as the dm_method definition.
• The Java method is self contained and is stored automatically in the default
location for the module.
• The Java method server does not have to be restarted to implement the method.

Note: We strongly recommend that developers avoid using the dba

\java_methods directory to deploy Java methods.

6.5 Adding additional servlets to the Java method

server
To use the HTTP_POST administration method, you must write and install the
servlet or servlets that handles those calls. Use the following procedure to
implement such a servlet.

To implement a new servlet:

1. Write the servlet.

2. Install the servlet on the Java method server.

3. Update the server configuration object for each server from which HTTP_POST
methods might originate.
Add the name of new servlet to the app_server_name property and the URI of
servlet to the app_server_uri property.
Use Documentum Administrator to modify the server configuration object.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 155

Chapter 6 Managing Java Method Servers

4. Select Re-initialize.
5. Click Check In.

156 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 7
Managing LDAP Servers

7.1 LDAP servers

An Lightweight Directory Access Protocol (LDAP) directory server is a third-party
product that maintains information about users and groups. Documentum Servers
use LDAP directory servers for two purposes:

• Manage users and groups from a central location.

• Authenticate users.

It is not necessary for all users and groups in a repository to be managed through an
LDAP directory server. A repository can have local users and groups in addition to
the users and groups managed through a directory server. You can use more than
one LDAP directory server for managing users and groups in a particular
repository.

Using an LDAP server provides a single place for making additions and changes to
users and groups. Documentum Server runs a synchronization job to automatically
propagate the changes from the directory server to all the repositories using the
directory server.

The LDAP support provided by Documentum Server allows mapping LDAP user
and group attributes to user and group repository properties or a constant value.
When the user or group is imported into the repository or updated from the
directory server, the repository properties are set to the values of the LDAP
properties or the constant. The mappings are defined when Documentum Server
creates the LDAP configuration. The mappings can be modified later.

Using an LDAP directory server includes 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.
• The LDAP synchronization job must have at least read access to a unique
identifier on the directory server, as follows:

– nsuniqueid on SunDirectory processor

– objectguid on Active Directory Server
– ibm-entryuuid on IBM
– guid on Novell
– orclguid on Oracle

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 157

Chapter 7 Managing LDAP Servers

Apart from the unique identifiers, all the attributes that have been mapped in the
LDAP configuration object should also have read access in the directory server.

7.1.1 Viewing LDAP server configurations

LDAP directory server configurations are managed under the Administration >
Basic Configuration > LDAP Servers node. You can configure and map your
existing LDAP configuration to a Documentum Server. Each LDAP server is
associated with an LDAP configuration object. You must have superuser privileges
to create, view, modify, or delete LDAP configuration objects.

Select Administration > Basic Configuration > LDAP Servers to view all primary
LDAP servers that are configured to the repository. If there are no LDAP servers
configured to the repository, Documentum Administrator displays the message No
LDAP Server Configurations. “LDAP Server Configuration page properties”
on page 158 describes the properties that are displayed on the LDAP Server
Configuration page.

From the LDAP Server Configuration page, you can:

• Add new LDAP servers

• View or modify existing LDAP server properties
• Synchronize LDAP servers
• Duplicate an existing LDAP server configuration
• Delete existing LDAP servers configurations

Table 7-1: LDAP Server Configuration page properties

Field label Value

Name The name of the LDAP configuration object.
Hostname The name of the host on which the LDAP
directory server is running.
Port The port number where the LDAP directory
server is listening for requests.
SSL Port The SSL port for the LDAP directory server.
Directory Type The directory type used by the LDAP
directory server. .
Import Indicates if users and groups, groups and
member users, or users only are imported.
Sync Type Indicates if synchronization is full or
incremental.
Failover Indicates if failover settings have been
established for the primary server.
Enabled Indicates whether the LDAP server is active.

158 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 7.1. LDAP servers

7.1.2 Adding or modifying LDAP server configurations

When adding an LDAP directory server to an existing Documentum installation, the
users and groups defined in the LDAP directory server are given precedence. The
user or group entry in the directory server matches a user or group in the repository,
the repository information is overwritten by information in directory server in case
synchronization type is set to full synchronization on Sync and Authentication tab.
To run the LDAP synchronization job for nested groups, new users and groups are
not synchronized in the repository.

To create a new LDAP configuration, you need the following information about the
LDAP directory server:

• The name of the host where the LDAP directory server is running
• The port where the LDAP directory server is listening
• The type of LDAP directory server
• The binding distinguished name and password for accessing the LDAP directory
server
• The person and group object classes for the LDAP directory server
• The person and group search bases
• The person and group search filters
• The Documentum attributes that you are mapping to the LDAP attributes

Notes

• Ensure that the binding user has the List Contents and Read Property
(LCRP) permission on the deleted objects container for configuring the
LDAP objects. Otherwise, the deleted users in the Active Directory server are
shown as active LDAP users in the repository. If the optional job argument
for LDAP Synchronization, container_for_deleted is set, the argument
value will be used instead of Deleted Objects while checking for objects
deleted at Active Directory.
• To avoid the null pointer exception while using
ldap_matching_rule_in_chain for nested group synchronization iteration
through a collection of objects retrieved from Active Directory, ensure that
you set the value of ldap_matching_rule_in_chain to <false>. By default,
the value is <true>.

Documentum Administrator User Guide contains the instructions on adding or

modifying an LDAP server configuration.

Documentum Server creates an ldap<objectID>.cnt password when you create the

LDAP configuration object. If you have more than one Documentum Server
associated with the repository, the password file must be copied to each
Documentum Server in the environment or authentication fails.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 159

Chapter 7 Managing LDAP Servers

7.1.2.1 LDAP Server Configuration properties

“LDAP Server Configuration Properties properties” on page 160 describes the
properties on the Info tab of the LDAP Server Configuration page. The properties
apply to new and existing LDAP configuration objects.

Table 7-2: LDAP Server Configuration Properties properties

Field Description
Name The name of the new LDAP configuration
object.

This field is read-only if you are viewing or

modifying the LDAP configuration object.
Status Select the Enable this LDAP Configuration
checkbox to enable the LDAP configuration.
Directory Type The Release Notes documents for your
version of Documentum Server contains
information on which LDAP server versions
are supported.

Options are:
• Sun ONE/Netscape/iPlanet Directory
Server (default)
• Microsoft Active Directory
• Microsoft ADAM
• Oracle Internet Directory Server
• IBM Directory Server
• Novell eDirectory

Hostname / IP Address The name of the host on which the LDAP

directory server is running.

Caution
For the 7.0 release, use only the
hostname and not the IP address.
However, you can use both the
hostname and IP address in pre-7.0
releases.

Port The port number where the LDAP directory

server is listening for requests.

The default is 389.

Binding Name The binding distinguished name used to
authenticate requests to the LDAP directory
server by Documentum Server or the check
password program.

160 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 7.1. LDAP servers

Field Description
Binding Password The binding distinguished password used to
authenticate requests to the LDAP directory
server by Documentum Server or the check
password program.

The Binding Password field only appears on

the New LDAP Server Configuration - Info
page.
Confirm Password If adding a new LDAP server configuration,
re-enter the binding password for
verification.

The Confirm Password field only appears on

the New LDAP Server Configuration page.
Set Click to access the LDAP Server
Configuration Properties page to set the
password. This link appears only on the
LDAP Server Configuration Properties - Info
page.
Use SSL Specifies whether SSL is used for
authentication.
SSL Port Specifies the SSL port. This option only
displays when the Use SSL option is
selected.

Enter 636 for the SSL port value.

Certificate Location Specifies the location of the LDAP certificate
database. If you selected Use SSL, the
default location is ldapcertdb_loc.

Note: For LDAP in SSL mode:

• To use the certificate chain, create
the <DM_LDAP_CERT_FILE>
environment variable and set it to 1.
• To ignore the hostname check, create
the
<DM_LDAP_IGNORE_HOSTNAME
_CHECK> environment variable and
set it to 1.

If you are using more than one LDAP server

in SSL mode, you must store the LDAP
certificates a single location, as described in
“Using multiple LDAP servers in SSL mode”
on page 175.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 161

Chapter 7 Managing LDAP Servers

Field Description
Validate SSL Connection If you selected Use SSL, click to validate that
a secure connection can be established with
the LDAP server on the specified port. If the
validation fails, the system displays an error
message and you cannot proceed further
until valid information is provided.

Follow these manual steps for SSL validation for 6.5x and below Documentum
Servers:

1. Depending on the operating system (other than Windows 64-bit) on which the
application server is installed, copy all the jar files from $Application_root$/
WEB-INF/thirdparty/$osname$ to $Application_root$/WEB-INF/lib
For example, if the operating system on which the DA application is installed is
Windows, copy all the jar files from $Application_root$/WEB-INF/thirdparty/
win32/ to $Application_root$/WEB-INF/lib
If the operating system on which the application server is installed is Windows
64-bit and the application server is using 64-bit JDK, do the following:

1. Backup the jss311.jar file and delete it from $Application_root$/WEB-INF/lib

2. Copy the jss42.jar file from $Application_root$/WEB-INF/thirdparty/
win64/6.0.6 to $AppServer_root$/WEB-INF/lib

2. Depending on the operating system (other than Windows 64-bit) on which the
application server is installed, copy all *.dll, (for Windows) or *.so (for Linux)
files from $Application_root$/WEB-INF/thirdparty/$osname$ to
$AppServer_root$/da_dlls

Note: If the da_dlls folder does not exist in the above specified location,
create it.

For example, if the operating system on which the DA application is installed is

Windows, copy all the dll files from $Application_root$/WEB-INF/thirdparty/
win32/ to $Application_root$/da_dlls
If the operating system on which the application server is installed is Windows
64-bit and the application server is using 64-bit JDK, do the following:

1. Copy the Microsoft.VC90.DebugCRT.manifest file from $Application_root$/

WEB-INF/thirdparty/win64/6.0.6 to $AppServer_root$/da_dlls
2. Copy all *.dll files from $Application_root$/WEB-INF/thirdparty/
win64/6.0.6 to $AppServer_root$/da_dlls

3. Set the path of the dlls in startup batch file of the application server.

• For Windows operating system: PATH=$AppServer_root$\da_dlls;%PATH

%;

162 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 7.1. LDAP servers

• For Linux operating system: LD_LIBRARY_Path=$AppServer_root$/da_dlls:

%LD_LIBRARY_PATH%:

7.1.2.2 LDAP authentication using Digest-MD5 mechanism

LDAP authentication using Digest-MD5 authentication mechanism is supported
from the 16.7 release.

Perform the following to allow LDAP authentication to use Digest-MD5:

1. Add DM_LDAP_USER_AUTH_METHOD as r_module_name attribute in the

dm_docbase_config object.

2. Configure the corresponding value in r_module_mode for same index where

DM_LDAP_DIGESTMD5_USER_AUTH_MECH is configured. Valid values are:

• 1: Used for Digest-MD5.

Note: Ensure that you set the value of ssl_mode to 0 in the active
dm_ldap_config object.
• 2: Used for LDAP_SIMPLE_BIND.

7.1.2.3 LDAP Server Sync & Authentication properties

“LDAP Server Sync & Authentication properties” on page 163 describes the
properties on the Sync & Authentication tab of the LDAP Server Configuration page.
The properties apply to new and existing LDAP configuration objects.

Table 7-3: LDAP Server Sync & Authentication properties

Field Description
Import Specifies how users and groups are
imported. Available options are:
• Users and groups (default)
• Users only
• Groups & member users
Synchronize Nested Groups in the repository Select to synchronize the nested groups in
the repository.

Note: This option is enabled only if

Import field has the value Users and
groups or Groups & member users.
This option is disabled if you select
Users only for Import field.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 163

Chapter 7 Managing LDAP Servers

Field Description
Sync Type Specifies how users and groups are
synchronized. Available options are:
• Full: Import all based on user/group
mappings (default)
• Incremental: Import only new or updated
user/groups/members
If Groups and member users is selected
in the Import field and a group was not
updated but any of the group members
were, the incremental synchronization is
updating users identified by the user
search filter.

Note: To run an incremental

synchronization job, set the LDAP
server and the Documentum Server
in the same time and time zone
without any clock drifts.
Deleted Users Specifies whether deleted user accounts are
marked inactive. Available options are:
• set to inactive (default)
• unchanged
Update Names Select to Update user names in repository or
Update group names in repository.

The Update group names in repository

checkbox is not enabled if Users Only is
selected in the Import field.
User Type Select a user type. The default is dm_user.
Bind to User DN Options are:
• Search for DN in directory using user’s login
name
• Use DN stored with user record in repository
(default)
External Password Check Select to use external password check to
authenticate users to directory.

The LDAP synchronization job must have at least read access to a unique identifier
on the directory server, as follows:

• nsuniqueid on Sun One/Netscape/iPlanet Directory Server

• objectguid on Microsoft Active Directory Server
• ibm-entryuuid on IBM Directory Server
• guid on Novell eDirectory

164 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 7.1. LDAP servers

• orclguid on Oracle Internet Directory Server

Apart from the unique identifiers, all the attributes that have been mapped in the
LDAP configuration object should also have read access in the directory server.

7.1.2.4 LDAP Nested Groups

Starting with the 7.0 release, nested groups in LDAP is supported. You can
synchronize nested groups in the repository between Documentum Server and the
LDAP directory server. The group search filter of the default LDAP config object
needs to be set to the appropriate group name that forms the root group of the
nested group structure. Starting with the 7.1 release, nested cyclic groups are also
supported where a group forms a cycle with another in LDAP and both these
groups are then synchronized into the repository. The cycles within these two
groups are not retained since Documentum Server does not support cycles in
groups.

To activate the nested cyclic group feature, you must update the
dm_docbase_config object as shown below:
API>
retrieve,c,dm_docbase_config
...
3c00014d80000103
API> append,c,l,r_module_name
SET> LDAP_CYCLIC_SAVE
...
OK
API> append,c,l,r_module_mode
SET> 1
...
OK
API> save,c,l
...
OK
API>

7.1.2.5 LDAP Server mapping properties

“LDAP Server mapping properties” on page 165 describes the properties on the
Mapping tab of the LDAP Server Configuration page. The properties apply to new
and existing LDAP configuration objects.

Table 7-4: LDAP Server mapping properties

Field Description
User Object Class Type the user object class to use for searching
the users in the directory server.
User Search Base Type the user search base. This is the point in
the LDAP tree where searches for users start.
For example:

cn=Users,ou=Server,dc=sds,dc=inengvm1llc,
dc=corp,dc=test,dc=com.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 165

Chapter 7 Managing LDAP Servers

Field Description
User Search Filter Type the person search filter. This is the
name of the filter used to make an LDAP
user search more specific. The typical filter is
cn=*
Search Builder Click to access the Search Builder page. This
page enables you to build and test a user
search filter. When finished, the User Search
Filter field is populated with the resulting
filter.
Group Object Class Type the group object class to use for
searching the groups in the directory server.
Typical values are:
• For Netscape and Oracle LDAP servers:
groupOfUniqueNames
• For Microsoft Active Directory: group
Group Search Base Type the group search base. This is the point
in the LDAP tree where searches for groups
start. For example:

cn=Groups,ou=Server,dc=sds,dc=inengvm1llc
,dc=corp,dc=test,dc=com.
Group Search Filter Type the group search filter. This is the name
of the filter used to make an LDAP group
search more specific. The typical filter is cn=*
Search Builder Click to access the Search Builder page. This
page enables you to build and test a group
search filter. When finished, the Group
Search Filter field is populated with the
resulting filter.
Property Mapping When a new configuration is added, this
table populates with the mandatory mapping
attributes. The mappings are dependent
upon the directory type. This table defines
the pre-populated attributes and their
mappings. All mapping types are LDAP
Attribute.
Add Click to access the Map Property page to add
an attribute. From there, select a
Documentum attribute, then select the LDAP
attribute to which the Documentum attribute
maps or type in a custom value.
Edit Select an attribute and then click Edit to
access the Map Property page. On the Map
Property page, edit the attribute properties.

166 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 7.1. LDAP servers

Field Description
Delete Select an attribute and then click Delete to
remove an attribute. The system displays the
Deletion Confirmation page.
Repository Property Displays the repository property that is the
target of the mapping.
Type Identifies the source of the property: User or
Group.
Map To Displays which attributes on LDAP that the
property is mapped to.
Map Type Identifies the type of data: LDAP attribute,
expressions, or a fixed constant.
Mandatory Indicates if the mapping is mandatory for the
attribute.

Documentum Server requires three

properties to be defined for a user and one
property to be defined for a group. The
mandatory properties are:
• user_name
• user_login_name
• group_name

You can change the defaults, but you must

provide some value or mapping for these
properties. Users cannot be saved to the
repository without values for these three
properties, nor can a group be saved to the
repository without a group name.

7.1.2.6 LDAP Server failover properties

“LDAP Server failover properties” on page 167 describes the properties on the
Failover tab of the LDAP Server Configuration page. The properties apply to new
and existing LDAP configuration objects.

Table 7-5: LDAP Server failover properties

Field Description
Failover Settings Use this section to enter settings for the
primary LDAP server.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 167

Chapter 7 Managing LDAP Servers

Field Description
Retry Count The number of times Documentum Server
tries to connect to the primary LDAP server
before failing over to a designated secondary
LDAP server. The default is 3.

If the retry count value is set to 0,

Documentum Server immediately reports
that it failed to contact the primary LDAP
directory server.
Retry Interval Enter an interval number and select a
duration (seconds, minutes, or hours)
between retries. The default is at 3 seconds.

Documentum Server fails to bind to the

primary LDAP directory server, it waits the
number of seconds specified before
attempting to bind to the primary LDAP
directory server again.
Reconnect Enter an interval number and select a
duration (seconds, minutes, or hours) after a
failover for the system to try to reconnect to
the primary LDAP server.

The default is set at 5 minutes.

Secondary LDAP Servers Specifies secondary LDAP servers.
• To add a new secondary LDAP server,
click Add. The Secondary LDAP Server
page is displayed.
• To modify an existing secondary LDAP
server, select the checkbox next to the
name and click Edit. The Secondary
LDAP Server page is displayed.
• To delete an existing secondary LDAP
server, select the checkbox next to the
name and click Delete.
• To reorder the list of LDAP servers, click
Move Up or Move Down.
Name Name of the secondary LDAP server.
Hostname The name of the host on which the secondary
LDAP directory server is running.
Port The port information.
SSL Port The SSL port number.

168 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 7.1. LDAP servers

7.1.3 Mapping LDAP Servers

LDAP directory servers allow you to define attribute values for user and group
entries in the directory server. Documentum Server supports mapping those
directory server values to user and group properties in the repository. Using
mapping automates setting user and group properties.

Mappings between LDAP attributes and repository properties are defined when you
create the LDAP configuration object. You can map the LDAP values to the
following properties:

• System or user-defined properties

• Multiple directory values to a single repository property, using an expression.
For example, the following expression uses the LDAP attributes sn and given
name to generate a user_address value:
${sn}_${givenname#1}@company.com

If the sn (surname) of user is Smith and the given name is Patty, the expression
above resolves to [email protected]. The 1 at the end of given name directs
the system to only use the first letter of the given name.

You can specify an integer at the end of an LDAP attribute name in an expression to
denote that you want to include only a substring of that specified length in the
resolved value. The integer must be preceded by a pound (#) sign. The substring is
extracted 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.

Note: Documentum Server does not support powershell or any other scripting
extensions for the expression notation.

Values of repository properties that are set through mappings to LDAP attributes
can only 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 after the user or group is synchronized for the first time is not
recommended. Doing so may cause inconsistencies in the repository.

“Netscape iPlanet, Oracle Internet Directory Server, and Microsoft Active

Directory example” on page 170 contains examples of how the Attribute Map
page for LDAP configurations is typically completed for Netscape iPlanet,
Oracle Internet Directory Server, and Microsoft Active Directory LDAP
servers.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 169

Chapter 7 Managing LDAP Servers

Table 7-6: Netscape iPlanet, Oracle Internet Directory Server, and

Microsoft Active Directory example

DM attribute DM type LDAP attribute Type

user_name dm_user cn A
user_login_name dm_user uid A

7.1.3.1 Mapping guidelines

The following rules apply when mapping LDAP group or user attributes to a
repository property:

• In expressions, spaces are not required between references to LDAP attributes

due to the bracket delimiter. If there is a space between mapped values, it
appears in the result of the mapping.
• The length of the expression mapped to a single repository property cannot
exceed 64 characters. Expressions that exceed 64 characters are truncated. The
expression is recorded in the map_val property of the ldap config object. This
property 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.

7.1.3.2 Using Search Builder

Access the Search Builder page by clicking the Search Builder button on the
Mapping tab of the New LDAP Server Configuration or LDAP Server Configuration
Properties page.

The Search Builder page enables you to build and test a user or group search filter.
You can enter up to ten lines of search criteria. When finished, the User Search Filter
or Group Search Filter field is populated with the resulting filter.

7.1.3.3 Adding or modifying repository property mapping

On the Map Property page, you can add or modify mapping properties.

To add or modify repository property mapping:

1. Access the Map Property page.

2. Select a repository property to map.

3. In the Map To section, select the LDAP property to which the repository
property maps or type a custom value. Options are:

• Single LDAP Attributes: If selected, select an LDAP attribute from the drop-
down list.
• Fixed Value: If selected, type a custom value.

170 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 7.1. LDAP servers

• Expression: If selected, type an expression and select an LDAP attribute

reference from the drop-down list. Click the Test Expression button to test.

4. In the Reject User/Group section, select to reject synchronization of any LDAP

user or group. Options for when to reject synchronization are:

• Is empty or has insufficient characters

• Is empty
• Never reject any user/group

5. Click OK to save the changes or click Cancel.

7.1.4 Configuring secondary LDAP servers

You can configure Documentum Server to use other LDAP directory servers for user
authentication in the event that the first LDAP directory server is down. By default,
the primary LDAP server handles all user authentication requests. However, if
Documentum Server fails to bind to the primary LDAP directory server, you can
define a way for it to bind to secondary LDAP servers, authenticate users, and then
reattempt the connection with the primary LDAP directory server.

Provide the information for the secondary LDAP server, as described in “Secondary
LDAP Server page properties” on page 171.

Table 7-7: Secondary LDAP Server page properties

Field Description
Name Enter the name of the secondary LDAP
server.
Hostname / IP Address Type the name of the host on which the
secondary LDAP directory server is running.
Port The port information is copied from the
primary LDAP server.
Binding Name The binding name is copied from the
primary LDAP server.
Binding Password Type the binding distinguished password
used to authenticate requests to the
secondary LDAP directory server by
Documentum Server or the check password
program.
Confirm Password Re-enter the binding password for
verification.
Bind to User DN The bind to user DN information is copied
from the primary LDAP server.
Use SSL The SSL information is copied from the
primary LDAP server.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 171

Chapter 7 Managing LDAP Servers

Field Description
SSL Port The SSL port number is copied from the
primary LDAP server.
Certificate Location The certificate location is copied from the
primary LDAP server.

7.1.5 Changing the binding password

Change the binding password for LDAP directories on the LDAP Server
Configuration Properties page. Access this page by clicking the Change link on the
Info tab of the LDAP Server Configuration Properties page.

Documentum Administrator User Guide contains the instructions on changing the

binding password.

7.1.6 Forcing LDAP server synchronization

The Synchronize Now option calls the SBO API to synchronize the LDAP
configuration. The type of synchronization is determined by the first_time_sync flag
on the LDAP configuration object.

Documentum Administrator User Guide contains the instructions on forcing LDAP

server synchronization.

7.1.7 Duplicating LDAP configurations

Use the Save As option to create a copy of an LDAP configuration. The new LDAP
configuration contains all the details of the original configuration object except for
the secondary, or failover, servers. Secondary servers cannot be shared by the
primary server.

Documentum Administrator User Guide contains the instructions on duplicating LDAP

configurations.

7.1.8 Deleting LDAP configurations

You must be a superuser to delete an LDAP configuration.

Before deleting an LDAP configuration object, note the following potential

consequences:

• If you delete an LDAP configuration object that is referenced by server

configuration object of Documentum Server, the Documentum Server cannot use
that LDAP server to authenticate users and there is no default LDAP object
referenced in the server configuration object.
• If you delete an LDAP configuration object that is referenced by server
configuration object of Documentum Server and by user or group objects, the
server cannot use the LDAP server to authenticate users, no default LDAP object

172 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 7.1. LDAP servers

is referenced in the server configuration object, and user and group objects
referencing the LDAP object cannot be updated correctly.
If you delete the LDAP configuration object, you must manually update user and
group objects referencing the LDAP object so that the users and groups can be
authenticated with a different authentication mechanism. To locate users
referencing the LDAP configuration object, click User Management > Users and
search by typing the LDAP Config object name in the User Login Domain field.

Documentum Administrator User Guide contains the instructions on deleting LDAP

configurations.

7.1.9 Using LDAP directory servers with multiple

Documentum Servers
If multiple Documentum Servers are running against a particular repository, you
must perform some additional steps to enable LDAP authentication regardless of the
particular Documentum Server to which a user connects.

Documentum Administrator User Guide contains the instructions on using LDAP

directory servers with multiple Documentum Servers.

7.1.10 LDAP proxy server support

Documentum Server supports LDAP proxy servers, for use in LDAP configurations.
If you are using Global Catalog in Microsoft Active Directory Server, you have to
ensure that all attributes required during LDAP synchronization are present in the
Global Catalog.

7.1.11 Configuring LDAP synchronization for Kerberos users

LDAP synchronization in conjunction with Kerberos SSO authentication can be
implemented in two different ways:

• Using an existing LDAP configuration to authenticate Kerberos users.

• Creating a new LDAP configuration to authenticate Kerberos users.

To use an existing LDAP configuration to authenticate Kerberos users:

1. Modify the user login domain on page 207 attribute in the user object of all
Kerberos users to use the short domain name instead of the name of the LDAP
server.
For example, if a Kerberos user is part of the wdkdomain.com domain, change
the user login domain attribute to wdkdomain.
2. Change the user source on page 208 attribute in the user object to dm_krb for all
Kerberos users that are synchronized via LDAP, if the password is not in plug-
in format. Changing the user source attribute is optional.
3. Run the LDAP synchronization job.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 173

Chapter 7 Managing LDAP Servers

To create a new LDAP configuration to authenticate Kerberos users

1. Create an LDAP configuration object. Use the short domain name as the LDAP
configuration object name on page 158.
For example, if Kerberos users are part of the wdkdomain.com domain, create
an LDAP configuration object using wdkdomain as the LDAP configuration
object name.

2. Change the user source on page 208 attribute in the user object to dm_krb for all
Kerberos users that are synchronized via LDAP.

3. Run the LDAP synchronization job.

7.2 LDAP certificate database management

The LDAP certificate database management system enables administrators to:

• Import certificates into the LDAP certificate database on the Documentum

Server.
• View certificate information in the LDAP certificate database.

Only an administrator who is the installation owner can access the LDAP Certificate
Database Management node.

7.2.1 Viewing LDAP certificates

Documentum Server creates a certificate database when an administrator attempts
to view the LDAP Certificate Database List page for the first time and the certificate
database is not present at the certificate location that was specified when the LDAP
server was added.

Documentum Administrator User Guide contains the instructions on viewing LDAP

certificates.

7.2.2 Importing LDAP certificates

Documentum Administrator User Guide contains the instructions on importing LDAP
certificates.

174 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 7.2. LDAP certificate database management

7.2.3 Using multiple LDAP servers in SSL mode

Documentum Server supports running more than one LDAP server in SSL mode.
However, in this case all SSL-enabled LDAP configuration objects must point to the
same certificate database location. Otherwise, LDAP synchronization does not work
properly.

To set up multiple LDAP servers in SSL mode:

1. Identify a location for the certificate database.

The default location for the certificate database is the location that is specified in
the ldapcertdb_loc object.

2. Import all required certificates into the certificate database, as described in

“Importing LDAP certificates” on page 174.

3. Modify the certification location field for each LDAP server configuration that
uses SSL to point to the same certificate database location.
By default, Documentum Server assigns the file path that is specified in the
ldapcertdb_loc object.

7.2.4 Replacing or removing LDAP certificates

Replacing, deleting, or revoking of LDAP database certificates in the LDAP
certificate database is not supported using the LDAP Certificate Management
functionality. To update the certificates, manually remove the existing LDAP
certificate database on the Documentum Server, restart the method server, then
import the new certificates, as described in “Importing LDAP certificates”
on page 174.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 175

Chapter 8
Managing MSA for Documentum Services

You can manage Managed Service Accounts (MSA) for Documentum services. Use
the instructions described in this chapter to configure MSA for starting or stopping
Documentum processes securely using MSA user account. The Documentum
processes include repository service, connection broker service, and JMS service.

8.1 Prerequisites
1. Configure the Active Directory Module for Powershell and install the Active
Directory Domain Services tools in a Windows Server machine. Microsoft
Documentation contains the instructions.

2. (For Windows Server 2016) Perform the following:

a. Navigate to the Windows Server Manager, click Promote Server to a

Domain > Add new Forest, and then provide the login credentials.
b. Restart the Windows Server and log in as an administrator.
c. In Windows Server Manager, navigate to Tools and open Active Directory
Module for Powershell.

3. (For Windows Server 2012) Perform the following:

a. Configure the Active Directory Module for Powershell in a Windows

Server machine as described in Step 1.
b. Navigate to Windows Server Manager > Active Directory Domain
Services.
c. Click Create New. Provide a name and password for the Domain
Controller and click OK.
d. Install the Active Directory Domain Services.
e. Restart the Windows Server and log in as a Domain Controller user.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 177

Chapter 8 Managing MSA for Documentum Services

8.2 Creating and associating MSA with Microsoft

Windows Server
1. Open the configured Active Directory Module for Powershell in any of the
Windows Server.

2. Import the Active Directory Module in the Windows Server. For example:
> Import-Module ActiveDirectory

3. Create the MSA in the Active Directory manually (for example, myacc4) or
using the Active Directory Module for Poweshell. For example:

a. Create Key Distribution Service (KDS).

"root key":
> Add-KdsRootKey -EffectiveTime ((get-date).addhours(-10));

b. Create MSA.
> New-ADServiceAccount -Name myacc4 -Enabled $true
// DNSHostName : hostname.Primary DNS Suffix (for example,
win12r2orcl-001.ottest.local)

4. Verify if the new MSA, myacc4, is created in the Active Directory. For example,
fetch an Active Directory MSA details in Powershell:
> Get-ADUser -Server <IP address of Active Directory Server or DNS Host Name>
> Filter : SAMAccountName -like “myacc4”

5. Associate the new MSA, myacc4, with a target machine. For example:
> Add-ADComputerServiceAccount -Identity win12r2orcl-001 -ServiceAccount myacc4

6. Import the Active Directory Module to a target machine. For example:

> Import-Module ActiveDirectory

7. Install the MSA you created in the local machine. Provide the permission to the
Server to retrieve password of MSA from the Active Directory. For example:
> Set-ADServiceAccount myacc4 -PrincipalsAllowedToRetrieveManagedPassword
win12r2orcl-001$
> Install-ADServiceAccount -identity myacc4;

8. Restart the machine.

9. Log in as an administrator and install Documentum Server.

10. Create the dm_ldap_config object using IAPI and associate with the Active
Directory.

11. Modify the filters and search appropriately in the LDAP configuration and then
run the LDAP synchronization job to synchronize the MSA user in
Documentum Server from Active Directory. For example:
retrieve,c,dm_ldap_config

12. Verify the synchronized user in the repository using IAPI. For example:

178 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 8.2. Creating and associating MSA with Microsoft Windows Server

retrieve,c,dm_user where user_name=’myacc4’

Caution
Do not change user_password of the MSA user using IAPI, as it is
encrypted. Changing it could lead to corruption and cause issues with
the synchronization between Documentum Server and Active
Directory.

13. Dump the synchronized user using IAPI.

The user, system, application, and the internal attributes are updated.

14. Associate the MSA with your services. For example, for Documentum Server,
associate with the Documentum repository, connection broker, and JMS
services.

15. Change the installation owner manually to a domain user account as follows:

a. Add any existing Documentum Server machine to the domain, configure

the config.xml file, and then run the migration utility to change the install
owner.
b. Run the following queries on the database:
BEGIN TRAN
update dm_user_s set user_os_domain = 'otxmsa.local' where
user_login_name='myacc4$';
update dm_user_s set user_global_unique_id = 'otxmsa.local:myacc4$' where
user_login_name='myacc4$';
update dm_user_s set user_login_domain = 'otxmsa.local' where
user_login_name='myacc4$';
update dm_server_config_s set r_install_domain = 'otxmsa.local';
COMMIT TRAN

c. Edit the server.ini file (if it has not changed). For example:
user_auth_target = <DOMAIN NAME> install_owner = <DOMAIN USER>

d. Modify the following entries manually in the Windows registry. For

example:

• [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services
\DmServer<Docbasename>]
ObjectName=<DOMAIN NAME>\<DOMAIN USER>

• [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services
\DmServer<Docbasename>]
ImagePath=C:\Documentum\product\16.7\documentum.exe -docbase name testenv -
security acl -init_file
C:\Documentum\dba\config\testenv\server.ini -run as service -install owner
myacc4$ -logfile

• [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\DmMethodServer]
ObjectName=<DOMAIN NAME>\<DOMAIN USER>

• [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\DmDocBroker]
ObjectName=<DOMAIN NAME>\<DOMAIN USER>

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 179

Chapter 8 Managing MSA for Documentum Services

• [HKEY_LOCAL_MACHINE\SOFTWARE\Documentum\Server\16.4]
“DM_DMADMIN_USER"="<DOMAIN USER>"
"DM_DMADMIN_DOMAIN"="<DOMAIN NAME>"

e. Right-click on DmServer<repository name> > Permissions > Advanced >

Change owner > Object Types > Service accounts, enter the name of MSA
and click OK.
Ensure that the full control is provided to this user, similar to the
DmMethodServer and DmDocBroker services.
f. Invoke regedit and verify if the install owner has full permissions on the
following entries:

• [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application
\Documentum]

• [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog]

• [HKEY_LOCAL_MACHINE\SOFTWARE\DOCUMENTUM\DOCBASES]

g. Run the following command and grant permission for the new installation
owner:
> icacls C:\Documentum /grant <DOMAIN NAME>\<DOMAIN USER>:F /t /q

After the completion of all the steps, ensure that all services are up and running.

16. Ensure that Documentum connection broker and JMS services starts from
services.msc.

17. To start the repository using MSA, instead of using services.msc, open the
command prompt window and set the installation owner explicitly for your
MSA user. For example:
> C:\Documentum\product\16.7\bin\documentum.exe -docbase_name testusername -
security acl -init_file

C:\Documentum\dba\config\testusername\server.ini -install_owner myacc4

If the repository fails to start, run the dm_crypto_boot utility and verify the
password.

18. Navigate to %DCTM_HOME%\bin and run the following command to start the
agent exec program:
> dm_agent_exec.exe -docbase_name testenv -docbase_owner Administrator

You can use IAPI as a trusted administrator user and run jobs such as
dm_UserRename, dm_LDAPSynchronization, and so on.

180 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 8.3. Removing MSA

8.3 Removing MSA

1. Run the migration utility and change the installation owner to administrator
for Documentum Server.

2. Run the following PowerShell Command let to remove the MSA from the local
machine:
> Remove-ADServiceAccount -identity <MSA name>

3. (Optional) Remove the service account from Active Directory. For example:
> Remove-ADComputerServiceAccount -Identity <the machine where MSA is assigned to> -
ServiceAccount <MSA>

Skip this step if you want to reassign an existing MSA from one machine to
another.

Notes

• When you want to create new dm_ldap_config object other than the one
already created, you must manually provide full access permission to the
MSA user to access the new .cnt file generated at C:\Documentum\dba
\config\testenv\. Otherwise, it results in the access denied error when
you run the LDAP synchronization job using the new LDAP configuration
object. This is because, Windows does not allow default user permissions on
a new file or folder.
• Configuration is for MSA user domain only. LDAP server or the Active
Directory different from MSA domain is not supported for MSA
configuration.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 181

Chapter 9

OpenText Directory Services Integration with

Documentum Server

9.1 Overview
With the OpenText Directory Services (OTDS) integration with Documentum Server,
the following are supported:

• Users and groups (existing or new) in OTDS can be pushed or synchronized to

Documentum Server.
• Users in OTDS can be authenticated against OTDS using the oAuth2 token
(authentication and authorization protocol), OTDS ticket, and also using plain
password mechanisms.
• Using the oAuth2 token, Documentum client products can leverage OTDS
capabilities to support additional SSO mechanism.

9.2 Configuring OTDS integration with Documentum

Server
You must perform the following instructions in OTDS:

1. Create a partition.
Partition in OTDS is similar to LDAP configuration in Documentum Server. You
can create partition using AD server details, create user and group filters,
monitor protocol, perform AD to OTDS attributes mapping, and so on.

2. Create a resource.
Resource represents any ECM server (for example, Documentum server). In
resource, you can configure resource REST (Generic) server URL (http://
<JMS_Host>:<JMS_Port>/dmotdsrest), administrator credentials of repository,
and OTDS to repository attribute mappings.

Notes

• Ensure that the value of the <user_name> and <__NAME__> resource

attributes in User Attributes Mappings are same.

3. (Optional) Select Actions > Include Groups of the access role to synchronize
groups.

4. Map the resources to partition in access role.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 183

Chapter 9 OpenText Directory Services Integration with Documentum Server

Access role is created automatically when creating a resource. In access role,

you need to add the partition and the users or groups that need to be pushed to
Documentum Server.

Caution
You must not consolidate resources manually using the Actions >
Consolidate option in the resources page because the synchronization of
the resource is automatic.

OpenText Directory Services documentation contains the detailed instructions.

9.3 Supported functions

Function Existing LDAP in OTDS Integration with
Documentum Server Documentum Server
Full synchronization Synchronize LDAP Consolidation of partition or
configuration in full resources in OTDS.
synchronization mode.
Incremental synchronization Synchronize LDAP Automatically monitored by
configuration in incremental OTDS.
synchronization mode.
Note: Restarting
partition for
incremental
synchronization is for
troubleshooting only.
Import mode Import mode option in LDAP Use Include Groups option
configuration. in Access Role.
Deleting users in repository Inactive or unchanged Set
options for user deletion in inactive_deleted_user
LDAP configuration. to T or F in dmotds.
properties of the
dmotdsrest.war in JMS.

The default value is T.

Renaming users in repository Enable or disable user Set user_rename_enabled
renaming option in LDAP to T or F in Resources > User
configuration. Attribute Mappings in
OTDS.

The default value is F.

Renaming groups in Enable or disable group Set
repository renaming option in LDAP groups_rename_enabled
configuration. to T or F in Resources >
Group Attribute Mappings
in OTDS.

The default value is F.

184 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 9.4. Configuring OTDS authentication in Documentum Server

Function Existing LDAP in OTDS Integration with

Documentum Server Documentum Server
Custom user type User Type option in LDAP Set user_type to the
configuration. corresponding type in
Resources > User Attribute
Mappings in OTDS.

The default type is dm_user.

Creating default cabinet for Using the Set
users create_default_cabinet create_default_cabinet
in LDAP synchronization job to T or F in Resources > User
argument. Attribute Mappings in
OTDS.

The default value is F.

9.4 Configuring OTDS authentication in

Documentum Server
1. Update the Documentum Server configuration object with the app_server_uri
of OTDSAuthentication as follows:
API> retrieve,c,dm_server_config
API> append,c,l,app_server_name
SET> OTDSAuthentication
API> append,c,l,app_server_uri
SET> http://<JMS_Host>:<JMS_Port>/
OTDSAuthentication/servlet/authenticate
API> save,c,l

2. Obtain OTDS certificate. Run the following URL: https://

otds_ip:otds_port/otdsws/rest/systemconfig/certificate_content.

3. Configure the OTDS certificate at <JMS_Installation_Directory>\server\

DctmServer_MethodServer\deployments\ServerApps.ear\
OTDSAuthentication.war\WEB-INF\classes\otdsauth.properties.

4. Configure the OTDS web service endpoint for password authentication,

http://otds_ip:otds_port/otdsws/rest/authentication/credentials, in
the otdsauth.properties file.

5. (Optional only for OTDS ticket authentication)

a. Configure the OTDS web service endpoint, http://otds_ip:otds_port/

otdsws/rest/authentication/resource/validation, in the otdsauth.
properties file.
b. Configure the repository name, resource ID, and secret key of the resource
in the otdsauth.properties file.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 185

Chapter 9 OpenText Directory Services Integration with Documentum Server

9.5 OTDS users authentication

You can authenticate the OTDS users using the following IAPI commands:

• Password-based authentication:
connect,<docbase_name>,<user_login_name>,dm_otds_password=<user_pa
ssword>

• oAuth2 token-based authentication:

connect,<docbase_name>,<user_login_name>,dm_otds_oauth=<oAuth2_tok
en>

• oAuth2 token-based authentication without user login name:

connect,<docbase_name>,null,dm_otds_ticket=<oAuth2_token>

• OTDS ticket-based authentication: connect,<docbase_name>,null,

dm_otds_ticketex=<OTDS_ticket>

9.6 Troubleshooting
Use the following information, as appropriate:

• The trace_authentication and trace_http_post parameters can be enabled

in Documentum Server to troubleshoot the authentication mechanism in
Documentum Server.
• The log4j.category.com.documentum.cs.otds parameter can be set to DEBUG
in <JMS_Installation_Directory>\server\DctmServer_MethodServer
\deployments\ServerApps.ear\APP-INF\classes\log4j.properties to
troubleshoot the user synchronization between OTDS and repository of the
Documentum Server.
• The log4j.rootCategory parameter can be set to DEBUG in
<JMS_Installation_Directory>\server\DctmServer_MethodServer
\deployments\ServerApps.ear\OTDSAuthentication.war\WEB-INF\classes
\log4j.properties to troubleshoot the user authentication.

• The logs of application dmotdsrest (dmotdsrest.log) and OTDSAuthentication

(otdsauth.log) are available at <JMS_Installation_Directory>\server\
DctmServer_MethodServer\logs.

• To obtain the list of all the users and groups synchronized from OTDS to the
repository, use the following DQL queries:

– List of users: select user_name from dm_user where user_source = 'OTDS'

– List of groups: select group_name from dm_group where group_source =
'OTDS'

186 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 10
Distributed Content Configuration

10.1 Network locations

Network locations are a basic building block of a single-repository distributed
environment for web-based clients. Network locations identify locations on a
network, and, optionally, a range of IP addresses, from which users connect to
Documentum web clients. For example, a Documentum installation could include
network locations called San Francisco, New York, London, Athens, Tokyo, and
Sydney, corresponding to users in those cities. A network location can also identify
specific offices, network subnets, or even routers.

Network locations are associated with server configuration objects and acs
configuration objects. The server configuration objects and acs configuration objects
contain information defining the proximity of a Documentum Server or ACS Server
to the network location. Documentum Server uses the information in the server
configuration objects and acs configuration objects and their associated network
locations to determine the correct content storage area from which to serve content
to a web client end user and to determine the correct server to serve the content.

Creating network locations requires superuser privileges. Network locations can be

created only in a repository designated as a global registry, and the name of each
location must be unique among the set of network locations in the global registry.
Network locations should be created in the global registry repository that is defined
when DFC is installed on the Documentum Administrator host. If a network
contains multiple global registry repositories, a particular Documentum
Administrator instance only recognizes the global registry that was designated
during DFC installation on the Documentum Administrator host. You can connect to
a global registry repository without being able to create network locations in that
global registry.

Use the Administration > Distributed Content Configuration > Network Locations
navigation in Documentum Administrator to access the Network Locations list page.
From the Network Locations list page, you can create, copy, view, modify, and
delete network locations.

Documentum Platform and Platform Extensions Installation Guide contains more

information on network locations.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 187

Chapter 10 Distributed Content Configuration

10.1.1 Creating, viewing, or modifying network locations

Network locations should be created in the global registry repository that is defined
when DFC is installed on the Documentum Administrator host. You must have
superuser privileges in the global registry repository to create network locations.
Documentum Platform and Platform Extensions Installation Guide provides additional
information on network locations.

Note: When localhost is in the URL used from a browser on the application
server host to access an application server, it resolves to 127.0.0.1. Unless
127.0.0.1 is included in a network location, the correct network location is not
selected automatically. Therefore, when you create network locations, include
the IP address 127.0.0.1 in a network location if you want to:

• Run a browser on the application server host where a WDK application is

located.
• Use localhost in the URL when accessing the application.
• Automatically select the correct network location.

Table 10-1: Network location properties

Field label Value

Network Location Identifier An identifier that is used by system and
network administrators. For example, to
identify network locations by network
subnets. This field cannot be edited after the
network location is created.
Subject A description of the network location.
Default Network Location Select to display the network location to
users whose IP address is not mapped to a
particular network location.

At log-in time, an end user whose IP address

is not mapped to a network location sees a
set of possible network locations. When
selected, this network location is on the list
from which the user selects. If there is only
one network location with this checkbox
selected, that network location is used
automatically and the user does not see the
list.

188 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 10.1. Network locations

Field label Value

Network Location Name A descriptive name of the network location.
For example, the geographical location of the
network, such as Paris, San Francisco. The
name is displayed on the login page for
Documentum web clients when users must
choose a network location. The display name
is not the object name. The display name can
be modified after the network location is
created.
IP Address Ranges The IP address range identified by the
network location. Each range must conform
to standard IP address conventions. A
network location may have multiple IP
address ranges. It is recommended that each
IP address is mapped to a single network
location, but if an IP address maps to
multiple physical locations, you may need to
map that address to multiple network
locations.

Type the IP address in one of the following

formats:
• IPv4 address range can be entered by
separating the two IP address with a
hyphen(-). For example: x.x.x.x-x.x.x.x
where x is from 0 to 255.
• IPv6 address range can be entered by
separating the two IP addresses with a
hyphen(-). For example: x:x:x:x:x:x:x:x-
x:x:x:x:x:x:x:x or x:x:x::/y (ipv6-address/
prefix-length) where the x’s are the
hexadecimal values of the eight 16-bit
pieces of the address and y is a decimal
value specifying how many of the
leftmost contiguous bits of the address
comprise the prefix.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying network locations.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 189

Chapter 10 Distributed Content Configuration

10.1.2 Copying network locations

To save time retyping existing information, you can copy a network location file
using the Save As option. To copy a network location, you must be connected to the
repository known to DFC on the Documentum Administrator host as a global
registry and you must be logged in as a user with superuser privileges.

Documentum Administrator User Guide contains the instructions on copying network

locations.

10.1.3 Deleting network locations

You must have superuser privileges to delete a network location. Users who connect
from a location that was mapped to a deleted network location are not automatically
mapped when they connect to a web client. If you selected any network locations to
be displayed to users who are not automatically mapped, the users see that list when
they log in.

Network locations are used to determine which server provides content files to end
users. If the network location that you are deleting is associated with any BOCS or
ACS servers, users at those locations could not receive content in the most efficient
manner possible.

When you delete network locations, references to the network locations in existing
server configuration objects, acs configuration objects, bocs configuration objects,
and BOCS caching jobs are not automatically removed. You must manually remove
any references to the deleted network locations.

Documentum Administrator User Guide contains the instructions on deleting network

locations.

10.2 ACS servers

An Accelerated Content Services (ACS) server is a light-weight server that is
automatically created during a Documentum Server installation. The ACS server
reads and writes content for web-based client applications using HTTP and HTTPS
protocols. ACS servers do not modify object metadata but write content to storage
areas.

Each Documentum Server host installation has one ACS server that communicates
with one Documentum Server per repository and the Documentum Message
Services (DMS) server. A single ACS server can serve content from multiple
repositories. WDK-based applications can use the ACS server if the ACS server is
enabled in the app.xml file of the applications.

Most ACS server properties can be modified using Documentum Administrator.

Certain ACS server behavior is configured the acs.properties file on the ACS server
host and cannot be modified by Documentum Administrator.

190 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 10.2. ACS servers

Documentum Platform and Platform Extensions Installation Guide provides information

on modifying the acs.properties file and additional information about the ACS
server.

The ACS server is configured on the ACS Servers Configuration page that can be
accessed in the Administration > Distributed Content Configuration > ACS
Servers node. The ACS Servers Configuration page displays information about the
ACS server, as described in “ACS Server Configurations” on page 191.

Table 10-2: ACS Server Configurations

Column Description
Name The name that is assigned to the ACS server
during the Documentum Server installation.
The name cannot be modified.
Documentum Server The name of the Documentum Server the
ACS server is associated with.
Content Access Specifies how the ACS server can access
content. Valid values are:
• Access all stores: The ACS server can
access all stores that are connected to the
Documentum Server.
• Access local stores only: The ACS server can
read content from local file stores, but is
unable to use Surrogate Get to request
content files it does not find in the local
file stores.
• None (disabled): The ACS server is
disabled.
Projections & Stores from Specifies the connection broker projections,
network locations, and local stores
information for the ACS server.
Description A description of the ACS server.
Dormancy Status The current dormancy status of the ACS
server. Valid values are:
• Dormant
• Active

Note: The Dormancy Status column is

only visible for 7.0 and later versions of
repositories.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 191

Chapter 10 Distributed Content Configuration

10.2.1 Viewing or modifying the ACS server configuration

properties
Documentum Administrator User Guide contains the instructions on viewing or
modifying the ACS server configuration properties.

Table 10-3: ACS Server Configuration properties

Field Description
ACS Server Configuration
Name The name that is assigned to the ACS server
during the Documentum Server installation.
The name cannot be modified.
Associated Content Server The name of the Documentum Server that
the ACS server is associated with.
Description A description of the ACS server.
ACS Server Version The major and minor version of the ACS
server.

The ACS server version indicates the

underlying repository version.

Valid values:
• 2.1: Specifies that the ACS server is part
of a Documentum version 6.5 SPx
repository.
• 2.2: Specifies that the ACS server is part
of a Documentum version 6.6 to 6.6
(Patch 21) repository.
• 2.3: Specifies that the ACS server is part
of a Documentum version 6.6 (Patch 22)
to 16.x repository.
Dormancy Status Indicates the dormancy status of ACS server.

Note: The Dormancy Status label is

only visible for 7.0 and later versions of
repositories.
Content Access Specifies how the ACS server can access
content. Valid values are:
• Access all stores: The ACS server can
access all stores that are connected to the
Documentum Server.
• Access local stores only: The ACS server can
read content from local file stores in the
repository.
• None (disabled): The ACS server is
disabled.

192 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 10.2. ACS servers

Field Description
ACS Server Connections
Protocol The protocol the ACS server uses. Valid
values are http and https. Click Add to add a
protocol, or select a protocol from the list and
click Edit to modify it or Delete to remove
the protocol.
Base URL The base URL for the ACS server. The base
URL requires the following format:
<protocol>://<host>:<port>/ACS/servlet/ACS

10.2.2 ACS projections and stores

ACS projections and stores are configured on the Projections & Stores page.

Table 10-4: ACS Projections & Stores properties

Field Description
Source Specifies where to use projections and stores
for the ACS server. Valid values are:
• Associated Content Server: The ACS
server uses the connection broker
projections, network locations, and local
stores already configured for ACS.
• Settings entered here: You must enter the
ACS server uses connection brokers,
network locations, and near stores
manually.
If you select this option, an Add buttons
displays in the Connection Broker
Projections, Network Location
Projections, and Local Stores sections.
Connection Broker Projections
Target Host The host name of the server that hosts the
connection broker.

Click Add to add a target host, or select a

host from the list and click Delete to remove
the host.

The Documentum connection broker is a

process that provides client sessions with
server connection information. Each ACS
server broadcasts information to connection
brokers at regular intervals.
Port The port number on which the connection
broker is listening.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 193

Chapter 10 Distributed Content Configuration

Field Description
Enabled Enables projections to the connection broker.
Network Location Projections
Network Location Specifies a network location in the global
registry of the Documentum Server host.

Click Add to add a network location, or

select a location from the list and click Delete
to remove the location.

Network locations identify locations on a

network, and, optionally, a range of IP
addresses, from which users connect to
Documentum web clients.
Display Name A name that describes the network location.
Proximity The proximity value for the network
location.
Enabled Enables projection to that network location.
Local Stores
Local Store A local store.

Click Add to add a store, or select a store

from the list and click Delete to remove the
store.

Local stores are defined as near to the ACS

server.
Type Specifies the storage type associated with the
local store. This property cannot be modified.

Documentum Administrator User Guide contains the instructions on viewing or

modifying the ACS projection stores.

10.2.3 Designating connection brokers for an ACS server

Connection broker projections are configured in the Connection Broker Projections
section of the ACS Server Configurations page.

194 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 10.2. ACS servers

Table 10-5: ACS Connection Broker Projections properties

Field Description
Source Specifies where to use projections for the
ACS server. Valid values are:
• Associated Content Server: The ACS
server uses the connection broker
projections, network locations, and local
stores already configured for ACS.
When this option is selected, you cannot
modify the connection broker projections.
• Settings entered here: Select this option
to designate connection broker
projections.
If you select this option, an Add buttons
displays in the Connection Broker
Projections, Network Location
Projections, and Local Stores sections.
Connection Broker Projections
Target Host The host name of the server that hosts the
connection broker.

Click Add to add a target host, or select a

host from the list and click Delete to remove
the host.

The Documentum connection broker is a

process that provides client sessions with
server connection information. Each ACS
server broadcasts information to connection
brokers at regular intervals.
Port The port number on which the connection
broker is listening.
Enabled Enables projections to the connection broker.

Documentum Administrator User Guide contains the instructions on designating

connection brokers for an ACS server.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 195

Chapter 10 Distributed Content Configuration

10.2.4 Choosing network locations

Use the Choose Network Locations page to designate network locations. The
network locations displayed on this page are in the global registry known to DFC on
the Documentum Administrator host.

Documentum Administrator User Guide contains the instructions on adding or deleting

network locations.

10.3 BOCS servers

Branch Office Caching Services (BOCS) servers cache content locally. Caching
content allow quick access to content. The amount of cached content and the storage
time can be configured. Content can also be cached programmatically prior to user
requests or through a pre-caching job. A BOCS server can serve content from
multiple repositories.

BOCS servers communicate only with ACS servers and DMS servers, but not
directly with Documentum Servers. Every BOCS server for Documentum 6 or later
repositories is associated with a dm_bocs_config object. The installation program for
the BOCS server does not create the object at installation time. The BOCS server
must be added manually, using the properties on the BOCS Servers Configuration
page. All BOCS configuration objects for Documentum 6 or later repositories reside
in the global registry in the /System/BocsConfig folder.

To create, modify, or view BOCS configuration objects, you must have superuser
privileges and be connected to the global repository that is associated with the DFC
installation. If you are not connected to the global repository and click the BOCS
Server node, the system displays an error message and provides a link to the login
page of the global registry repository.

10.3.1 Creating, viewing, or modifying BOCS servers

You can create, view, or modify the BOCS configuration object in the global registry
repository after the BOCS server is installed on its host. To create, view, or modify
BOCS configuration objects, you must have superuser privileges and be connected
to the global registry that is associated with the DFC installation.

Table 10-6: BOCS server properties

Field label Value

BOCS Server Configuration Info
Name The object name of the BOCS server.

The object name cannot be modified for

existing BOCS server configuration objects.
Description Description of the BOCS server.

196 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 10.3. BOCS servers

Field label Value

BOCS Server Version A numeric string that identifies the set of
distributed content features with which the
BOCS server is compatible. In some cases, a
set of features spans multiple product
versions. Valid values are:
• 1: The Content Access options are limited
to Read Only and None (disabled).
• 2.1: Compatible with Documentum
Server version 6.5 SPx and 6.6.
• 2.2: Compatible with Documentum
Server version 6.6 to 6.6 (Patch 21). This
value is used only when Atmos and ACS
Connector integration is available.
• 2.3: Compatible with Documentum
Server versions 6.6 (Patch 22) to 16.x. This
value is only valid if the actual version of
the installed BOCS server is from 6.6
(Patch 22) to 16.x.
Content Access Select an access type, as follows:
• Read and synchronous write: Select this
option for the BOCS server to support
read and synchronous write.
• Read, synchronous, and asynchronous
write: Select this option for the BOCS
server to support read, synchronous
write, and asynchronous write.
• None (disabled): The BOCS server is
disabled.
Network Locations Network locations served by the BOCS
server.

Click Select to access the Choose a Network

Location page to select network locations.
Repositories Select a repository from which to serve
content, as follows:
• all repositories: Content is served from
all repositories.
• selected repositories only: Serves content
from all repositories that are specified on
the Include list. Click Edit to add specific
repositories.
• all except selected repositories: Serves
content from all repositories except the
repositories that are specified in the
Exclude list.
Click the Edit link to add specific
repositories to exclude.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 197

Chapter 10 Distributed Content Configuration

Field label Value

Proxy URL The BOCS proxy URL. The URL can contain
up to 240 characters. The BOCS proxy URL is
a message URL that only DMS uses when
BOCS is in push mode.
BOCS Server Connections
Add Click to access the BOCS Server Connection
page to add a protocol and base URL for the
BOCS server.
Edit Select a communication protocol and then
click Edit to access the BOCS Server
Connection page to edit a protocol and base
URL for the BOCS server.
Delete To delete a BOCS server protocol and base
URL, select a communication protocol and
then click Delete.
Protocol and Base URL The communication protocols used by the
BOCS server to provide content to end users.
The HTTP and HTTPS protocols are
supported. The Base URL must be provided
when the BOCS server is created. It is in the
form:
<protocol>://<host>:<port>/ACS/servlet/ACS

where protocol is http or https; host is the

name of the computer on which the BOCS
server is installed; and port is the port
designated for communications during
BOCS server installation.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying BOCS servers.

10.3.2 Setting BOCS server security

The BOCS server security properties specifies whether the BOCS server is in push or
pull mode and is used to upload a public key from the BOCS server.

The BOCS server configuration object in the global registry contains the public key
information and generates an electronic signature for the BOCS server to use when
contacting the DMS server. When the BOCS server connects to the DMS server in
pull or push mode, it sends its electronic signature to DMS where DMS matches the
electronic signature to the public key in the BOCS configuration object. If the DMS
server authenticates the BOCS electronic signature, the BOCS server can then pull or
push its messages from or to the DMS server respectively.

198 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 10.3. BOCS servers

Table 10-7: BOCS server security properties

Field label Value

Pull Mode Enabled Specifies whether the BOCS server
communicates with the DMS server using
the pull mode.

If this option is not selected, the BOCS server

communicates with the DMS server using
the push mode.
Public Key Installed Displays the last updated status for the
public key.
Upload Public Key File Click Browse to locate and install the public
key file for the BOCS server.

Documentum Administrator User Guide contains the instructions on setting BOCS

server security.

10.3.3 Setting BOCS server communication protocols

On the BOCS Server Connection page, set the communication protocols used by the
BOCS server.

To access the BOCS Server Connection page, click Add or Edit in the BOCS Server
Connections section of the BOCS Server Configuration page.

Documentum Administrator User Guide contains the instructions on setting BOCS

server communication protocols.

10.3.4 Deleting BOCS servers

You can delete BOCS server configuration objects from a global registry repository.

Deleting the configuration object does not uninstall the BOCS servers; they must be
manually uninstalled from the hosts on which they are running. Without the
configuration object, the BOCS Server cannot provide content from this repository.

Documentum Administrator User Guide contains the instructions on deleting BOCS

servers.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 199

Chapter 10 Distributed Content Configuration

10.4 Configuring distributed transfer settings

The distributed transfer object is created when the repository is created. The
distributed transfer configuration object controls whether reading and writing
content through ACS is enabled for the repository and whether BOCS pre-caching is
also enabled. Administrators cannot create new distributed transfer objects;
however, administrators with superuser privileges can configure the default object.

Documentum Administrator User Guide contains the instructions on configuring

distributed transfer settings.

10.5 Messaging server configuration

A Documentum Messaging Services (DMS) server is an intermediary server that
provides messaging services between an ACS or BOCS server and a web application
server. The messaging server configuration object must be created and set up in the
global registry using Documentum Administrator. Administrators with superuser
privileges only can configure the messaging server configuration object.
Administrators with superuser privileges connecting to 6.7 and below global
registry can only create default messaging server configuration object. If a
messaging server configuration object exists, administrator cannot create new
objects.

Note: You can create multiple messaging server configuration objects using
Documentum Administrator 7.0 on 7.0 and later versions of Documentum
Server and repositories. Use the File > New > Messaging Server Configuration
in the Messaging Server list page.

Use the Administration > Distributed Content Configuration > Messaging Server
navigation to access the Messaging Server Configuration list page.

To modify or view the DMS server configuration object, you must be connected to
the repository known to DFC on the Documentum Administrator host as a global
registry and you must be logged in as a user with superuser privileges.
Administrators logging in to a Documentum repository that is not the global registry
do not see a Messaging Server Configuration list page. If they click the Messaging
Server node, the system displays a message informing administrators that they
logged in to a non-global registry repository and the messaging server configuration
object is stored only in the global registry repository. The system also shows a link
for the administrator to click to navigate to the login page of the global registry
repository.

To save time retyping existing information, you can copy a messaging server
configuration using the Save As option. To copy a messaging server, you must be
connected to the repository known to DFC on the Documentum Administrator host
as a global registry and you must be logged in as a user with superuser privileges.

Documentum Administrator User Guide contains the instructions on the following:

• Viewing or modifying the messaging server configuration

200 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 10.5. Messaging server configuration

• Copying a messaging server

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 201

Chapter 11
User Management

11.1 Administering users, groups, roles, and sessions

Users, groups, roles, and sessions are managed in the User Management node. The
User Management node is accessed by selecting Administration > User
Management.

The User Management page contains links to the user management features that can
be configured for a repository, as described in “Users, groups, roles, and sessions”
on page 203.

Table 11-1: Users, groups, roles, and sessions

Link Description
Users Accesses the Users page. From the Users
page you can
• Search for existing user accounts.
• Create, modify, and delete user accounts.
• View and assign group memberships for
a particular user account.
• Change the home repository for
particular user accounts.

The “Users” on page 204 section contains

more information on user accounts.
Groups Accesses the Groups page. From the Groups
page you can
• Search for existing group accounts.
• Create, modify, and delete group
accounts.
• View and reassign group a particular
group account.

The “Groups” on page 219 section contains

more information on group accounts.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 203

Chapter 11 User Management

Link Description
Roles Accesses the Roles page. From the Roles
page you can
• Search for existing roles.
• Create, modify, and delete roles.
• View current group memberships and
reassign roles.

The “Roles” on page 227 section contains

more information on roles.
Module Roles Accesses the Modules Roles page. From the
Modules Roles page you can
• Search for existing module roles.
• Create, modify, and delete module roles.
• View current group memberships and
reassign module roles.

The “Modules roles” on page 229 section

contains more information on module roles.
Sessions Accesses the Sessions page. From the
Sessions page you can
• Search for sessions.
View session properties and session logs.

The “Sessions” on page 231 section contains

more information on sessions.

11.2 Users
A repository user is a person or application with a user account that has been
configured for a repository. User accounts are created, managed, and deleted on the
User node. In a Documentum repository, user accounts are represented by user
objects. Whenever a new user account is added to a repository, Documentum Server
creates a user object. A user object specifies how a user can access a repository and
what information the user can access.

204 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.2. Users

11.2.1 Locating users

Use the search filters on the Users page to locate users.

Table 11-2: User search filters

Field Description
User Name Filters the search results by user name.
Default Group Filters the search results the name of the
default group.
User Login Name Filters the search results by the login name of
the user.
User Login Domain Filters the search results by login domain.

Documentum Administrator User Guide contains the instructions on locating users.

11.2.2 Creating or modifying users

You must be the installation owner, or have system administrator or superuser
privileges to create users. Superusers and system administrators cannot modify their
own extended privileges.

Before you create users, determine what type of authentication the server uses. If the
server authenticates users against the operating system, each user must have an
account on the server host. If the server uses an LDAP directory server for user
authentication, the users do not need to have operating system accounts.

If the repository is the governing member of a federation, a new user can be a global
user. Global users are managed through the governing repository in a federation,
and have the same attribute values in each member repositories within the
federation. If you add a global user to the governing repository, that user is added to
all the member repositories by a federation job that synchronizes the repositories.

If a user is authenticated by an LDAP server, only a superuser can modify the

LDAP-mapped attributes of user.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 205

Chapter 11 User Management

Table 11-3: User properties

Field label Value

State Indicates the user account state in the
repository. Valid values are:
• Active: The user is a currently active
repository user. Active users are able to
connect to the repository.
• Inactive: The user is not currently active in
the repository. Inactive users are unable
to connect to the repository. The user
automatically moves to ACTIVE state
after auth_deactivation_interval minutes,
if auth_deactivation_interval is greater
than zero.
The user is automatically assigned to
INACTIVE state by Documentum Server
if the user exceeds max_auth_attemp
failure attempts within
auth_failure_interval minutes.
• Locked: The user is unable to connect to
the repository.
• Locked and inactive: The user is inactive
and unable to connect to the repository.
The user moves to locked and inactive
states, if a locked user exceeds
max_auth_attemp failure attempts within
auth_failure_interval minutes.

If the user is a superuser, only another

superuser can reset the state.
Name The user name for the new user. The user
name cannot be modified, but can be
reassigned to another user.
User Login Name The login name used for authenticating a
user in repositories.

If the user is an operating system user, the

user login name must match the operating
system name of the user. If the user is an
LDAP user, the user login name must match
the LDAP authentication name of the user.

206 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.2. Users

Field label Value

User Login Domain Identifies the domain in which the user is
authenticated. This is typically a Windows
domain or the name of the LDAP server used
for authentication.

If you are using Kerberos authentication with

LDAP synchronization, the user login
domain must be set to the short domain
name, as described in “Configuring LDAP
synchronization for Kerberos users”
on page 173.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 207

Chapter 11 User Management

Field label Value

User Source Specifies how to authenticate user name and
password of a given repository user. Valid
values depend on whether the repository
runs on a Linux or Windows server.
• None: The user is authenticated in a
Windows domain.
• UNIX only: The user is authenticated
using the default Linux mechanism,
dm_check_password or other external
password checking program.
• Domain only: The user is authenticated
against a Windows domain.
• UNIX first: This is used for Linux
repositories where Windows domain
authentication is in use. The user is
authenticated first by the default Linux
mechanism; if that fails, the user is
authenticated against a Windows
domain.
• Domain first: This is used for Linux
repositories where Windows domain
authentication is in use. The user is
authenticated first against a Windows
domain; if that fails, the user is
authenticated by the default Linux
mechanism.
• LDAP: The user is authenticated through
an LDAP directory server.
• Inline Password: The user is authenticated
based on a password stored in the
repository. This option is available only
when Documentum Administrator is
used to create users. It is not available in
other applications in which it is possible
to create users.
• dm_krb: The user is authenticated using
Kerberos Single-Sign-On (SSO).

Note: If the value of User Source is

None or Domain only then user must
have the Allow logon locally privilege
to change the password. You can
change the user privileges using
Administrative Tools in Windows.

208 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.2. Users

Field label Value

Password The password for the user.

This field is displayed if Inline Password is

selected as the User Source. Type the
password, which is then encrypted and
stored in the repository.

This must be provided manually for users

added using an imported LDIF file.
Confirm Password The password for the user.

This field is displayed if Inline Password is

selected as the User Source. Enter the same
password you entered in the Password field.
Description A description of the user account.
E-Mail Address The E-mail address of the user. This is the E-
Mail address to which notifications are sent
for workflow tasks and registered events.
User OS Name The operating system user name of the user.
Windows Domain The Windows domain associated with the
user account or the domain on which the
user is authenticated. The latter applies if
Documentum Server is installed on a Linux
host and Windows domain authentication is
used.
Home Repository The repository where the user receives
notifications and tasks.
User is global If the user is created in the governing
repository of a federation, select this option
to propagate the user account to all members
of the federation.
Restrict Folder Access To Specifies which folders the user can access.
Click Select to specify a cabinet or folder.
Only the selected cabinets and folders
display for the user. The other folders do not
display but the user can access the folders
using the search or advanced search options.

If no folders or cabinets are specified, the

user has access to all folders and cabinets in
the repository, depending on the permissions
on those cabinets and folders, and depending
on folder security.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 209

Chapter 11 User Management

Field label Value

Default Folder The default storage place for any object the
user creates. This option only displays when
you are creating a user. Valid values are:
• Choose existing folder: Select this option to
assign a folder you already created as the
default folder for that user.
• Choose/Create folder with the user name:
Select this option to automatically create a
folder with the name of the user as the
object name.
Default Group The group that is associated with the default
permission set of the user. Click Select to
specify a default group.

When the user creates an object in the

repository, it automatically belongs to this
group.
Default Permission Set The permission set that assigns the default
permissions to objects the user creates. Click
Select to specify a default permission set.
Db Name The user name of the user in the underlying
RDBMS. The DB Name is only required if the
user is a repository owner or a user who
registers RDBMS tables.
Privileges The privileges that are assigned to the user.

User privileges authorize certain users to

perform activities in the repository. Select
one of the privileges from the drop-down
list, as follows:
• None
• Create Type
• Create Cabinet
• Create Cabinet and Type
• Create Group
• Create Group and Type
• Create Group and Cabinet
• Create Group, Cabinet, and Type
• System administrator
• Superuser: If you grant superuser
privileges to a user, add that user
manually to the group called
admingroup. If you revoke the superuser
privileges of a user, remove the user from
the admingroup.

210 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.2. Users

Field label Value

Extended Privileges Specifies the auditing privileges for the user.
Superusers and system administrators
cannot modify their own extended
privileges.
• None: The user cannot configure auditing,
view audit trails, or purge audit trails.
• Config audit: The user can configure
auditing.
• Purge audit: The user can purge existing
audit trails.
• Config and Purge Audit: The user can
configure auditing and purge existing
audit trails.
• View Audit: The user can view audit trails.
• Config and View Audit: The user can
configure auditing and view existing
audit trails.
• View and Purge Audit: The user can view
existing audit trails and purge them.
• Config, View, and Purge Audit: The user
can configure auditing and view and
purge existing audit trails.
Client Capability Describes the expertise level of the user.

The client capability setting is used by

Documentum client products to determine
which functionality to deliver to the user.
Documentum Server does not recognize or
use the client capability setting. The
Documentum client documentation contains
the information on the client features
available with each setting.

Choose a user type from the list:

• Consumer
• Contributor
• Coordinator
• System Administrator

Alias Set The default alias set for the user. Click Select
to specify an alias set.
Disable Workflow Indicates whether a user can receive
workflow tasks.
Disable Authentication Failure Checking If selected, user can exceed the number of
failed logins specified in the Maximum
Authentication Attempts field of the
repository configuration object.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 211

Chapter 11 User Management

Documentum Administrator User Guide contains the instructions on creating or

modifying user accounts.

11.2.3 Creating global users

A global user is a repository user who is found in all members of a repository
federation and whose attribute values are the same in all of the repositories. Global
users are managed through the governing repository. If you add a global user to the
governing repository, that user is added to all the member repositories by a
federation job that synchronizes the repositories.

To create a global user, connect to the governing repository of a federation and

create the user there. On the New User - Info page, select User is global to make the
user global.

Connect to the governing repository to modify the attributes of a global user.

Global users can also have local attributes, which you can modify in a local
repository.

11.2.4 Setting default permissions for folders and cabinets

When you create a new user, you assign the user a default folder. Documentum
Administrator allows you to select between assigning an existing folder as the
default folder or creating a folder with the name of user. If you have Documentum
Administrator create the folder for a new user and you can control the permissions
assigned to folder.

To set default permissions for folders:

1. Create a alias set called UserPropertiesConfiguration.

2. Assign ownership of the UserPropertiesConfiguration alias set to the repository
owner.
This is the user whose account is used for database access (dm_dbo).
3. Create two aliases in UserPropertiesConfiguration.

• DefaultFolderAcl
Point this alias to the permission set to be applied to the new folder created
for new users.
• DefaultFolderAclDomain
Point this alias to the user who owns the permission set you use for the
DefaultFolderAcl alias.

When you add a user, Documentum Administrator applies the permission set you
designate to the new folder. If a new user is not present as an accessor in the
permission set, the user is granted write permission on the folder. The permission
set for the folder is then modified to a system-generated permission set, but it
otherwise has the permissions from the permission set you created.

212 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.2. Users

You can use Documentum Administrator to create a default folder for an existing
user and permissions on the set are applied if you have created the necessary alias
set and aliases.

If the UserPropertiesConfiguration alias set does not exist and a superuser creates
the user, the user owns the folder and has delete permission. If a system
administrator creates the user, the user is not the owner of the default folder, but the
user has change owner permission on the folder as well as write permission.

11.2.5 Importing users

You can create repository users from information contained in an input file. Before
you begin importing users, determine the following:

• Authentication type
If the server authenticates users against the operating system, each user must
have an account on the server host. If the server uses an LDAP directory server
for user authentication, the users do not need to have operating system accounts.
• Groups and ACLs
If you specify the attributes user_group (the default group of user) and acl_name
(the default permission set of user), any groups and permission sets must already
exist before you import the users.
• Passwords
If you are creating a user who is authenticated using a password stored in the
repository, the password cannot be assigned in the input file. You must assign
the password manually by modifying the user account after the user has been
imported..

Table 11-4: Import user properties

Field label Value

State Indicates the state of user in the repository.
Select one of the following:
• Active: The user is a currently active
repository user. Active users are able to
connect to the repository.
• Inactive: The user is not currently active in
the repository. Inactive users are unable
to connect to the repository.

If the user is a superuser, only another

superuser can reset the state.
Source The name of an input file. Click Browse to
browse to the location of the LDIF file
containing information for creating the new
users.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 213

Chapter 11 User Management

Field label Value

User Source Specifies how to authenticate user name and
password of a given repository user. Valid
values are:
• None: Windows only. This means the user
is authenticated in a Windows domain.
• UNIX only: The user is authenticated
using the default Linux mechanism,
dm_check_password or other external
password checking program. This option
only displays on Linux hosts.
• Domain only: The user is authenticated
against a Windows domain. This option
only displays on Linux hosts.
• UNIX first: This is used for Linux
repositories where Windows domain
authentication is in use. This option only
displays on Linux hosts.
The user is authenticated first by the
default Linux mechanism. If the
authentication fails, the user is
authenticated against a Windows
domain.
• Domain first: This is used for Linux
repositories where Windows domain
authentication is in use. This option only
displays on Linux hosts.
The user is authenticated first against a
Windows domain; if that fails, the user is
authenticated by the default Linux
mechanism.
• LDAP: The user is authenticated through
an LDAP directory server.
Description A description of the user account.
E-Mail Address The E-mail address of the user. This is the E-
Mail address to which notifications are sent
for workflow tasks and registered events.
Windows Domain (Windows only) The domain name
associated with the Windows account of new
user.
Home Repository The repository where the user receives
notifications and tasks.
User is global If the user is created in the governing
repository of a federation, select this option
to propagate the user account to all members
of the federation.

214 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.2. Users

Field label Value

Default Folder The default storage place for any object the
user creates. Click Select to assign a folder.
Default Group The group that is associated with the default
permission set of the user. Click Select to
specify a default group.

When the user creates an object in the

repository, it automatically belongs to this
group.
Default ACL The permission set that assigns the default
permissions to objects the user creates. Click
Select to specify a default permission set.
Db Name The user name of the user in the underlying
RDBMS. The DB Name is only required if the
user is a repository owner or a user who
registers RDBMS tables.
Privileges The privileges that are assigned to the user.

User privileges authorize certain users to

perform activities in the repository. Select
one of the privileges from the drop-down
list, as follows:
• None
• Create Type
• Create Cabinet
• Create Cabinet and Type
• Create Group
• Create Group and Type
• Create Group and Cabinet
• Create Group, Cabinet, and Type
• System Administrator
• Superuser: If you grant superuser
privileges to a user, add that user
manually to the group called
admingroup. If you revoke the superuser
privileges of a user, remove the user from
the admingroup.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 215

Chapter 11 User Management

Field label Value

Client Capability Indicates what expertise level of the user.
This option is for informative purposes only
and is not associated with any privileges.
Documentum Server does not recognize or
enforce these settings.

Choose a user type from the list:

• Consumer
• Contributor
• Coordinator
• System Administrator

Alias Set The default alias set for the user. Click Select
to specify an alias set.
If user exists, then overwrite user Select this option if a user already exists in
information the repository and you want to replace
existing information with the imported
information.
If user exists, then ignore information Select this option if a user already exists in
the repository and you want to retain the
existing information.

Documentum Administrator User Guide contains the instructions on importing new

users.

11.2.5.1 Import file format

You can create repository users from information contained in an input file.

Each imported user starts with the header object_type:dm_user. Follow the header
with a list of attribute_name:attribute_value pairs. The attributes user_name and
user_os_name are required. In addition, the following default values are assigned
when the LDIF file is imported:

Table 11-5: Default values for new users

Argument Default
user_login_name username
privileges 0 (None)
folder /username
group docu
client_capability 1

Each attribute_name:attribute_value pair must be on a new line. For example:

216 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.2. Users

object_type:dm_user
user_name:Pat Smith
user_group:accounting
acl_domain:smith
acl_name:Global User Default ACL
object_type:dm_user
user_name:John Brown

If the ldif file contains umlauts, accent marks, or other extended characters, store the
file as a UTF-8 file, or users whose names contain the extended characters are not
imported.

The attributes you can set through the LDIF file are:
user_name
user_os_name
user_os_domain
user_login_name
user_login_domain
user_password
user_address
user_db_name
user_group_name
user_privileges (set to integer value)
default_folder
user_db_name
description
acl_domain
acl_name
user_source (set to integer value)
home_docbase
user_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)

You can specify as many of the attributes as you wish, but the attribute_names must
match the actual attributes of the type.

The attributes may be included in any order after the first line
(object_type:dm_user). The Boolean attributes 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
the file to import the users. Additionally, the ACLs must represent system ACLs.
They cannot represent private ACLs.

Any groups that you identify by user_group_name must exist before you run the file
to import the users.

Documentum Server creates the default folder for each user if it does not already
exist.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 217

Chapter 11 User Management

11.2.6 Deleting users

You can remove users from the repository, but Documentum strongly recommends
making users inactive or reassigning them rather than deleting them from the
repository.

When you delete a user, the server does not remove the users name from objects in
the repository such as groups and ACLs. Consequently, when you delete a user, you
must also remove or change all references to that user in objects in the repository.

You can delete a user and then create a user with the same name. If you add a new
user with the same name as a deleted user and have not removed references to the
deleted user, the new user inherits the group membership and object permissions
belonging to the deleted user.

You cannot delete the repository owner, installation owner, or yourself.

Documentum Administrator User Guide contains the instructions on deleting users.

11.2.7 Reassigning objects to another user

If you want to delete a user from the repository, make the user inactive, or rename a
user, you can assign objects owned by that user to another user. For example, to
change the user name of a particular user, you have to create a new user and assign
the objects that belonged to the old user name to the new user.

Documentum Administrator User Guide contains the instructions on reassigning

objects to another user.

11.2.8 Changing the home repository of a user

The home repository is where users receive tasks and notifications in their inboxes.

Documentum Administrator User Guide contains the instructions on changing the

home repository of a user.

11.2.9 Activating or deactivating a user account

Changing a user account from active to inactive is an alternative to deleting the user
from the repository. If the account is a superuser account, only another superuser
can reset the account.

Documentum Administrator User Guide contains the instructions on changing a user

from active to inactive or inactive to active.

218 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.3. Groups

11.2.10 Viewing groups, workflows, alias sets, permission sets,

and documents of a user
You can determine the groups to which a user belongs.

Documentum Administrator User Guide contains the instructions on viewing the

groups, workflows, permission sets, alias sets, or documents of a user.

11.2.11 Viewing or deleting change home repository logs

You can view or delete the logs generated by changing the home repository of user.

Documentum Administrator User Guide contains the instructions on viewing or

deleting change home repository logs.

11.2.12 Viewing user reassign logs

You can view or delete the logs generated by reassigning objects of user to another
user.

Documentum Administrator User Guide contains the instructions on viewing the user
reassign logs.

11.2.13 Reassign reports

This page displays reassign logs, including group and user reassign logs.

11.3 Groups
A group represents multiple repository users, and can contain groups, users, or
roles. By default, a group is owned by the user who creates the group. Groups can
be public or private. By default, groups created by a user with Create Group
privileges are private, while groups created by a user with system administrator or
superuser privileges are public.

A group can be a dynamic group. A dynamic group is a group, of any group class,
whose list of members is considered a list of potential members.

To create or modify groups, you must have privileges as shown in the following
table:

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 219

Chapter 11 User Management

Table 11-6: Privileges for creating or modifying groups

Privilege Create Modify Delete

Create Group Can create group or Can add or delete Can delete groups
assign ownership to a members and assign the user owns,
group to which the ownership to a group including groups
user belongs. to which the user where a group is
belongs. owner and the user is
a member of the
group.
System administrator Can create group or Can update the Can delete groups
assign ownership to a group the system the system
group to which the administrator owns, administrator owns,
user belongs. including groups including groups
where a group is where a group is
owner and the owner and the
system administrator system administrator
is a member of the is a member of the
group. group.
Superuser Can create a group Can update group Can delete any
and assign administrator, owner, group.
ownership to a or members of a
different user or group.
group.

A group can own SysObjects and permission sets.

The name assigned to a group must consist of characters that are compatible with
the Documentum Server OS code page.

If you create a role as a domain, it is listed on the groups list, not the roles list.

To jump to a particular group, type the first few letters of its object name in the
Starts with box and click Search. To view a list of all groups beginning with a
particular letter, click that letter. To view a different number of groups than the
number currently displayed, select a different number in the Show Items list.

To view the members of a group, click the group name.

220 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.3. Groups

11.3.1 Dynamic groups

A dynamic group is a group, of any group class, whose list of members is
considered a list of potential members. A dynamic group is created and populated
with members like any other group. Whether or not a group is dynamic is part of the
groups definition. It is recorded in the is_dynamic attribute and can be changed after
the group is created. (In this application, is_dynamic is the field labeled Dynamic
Group.

When a session is started, whether Documentum Server treats a user in a dynamic

group as an actual 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 group

You can use dynamic groups to model role-based security. For example, suppose
you define a dynamic group called EngrMgrs. Its default membership behavior is to
assume that users are not members of the group. The group is granted the privileges
to change ownership and change permissions. When a user in the group accesses the
repository from a secure application, the application can issue the session call to add
the user to the group. If the user accesses the repository from outside your firewall
or from an unapproved application, no session call is issued and Documentum
Server does not treat the user as a member of the group. The user cannot exercise the
change ownership or change permissions permits through the group.

11.3.2 Privileged groups

Installing Documentum Server installs a set of privileged groups. Members of
privileged are allowed to perform privileged operations even though the members
do not have the privileges as individuals. The privileged groups are divided into
two sets.

The first set of privileged groups are used in applications or for administration
needs. With two exceptions, these privileged groups have no default members when
they are created. You must populate the groups. The following table describes these
groups.

Table 11-7: Privileged groups

Group Description
dm_browse_all Members of this group can browse any
cabinets and folders in the repository, folders
except the rooms that were created using
Documentum Collaborative Services (DCS).

The dm_browse_all_dynamic is a member of

this group by default.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 221

Chapter 11 User Management

Group Description
dm_browse_all_dynamic This is a dynamic role group whose members
can browse any object in the repository. The
dm_browse_all_dynamic group is a member
of the dm_browse_all group.
dm_escalated_allow_save_on_lock Used internally for RPS.

Created and managed by superusers only.

Members of this group can modify and save
changes to an object that is checked out by
other users.
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 the repository.

Note: Adding an user to the

dm_superusers privilege group does
not offer superuser privileges to that
user until a particular DFC API is
called. Also, calling that API offers the
privileges to the user only for that
session and it is not permanent.

The dm_superusers_dynamic group is a

member of this group by default.
dm_superusers_dynamic A dynamic role group whose members are
treated as superusers in the repository. The
dm_superusers_dynamic group is a member
of the dm_superusers group.
dm_sysadmin Members of this group are treated as users
with system administrator user privileges.
dm_create_user Member of this group have Create User user
privilege.

222 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.3. Groups

Group Description
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 cannot 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

11.3.3 Locating groups

You can locate groups in a repository.

Documentum Administrator User Guide contains the instructions on locating groups.

11.3.4 Viewing group memberships

You can view where a group is used.

Documentum Administrator User Guide contains the instructions on viewing group

memberships.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 223

Chapter 11 User Management

11.3.5 Creating, viewing, or modifying groups

You can create a group or view and modify group properties on the Info tab of the
New Group and Group properties pages.

Table 11-8: Group properties

Field label Value

Name The name of the repository group.
Group Native Room The native room of group. This field appears
only if the rooms feature of Collaborative
Services is enabled.
E-Mail Address The email address for the new group.

If no value is entered in this field, the group

email address defaults to the group name.
Owner The name of a repository user who has the
Create Group privilege and who owns this
group.

If you are a superuser, you can select the

owner. Otherwise, you can set this to a group
of which you are a member.
Administrator Specifies a user or group, in addition to a
superuser or the group owner, who can
modify the group. If this is null, only a
superuser and the group owner can modify
the group.

Only a superuser and the group owner can

change the administrator of a group.
Alias Set The default alias set for the group.
Group is Global Displayed only in the governing repository
of a federation and the group must be a
global group.
Description A description of the group.

224 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.3. Groups

Field label Value

Private Defines whether the group is private. If not
selected, the group is created as a public
group.

A group with Private enabled can be

updated only by a user who is the owner of
the group or is listed as the group
administrator of the group.

A group with Private not enabled can be

updated by a user with system administrator
privileges as well as by the group owner or
administrator.

A superuser can update any group,

regardless if Private is enabled or not.
Dynamic Indicates if the group is a dynamic group. A
dynamic group is a group, of any group
class, whose list of members is considered a
list of potential members. User membership
is controlled on a session-by-session basis by
the application at runtime. The members of a
dynamic group comprise of the set of users
who are allowed to use the group; but a
session started by one of those users will
behave as though it is not part of the group
until it is specifically requested by the
application.
Protected Indicates if the group is protected against
adding or deleting members. Use of a
protected dynamic group is limited to
applications running with a DFC installation
that has been configured as privileged
through the Documentum Administrator
client rights administration.

The Protected checkbox is enabled only

when Dynamic Group is selected.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying groups.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 225

Chapter 11 User Management

11.3.6 Adding users, groups, or roles to a group

A group can contain users, other groups, or roles. You can add users, groups, or
roles to a group.

Documentum Administrator User Guide contains the instructions on adding users to a

group.

11.3.7 Removing users from a group

You can remove users from a group.

Documentum Administrator User Guide contains the instructions on removing users

from a group.

11.3.8 Deleting groups

You can delete a group if you are the owner of group, a superuser, a member of the
group that owns the group to be deleted, or identified in the group_admin attribute
of group, either as an individual or as a member of a group specified in the attribute.
However, to preserve repository consistency, do not remove groups from the
repository. Instead, remove all members of the group and leave the group in the
repository, or reassign all objects owned by the group to another group or user and
then delete the group.

Documentum Administrator User Guide contains the instructions on deleting a group.

11.3.9 Reassigning the objects owned by a group

You can reassign the objects owned by a group to another group.

Documentum Administrator User Guide contains the instructions on reassigning a

group.

11.3.10 Viewing group reassign logs

You can view or delete the logs generated by reassigning the members of a group to
another group.

Documentum Administrator User Guide contains the instructions on viewing group

reassign logs.

226 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.4. Roles

11.4 Roles
A role is a type of group that contains a set of users or other groups that are assigned
a particular role within a client application domain.

If you create a role as a domain, it is listed in the groups list, not the roles list.

11.4.1 Creating, viewing, or modifying roles

You can create, view, or modify roles.

Table 11-9: Role properties

Field label Value

Name The name of the repository role.
Group Native Room The native room for the role. The field
appears only if the rooms feature of
Collaborative Services is enabled.
E-Mail Address The email address for the new role. This is
typically the email address of the owner of
role.

If no value is entered in this field, the role

email address defaults to the role name.
Owner The name of a repository user who has the
Create Group privilege and who owns this
role.
Administrator Specifies a user or group, in addition to a
superuser or the role owner, who can modify
the role. If this is null, only a superuser and
the role owner can modify the role.
Alias Set The default alias set for the role.
Role Is Global If the role is being created in the governing
repository of a federation, select to propagate
the attributes of role to all members of the
federation.
Description A description of the role.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 227

Chapter 11 User Management

Field label Value

Private Defines whether the role is private. If not
selected, the role is created as a public role.

A role with Private enabled can be updated

only by a user who is the owner of the role or
is listed as the roll administrator. A role with
Private not enabled can be updated by a user
with system administrator privileges as well
as by the role owner or administrator. A
superuser can update any role, regardless if
Private is enabled or not.

By default, roles created by users with

System Administration or superuser
privileges are public, and roles created by
users with a lower user privilege level are
private.
Create role as domain Select to create a dm_group object with
group_class as domain.

This field only appears on the New Role -

Info page.
Dynamic Indicates if the role a dynamic role. A
dynamic role is a role whose list of members
is considered a list of potential members.
User membership is controlled on a session-
by-session basis by the application at
runtime. The members of a dynamic role
comprise of the set of users who are allowed
to use the role; but a session started by one of
those users will behave as though it is not
part of the role until it is specifically
requested by the application.
Protected Indicates if the role is protected against
adding or deleting members. Use of a
protected dynamic role is limited to
applications running with a DFC installation
that has been configured as privileged
through the Documentum Administrator
client rights administration.

The Protected checkbox is enabled only

when Dynamic Role is selected.

Documentum Administrator User Guide contains the instructions on creating roles.

228 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.5. Modules roles

11.4.2 Adding users, groups, or roles to a role

You can add users, groups, or roles to a role.

Documentum Administrator User Guide contains the instructions on adding users,

groups, or roles to a role.

11.4.3 Reassigning roles

If you plan to delete a role, consider reassigning the users and other objects
belonging to the role. You can reassign the users and other objects.

Documentum Administrator User Guide contains the instructions on reassigning a role.

11.4.4 Deleting roles

Roles are a type of group. It is therefore recommended that you do not delete a role.
Instead, remove all members of the role and leave the role in the repository. You can
also reassign the members of the role to another role.

Documentum Administrator User Guide contains the instructions on deleting a role.

11.5 Modules roles

Module roles are required by applications that run privileged escalations and they
behave the same as roles with respect to memberships. Module roles are dm_group
objects with group_class set to module role. Any user, group, or dynamic group can
be a member of a module role.

By default, module roles are dynamic. A dynamic module role is a role whose list of
members is considered a list of potential members. User membership is controlled
on a session-by-session basis by the application at runtime. The members of a
dynamic module role comprise of the set of users who are allowed to use the
module role; but a session started by one of those users will behave as though it is
not part of the module role until it is specifically requested by the application.
Administrators should not modify module roles unless they are configuring a client
that requires privileged escalations.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 229

Chapter 11 User Management

11.5.1 Creating, viewing, or modifying module roles

You can create new module roles.

Table 11-10: Module role properties

Field label Value

Name The name of the repository module role.
Group Native Room The native room for the module role. The
field appears only if the rooms feature of
Collaborative Services is enabled.
E-Mail Address The email address for the module role.

If no value is entered in this field, the module

role email address defaults to the module
role name.
Owner The name of a repository user who has the
Create Group privilege and who owns this
module role.
Administrator Specifies a user or group, in addition to a
superuser or the module role owner, who
can modify the module role. If this is null,
only a superuser and the module role owner
can modify the module role.
Alias Set The default alias set for the module role.
Module Role is Global If the module role is being created in the
governing repository of a federation, select to
propagate the attributes of module role to all
members of the federation.
Description A description of the module role.
Private Defines whether the module role is private. If
not selected, the module role is created as a
public module role.

A module role with Private enabled can be

updated only by a user who is the owner of
the role or is listed as the roll administrator.
A module role with Private not enabled can
be updated by a user with system
administrator privileges as well as by the
role owner or administrator. A superuser can
update any module role, regardless if Private
is enabled or not.
Protected Select to restrict the module role to be used
only by applications running on a privileged
client.

230 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.6. Sessions

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying module roles.

11.5.2 Reassigning module roles

If you plan to delete a module role, consider reassigning the users and other objects
belonging to the module role. You can reassign the users and other objects.

Documentum Administrator User Guide contains the instructions on reassigning

module roles.

11.5.3 Deleting module roles

Module roles are a type of group. It is therefore recommended that you do not delete
a module role. Instead, remove all members of the module role and leave the
module role in the repository. You can also reassign the members of the module role
to another module role.

Documentum Administrator User Guide contains the instructions on deleting module

roles.

11.6 Sessions
A repository session is opened when an end user or application establishes a
connection to a server. Each repository session has a unique ID.

During any single API session, an external application can have multiple repository
sessions, each with a different repository or server or both.

A repository session is terminated when the end user explicitly disconnects from the
repository or the application terminates.

You can use Documentum Administrator to monitor repository sessions only. It

cannot monitor any other sessions (for example, eConnector for JDBC sessions).

The Sessions page lists sessions in the current repository. For each session, the name,
Documentum Session ID, Database Session ID, Client Host, Start Time, time Last
Used, and State are displayed. To view all sessions or user sessions, make a selection
from the drop-down list. To view a different number of sessions, select a new
number from the Show Items drop-down list. To view the next page of sessions,
click the > button. To view the previous page of sessions, click the < button. To jump
to the first page of sessions, click the << button. To jump to the last page, click>>.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 231

Chapter 11 User Management

11.6.1 Viewing user sessions

You can view user sessions and details of user sessions. User session information
that can be viewed includes the root process start time, root process ID, session ID,
client library version, and how the user is authenticated.

Documentum Administrator User Guide contains the instructions on viewing user

sessions.

11.6.2 Viewing user session information

You can view information about user sessions.

Table 11-11: Session information

Field Description
Root Process Start Date The last start date for the server to which the
session is connected
Root Process ID The process ID of the server on its host
User Name The session user
Client Host The host from which the session is connected
Session ID The ID of the current repository session
Database Session ID The ID of the current database session
Session Process ID The operating system ID of the current
session process
Start Time The time the session was opened
Last Used The time of the last activity for the session
Session Status The status of the current session
Client Library Version The DMCL version in use
User Authentication The authentication type
Shutdown Flag An internal flag
Client Locale The preferred locale for repository sessions
started during an API session

Documentum Administrator User Guide contains the instructions on viewing user

session information.

232 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 11.6. Sessions

11.6.3 Viewing user session logs

You can view user session logs. Session logs provide information about the actions
performed in a session.

Documentum Administrator User Guide contains the instructions on viewing user

session logs.

11.6.4 Killing user sessions

You can kill user sessions.

Documentum Administrator User Guide contains the instructions on killing user

sessions.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 233

Chapter 12
Security and Authentication

12.1 Object permissions

Access to folders and documents in a repository is subject to security restrictions of
an organization. All content in the repository is associated with object permissions,
which determines the access users have to each object in the repository such as a file,
folder, or cabinet and governs their ability to perform specific actions. There are two
categories of object permissions:

• Basic: Required for each object in the repository

• Extended: Optional

Basic permissions grant the ability to access and manipulate content of an object. The
seven basic permission levels are hierarchical and each higher access level includes
the capabilities of the preceding access levels. For example, a user with Relate
permission also has Read and Browse.

Table 12-1: Basic permissions

Basic permission Description

None No access to the object is permitted.
Browse Users can view the properties of object but
not the content of object.
Read Users can view both the properties and
content of the object.
Relate Users can do the above and add annotations
to the object.
Version Users can do the above and modify the
content of object and check in a new version
of the item (with a new version number).
Users cannot overwrite an existing version or
edit the properties of item.
Write Users can do the above and edit object
properties and check in the object as the
same version.
Delete Users can do all the above and delete objects.

Extended permissions are optional, grant the ability to perform specific actions
against an object, and are assigned in addition to basic permissions. The six levels of
extended permissions are not hierarchical, so each must be assigned explicitly. Only
system administrators and superusers can grant or modify extended permissions.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 235

Chapter 12 Security and Authentication

Table 12-2: Extended permissions

Extended permission Description

Execute Procedure Superusers can change the owner of an item
and use Execute Procedure to run external
procedures on certain object types. A
procedure is a Docbasic program stored in
the repository as a dm_procedure object.
Change Location Users can move an object from one folder to
another in the repository. A user also must
have Write permission to move the object. To
link an object, a user also must have Browse
permission.
Change State Users can change the state of an item with a
lifecycle applied to it.
Change Permission Users can modify the basic permissions of an
object.
Change Ownership Users can change the owner of the object. If
the user is not the object owner or a
superuser, they also must have Write
permission.
Delete Object Users can only delete the object. For
example, you may want a user to delete
documents but not read them. This is useful
for Records Management applications where
discrete permissions are common.
Change Folder Links Users can link or unlink an object to the
folder in the repository.

When a user tries to access an object, Documentum Server first determines if the
user has the necessary level of basic permissions. If not, extended permissions are
ignored.

Permission sets (also known as access control lists, or ACLs) are configurations of
basic and extended permissions assigned to objects in the repository that lists users
and user groups and the actions they can perform. Each repository object has a
permission set that defines the object-level permissions applied to it, including who
can access the object. Depending on the permissions, users can create new objects;
perform file-management actions such as importing, copying, or linking files; and
start processes, such as sending files to workflows.

Each user is assigned a default permission set. When a user creates an object, the
repository assigns the default permission set of user to that object. For example, if
the default permission set gives all members of a department Write access and all
other users Read access, then those are the access levels assigned to the object.

Users can change access levels of object by changing the permission set of an object.
To do this, the user must be the owner of object (typically the owner is the user who
created the object) or they must have superuser privileges in the repository of object.

236 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.1. Object permissions

When a user modifies a permission set, it is saved as a permission set assigned to

them. They can then apply the permission set to other objects in the repository.

The ability to modify permission sets depends on the user privileges in the
repository:

• Users with superuser privileges can modify any permission set in the repository.
They can designate any user as the owner of a permission set, and change the
owner of a permission set. This permission is usually assigned to the repository
administrator.
• Users with system administrator privileges can modify any permission set
owned by them or by the repository owner. They can designate themselves or the
repository owner as the owner of a permission set they created and can change
whether they or the repository owner owns the permission set. This permission
is usually assigned to the repository administrator.
• Users with any privileges less than the superuser or system administrator
privileges are the owner only of the permission sets they create. They can modify
any permission set they own, but cannot change the owner of the permission set.

If you designate the repository owner as the owner of a permission set, that
permission set is a System (or Public) permission set. Only a superuser, system
administrator, or the repository owner can edit the permission set. If a different user
is the owner of the permission set, it is a Regular (or Private) permission set. It can
be edited by the owner, a superuser, system administrator, or the repository owner.

A user with Write or Delete permission can change which permission set is assigned
to an object.

Security protects the information in each repository using object permissions to

control access to cabinets, folders, documents, and other objects. Object permissions
determine what actions users can perform on objects. Permissions can be added,
removed, modified, or replaced, and set differently for different users.

If you use Documentum Web Publisher and if the user does not assign the default
permission set, the Documentum Server assigns a default permission set according
to the setting in the default_acl property in the server configuration object.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 237

Chapter 12 Security and Authentication

12.2 Changing default operating system permits on

public directories and files (Linux only)
On Linux platforms, Documentum Server assigns default operating system
permissions to newly created files and directories. For example, when DFC creates
directories on the client machines or writes files to directories on the client machines,
it assigns default operating system permissions to those directories and files.

Internally, Content Cerver refers to permissions with the symbolic names

dmOSFSAP_Public, dmOSFSAP_Private, dmOSFSAP_Public ReadOnly,
dmOSFSAP_PrivateReadOnly, and dmOSFSAP_PublicOpen. The
dmOSFSAP_PublicOpen permissions assigned to public directories and files can be
modified using the umask key in the server.ini file. Setting umask affects all public
directories and files created after the key is set. By default the
dmOSFSAP_PublicOpen permissions are 777 for directories and 666 for files.

The “umask” on page 83 section contains more information on unmask key.

12.3 Folder security

Folder security is an additional level of security that supplements the existing
repository security. Implementing this security option further restricts allowable
operations in a repository. Folder security prevents unauthorized users from adding
documents to, removing documents from, or changing contents of secured folders.
When folder security is enabled, a user must have Write permission or Change
Folder Links permission for the:

• Target folder to create, import, copy, or link an object into the folder.
• Source folder to move or delete an object from a folder.

Folder security only pertains to changing the contents in a folder. For example, a
user with Browse permission on a folder can still check out and check in objects
within the folder.

If you use Documentum Web Publisher, and if folder security is used in a repository,
any content files in the WIP state must have the same permission as the folder. To
use the same folder permission, the administrator must ensure the lifecycle in WIP
state does not apply any set ACL action. For example:
WIP - folder acl
Staging - WP "Default Staging ACL"
Approved - WP "Default Approved ACL"

The following table lists the actions affected by folder security.

238 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.4. Additional access control entries

Table 12-3: Permissions required under folder security

Action Requires at least Write or Change Folder

Links permission for:
Create an object Cabinet or folder in which you create the
new object
Import file(s) or folder Cabinet or folder to which you import the
file(s) or folder
Move an object Both the cabinet or folder from which you
remove the object and the destination folder
or cabinet
Copy an object Destination cabinet or folder
Link an object Destination cabinet or folder
Unlink an object Cabinet or folder from which you unlink the
object
Delete one version of a document The primary folder of document
Delete all versions of a document The primary folder of document
Delete unused versions of a document The primary folder of document

Consult the repository administrator to determine if folder security is enabled in the

repository.

12.4 Additional access control entries

When Trusted Content Services is enabled in a repository, additional access control
entries are available. Set up the additional access control entries on the Permissions
page under the Security node. The access control entries described in the following
table are independent of each other, not hierarchical, and must be explicitly
assigned.

Table 12-4: Additional access control entries

Access control entry Effect of the entry

Access Restriction An access restriction entry denies a user the
right to the base object-level permission level
specified in the entry. For example, if a user
would otherwise have Delete permission as a
member of a particular group, an access
restriction might limit the user to, at most,
Version permission. The user would
therefore lose Write and Delete permissions.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 239

Chapter 12 Security and Authentication

Access control entry Effect of the entry

Extended Restriction An extended restriction entry denies a user
or the members of a specified group the
specified extended object-level permission.
For example, if a user would otherwise have
Change Permission rights as a member of a
particular group, an extended restriction
would remove that right.
Required Groups A required group entry requires a user
requesting access to an object governed by
the permission set to be a member of the
group identified in the entry. If there are
entries for multiple groups, the user must be
a member of all the groups before
Documentum Server allows access to the
object.
Required Group Set A required group set entry requires a user
requesting access to an object governed by
the permission set to be a member of at least
one group in the set of groups.

12.5 Default alias sets

The Documentum Server adds two default aliases to a permission set:

• dm_owner: Represents the owner of the permission set.

• dm_world: Represents all repository users.

Notes

• You cannot delete dm_owner or dm_world aliases from a permission set.

• dm_owner and dm_world are just containers used by server to determine
the permissions defined for owners and other users in the repository. This is
internal to DFC and server and any end user application should not use
them to set permits for ACLs.

12.6 Access evaluation process

When a user who is not the owner of the object or a superuser requests access to an
object, Documentum Server evaluates the entries in the permission set of the object,
as follows:

1. Checks for a basic access permission or extended permission entry that gives the
user the requested access level (Browse, Read, Write, and so forth)

Note: Users are always granted Read access if the user owns the document,
regardless of whether there is an explicit entry granting Read access or not.

240 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.6. Access evaluation process

2. Checks for no access restriction or extended restriction entries that deny the user
access at the requested level.
A restricting entry, if present, can restrict the user specifically or can restrict
access for a group to which the user belongs.
3. If there are required group entries, the server checks that the user is a member of
each specified group.
4. If there are required group set entries, the server checks that the user is a
member 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 of any required groups or groups sets, the user is granted access at the
requested level.

When a user is the object owner, Documentum Server evaluates the entries in the
permission set of object in the following manner:

1. Checks if 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
is allowed only Read permission as their default base permission, but is not
granted any extended permissions.
2. Determines what base and extended permissions are granted to the owner
through entries for dm_owner, the owner specifically (by name), or through
group membership.
3. 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 base and extended permissions of owner.

• If there are no restrictions on the base permissions of the owner and the
dm_owner entry does not specify a lower level, the owner has Delete
permission by default.
• If there are restrictions on the base permission of the owner, the owner has
the permission level allowed by the restrictions. However, an owner will
always have at least Browse permission; they cannot be restricted to None
permission.
• If there are no restrictions on the extended permissions of owner, they have,
at minimum, all extended permissions except delete_object by default. The
owner may also have delete_object if that permission was granted to
dm_owner, the user specifically (by name), or through a group to which the
owner belongs.
• If there are restrictions on the extended permissions of owner, then the
extended permissions of owner are those remaining after applying the
restrictions.

When Documentum Server evaluates the access of superuser to an object, the server
does not apply AccessRestriction, ExtendedRestriction, RequiredGroup, or
RequiredGroupSet entries to the superuser. A base permission of superuser is

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 241

Chapter 12 Security and Authentication

determined by evaluating the AccessPermit entries for the user, for dm_owner, and
for any groups to which the user belongs. The superuser is granted the least
restrictive permission among those entries. If that permission is less than Read, it is
ignored and the superuser has Read permission by default.

The extended permissions of a superuser are all extended permits other than
delete_object plus any granted to dm_owner, the superuser by name, or to any
groups to which the superuser belongs. This means that the extended permissions of
superuser may include delete_object if that permit is explicitly granted to
dm_owner, the superuser by name, or to groups to which the superuser belongs.

12.7 Permission sets

Permission sets are displayed on the Permission Sets page and are accessed by
selecting Administration > Security. The Permission Sets page displays all
permission sets that are configured for the repository.

Table 12-5: Permissions Sets page

Column Description
Name The object name of the permission set.
Owner The user or group that owns the permission
set.
Class Specifies set how the permission set is used:
• Regular: The permission set can only be
used by the owner.
• Public: The permission set can be used by
any user.
Description A description of the permission set.

12.8 Authenticating in domains

For domain authentication on Windows platforms, Documentum Server
authenticates user names and passwords within a domain. The user domain is
stored in the user_os_domain property of the user object. A default domain is
defined for all users in the repository in the user_auth_target key of the server.ini
file.

Whether the server uses the user-specific domain or the default domain for
authentication depends on whether the server is running in domain-required mode.
By default, the Documentum Server installation procedure installs a repository in
no-domain required mode. If a Windows configuration has only users from one
domain accessing the repository, the no-domain required mode is sufficient. If the
users accessing the repository are from varied domains, using domain-required
mode provides better security for the repository.

242 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.9. Principal authentication

12.8.1 No-domain required mode

In no-domain required mode, users are not required to enter a domain name when
they connect to the repository. In this mode, a user name must be unique among the
user_os_name values in the repository.

The server authenticates users depending on the user_os_domain property value.

The property can contain an asterisk (*), a blank, or a domain name.

• If user_os_domain contains an asterisk or blank, Documentum Server

authenticates the user with the user name and the domain specified in the
connection request. If no domain is included in the connection request, the server
uses the domain defined in the user_auth_target key in the server.ini file.
• If user_os_domain contains a domain name, Documentum Server authenticates
against the domain identified in the user_os_domain property.

12.8.2 Domain-required mode

In domain-required mode, users must enter a domain name or the name of an LDAP
server when they connect to the repository. The domain value is defined when the
user is created and is stored in the user_login_domain property in the user object.

In domain-required mode, the combination of the login name and domain or LDAP
server name must be unique in the repository. It is possible to have multiple users
with the same user login name if each user is in a different domain.

Trusted logins do not require a domain name even if the repository is running in
domain-required mode.

12.9 Principal authentication

Some applications require authenticating users with external authentication
mechanisms that are not accessible to Documentum Server. For these cases,
Documentum Server supports principal authentication and principal mode for
privileged DFC clients (trusted clients). Principal mode is a DFC mechanism that
allows trusted clients to log in to Documentum Server without having to go through
another password authentication process.

Privileged DFC provides a client rights domain that is implemented using a client
rights domain object (dm_client_rights_domain). The client rights domain contains
the Documentum Servers that share the same set of client rights objects
(dm_client_rights). The client rights domain is configured in a global repository that
acts as a governing repository. Multiple repositories can be grouped together under
the global repository to share privileged DFC information. The global repository
propagates all changes in the client rights objects to the repositories that are
members of the domain.

Privileged DFC is configured using the Documentum Administrator interface.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 243

Chapter 12 Security and Authentication

12.9.1 Client rights domains

A client rights domain contains the Documentum Servers that share the same set of
client rights objects. The client rights domain is configured in a global repository that
acts as a governing repository. Multiple repositories can be grouped together under
the global repository to share privileged DFC information.

Privileged DFC is the term used to refer DFC instances that can invoke escalated
privileges or permissions for a particular operation. For example, privileged DFC
can request to use a privileged role for an application to perform an operation that
requires higher permissions or a privilege.

A client rights domain is a group of repositories that share the same client rights.
The group of repositories in a client rights domain is typically governed by a global
repository (global registry). The following rules and restrictions apply to a client
rights domain and repository members of that domain:

• A client rights domain can only be configured in a global repository.

• Only a global repository can be a governing repository.
• A global repository can only have one client rights domain.
• A global repository cannot be the governing repository and also a member
repository of the client rights domain.
• A repository can only be a member of one client rights domain.
• The global repository must have access to all member repositories in the client
rights domain.
• Changes to the client rights in the governing repository are automatically
propagated to all member repositories in the same domain.

12.9.1.1 Creating a client rights domain

Creating a clients right domain requires superuser privileges and the repository on
which you are creating a client rights domain must be a global registry.

Documentum Administrator User Guide contains the instructions on creating a client

rights domain.

244 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.9. Principal authentication

12.9.1.2 Enabling or disabling a client rights domain

Any modifications to a client rights domain require superuser privileges.

Documentum Administrator User Guide contains the instructions on enabling or

disabling a client rights domain.

12.9.1.3 Deleting a client rights domain

Deleting a clients rights domain requires superuser privileges. Deleting a client
rights domain also deletes associated member repository entries.

Deleting a client rights domain automatically starts dm_PropagateClientRights job,

which removes the associated member repository entries. The job execution can take
approximately 2 to 4 minutes and until the job has completed successfully, any
member repository of the deleted client rights domain cannot be associated with
another client rights domain.

Documentum Administrator User Guide contains the instructions on deleting a client

rights domain.

12.9.1.4 Adding member repositories

Adding a repository to a client rights domain requires superuser privileges.

Table 12-6: Member repository properties

Field Name Description

Member Repository Name The name of the repository. The repository
cannot be the governing repository (global
registry).
Login Name The login name of the repository user. The
user must have system administrator
privileges and be a member of the
dm_sysadmin group.
Password The password of the repository user.
User Login Domain The name of the login domain for the user.
Optional property.
Application Alias Name The application name for the DFC instance.
Optional property.

Documentum Administrator User Guide contains the instructions on adding member

repositories.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 245

Chapter 12 Security and Authentication

12.9.1.5 Viewing repository memberships

Viewing a member repository or modifying repository login information in a client
rights domain requires superuser privileges.

Documentum Administrator User Guide contains the instructions on viewing

repository memberships.

12.9.1.6 Removing a member repository from a client rights domain

Removing a member repository from a client rights domain requires superuser
privileges. Removing a member repository also removes the client rights entries
from the member repository.

Removing a member repository automatically starts dm_PropagateClientRights job,

which removes the client rights entries from the member repository. The job
execution can take approximately 2 to 4 minutes and until the job has completed
successfully, the member repository cannot be associated with another client rights
domain.

Documentum Administrator User Guide contains the instructions on removing

repository memberships.

12.10 Privileged clients

Privileged DFC is the term used to refer DFC instances that are recognized by
Documentum Servers as privileged to invoke escalated privileges or permissions for
a particular operation. In some circumstances, an application needs to perform an
operation that requires higher permissions or a privilege than is accorded to the user
running the application. In such circumstances, a privileged DFC can request to use
a privileged role to perform the operation. The operation is encapsulated in a
privileged module invoked by the DFC instance. Supporting privileged DFC is a set
of privileged groups, privileged roles, and the ability to define TBOs and simple
modules as privileged modules. The privileged groups are groups whose members
are granted a particular permission or privileged automatically.

Each installed DFC has an identity, with a unique identifier extracted from the PKI
credentials. The first time an installed DFC is initialized, it creates its PKI credentials
and publishes its identity to the global registry known to the DFC. In response, a
client registration object and a public key certificate object are created in the global
registry. The client registration object records the identity of the DFC instance. The
public key certificate object records the certificate used to verify that identity.

In Documentum Administrator, the privileged DFC clients are managed on the

Privileged Clients page. To access the Privileged Clients page, select Administration
> Client Rights Management > Privileged Clients.

The Privileged Clients page provides the following information:

246 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.10. Privileged clients

Table 12-7: Privileged Clients page information

Column Description
Client Name The name of the DFC client.
Client ID A unique identifier for the DFC client.
Host Name The name of the host on which the DFC
client is installed.
Approved Indicates if the given DFC client is approved
to perform privilege escalations.
Manage Clients The Manage Client button displays the
Manage Client page, which lists all DFC
clients that are registered in the global
registry.

12.10.1 Adding privileged DFC clients

The Manage Clients page displays the list of DFC clients created in the repository.
When an you select one or more DFC clients as a privileged DFC client, a DFC client
object is created in the logged in repository and displayed on the Privileged Clients
page. The public key certificate is copied to the local repository.

Notes

• To add a privileged DFC client, you must be logged in as a superuser and

you must be the owner of the dm_acl_superusers ACL or the install owner.

• If the DFC client does not have the global registry information configured,
that is valid dfc.globalregistry.repository, dfc.globalregistry.username and
dfc.globalregistry.password, then it will not be displayed in the list of DFC
clients.

Table 12-8: Manage Clients page information

Column Description
Client Name The name of the DFC client.
Client ID A unique identifier for the DFC client.
Host Name The name of the host on which the DFC
client is installed.
Creation Date The creation date of the DFC client.

Documentum Administrator User Guide contains the instructions on adding privileged

DFC clients.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 247

Chapter 12 Security and Authentication

12.10.2 Configuring privileged client trusted login and trusted

server privileges
Privileged Client trusted login and trusted server privileges are configured on the
Privileged Client Properties page.

Table 12-9: Privileged client properties

Field label Value

Client Name The name of the DFC client.
Client ID The unique identifier for the DFC client.
Host Name The name of the host on which the DFC
client is installed.
Client Privilege Indicates whether the DFC client is approved
to perform privilege escalations.
Trusted Login Specifies whether the client is allowed to
create sessions for users without user
credentials.

Select this option to enable the client to create

sessions for users without credentials.
Trusted Server Privilege Specifies whether the DFC client is part of a
trusted Documentum Server domain. If this
option is enabled, the client has direct access
to the repositories on the server.
Is globally managed Select to propagate the privileged DFC
information by domain. Optional property.
Application Name The application name for the DFC instance.
Optional property.

Documentum Administrator User Guide contains the instructions on enabling or

disabling trusted login and trusted server privileges.

12.10.3 Approving or denying privileged clients

DFC client privilege escalations are approved or denied on the Privileged Clients
page.

Documentum Administrator User Guide contains the instructions on approving or

denying privileged clients.

248 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.11. Administrator access sets

12.10.4 Deleting a DFC client and certificate

You can delete a DFC client and the certificate.

Note: You cannot delete a certificate that is also used by another DFC client.

Documentum Administrator User Guide contains the instructions on deleting a DFC

client and certificate.

12.11 Administrator access sets

The administrator access functionality enables access to administration nodes based
on roles. The nodes, such as Basic Configuration, User Management, Job
Management, and Audit Management, provide access to different repository and
server functions.

In Documentum Administrator, the administrator access sets are managed on the

Administrator Access Sets page. To access the Administrator Access Sets page, select
Administration > Administrator Access.

Note: Administrator Access functionality is available only on Documentum 6

and later repositories.

Administrator access set definitions reside in the global registry. The access sets do
not conflict with Documentum Server privileges. Object level and user level
permissions and permission sets take precedence over administrator access sets. In
general, administrator access sets control node access as follows:

• Users are not assigned an administrator access set and do not have superuser
privileges, cannot access administration nodes.
• Users who are assigned an administration access set, but do no have superuser
privileges, can only access the nodes that are enabled in their administration
access set.
• Users with superuser privileges and at least coordinator client capabilities are not
affected by administrator access sets. These users always have access to the entire
administration node.
• The Groups node is always enabled for users with Create Group privileges.
• The Types node is always enabled for users with Create Type privileges.

The list of available roles is retrieved from the repository to which the administrator
is connected. To ensure that administrator access sets function correctly across an
application, the roles associated with the administrator access sets must exist in all
repositories. If the same role name exists in both the global repository and a non-
global repository, the user of the role would see the nodes as per the administrator
access specified in the global repository. Even if the user is able to see the nodes, the
user can perform operations only with sufficient privileges.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 249

Chapter 12 Security and Authentication

Note: The following Administration nodes are currently not available for the
administrator access set functionality:

• Work Queue Management

• Distributed Content Configuration

• Privileged Clients

The User Management chapter provides information about setting up roles.

12.11.1 Creating, viewing, or modifying administrator access

sets
Only users with superuser privileges and Coordinator client capabilities or greater
can create, view, or modify administrator access sets.

Table 12-10: Administrator access set properties

Field label Value

Name Name of the administrator access set. The
administrator access set name must be
unique. After creating and saving an
administrator access set, the name cannot be
modified.
Description Description of the administrator access set.
Nodes Select one or more node options to designate
the nodes that users with this administrator
access set can access. At least one node must
be selected for an administrator access set.
The available node options are:
• Basic Configuration
• LDAP Server Configuration
• Java Method Servers
• User Management
• Audit Management
• Jobs and Methods
• Content Objects
• Storage Management
• Content Delivery
• Index Management
• Content Intelligence
• Content Transformation Services
• Resource Management

250 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.11. Administrator access sets

Field label Value

Assigned Role Indicates the role assigned to the
administrator access set. If the role does not
exist in the connected repository, the role is
displayed in a red font.

To select or modify a role, click Select to

select a role on the Choose a role page. The
assigned role must be unique for an
administrator access set or an error message
displays, prompting the user to select a
different role.

The list of available roles is retrieved from

the repository to which the administrator is
connected. To ensure that administrator
access sets function correctly across an
application, the roles associated with the
administrator access sets must exist in all
repositories. If an assigned role is missing in
a connecting repository, the administrator
access set does not apply for the missing role.
Documentum Administrator displays a
message notifying the user when an assigned
role is missing.

Administrator access sets can be created

without assigning a role, and they can
contain an inactive or missing role. This is
useful during the initial setup of your
system.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying administrator access sets.

12.11.2 Deleting administrator access sets

Only users with superuser privileges and Coordinator client capabilities or greater
can delete administrator access sets.

Documentum Administrator User Guide contains the instructions on deleting

administrator access sets.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 251

Chapter 12 Security and Authentication

12.12 Managing Authentication Plug-Ins, Signatures,

and Encryption Keys
12.12.1 Using authentication plug-ins
Documentum Server supports authentication plug-ins that are implemented as
DLLs or shared libraries, depending on the platform hosting the plug-in. The two
plug-ins provided with Documentum Server are for RSA and CA SiteMinder
support. You can also write and install custom modules.

12.12.1.1 Plug-in scope

You can use a plug-in to authenticate users connecting to a particular repository or
to any repository in the installation. All plug-in modules are installed at the root of
the base directory or one of the subdirectories. If they are installed at the root of the
base directory, they are loaded for all repositories in the installation. If the plug-ins
are installed in repository-specific subdirectories, they are only loaded for those
specific repositories.

A default %DOCUMENTUM%\dba\auth ($DOCUMENTUM/dba/auth) base

directory is created automatically during Documentum Server installation. For every
repository, there is a subdirectory under the base directory specific to that
repository. There also is a location object, called auth_plugin, that points to the base
directory and sets the auth_plugin_location property in the server configuration
object to the name of the location object.

When a Documentum Server starts, it loads the plug-ins found in its repository-
specific directory first and then those located in the base directory. If two or more
plug-ins loaded by the server have the same identifier, only the first one loaded is
recognized. The remaining plug-ins with the same name are not loaded.

12.12.1.2 Identifying a plug-in

There are two ways to identify an authentication plug-in:

• Include the plug-in identifier in the connection request arguments.

• Set the User Source property of a user account to the plug-in identifier of the
module.

When Documentum Server receives a connection request, it checks whether a plug-

in identifier is included in the arguments. If not, the server examines the User Source
property of the user account 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 before sending the connection request to the DMCL.

When you want to use a plug-in to authenticate a particular user regularly, set the
User Source property of that user account to the plug-in identifier.

252 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

12.12.1.2.1 Defining a plug-in identifier

Plug-in identifiers are defined as the return value of the dm_init method in the
interface of the plug-in module. 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 valid identifiers:

• myauthmodule

• authmodule1

• auth4modul

To include a plug-in identifier in a connection request, the application must prepend

the following syntax to the password argument:
DM_PLUGIN=plugin_identifier/

Plug-in identifiers are accepted in all methods that require a password.

12.12.1.3 Using the RSA plug-in

Note: OpenText strongly recommends you to use OpenText Directory Services

(OTDS) for SSO.

The RSA plug-in for Documentum allows Documentum Server to authenticate users
based on RSA ClearTrust single sign-on tokens instead of passwords.

Documentum Webtop and WebPublisher, and other Documentum WDK-based

applications, support the RSA plug-in, with some configuration required.

The Documentum 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 the plug-in. “RSA plug-in modules” on page 253 lists the
files for the plug-in on the supported platforms.

Table 12-11: RSA plug-in modules

Platform Plug-in module

Windows dm_rsa.dll
Linux dm_rsa.so

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 253

Chapter 12 Security and Authentication

12.12.1.4 Using the CA SiteMinder plug-in

Documentum provides an authentication plug-in supporting authentication against
a CA SiteMinder Policy Server. The plug-in enables validation of CA SiteMinder
tokens sent to Documentum Server by Web-based clients.

Documentum Webtop supports the CA SiteMinder Plug-in, with some configuration

required. 0

The Documentum 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 the plug-in. “CA SiteMinder plug-in files” on page 254, lists the files
for the plug-in on the supported platforms.

Table 12-12: CA SiteMinder plug-in files

Platform File
Windows dm_netegrity_auth.dll
Linux dm_netegrity_auth.so

The directory also includes the CA Siteminder header files and libraries, to allow
you to rebuild the plug-in.

To use the plug-in after you install it, include the plug-in identifier in connection
requests or set the user_source property in users to the plug-in identifier.
(“Identifying a plug-in” on page 252, contains more information.)

The plug-in identifier for the CA SiteMinder plug-in is dm_netegrity.

Note: The dm_netegrity plug-in user authentication fails when the SiteMinder
WebAgent uses NTLM authentication instead of BasicPassword authentication
to protect a web resource, such as Webtop. The dm_netegrity plug-in is
currently unable to match the user distinguished name (DN).

12.12.1.5 Using the CAS plug-in

The CAS plug-in for Documentum allows Documentum Server to authenticate users
based on LDAP or inline password against CAS server identity provider. The plug-
in supports CAS server connection over HTTP and HTTPS.

254 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

12.12.1.5.1 Authentication flow using CAS plug-in

This section describes the steps in the authentication flow using CAS plug-in.

Figure 12-1: Authentication flow using CAS plug-in

1. REST negotiates Proxy Ticket from CAS and generates a CAS proxy ticket for
Target Service name.
2. REST makes a connection to the repository using the credentials.

• Username: Name of the user for whom the proxy ticket is generated.
• Password: Proxy ticket as password. The format of the password is
DM_PLUGIN=dm_cas/M_PLUGIN=dm_cas/<proxy ticket>.
3. New CAS plug-in of Documentum Server calls CAS to validate Proxy Ticket.
The CAS plug-in sends a HTTP request to CAS URL, http://<cas server url>/
proxyValidate with two request parameters:

• service: This should match the Target Service parameter sent for generating
the proxy ticket.
• ticket: This contains the proxy ticket.
4. The CAS server sends a response if the proxy ticket validation is successful.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 255

Chapter 12 Security and Authentication

<cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
<cas:authenticationSuccess>
<cas:user>username</cas:user>
<cas:proxies>
<cas:proxy>https://10.37.10.28:8443/pgtCallbackcas:proxy>
https://10.37.10.28:8443/pgtCallback</cas:proxy>
</cas:proxies>
</cas:authenticationSuccess>
</cas:serviceResponse>

5. If the user name matches with CAS user name for which proxy ticket is
generated, Documentum Server returns REST, a session in the context of
requested user.

Note: If the client requires the login ticket to be valid across all the repositories,
then a global login ticket must be used. The requirements for generating global
login ticket are:

• All trusted repositories because global login ticket is valid only if receiving
repository and issuing repository are trusted.
• Identical login ticket in the receiving repository and the global ticket
generating repository.

12.12.1.5.2 Custom configurations for CAS plug-in

This section describes the configurations required on the Documentum Server and
LDAP.

12.12.1.5.2. Documentum Server configuration

1

The CAS plug-in is configured using the dm_cas_auth.ini file placed at <
%DOCUMENTUM%>\dba\auth directory.

The “Parameters for configuring CAS” on page 256 table lists the various
parameters required for configuring CAS.

Table 12-13: Parameters for configuring CAS

Name Description
server_host Host name that resolves to the CAS server.
server_port HTTP port number for connection with CAS
server.
url_path URL path used to send HTTP request to CAS
server to validated proxy ticket.
service_param Service name for which the proxy ticket is
generated.

Note: The service name must be a

registered service in CAS.

256 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

Name Description
is_https Specifies if HTTP connection should be done
on HTTPS.

12.12.1.5.2. LDAP configuration

2

CAS plug-in also supports authentication for LDAP users and requires
customization.

The CAS server is configured to synchronize with the LDAP server. The new
dmCSLdapUserDN attribute is used for authentication response that exposes the user
LDAP distinguished name (DN).

To customize the CAS server:

1. Add an entry to the attributeRepository bean.

<entry key="distinguishedName" value="dmCSLdapUserDN"/>

where distinguishedName is the attribute of Active Directory. Use the attribute

depending on your LDAP server.
<bean id="attributeRepository" class="org.jasig.services.persondir.support.
ldap.LdapPersonAttributeDao">
......
......
<property name="resultAttributeMapping">
<map>
......
<entry key="distinguishedName" value="dmCSLdapUserDN"/>
......
</map>
</property>
</bean>

2. Customize the casServiceValidationSuccess.jsp file located at WEB-INF/

view/jsp/protocol/2.0 for CAS to populate LDAP attributes in the results. After
the line
<cas:user>......</cas:user>,

add the following:

<c:forEach var="auth" items="${assertion.chainedAuthentications}">
<c:forEach var="attr" items="${auth.principal.attributes}">
<cas:attribute name="${fn:escapeXml(attr.key)}"
value="${fn:escapeXml(attr.value)}"/>
</c:forEach>
</c:forEach>

3. Once the Documentum Server is registered into CAS for proxy, set the
customized attribute dmCSLdapUserDN in the list of allowedAttributes.
For example, here is the sample of in-memory service registry setting:
<bean id="serviceRegistryDao"
class="org.jasig.cas.services.InMemoryServiceRegistryDaoImpl">
<property name="registeredServices">
<list>

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 257

Chapter 12 Security and Authentication

<!--the following registered service is for Documentum Server, as

an example -->
<property name="id" value="1" />
<property name="name" value="Documentum Server proxy service" />
<property name="description" value="Allows CAS Proxy for
Documentum Server repositories" />
<property name="serviceId" value="ContentServer" />
<property name="evaluationOrder" value="0" />
<property name="allowedAttributes">
<list><value>dmCSLdapUserDN</value><list>
</property>
</bean>
<!-- other settings, for HTTP/HTTPS, IMAP and others -->
<bean ..../>
</list>
</property>
</bean>

12.12.1.6 Implementing a custom authentication plug-in

You can write and install custom authentication plug-ins. On a Windows platform,
the plug-in must be a DLL. On Linux platforms, the plug-in must be a shared
library.

Authentication plug-ins that require root privileges to authenticate users are not
supported. If you want to write a custom authentication mechanism that requires
root privileges, use a custom external password checking program.

Caution
This section outlines the basic procedure for creating and installing a
custom authentication plug-in. Documentum provides standard support
for plugins that are created and provided with the Documentum Server
software, as part of the product release. For assistance in creating,
implementing, or debugging custom rules, contact OpenText Global
Technical Services for service and support options to meet your
customization needs.

To implement a custom authentication plug-in:

1. Write the plug-in, as described in “Writing the authentication plug-in”

on page 259.

2. Install the plug-in, as described in “Plug-in scope” on page 252.

3. Enable the plug-in, as described in “Identifying a plug-in” on page 252.

4. Restart Documentum Server to load the new plug-in.

258 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

12.12.1.6.1 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 methods have the following
functionality:

• dm_init
The dm_init method is called by Documentum Server when it starts up. The
method must return the plug-in identifier for the module. The plug-in identifier
should be unique among the modules loaded by a server. If it is not unique,
Documentum Server uses the first one loaded and logs a warning in the server
log file.
• dm_authenticate
The dm_authenticate_user method performs the actual user authentication.
• dm_change_password
The dm_change_password method changes the password of a user.
• dm_plugin_version
The dm_plugin_version method identifies the version of the interface. Version
1.0 is the only supported version.
• dm_deinit
The dm_deinit method is called by Documentum Server when the server shuts
down. It frees up resources allocated by the module.

the dmauthplug.h header file contains detailed comments about each of the interface
methods. The header file resides in the %DM_HOME%\install\external_apps
\authplugins\include\dmauthplug.h ($DM_HOME/install/external_apps/
authplugins/include/dmauthplug.h) directory. All authentication plug-ins must
include this header file.

Additionally, all plug-ins must link to the dmauthplug.lib file in the %DM_HOME%
\install\external_apps\authplugins\include ($DM_HOME/install/external_apps/
authplugins/include) directory.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 259

Chapter 12 Security and Authentication

12.12.1.6.1. Internationalization
1

An authentication plug-in can use a code page that differs from the Documentum
Server code page. To enable that, the code page must be passed in the output
property bag of the dm_init method. If the code page is passed, Documentum Server
translates all parameters in the input property bag from UTF-8 to the specified code
page before calling the dm_authenticate_user or dm_change_password methods.
The server also translates back any error messages returned by the plug-in. A list of
supported code pages is included in the header file, dmauthplug.h.

12.12.1.7 Tracing authentication plug-in operations

Plug-ins are responsible for writing their own trace files. The trace level is
determined by the DM_TRACE_LEVEL parameter in the input property bag. The
initial value of the parameter is taken from the server start up flag -
otrace_authentication. However, if a user issues a SET_OPTIONS administration
method that changes the trace authentication level, 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

parameter in the dm_init method.

12.12.2 Managing encrypted passwords

Documentum Server and many of the internal jobs that manage repository
operations use passwords stored in files in the installation. These passwords are
stored in encrypted format by default. The passwords are encrypted using the AEK
during Documentum Server installation or job creation. “Password files encrypted
by default” on page 260, 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 to access or edit these files.

Table 12-14: Password files encrypted by default

File Description
dbpasswd.txt This file contains one line with the database
password used by Documentum Server to
connect to the RDBMS. (This is password for
the repository owner.)
<docbase_name>.cnt The file contains one line with the password
used by an object replication job and the
distributed operations to connect to the
repository as a source or target repository.

If this file is present, the dm_operator.cnt file

is not.

260 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

File Description
dm_operator.cnt The file contains one line with the password
used by an object replication job and the
distributed operations to connect to
repositories.

If this file is present, <docbase_name>.cnt files

are not used.
federation.cnt Contains the information, including
passwords, used by a governing repository
server to connect to member repositories.
The file is stored with the governing
repository.

The format of the content of file is:

<member_repository_name>:<user_name>:<passw
ord>:[<domain>]

ldap_<object_id>.cnt Contains the password used by

Documentum Server to bind to an LDAP
server.

12.12.2.1 Using encryptPassword

Use encryptPassword to encrypt any password that you want to pass in encrypted
form to the one of the following methods:

• IDfSession.assume
• Authenticate in IDfSessionManager, IDfSession, or IDfClient
• A method to obtain a new or shared session.
• IDfPersistentObject.signoff
• IDfSession.changePpassword

Passwords encrypted with encryptPassword cannot be decrypted explicitly by an

application or user. There is no method provided to perform decryption of
passwords encrypted with encryptPassword. DFC decrypts those passwords
internally when it encounters the password in the arguments of one of the above
methods.

Passwords encrypted with encryptPassword are prefixed with DM_ENCR_PASS.

The Javadocs contains more information on using this method.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 261

Chapter 12 Security and Authentication

12.12.2.2 Using clear text passwords

If you do not want to use an encrypted password for a particular operation, use a
text editor to edit the appropriate file listed in “Password files encrypted by default”
on page 260. Remove the encrypted password and replace it with the clear text
password.

12.12.2.3 Changing an encrypted password

If you find it necessary to change one of the encrypted passwords described in
“Password files encrypted by default” on page 260, use the dm_encrypt_password
utility to do so. This utility takes non-encrypted password, encrypts it, and writes it
to a specified file. If the file is one of the password files maintained by Documentum
Server, the utility replaces the current encrypted password in that file with the new
password. You must be the repository owner to use this utility.

To encrypt or change a password in a password file maintained by repository, use

the following syntax:
dm_encrypt_password [-location <AEK_location>]-keyname <keyname>
[-passphrase <passphrase>] -docbase <repository_name>
-remote <remote_repository_name> | -operator | -rdbms -encrypt <password>

To create or change an encrypted password in a file that you have created, use the
following syntax:
dm_encrypt_password [-location <AEK_location>] -keyname <keyname>
[-passphrase <passphrase>] -file <file_name>
-encrypt <password>

The arguments have the following meanings:

-location <AEK_location> Identifies the location of the AEK file to be

used to encrypt the password. If this
argument is not set, the environment
variable DM_CRYTPO_FILE must be set.
-keyname <keyname> Specifies the AEK keyname.

262 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

-passphrase <passphrase> Specifies the passphrase used to protect the

AEK file.

If the argument is included without a

passphrase, the utility prompts for a
passphrase.

If the argument is not included, the utility

attempts to use the default passphrase. (The
default passphrase can be defined when the
dm_crypto_boot utility is run to set up the
AEK.)

If a default passphrase is not defined, the

utility checks the shared memory location,
based on the location argument or the
default location, for an AEK or passphrase. If
neither is found in shared memory, the
utility exits with an error.
-file <file_name> Identifies the file on which to operate.

Do not include this argument if you include

the -docbase argument.
-encrypt <password> Defines the password to encrypt. If specified,
the password is encrypted and written to the
file identified in the -file argument. If
unspecified, the utility encrypts the first line
found in the file and writes it back to the file.
-docbase <repository_name> Identifies the repository for which the
password is being encrypted.

Do not include this argument if you include

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 argument if

you include -remote.
-operator Identifies the file to operate on as
%DOCUMENTUM%\dba\config
\<repository_name>\dm_operator.cnt

You must include the -docbase argument if

you include -operator.
-rdbms Identifies the file to operate on as
%DOCUMENTUM%\dba\config
\<repository_name>\dbpasswd.txt

You must include the -docbase argument if

you include -rdbms.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 263

Chapter 12 Security and Authentication

For example, executing the utility with the following command line replaces the
database password used by the Documentum Server in the engineering repository to
connect with the RDBMS:
dm_encrypt_password keyname CSaek -docbase engineering -passphrase jdoe -rdbms
-encrypt 2003password

The AEK location is not identified, so the utility reads the location from the
DM_CRYPTO_FILE environment variable. The passphrase jdoe is used to decrypt
the AEK. The utility encrypts the password 2003password and replaces the current
RDBMS password in dbpasswd.txt with the newly encrypted password.

This example identifies a user-defined file as the target of the operation.

dm_encrypt_password keyname CSaek -passphrase jdoe
-file C:\engineering\specification.enc -encrypt devpass

The AEK location is not identified, so the utility reads the location from the
DM_CRYPTO_FILE environment variable. The password jdoe is used to decrypt the
AEK. The utility encrypts the password devpass and writes the encrypted value to
the file C:\engineering\specification.enc.

12.12.3 Implementing signature support

Documentum Server provides administration tasks that support using an electronic
signature feature in applications. There are three options for electronic signatures:

• Electronic signatures using addESignature

Electronic signatures are implemented through Documentum Server and provide
rigorous accountability. This option requires a Trusted Content Services license.
The “Customizing electronic signatures” on page 266 section contains the
information on using and customizing electronic signature support. Electronic
signatures are supported on all platforms.
• Electronic signatures using addDigitalSignature
Electronic signatures are implemented in client applications, using third-party
software. No additional Documentum Server license is needed. The “Supporting
electronic signatures” on page 269 section contains the instructions on
supporting electronic signatures.
• Simple signoffs
Simple signoffs are the least rigorous way to enforce an electronic signature
requirement. No additional Documentum Server license is needed. The
“Customizing simple signoffs” on page 270 section contains the instructions on
using and customizing simple signoffs.

264 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

12.12.3.1 Using electronic signatures

The default signature template is a form field based PDF template. You must have
Adobe Acrobat installed on your system to use this template. Documentum Server
version 6.6 and later supports publishing only static information on the signature
template. Static information, such as a company logo, can be converted to a form
field based template using Adobe LiveCycle Designer.

Note: We recommend that you backup any existing custom templates before
upgrading to a new template.

Figure 12-2: Signature page

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 265

Chapter 12 Security and Authentication

12.12.3.2 Customizing electronic signatures

There a variety of options for customizing the default signature template for
electronic signatures:

• Adding or removing properties from the template page

• Changing the property delimiters on the page
• Changing the look of the template by adding, removing, or rearranging elements
on the page or changing the font and point size of the properties
• Defining separate templates for different document types
• Configuring 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.

A signature in non-PDF format requires a custom signature creation method. A

custom method can use a custom signature page template, but it is not required. The
signature can be in any form that the method implements.

12.12.3.2.1 Configuring the number of allowed signatures

By default, each signature page can have six signatures. Additional signatures are
configured using the esign.signatures.per.page property in the esign.properties file.
The esign.properties file resides in the %DOCUMENTUM%\<WildFly_directory>
\server\DctmServer_MethodServer\deploy\ServerApps.ear\lib\configs.jar
directory.

The following table describes configuration parameters in the esign.properties file.

Table 12-15: Configuration parameters in esign.properties file

Property Description
esign.server.language=en Indicates the locale of the Documentum
Server.
esign.server.country=US Indicates the country code.
esign.date.format = MM/dd/yyyy HH:mm:ss Indicates the date format on the signature
page. If the date format is not provided in the
esign.properties file, the date format of the
Documentum Server is used.
esign.signatures.per.page Indicates the number of signatures per
signature page.

266 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

12.12.3.2.2 Creating custom signature creation methods and associated signature page
templates

If you do not want to use the default functionality, you must write a signature
creation method. Using a signature page template is optional.

This section outlines the basic procedure for creating and installing a user-defined
signature creation method. Documentum provides standard support for the default
signature creation method and signature page template installed with the
Documentum Server software. For assistance in creating, implementing, or
debugging a user-defined signature creation method or signature page template,
contact OpenText Global Technical Services for service and support options to meet
your customization needs.

To create a custom signature-creation method:

1. Write the method program.

2. Create a dm_method object that references the method program.

Use the following guidelines when writing the method:

• The method should check the number of signatures currently defined for the
object to ensure that adding another signature does not exceed the maximum
number of signatures for the document.
• The method must return 1 if it completes successfully or a number greater than 1
if it fails. The method cannot return 0.
• If the trace parameter is passed to the method as T (TRUE), the method should
write trace information to standard output.

To use the custom method, applications must specify the name of the method object
that represents the custom method in the addESignature arguments. The following
table describes the parameters passed by the addESignature method.

Table 12-16: Parameters passed by the addESignature method

Parameter Description
docbase Name of the repository.
user Name of the user who is signing.
doc_id Object ID of the document.
file_path The name and location of the content file.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 267

Chapter 12 Security and Authentication

Parameter Description
signature_properties A set of property and value pairs that
contain data about the current and previous
signatures. The information can be used to
fill in a signature page. The set includes:
• 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 parameter

corresponds to the number of the signature
to which the information applies.
application_properties User-defined set of property names and
values specified in the Addesignature
command line.
trace If tracing is turned on for SysObjects, this
parameter is passed as T (TRUE).
passThroughArgument1 User-defined information specified in the
addESignature command line.
passThroughArgument2 User-defined information specified in the
addESignature command line.

If you decide to create a new signature template page, you can define the format,
content, and appearance of the page. You can store the template as primary content
of an object or as a rendition. For example, you can create an XML source file for
your template and generate an HTML rendition that is used by the custom signature
creation method. If you store the template as a rendition, set the template page
modifier to dm_sig_template. Setting the page modifier to dm_sig_template ensures
that the Rendition Manager administration tool does not remove the template
rendition.

268 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

12.12.3.2.3 Publishing dynamic information

Documentum Server supports publishing dynamic information on custom signature

templates at the page level. The dynamic information is passed through the
app_properties parameter while executing the addESignature method.

Custom field names in custom signature templates must be added with a Ecustf_
prefix, using the following syntax:
'ECustF_Attribute_name1 = ''attr1_value'

12.12.3.2.4 Tracing electronic signature operations

You can trace the addESignature method and the default signature creation 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

recorded in the session log file. The tracing information for the signature creation
method is recorded in the server log file.

If you are using a custom signature creation method, trace messages generated by
the method 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
parameter set to T (TRUE) to the signature creation method.

Set the DM_DEBUG_ESIGN_METHOD environment variable to 1 to log additional

information about electronic signatures generated by addESignature to the
repository log file. You must restart Documentum Server after setting this variable.

12.12.3.2.5 Setting the Java memory allocation

To avoid performance issues while adding signatures to the document for files
greater than 30 MB, it is recommended to increase the JVM memory according to
availability. For, example, set the value as -Xms1024m -Xmx1024m in the JMS
startup file.

12.12.3.3 Supporting electronic signatures

Digital signatures, like electronic signoffs, are a way to enforce accountability.
Digital signatures 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. For example, you can implement digital signing using based on
Microsoft Office XP, in which case the signature is typically embedded in the content
file and stored in the repository as primary content for the document.

The implementation and management of electronic signatures is almost completely

within the context of the client application. The only system administration task is
registering the dm_adddigsignature event for signature by Documentum 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

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 269

Chapter 12 Security and Authentication

Documentum Server. To configure signing by the server, an explicit registration

must be issued for the dm_adddigsignature event. The “Audit properties”
on page 314 section contains the information on how Documentum Server
signatures on audit entries are implemented and how to configure their use.

12.12.3.4 Regenerating audit signatures

If there is a change in the time zone in Documentum Server host, run the following
command to recalculate the audit signature: apply,c,NULL,
REGENERATE_AUDIT_SIGNATURE,FROM_DATE,S,<from_date>,TO_DATE,S,
<to_date>,DATE_FORMAT,S,<format>,TRACE,B,<T/F>

Note: The FROM_DATE, TO_DATE, and FORMAT commands are mandatory

arguments. TRACE is an optional argument with the default value as <false>. If
enabled, trace messages are written to the repository log. The supported date
formats are mentioned in Documentum Server DQL Reference Guide.

For example:
apply,c,NULL,REGENERATE_AUDIT_SIGNATURE,FROM_DATE,S,'03/20/2015',
TO_DATE,S,'04/03/2015',FORMAT,S,'mm/dd/yyyy',TRACE,B,T

apply,c,NULL,REGENERATE_AUDIT_SIGNATURE,FROM_DATE,S,'01/04/2014',
TO_DATE,S,'02/10/2014',FORMAT,S,'mm/dd/yyyy'

12.12.3.5 Customizing simple signoffs

Simple signoffs are implemented using a IDfPersistentObject.signoff method and a
signature validation program. Documentum provides a default signature validation
program that authenticates a user based on the user authentication name and
password passed as arguments in the signoff method. If the authentication succeeds,
Documentum Server creates an audit trail entry of event type dm_signoff that
records what was signed, who signed it, and some information about the context of
the signing. The audit trail entry is not signed by Documentum 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 password argument of signoff and
creating a custom validation method to authenticate the user with that data.
For example, you can pass some biometric data and then validate that using a
custom validation program.
• Use an argument in a registration method to force Documentum Server to sign
the dm_signoff events or to add additional information to the entries.

Note: Documentum provides standard support for the default signature

validation method installed with the Documentum Server software. For
assistance in creating, implementing, or debugging custom rules, contact
OpenText Global Technical Services for service and support options to meet
your customization needs.

270 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

12.12.3.5.1 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 name and the signature data
passed using the user-password argument of the signoff method. If the personal
data is binary, you can use the uuencode program to convert the data to a
string. Data passed 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 configuration object to

point to the location object created in Step 2.
The signature_chk_loc property identifies the location of the signature
validation program to Documentum Server.

12.12.3.5.2 Registering for notification

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
audit event, because the server always generates an audit trail for signoff executions.

12.12.3.5.3 Querying the audit trail for signoffs

To return a collection of document objects signed by a specific user within a certain

time frame, use a DQL statement like the following:
SELECT "audited_obj_id" FROM "dm_audittrail" WHERE
"event_name" = 'dm_signoff' AND
"user_name" = 'tom' AND
substr ("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 following
DQL statement:
SELECT "user_name" FROM "dm_audittrail" WHERE
"audited_obj_id" = 'xxx' AND
"event_name" = 'dm_signoff'

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 271

Chapter 12 Security and Authentication

12.12.4 Managing encryption keys

Each Documentum Server software installation contains one master key, called the
Administration Encryption key, or AEK. The AEK is always stored locally in the
Documentum Server installation.

12.12.4.1 The AEK

Starting with the 7.2 release, the creation of AEK is performed during the creation of
the repository. Prior to 7.2, there was only one AEK in each Documentum Server
software installation. It will be created and installed during the Documentum Server
software installation procedure or when an existing repository was upgraded. The
AEK is used to encrypt:

• The repository keys

• Documentum passwords, such as those used by Documentum Server to connect
to the RDBMS, an LDAP directory server, or other repositories

The AEK is itself encrypted using a default passphrase provided by Documentum.

You can change the passphrase to a custom passphrase using a utility provided by
Documentum. Using a custom passphrase is recommended. “Changing a
passphrase” on page 277, has instructions for changing the passphrase.

The AEK is installed in the following location:

On Windows:
%DOCUMENTUM%\dba\secure\aek.key

On Linux:
$DOCUMENTUM/dba/secure/aek.key

The file is a read only file. The name of the file depends on the keyname parameter.

Documentum Server and all server processes and jobs that require access to the AEK
use the 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
the location defined in the DM_CRYPTO_FILE environment variable.
3. If the DM_CRYPTO_FILE environment variable is not defined, assume that the
location is %DOCUMENTUM%\dba\secure\<keyname> ($DOCUMENTUM/
dba/secure/<keyname>). If keyname is not specified, aek.key is assumed to be
the name of the key.

Starting with the 7.2 release, the creation of AEK can be performed during the
creation of the repository. During repository creation or upgrade, option is provided
to create or upgrade key or to use existing key.

272 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

You can choose to maintain your existing key. If you need to use the AEK key before
creating the repository, create a key using the dm_crypto_create tool. Starting with
the 7.2 release, changing of the AEK is also supported.

12.12.4.1.1 Sharing the AEK or passphrase

If there are multiple Documentum products installed on one host, the products can
use different AEKs or the same AEK.

On the same host, all keys have to use the same passphrase. If you want that
passphrase to be a custom passphrase, perform the following procedure after you
install the Documentum Server software.

To implement the same passphrase for multiple products:

1. Shut down Documentum Server if it is running.

2. Run the dm_crypto_change_password to change the passphrase to a custom

passphrase.
The “Changing a passphrase” on page 277 section contains the instructions.

3. Run the dm_crypto_boot utility using the -all argument.

The “Using dm_crypto_boot” on page 275 section contains the instructions.

4. Restart Documentum Server.

5. Install the remaining products on the host machine.

12.12.4.1.2 The AEK and distributed sites

If your repository is a distributed repository, all servers at all sites must be using the
same AEK. The installer handles the copying of AEK key.

In multiple-repository distributed sites, you should use the same AEK key.

12.12.4.1.3 Backing up the AEK

It is strongly recommended that you back up the AEK file separately from the
repository and content files. Backing up the AEK and the data it encrypts in different
locations helps prevent a dictionary-based attack on the AEK.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 273

Chapter 12 Security and Authentication

12.12.4.2 Repository encryption keys

A repository encryption key is created for a repository when the repository is
created. The key or its ID is encrypted using the AEK and stored in the i_crypto_key
property of the repository configuration object. This property cannot be changed
after the repository is created.

Documentum Server uses the repository encryption key to create the signature on
audit trail entries. The server also uses the repository encryption key to encrypt file
store keys.

A repository created to use local key management stores the encrypted key in the
repository configuration object.

12.12.4.3 Encryption utilities

The utilities that are used to manage the AEK are:

• 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 shared memory of host

machine after you define a custom passphrase.
– Reinstall an obfuscated AEK or passphrase in the shared memory of host
machine if you stop and restart a server host machine.
– (Windows only) Reinstall an obfuscated AEK or passphrase in the shared
memory of host machine if you log off the host machine after you stop
Documentum 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. The “Using dm_crypto_boot” on page 275
section contains more details and instructions on using the utility.
• dm_crypto_create
This utility is run automatically, during the Documentum Server installation
process, to create and install the AEK. You can use this utility to determine if an
AEK exists at a specified location and can be decrypted with a specified
passphrase. The “Using dm_crypto_create” on page 276 section contains the
instructions.
• dm_crypto_change_passphrase
The dm_crypto_change_passphrase utility changes the passphrase used to
encrypt an AEK. The “Changing a passphrase” on page 277 section contains the
instructions.

Note: When you run the utilities from command prompt or other Windows
utility, ensure that the application is launched as administrator using Run as

274 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

Administrator. If it is not done, Windows operating system restricts the access

to the shared memory and other system resources.

12.12.4.4 Using dm_crypto_boot

The dm_crypto_boot utility obfuscates the AEK or the passphrase used to decrypt
the AEK and puts the obfuscated AEK or passphrase in shared memory. The utility
is only used when you are protecting the AEK with a custom passphrase. It is not
necessary if you are using the Documentum default passphrase. If you are
protecting the AEK with a custom 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 before
restarting the product or products that use the AEK.
• After you install the Documentum Server software and before you install the
remaining products

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 have
access to the AEK file.

The syntax for the utility is:

dm_crypto_boot
[-keyname <keyname>] [-location <location> | -all]
[-passphrase <passphrase>] [-remove] [-noprompt]

The available arguments are:

• -passphrase <<passphrase>>: The -passphrase argument identifies the passphrase

used to encrypt the AEK. If you do not 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, the passphrase is not displayed on screen
when it is typed in.
• -keyname <<keyname>>: This is the name the of the key. By default, the name is
CSaek.

You must include either the -location or -all argument. Use -location if only one
product is accessing the AEK. Using -location installs an obfuscated AEK in shared
memory. The -location argument identifies the location of the AEK key. Ensure to
provide the complete path of the file along with the AEK file name when using the –
location argument. If you do not include 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 (Windows) or
$DOCUMENTUM/dba/secure/aek.key (Linux).

Use the -all argument if there are multiple products on the host machine that use the
same passphrase for their AEKs and also to use AES_256_CBC algorithm with a

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 275

Chapter 12 Security and Authentication

custom passphrase. If you include -all, the utility obfuscates the passphrase and
writes it into shared memory instead of the AEK. Each product can then obtain the
passphrase and use it to decrypt the AEK for their product.

To clean up the shared memory used to store the obfuscated AEK or passphrase,
execute the utility with the -remove argument. You must include the -passphrase
argument if you use -remove.

The -help argument returns help information for the utility. If you include -help, you
cannot include any other arguments.

12.12.4.5 Using dm_crypto_create

You can run the dm_crypto_create utility with the -check argument to determine
whether an AEK exists at a specified location and whether a particular passphrase
can be used to decrypt it. The syntax is:
dm_crypto_create
[-keyname <keyname>] [-location <location>]
[-passphrase <passphrase>] [-noprompt]
[-check] [-algorithm] [-help]

By default, the AEK key is created in %DOCUMENTUM%\dba\secure in Windows and

$DOCUMENTUM/dba/secure in Linux. However, if you want to create the AEK key in
a different location, use the -location argument using the dm_crypto_create utility.
The -location argument identifies the location of the AEK key. Ensure to provide the
complete path of the file along with the AEK file name when using the –location
argument. If you do not include the -location argument, the utility looks for the AEK
key in the location defined in DM_CRYPTO_FILE. If that environment variable is
not defined, the utility assumes the location %DOCUMENTUM%\dba\secure\aek.key
(Windows) or $DOCUMENTUM/dba/secure/aek.key (Linux).

The available arguments are:

• -passphrase <<passphrase>>: The -passphrase argument identifies the passphrase

whose use you wish to check. If you do not include the -passphrase argument,
the utility assumes the default passphrase but prompts you for confirmation.
Consequently, if you are checking the default passphrase and wish to avoid the
confirmation request, include the -noprompt argument. The -passphrase and -
noprompt arguments are mutually exclusive.

Note: If you are creating a custom passphrase for the AEK key, ensure that
you do not use:

– % special character in the custom passphrase for Windows

– $ special character in the custom passphrase for Linux
• -keyname <<keyname>>: This is the name of the key. By default, the name is
CSaek.

Starting with the 7.2 release, the utility is enhanced to provide the option for
specifying the algorithm used for generating encryption keys. The following
optional argument is introduced:

276 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

• -algorithm <<algorithm>>: This option allows to specify the algorithm that has to
be used for generating the AEK key. By default, AES_128_CBC is used. Valid
values are:

– AES_128_CBC

– AES_192_CBC

– AES_256_CBC

If the AEK file exists and decryption succeeds, the utility returns 0. If the AEK file
exists but decryption fails, the utility returns 1. If the AEK file is already existing at
the specified location, the utility returns 2. If the AEK file does not exist at the
specified location, the utility returns 3.

The -help argument returns help information for the utility. If you include -help, you
cannot include any other arguments.

12.12.4.6 Changing a passphrase

Use dm_crypto_change_passphrase to change the passphrase used to encrypt the
AEK in the installation. Installing the Documentum Server software installs the AEK
encrypted using a default passphrase. Use this utility, also, if business rules or a
security breach require you to change the passphrase. All Documentum products
that use the affected AEK must be stopped before running the utility.

The syntax is:

dm_crypto_change_passphrase [-keyname <keyname>][-location <location>]
-passphrase <old_passphrase> -newpassphrase <new_passphrase>
[-noprompt][-help]

The -location argument identifies the location of the AEK whose passphrase you
wish to change. If you do not include the argument, the utility looks for location
defined in DM_CRYPTO_FILE. If that environment variable is not defined, the
utility assumes the location %DOCUMENTUM%\dba\secure\aek.key (Windows) or
$DOCUMENTUM/dba/secure/aek.key (Linux).

The -passphrase argument identifies the current passphrase associated with the
AEK. The -newpassphrase argument defines the new passphrase you wish to use to
encrypt the AEK. Both phrases interact in a similar manner with the -noprompt
argument. The behavior is described in “Interaction of
dm_crypto_change_passphrase arguments” on page 277.

Table 12-17: Interaction of dm_crypto_change_passphrase arguments

-noprompt included -noprompt not included

-passphrase argument not Utility prompts for a Utility assumes the
included passphrase Documentum default
passphrase

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 277

Chapter 12 Security and Authentication

-noprompt included -noprompt not included

-passphrase keyword is included Utility prompts for a Utility assumes the
but no value passphrase Documentum default
passphrase
-newpassphrase argument not Utility prompts for a new Utility assumes the
included passphrase Documentum default
passphrase
-newpassphrase keyword is Utility prompts for a new Utility assumes the
included but no value passphrase Documentum default
passphrase

You must include a value for at least one of the passphrases. You cannot be
prompted for both values or allow both values to default.

To illustrate the use of this utility, here are some examples. The first example
changes the passphrase for the Documentum Server host AEK from the
Documentum default to “custom_pass1”. The -passphrase argument is not included
and the-noprompt is included, so the utility assumes that the current passphrase is
the default passphrase.
dm_crypto_change_passphrase -location %DOCUMENTUM%\dba\secure\aek.key
-newpassphrase custom_pass1 -noprompt

This next example changes the passphrase from one custom passphrase to another:
dm_crypto_change_passphrase -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_change_passphrase -location %DOCUMENTUM%\dba\secure\aek.key
-passphrase custom_pass1 -noprompt

Because the new passphrase is set to the Documentum default passphrase, it is not
necessary to include the -newpassphrase argument. The utility assumes that the new
passphrase is the default if the argument is not present and the -noprompt argument
is present.

The -help argument returns help information for the utility. If you include -help, you
cannot include any other arguments.

278 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

12.12.5 Managing the login ticket key

The login ticket key is used to generate and validate login tickets and application
access control tokens. The key is installed automatically when a repository is
created. Each repository has one login ticket key.

A repository created to use local key management stores the encrypted login ticket
key in the repository. There is no difference using the EXPORT_TICKET_KEY,
IMPORT_TICKET_KEY, and RESET_TICKET_KEY methods for either type of
repository.

12.12.5.1 Exporting and importing a login ticket key

If you are using global login tickets or global application access control tokens, both
the repository generating the ticket or token and the repository accepting the ticket
or token must be using the same login ticket key. When you install a repository, the
installation 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 key from one repository among those that will be exchanging global login
tickets or tokens and 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,

as described in “EXPORT_TICKET_KEY” on page 349. To import the key, use
IMPORT_TICKET_KEY, as described in “IMPORT_TICKET_KEY” on page 350.
These methods are also available as DFC methods (exportTicketKey and
importTicketKey) in the IDfSession interface.

You must restart Documentum Server after importing a login ticket key to make the
new login ticket key take effect.

12.12.5.2 Resetting a login ticket key

Resetting a login ticket key replaces the current login ticket key with a newly
generated key. You need to reset a login ticket key if the current key is
compromised. If you reset the login ticket key, the server of repository does not
accept any login tickets generated using the old key.

To reset a login ticket key, execute the RESET_TICKET_KEY method. You can also
use the DFC method, resetTicketKey, in the IDfSession interface.

You must restart Documentum Server after resetting a login ticket key.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 279

Chapter 12 Security and Authentication

12.12.6 Configuring application access control token use

Application access control (AAC) tokens are a security feature that you can use to
control access to a repository based on who is requesting access, the application or
host from which the request is issued, or some combination of these factors.

AAC tokens are enabled at the server level, to give you flexibility in designing your
security. For example, you can set up a server that requires a token to service users
outside a firewall and another server that does not require a token for users inside
the firewall.

Tokens are used in addition to user names and passwords (or login tickets) when
issuing a connection request. They are not a substitute for either. If a server requires
a token and the user making the connection request is not a Superuser, the
connection request must be accompanied by a token. Only Superusers can connect to
a repository through a server requiring a token without a token.

Documentum Server Fundamentals Guide contains complete information about tokens

and how they are implemented and used.

12.12.6.1 Enabling AAC token use by a server

Use Documentum Administrator to enable the use of application access control
tokens by a particular server. If use is enabled, non-Superuser users cannot access
the repository through that server unless the constraints specified in the token are
satisfied. Whether a server has AAC token use enabled is recorded in the
application_access_control property of its server config object.

12.12.6.1.1 Enabling machine-only AAC tokens

An application access control token can be created to be valid only when sent from a
particular host machine. This token authentication mechanism is dependent on
knowledge of the machine ID of host. If you are using such tokens, you must set the
dfc.machine.id key in the dfc.properties file used by client applications on that host
so that DFC can include that when sending the application token to Documentum
Server. Set the key to the machine ID of host.

12.12.6.2 Enabling token retrieval by the client library

You can configure client library behavior to allow the client library to automatically
retrieve a token from storage and append that token to connection request of an
application if a token is required and none is provided in the connection request. If
retrieval is enabled, the client library searches for a token file whose name matches
the name of the repository specified in the connection request. If such a token file is
found, the token it contains it is appended to the connection request. If such a token
file is not found, the client 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
application is run from different machines and that older applications can connect to
a server that requires an AAC token for connection.

280 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

To enable token retrieval:

1. Generate the token files using dmtkgen.

For instructions on using the utility, refer to “Generating tokens for storage”
on page 282.

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
library can retrieve tokens from storage. If it is set to true, the client library will
attempt to retrieve a token from storage for use when a connect request without a
token is issued to a server requiring a token. If the key is set to false, the client
library does not retrieve tokens from storage.

The dfc.tokenstorage.dir key tells the client library where to find the token files
generated by the dmtkgen utility. Any tokens that you generate using dmtkgen
must be placed in this 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 sets
the dfc.tokenstorage.enable key to false and the dfc.tokenstorage.dir to <user-selected
drive>:\Documentum\apptoken. If you upgrade or reinstall DFC, the procedure will
not reset those keys if you have changed them.

When you install Documentum Server for the first time on a host machine, the
process also installs DFC. The DFC installation process sets the
dfc.tokenstorage.enable key in the dfc.properties file on the server host to false and
the dfc.tokenstorage.dir to %Documentum%\apptoken ($DOCUMENTUM/
apptoken). However, when the Documentum Server installer runs, it resets the
tdfc.tokenstorage.enable key to true. The dfc.tokenstorage.dir is not reset.

The dfc.properties file on the server host is used by the internal methods to connect
to repositories. The dfc.tokenstorage.enable and dfc.tokenstorage.dir settings in this
dfc.properties file affect methods associated with dm_method objects. Replication
and federation methods are not affected by the settings in this dfc.properties file
because these jobs execute as a Superuser.

Note: Documentum Server Fundamentals contains the additional information

about how internal methods are affected by this setting.

If you are installing an upgrade to Documentum Server or a previous DFC

installation occurred and a dfc.properties file already exists on the host machine
with these keys set, installing Documentum Server and a new DFC does not
overwrite their values.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 281

Chapter 12 Security and Authentication

12.12.6.3 Generating tokens for storage

Use the dmtkgen utility to generate application access control tokens to be stored on
host machines. The utility is found in %DM_HOME%\bin ($DM_HOME/bin). Each
execution 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 a
sample of the file 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>

“dmtkgen utility arguments” on page 282, lists the arguments accepted by this
utility.

Table 12-18: dmtkgen utility arguments

Argument Description
-u username User as whom the utility is running

This is a required argument.

-p password Password for the user identified in username

This is a required argument.

-d domain Domain of the user identified in username

This argument is required only if a domain is

required to authenticate the user.
-b repository_name Name of the repository to which to connect
to create the token.

This is a required argument.

-a user|group name Name of the user or group who can use this
token. If a group is specified, all members of
the group can use this token.

This is an optional argument. If unspecified,

then all users can use the token.

282 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.12. Managing Authentication Plug-Ins, Signatures, and Encryption Keys

Argument Description
-s scope Scope of the generated token. Valid values
are
• docbase
Specifying docbase restricts the use of
token to the repository identified in the
output name of the file.
• global
Specifying global allows the token to be
used to connect to any repository having
the same login ticket key 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 is interpreted in minutes.

This is an optional argument. The default is

one year, expressed in minutes.
-i application_identifier User-defined application identifier
representing the application for which this
token is valid.

This is an optional argument. If unspecified,

the token is valid for all applications.
-m machine_only Boolean flag indicating whether the token is
valid only when used on the machine on
which the token was generated. T means the
token may only be used from the machine on
which it was generated. F means that the
token may be sent from any machine.

This is an optional argument. The default is

F.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 283

Chapter 12 Security and Authentication

Argument Description
-o output_file The name of the generated XML token file.
You can speicify a full file path or only the
file name.

The file name must be either:

default.tkn

or
repository_name.tkn

This is an optional argument. It defaults to

repository_name.tkn where repository_name is
the repository identified in the -b argument.
If you include a name but not a file path, the
file is stored in the current directory.

The implementation imposes a naming

constraint on global tokens. Refer to
“Naming the output file” on page 284, for
information.

12.12.6.3.1 Naming the output file

Token files are retrieved by repository name. If the client library is looking for a
token in storage for a particular connection request, it searches for a token whose
name is the name of the requested repository in the connection request. If the library
cannot find a token whose name matches the repository name in the connection
request, it searches for a token file called default.tkn. Because of this token file search
algorithm, if you create a global token file for use across multiple repositories, you
must name the file default.tkn.

12.12.6.4 Storing tokens generated by dmtkgen

The client library looks for the stored tokens in the location identified by the
dfc.tokenstorage.dir key in the dfc.properties file of client. After you generate the
token file, you can copy the file to that location for each client machine where the
token will be used. Because the generated file is an ASCII file, you can copy the file
across operating systems. For example, if it was generated on a Windows host
machine, you can copy it to a UNIX host machine. Similarly, if it was generated on a
UNIX host machine, you can copy it to a Windows host machine.

If the location specified in dfc.tokenstorage.dir is visible to the machine on which

you generate the token, you can specify the location in the -o argument and the
token file will be saved to the correct location automatically.

The dfc.tokenstorage.dir key is set automatically when the DFC is installed. For
more information about its setting, refer to “Enabling token retrieval by the client
library” on page 280.

284 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.13. Enabling Kerberos Authentication

12.13 Enabling Kerberos Authentication

12.13.1 Overview
Documentum supports Kerberos secure Single-Sign-On (SSO) using Microsoft
Active Server Domain Services for Kerberos Key Distribution Center (KDC) services
in the following ways:

• In a single domain.
• In one-way and two-way trusts between multiple domains.
• In one-way and two-way trusts across forests.

Note: In addition, the DFS client and server must be in the same domain,
whereas Documentum Server can be in a different domain.

Kerberos single sign-on (SSO) is a network authentication protocol designed to

provide strong authentication for client/server applications by using secret-key
cryptography. The Kerberos protocol uses strong cryptography so that a client can
prove its identity to a server (and vice versa) across an insecure network connection.
After a client and the server have used Kerberos to prove their identities, they can
also encrypt all of their communications to ensure privacy and data integrity.

Kerberos provides secure and reliable authentication to multiple applications that

use Kerberos for authentication. In most distributed network systems, a password is
used to prove the identity of user, and this password is transmitted over the
network from the client machine to the machine that the user wants to access. So, a
mechanism that prevents anyone from intercepting or eavesdropping on the
transmitted plain passwords is vital for security. In addition, another pain point
while using passwords for authentication is that the password must be supplied
every time a connection is requested to the remote machine. Kerberos helps users
avoid this issue and solves the central problem of using passwords for
authentication without sending them over the network.

Users are automatically signed in and authenticated based on their Windows

credentials. For example, if Kerberos SSO is configured on a Documentum system,
clients requesting services from the Documentum repository send a service ticket
that the Documentum system uses to validate the clients rather than prompting the
user to provide login credentials.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 285

Chapter 12 Security and Authentication

12.13.1.1 Documentum Kerberos architecture

Kerberos operates by encrypting data with a symmetric key. A symmetric key is a
type of authentication where both the client and server use a single encryption/
decryption key to send or receive data. When working with the encryption key, the
details are sent to a KDC, instead of being sent directly between each computer.

Documentum Server includes a Kerberos authentication plug-in that enables

Kerberos support for KDC services. The Kerberos authentication plug-in is
automatically installed with Documentum Server.

Note: Kerberos SSO authentication is not supported on ACS and BOCS

servers.

This figure describes how Kerberos authentication is used to verify the credentials of
Documentum clients:

Figure 12-3: Kerberos in Documentum environment

On a Documentum system, the Kerberos authentication process involves the

following steps:

1. A Documentum user logs in to a client computer by specifying Windows login

credentials, such as a username and password, and accesses a Documentum
application from the client. The local computer/client sends the login credentials
and the service name of the application to the Key Distribution Center (KDC) for
identification.
2. The Kerberos authentication service/server (AS) component at the KDC receives
the request from the client, verifies whether the client is the computer it claims to
be, and generates a Ticket Granting Ticket (TGT).
3. When the user accesses a Documentum client, the client sends the TGT to the
KDC to obtain a Service Ticket (ST) for the service, using the service SPN.

286 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.13. Enabling Kerberos Authentication

Note: It is mandatory that the SPN of all services are registered in the
KDC. The KDC can provide the Service Ticket only for a registered service.
4. The KDC Ticket Granting Service (TGS) authenticates the TGT and generates an
ST.
5. The client running the Documentum application uses the relevant DFC-based
API and provides the username and ST as password.
6. The Documentum Foundation Classes (DFC) pass the login information to the
Documentum Server service.
7. The Documentum Server service validates the ST and authenticates the user.
8. If authentication is enabled, the Documentum Server service sends the
acknowledged ticket to DFC.
9. DFC sends the acknowledged ticket back to the client to validate the
Documentum Server service. A session is established and no further
authentication is required.

12.13.1.2 Procedure to enable Kerberos SSO

Make sure that you have performed the following tasks:

• You have installed Documentum Server.

• On Windows, you must have manually configured the Data Encryption Standard
(DES), RC4, AES128, and AES256 Kerberos encryption types (security settings)
for Kerberos because they are disabled by default. Make sure that the following
encryption types have been selected:

– DES_CBC_CRC
– DES_CBC_MD5
– RC4_HMAC_MD5
– AES128_HMAC_SHA1
– AES256_HMAC_SHA1

For more information and instructions, see Microsoft documentation.

1. Create one or more Kerberos realms and add all servers and clients that are
participating in Kerberos authentication to those Kerberos realms.
See “Configuring krb5.ini file” on page 288.

2. Create Kerberos users, either manually or by synchronizing with an LDAP

directory server.
See “Creating Kerberos user accounts” on page 288.

3. Configure the service principal name (SPN) of repository in the Active

Directory and generate a *.keytab file.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 287

Chapter 12 Security and Authentication

See “Configuring a service principal name of repository and *.keytab file”

on page 289.

4. (Optional) Configure Kerberos on Documentum Servers on Linux. See

“Configuring Kerberos for Documentum Server on Linux” on page 292.

12.13.1.2.1 Creating Kerberos user accounts

Kerberos SSO can only authenticate users who are registered as Kerberos users in
the Active Directory and in a repository.

To create Kerberos users for a repository, perform one of the following tasks:

• Create the user account manually in the Active Directory and repository.
• Synchronize the users from the Active Directory using LDAP synchronization,
then modify the LDAP configuration object.

12.13.1.2.1. Creating Kerberos users in a repository

1

Only the installation owner, system administrator, or superuser can create users in a
repository. If an LDAP server authenticates a user, only a superuser can modify the
user’s LDAP-mapped attributes.

There are two options for creating Kerberos users in the repository.

• Create the user manually, both in Active Directory and in the repository. For
each user in the repository, set the User Source property to dm_krb or leave it
blank. Setting the User Source property to dm_krb is optional.
• Synchronize the users from Active Directory using LDAP synchronization, then
modify the User Login Domain in the LDAP configuration object, as described
in “Configuring LDAP synchronization for Kerberos users” on page 173.

12.13.1.2.2 Configuring krb5.ini file

Create the krb5.ini file as follows:

Note: This file is typically created in C:\Windows.

[libdefaults]
default_realm = <REALM>
forwardable = true
ticket_lifetime = 24h
clockskew = 72000
default_tkt_enctypes = <ticket encryption standards>
default_tgs_enctypes = <ticket granting server encryption standards>

[realms]
<REALM> = {
kdc = <kdc_server_ip>
admin_server = <admin_server_ip>
}

[domain_realm]

288 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.13. Enabling Kerberos Authentication

<domain> = <REALM>

[logging]
default = c:\kdc.log
kdc = c:\kdc.log

[appdefaults]
autologin = true
forward = true
forwardable = true
encrypt = true

<kdc_server_ip> The IP address of the KDC server.

<admin_server_ip> The IP address of the Administration server.
<domain> The domain in which the SPN of
Documentum Server resides.
<REALM> The realm name. For example: MYDOMAIN.
MYCORP.COM
<ticket encryption standards> The encryption standard entries. For
example, aes128-cts.
<ticket granting server encryption standards>

12.13.1.2.3 Configuring a service principal name of repository and *.keytab file

To enable authentication of the repository on the Kerberos Key Distribution Center

(KDC), register the service principal name (SPN) of repository on the Active Server
KDC using the Microsoft ktpass utility. A Kerberos SPN uniquely identifies a
service that uses Kerberos authentication. In this case, the service is your
Documentum Server repository. Executing the ktpass utility also generates a
*.keytab file. The *.keytab file contains name or value pairs consisting of SPN of a
repository and a long-term key derived from a password. Both the Documentum
Server and the KDC must be able to access the *.keytab file. The syntax of the
filename is:
<repo_name>.<xxxx>.keytab

Note: The length of the *.keytab filename is limited by the operating system.

where:

• <repo_name> is the name of the repository for which the SPN of repository is
registered.
• <xxxx> is a string that makes the file name unique.

The filename must be unique because Documentum Server can be registered in

multiple, trusted domains.

Note: Although the *.keytab file is usually used on non-Windows machines,

Documentum Server leverages the *.keytab file to improve network
performance by eliminating Kerberos authentication communication between
Windows machines and the KDC.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 289

Chapter 12 Security and Authentication

12.13.1.2.3. Mapping the SPN of repository to a user name

1

You must configure a unique SPN for each repository. It is recommended to use the
following SPN syntax for registering a repository on the KDC service.

Forest Configuration SPN

Two-way trust within the same forest <service-class>/<repository-name>

<service-class>/<repository-
name>@<service-domain-name>
The SPN name format is not mandated to have CS/<repository-name>@<service-domain-
name> format but it is recommended. For example: The SPN name can be documentum/
hostname@<service-domain-name>. Only mandatory step for the new format is that
repository names have to be mapped with the corresponding SPN names as specified in
dfc.properties. Documentum Foundation Classes Development Guide describes how to
specify the repository-name SPN name mappings.

For example:
CS/[email protected]

where:

• CS is the service class.

• REPO1 is the repository name.
• MYDOMAIN.COM is the domain in which the SPN of Documentum Server is to be
registered.

12.13.1.2.3. Creating the *.keytab file for the repository

2

In the following procedures a user is registered on the KDC service to act as the
service principal for the repository service. This user maps to the SPN of repository
itself yet is distinct from users who need to be authenticated to use the service.

There are two recommended procedures for registering repository SPNs. The
simplest approach is to create SPN of a single repository mapped to a single Active
Directory user, which enables you to set a single password for the SPN of repository.
An alternate approach is to register multiple repository SPNs mapped to a the same,
single Active Directory user.

To map SPN of repository to a user name:

Notes

• For the ktpass utility syntax, see Microsoft documentation.

• For more information about the setspn command, see Microsoft
documentation.

290 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.13. Enabling Kerberos Authentication

1. Log in to the machine that runs the KDC service.

2. Create a user in the Active Directory.

3. To map the SPN of repository to the user name specified in Step 2 using a one-
to-one mapping, perform the following steps:

a. Execute the ktpass utility with the user specified in Step 2 as follows:

Note: For a one-to-one mapping, do not map the same repository

SPN to more than one user account.

For example:
ktpass /pass testpass
-out c:\Nag\REPO66.2008.keytab
-princ CS/[email protected]
/kvno 7 -crypto RC4-HMAC-NT +DumpSalt
-ptype KRB5_NT_SRV_HST /mapOp set /mapUser rcfkrbuser33

b. To restrict Kerberos delegation privileges for the new user, execute the
setspn command using the following syntax:
setspn -A CS/<reponame>@domain.com domain.com\<documentum_server_username>

On User Properties > Delegation of new user, select the Do not trust this
user for delegation checkbox.
c. Copy the *.keytab file to $DOCUMENTUM/dba/auth/Kerberos on the
Documentum Server.

Note: This folder was created during Documentum Server

installation.

4. To map multiple repository SPNs to the same user name using many-to-one
mapping, perform the following steps:

a. Set the SPN of a repository and create the *.keytab file using ktpass
utility with the user specified in Step 2.
Remember the salt string and the key version number (vno) because you
need to use them in Step 4.c.
For example:
ktpass /pass testpass
-out c:\Nag\REPO66.2008.keytab
-princ CS/[email protected]
/kvno 7 -crypto RC4-HMAC-NT +DumpSalt
-ptype KRB5_NT_SRV_HST /mapOp set /mapUser rcfkrbuser33

b. Set the SPN of another repository using the setspn utility to the same user
(<documentum_server_username> in the following syntax) created in Step
2. For example:
setspn -A CS/<reponame>@domain.com domain.com\<documentum_server_username>

On User Properties > Delegation of new user, select the Trust this user for
delegation to any service (Kerberos only) checkbox.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 291

Chapter 12 Security and Authentication

c. Execute the ktpass utility for the SPN of second repository without setting
the user specified in Step 2.
Use the salt and key version number (kvno) that were created in Step 4.a.
For example:
ktpass /pass testpass
-out c:\Nag\REPO66.2008_2.keytab
-princ CS/[email protected]
/kvno 7 -crypto RC4-HMAC-NT +DumpSalt
-ptype KRB5_NT_SRV_HST /mapOp set
-in c:\Nag\REPO66.2008.keytab

d. Repeat Step 4.b and Step 4.c for SPN of each additional repository.
e. Copy the *.keytab file to $DOCUMENTUM/dba/auth/Kerberos on the
Documentum Server host.

Note: This folder was created during Documentum Server

installation.

5. Reinitialize the Documentum Server.

See “Reinitializing Documentum Server” on page 293.

12.13.1.2.4 Configuring Kerberos for Documentum Server on Linux

1. Specify the Linux machines in the Active Directory machine domain in the /
etc/krb5.conf file as follows:
[libdefaults]
default_realm = <REALM>
forwardable = true
ticket_lifetime = 24h
clockskew = 72000
default_tkt_enctypes =
default_tgs_enctypes =

[realms]
<REALM> = {
kdc = <kdc_server_ip>
admin_server = <admin_server_ip>
}

[domain_realm]
<domain> = <REALM>

[logging]
default = c:\kdc.log
kdc = c:\kdc.log

[appdefaults]
autologin = true
forward = true
forwardable = true
encrypt = true

<kdc_server_ip> The IP address of the KDC server.

<admin_server_ip> The IP address of the Administration
server.
<domain> The domain in which the SPN of
Documentum Server resides.

292 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.14. Enabling SAML Authentication

<REALM> The realm name. For example:

MYDOMAIN.MYCORP.COM

2. Copy the *.keytab files to $DOCUMENTUM/dba/auth/kerberos and restart the

repository using the following command:
/dm_start_(docbasename) -otrace_authentication

This command enables authentication trace in the dm_krb_docbasename.log

file.

3. Set the encryption standard entries in the /etc/krb5.conf file.

4. Reinitialize the Documentum Server.

See “Reinitializing Documentum Server” on page 293.

12.13.1.2.5 Reinitializing Documentum Server

Reinitializing the Documentum Server initializes the Kerberos plug-in, which

reloads the SPNs from the repository’s *.keytab file. This command enables you to
update the Kerberos system without restarting Documentum Server. Reinitialization
is required if a new SPN has been registered and copied to the repository. However,
this step is not required if you have changed the password on an existing SPN.

In Documentum Administrator, on Server Configuration Properties > Info, select

Re-Initialize Server.

12.14 Enabling SAML Authentication

12.14.1 Overview
Documentum supports Security Assertion Markup Language (SAML) using
Microsoft Active Directory Federation Services (AD FS) 2.0. You must install and
configure AD FS 2.0 to enable SAML authentication.

The SAML 2.0 is an XML-based framework that allows identity and security
information to be shared across security domains. The SAML specification, while
primarily is targeted at providing cross-domain web browser single sign-on, is also
designed to be modular and extensible to facilitate use in other SSO contexts.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 293

Chapter 12 Security and Authentication

12.14.2 Documentum SAML architecture

SAML authentication plugin is deployed in JMS of Documentum Server as a servlet.
Clients uses the existing DFC Authentication APIs to authenticate the SAML token
by prefixing it with dm_saml=. Documentum Server checks for the prefix and if
available, calls SAML authentication module through DO_POST to JMS. Servlet
validates the token and either returns saml_authentication = true or
saml_authentication = false. Based on the response, Documentum Server either
provides or denies the request to the session.

Properties file for SAML in Documentum Server is available at the following

location: %DOCUMENTUM%\<WildFly version folder>\server\
DctmServer_MethodServer\deployments\ServerApps.ear\
SAMLAuthentication.war\WEB-INF\classes

• log4j.properties where SAMLAuthentication log file location can be specified.

• saml.properties that has the following parameters:

– <stackTrace>: Set the value to true if stackTrace is required in log file in case of
failure. The default value is false.
– <certPath>: Path where token signing certificate from SAML server has to be
placed in Documentum Server. Default path for Windows is C:/SAML/cert.
For Linux, set the appropriate certificate path.
– <responseSkew>: Maximum time difference allowed between Documentum
Server and Active Directory machine in seconds. The default value is 60
seconds.

Sample web applications can be provided separately if you want to test the basic
SAML functionalities. You must contact Engineering for guidance on deploying and
testing the application.

The following figure describes how SAML authentication is used to verify the
credentials of Documentum clients:

294 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 12.14. Enabling SAML Authentication

Figure 12-4: SAML in a Documentum environment

12.14.3 Configuring Name ID

Each user must have their own SAML assertion for authentication. To achieve this,
configure Name ID in AD FS.

1. Click Edit Claim Rules in AD FS.

2. In Issuance Transform Rules, click Add Rule.
3. Select the LDAP and add the two attributes for the following outgoing claim
types: Windows account name and Name ID

12.14.4 Configuring for encrypted assertions

1. Generate the public-private key pair or use the existing keys generated for SSL
communication.
2. Import the public key certificate using the options in Microsoft AD FS. Microsoft
documentation contains the information.
3. Use the following command to convert private key to the PKCS8 DER format:
openssl pkcs8 -topk8 -inform PEM -outform DER -nocrypt
-in adfs.key -out adfs.pk8

4. Copy the PKCS8 file from Step 3 in the location configured in <certPath> under
saml.properties.

5. Run the following command to enable encryption at Documentum Server:

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 295

Chapter 12 Security and Authentication

Set-ADFSRelyingPartyTrust -TargetName saml -EncryptClaims $true

12.14.5 Troubleshooting
Tracing can be done at two levels:

• Documentum Server:
apply,c,NULL,SET_OPTIONS,OPTION,S,trace_http_post,VALUE,B,T
apply,c,NULL,SET_OPTIONS,OPTION,S,rpctrace,VALUE,B,T
apply,c,NULL,SET_OPTIONS,OPTION,S,trace_authentication,VALUE,B,T

• Servlet: Check the log file location mentioned in log4j.properties for

information on the validation results.

296 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 13

Logging and Tracing

13.1 Introduction
Documentum supports tracing and logging facilities for both Documentum Server
and DFC operations. The logging facilities record information generated
automatically by Documentum Server or DFC, including error, warning, and
informational messages. Logging errors, warnings, and informational messages
occurs automatically.

The tracing facility records information that is explicitly requested by user or an

application. Enabling or disabling tracing requires system administrator or
superuser privileges.

13.2 Documentum Server logging and tracing

Documentum Server logging and tracing provides information about Documentum
Server operations. Documentum Server records logging information and tracing
information, with a few exceptions, in the following files:

• Repository log file

Contains information about root server activities. This file is also sometimes
referred as the Documentum Server log file.

• Session log files

Contains all informational, warning, error, and fatal error messages and, by
default, all SQL commands generated from DQL commands.
Session log files are stored in the %DOCUMENTUM%\dba\log
\<hex_repository_id>\<username> ($DOCUMENTUM/dba/log/<hex_repository_id>/
<username>) directory, where <hex_repository_id> is the repository ID expressed as
a hexadecimal value and <username> is the account under which the session is
running. The session log name is the session ID. The server creates a separate
session log for each new connection.
Sessions that are connected to the primary Documentum Server create their
session logs under the primary server and sessions that are connected to one or
more RCS create their session logs under the remote server(s). Because sessions
are assigned using a round-robin method, look in both places for session logs.

Some features, such as jobs, record tracing and logging information in log files
specific to those features. The sections that describes those features contain more
details about the associated log files.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 297

Chapter 13 Logging and Tracing

13.2.1 Tracing from the startup command line

A variety of tracing operations can be initiated from the Documentum Server startup
command line. To start tracing at server start-up, specify the trace flags for the
options with the -o option 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, add the -o option to the command line by editing the
Documentum Server service entry.

The following table describes the trace flags for the -o option at server start-up. The
generated trace information is recorded in the repository log file.

Table 13-1: Server start-up trace options

Option name Description
crypto_trace Cryptography information.
debug Session shutdown, change check, launch and
fork information.
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,
SSL, connection ID, client host address, and
client host name).
ossl_trace SSL communication information.
rpctrace Turns on tracing of RPC calls.
sqltrace SQL commands sent to the underlying
RDBMS for subsequent sessions, including
the repository session ID and 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 keys and operations using single-
use login tickets.
trace_authentication Detailed authentication information.
trace_complete_launch Linux 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
server command line and then stop and restart the server.

298 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 13.2. Documentum Server logging and tracing

13.2.2 Using the setServerTraceLevel method

The setServerTraceLevel method is defined for the DFC IDfSession interface. The
method takes two arguments, a trace level, defined as an integer value, and a facility
name. The following table describes the trace levels for the setServerTracelLevel
method.

Table 13-2: Trace level severity values

Severity level Meaning

0 No messages, tracing is turned off. Use this
value to turn off tracing for the specified
facility.
1 Level 1 trace messages
2 Level 2 trace messages
3 Level 3 trace messages
4 Level 4 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 also
receive all the other messages specified by the lower levels in addition to the timing
information.

Note: The severity levels are also applicable for -Ftrace_level and -Ltrace_level
arguments.

The following table describes the facilities for the setServerTraceLevel method.

Table 13-3: Valid facilities for setServerTraceLevel

Facility Description
ALL Traces all available trace facilities.
DM_CONTENT Traces content operations. The information is
recorded in the session log file.
DM_DUMP Traces dump operations. The information is
recorded in the session log file.
DM_LOAD Traces load operations. The information is
recorded in the session log file.
DM_QUERY Traces query operations. The information is
recorded in the session log file.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 299

Chapter 13 Logging and Tracing

Facility Description
SQL_TRACE Traces generated SQL statements. The
information is recorded in the session log
file.

Tracing for this facility is turned on by

default. Turning it off is not recommended
by OpenText Global Technical Services.
DM_SYSOBJECT Traces SysObject operations. The information
is recorded in the session log file.

13.2.3 Using the SET_OPTIONS method

The SET_OPTIONS administration method controls wide range of Documentum
Server tracing options, including tracing Centera and NetApp SnapLock storage
area operations, digital shredding operations, and connection broker information.
The “SET_OPTIONS” on page 364 section contains a complete list of the trace
options for the SET_OPTIONS method.

The method can be executed from Documentum Administrator or using the DQL
EXECUTE statement or an IDfSession.apply method.

Turning tracing on and off using SET_OPTIONS affects only new sessions. Current
sessions are not affected.

13.2.4 Examples of server tracing

The following example describes a section from the server log 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 describes a log file section for query tracing. The example
assumes that the following query is issued:
SELECT "user_os_name" FROM "dm_user" WHERE "user_name"='zhan'

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:

300 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 13.3. DFC logging

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

13.2.5 Determining active tracing options

To determine whether a particular Documentum Server tracing option is enabled,
use an IDfSession.isServerTraceOptionSet method with the name of the option as the
method argument. For example, to determine if the docbroker_trace tracing option is
enabled, specify the option name as the method argument.

You cannot specify a facility name with the isServerTraceOptionSet method.

13.3 DFC logging

DFC logging and the location of the log file is controlled by the log4j.properties file.
The default location is ${user.dir}/documentum/logs/documentum.log.

The standard Java documentation contains the information on the configurable

logging options.

To record debug information generated by specific packages or classes, we

recommend to use the DFC trace file, rather than the log4j log file, as described in
“Directing categories to the trace file” on page 309.

13.4 DFC tracing

DFC supports a set of tracing configuration options for DFC operations, such as
tracing for individual users, individual threads, and methods. The trace file format
can be configured as well, such as timestamps within the file and how to record
method entrances and exits.

All DFC tracing is configured in the dfc.properties file. The entries are dynamic.
Adding, removing, or changing a tracing key entry is effective immediately without
having to stop and restart DFC or the application.

13.4.1 Enabling DFC tracing

DFC tracing options are configured in the dfc.properties file.

To enable DFC tracing:

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

2. Modify the tracing properties by changing the key values, as desired.

3. Change the dfc.tracing.enable key to true to start tracing:

dfc.tracing.enable=true

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 301

Chapter 13 Logging and Tracing

Trace log file names have the following format:

<file_prefix>[.<identifier>].<timestamp>.log

Where file_prefix is a string that is prepended to the beginning of the name of each
trace file generated by DFC and timestamp records when the file was created. An
identifier is included in the file name only if you are generating log files for
individual users or threads. The identifier is the user name, if the logs are generated
for individual users or the thread name, if logs are generated for individual threads.

Enabling tracing creates a logger and a logging appender that record the entries in
the trace log file. The logging appender determines the name, location, and format of
the trace file. The “Logging appender options” on page 302 section contains more
information.

13.4.2 Logging appender options

The logging appender controls various trace file options, such as the name, location,
and format of the trace file. The following table describes the appender options.

Table 13-4: Logging appender configuration options

Key Option Description

dfc.tracing.date_format Date format for timestamp Defines a date format if
dfc.tracing.timing_style, in
dfc.properties, is set to date.
The “Defining the trace file
timestamp format”
on page 304 section contains
more information.
dfc.tracing.dir Location of file The directory where the trace
file is stored.

The default location is $

{dfc.data.dir}/logs.

Valid values for this property

are any valid directory path.
dfc.tracing.file_creation_mod Creation mode Controls whether trace
e information is logged in one
file or multiple files. The
“Defining file creation mode”
on page 303 section contains
more information.
dfc.tracing.file_prefix File name prefix Defines the base name of the
trace file. The default value is
dfctrace.

302 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 13.4. DFC tracing

Key Option Description

dfc.tracing.max_backup_inde Maximum number of A positive integer value that
x backups for the file defines the number of back-
up files the logger retains for
the log file. When the
maximum number is
reached, the oldest backup is
destroyed when a new back-
up is created.

The default value is 1.

dfc.tracing.max_file_size Maximum file size An integer value that defines
the maximum size of a trace
file before it is rolled over.
Valid values are any string
accepted by log4j as
MaxFileSize.

If no unit of measure is
specified, the integer value is
interpreted as bytes.

The default size is 100 MB.

13.4.3 Defining file creation mode

The dfc.tracing.file_creation_mode key controls whether the log entries are recorded
in one or several log files. By default all DFC trace entries are recorded in one log
file. The following table describes all valid values for dfc.tracing.file_creation_mode
key.

Table 13-5: Valid values for the dfc.tracing.file_creation_mode key

Value Description
standard All log entries are recorded in one log file.
This is the default.
thread DFC creates a log file for each thread in the
following format:
<file_prefix>.<threadname>.<timestamp>.log

Tracing by thread is only recommended in

combination with the
dfc.tracing.thread_name_filter key.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 303

Chapter 13 Logging and Tracing

Value Description
user DFC creates a log file for each user in the
following format:
<file_prefix>.<username>|
default.<timestamp>.log

If the a user cannot be determined for a

particular call, the trace is logged in a
separate default log file.

Tracing by user is only recommended in

combination with the
dfc.tracing.user_names_filter key.

13.4.4 Defining the trace file timestamp format

Each entry in a log file has a timestamp. If the file is recorded in compact mode,
there are two columns for the timestamp. The first column records the entry time
and the second column records the duration of the method call, the difference
between method entry and method exit time. If the log file is recorded in standard
mode, there is one column for the timestamp in the entry. The value recorded is
either the entry time or the exit time, depending on whether the log entry is
recording the method entry or exit.

By default, timestamps are expressed in seconds. You can configure the timestamp
display using the dfc.tracing.timing_style key. The following table describes the
valid values for dfc.tracing.timing_style.

Table 13-6: Valid values for dfc.tracing.timing_style

Value Description
nanoseconds The timestamp value is expressed in
nanoseconds.

Whether the timestamp values are actually

returned in nanoseconds depends on the
underlying operating system. The values
cannot be correlated to absolute time.
milliseconds The timestamp value is expressed in
milliseconds.
milliseconds_from_start The timestamp is recorded as the number of
milliseconds from the start of the JVM
process.
seconds The timestamp value is displayed as the
number of seconds from the start of the
process. The value is a float.

This is the default timing style.

304 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 13.4. DFC tracing

Value Description
date The timestamp value is displayed as a date
string. The default format is:
yyyy/MM/dd-HH:mm:ss.S

(The Javadocs contains the information for

the SimpleDateFormat class.)

The date setting is only used if

dfc.tracing.mode is set to standard. If you set
dfc.tracing.timing_style to date and the mode
is compact, the timing style defaults to
milliseconds.

If the timing style is set to date, you can also

set dfc.tracing.date_format key and
dfc.tracing.date_format_width key to define
an alternate date format, as described in
“Defining the date format” on page 305t.

13.4.4.1 Defining the date format

There are three keys that determine the date format in a trace file:

• dfc.tracing.timing_style
If the key value is date, the date format and column width can be specified in the
dfc.tracing.date_format and dfc.tracing.date_column_width keys.
• dfc.tracing.date_format
Specifies a date format that is different from that default format. The specified
format specify must conform to the syntax supported by the Java class
java.text.SimpleDateFormat.
• dfc.tracing.date_column_width
This key specifies the column width as a positive integer value. The default
column width is 14. If the format specified in dfc.tracing.date_format is wider
than 14 characters, modify the column width to the required number of
characters.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 305

Chapter 13 Logging and Tracing

13.4.5 Configuring method tracing

The following keys control method tracing:

• dfc.tracing.max_stack_depth
This key controls the depth of tracing into the DFC call stack. The default value
for this key is 1, meaning only the first method call in a DFC stack is traced. A
value of -1 means that all levels of method calls are traced.
• dfc.tracing.mode
This key controls how the method entry and exit is recorded in the log file. Valid
values are:

– compact: DFC adds one line to the file that records both entry and exit and
return value for a method. The methods are logged in the order of method
entrance. DFC buffers the log entries for a sequence of method calls until the
topmost method returns.
– standard: DFC creates one line in the file for a method entry and one line for a
method exit. The log entries for exit record the return values of the methods.

The default value is compact.

• dfc.tracing.method_name_filter[n]
This key specifies tracing for packages, classes, and methods. The key is a
repeating key, that allows multiple entries in the dfc.properties file. Each entry
has one value, specifying a package, class or method. Like repeating repository
properties, each dfc.tracing.method_name_filter entry is referenced using a
square-bracketed integer, with the first entry beginning with zero. For example:
dfc.tracing.method_name_filter[0]=<value>
dfc.tracing.method_name_filter[1]=<value>
dfc.tracing.method_name_filter[2]=<value>

Where <value> is one or more string expressions that identify what to trace. The
syntax of the expression is:
([<qualified_classname_segment>][*]|*)[.[<method_name_segment>][*]()]

For example, the value com.documentum.fc.client.DfPersistentObject traces all

methods on DfPersistentObject and any lower level calls made within the context
of those methods

306 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 13.4. DFC tracing

13.4.6 Tracing users by name

The dfc.tracing.user_name_filter key traces users. The key is a repeating key that
allows multiple entries in the dfc.properties file. Each entry specifies one regular
expression that identifies the user or users to trace. Each dfc.tracing.user_name_filter
entry is referenced using an integer in brackets, the first entry beginning at zero.

For example:
dfc.tracing.user_name_filter[0]=<expression>
dfc.tracing.user_name_filter[1]=<expression>
dfc.tracing.user_name_filter[2]=<expression>

The expression is a regular expression, using the syntax for a regular expression as
defined in the Java class java.util.regex.Pattern. DFC traces activities of the users
whose login names (dm_user.user_login_name) match the specified expression. The
log entries contain the user name. By default, dfc.tracing.user_name_filter key
empty, which means that all users are traced.

The tracing output does not necessarily include all DFC calls made by a particular
user. For some calls, it is not possible to identify the user. For example, most
methods on the DfClient interface are unrelated to a specific session or session
manager. Consequently, when tracing 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 IDfSessionManager.
• An IDfSessionManager method call that sets or gets an IDfLoginInfo object.

13.4.7 Tracing threads by name

To trace specific threads, set the dfc.tracing.thread_name_filter key. The key is a
repeating 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. Each
dfc.tracing.thread_name_filter entry is referenced using an integer in brackets, the
first entry beginning at zero.

For example:
dfc.tracing.thread_name_filter[0]=<expression>
dfc.tracing.thread_name_filter[1]=<expression>
dfc.tracing.thread_name_filter[2]=<expression>

Each dfc.tracing.thread_name_filter entry is set to a regular expression that identifies

a thread or threads you want to trace. The regular expression must use the syntax
for a regular expression defined in the Java class java.util.regex.Pattern.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 307

Chapter 13 Logging and Tracing

The key is not set by default, which means that all methods in all traced threads are
traced by default. Setting the key is primarily useful for standalone DFC-based
applications that may spawn DFC worker threads.

Note: You can use dfc.tracing.file_creation_mode to further sort the entries for
each thread into separate files. The “Defining file creation mode” on page 303
section contains more information.

13.4.8 Including the session ID

By default, log entries contain the user name associated with the logged operation.
To include a session ID with each entry, enable the dfc.tracing.include_session_id.
key by setting the Boolean value to true. By default, the key is disabled. Enabling the
key instructs DFC tracing to add the session ID and the identity hash code of the
associated session manager to the log entries. The session ID has the format s<n>,
where s is an abbreviation for session and <n> is the session number.

13.4.9 Tracing RPC calls

There are two keys that control RPC call tracing:

• dfc.tracing.include_rpc_count
This Boolean key instructs DFC to add an additional column to each log file entry
that records the current RPC call count for the associated session. The logged
value is N/A if DFC cannot determine the session. If the mode is set to compact,
the logged RPC count is the count at the time the method exits. The default value
for the key is false.
• dfc.tracing.include_rpcs
This Boolean key instructs DFC to include a separate line in the trace file for each
executed RPC call. The default value for this key is false.

13.4.10 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. To obtain an exact
stack trace for an exception, enable the dfc.tracing.print_exception_stack key by
setting the key value to true.

If the key is enabled, the tracing facility logs the entire stack trace for the exception.
The stack trace is recorded immediately following the line that logs the exit of the
method that caused the exception. The trace is indented and prefixed with
exclamation marks.

The default value for this key is false.

308 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 13.4. DFC tracing

13.4.11 Setting verbosity

The dfc.tracing.verbosity key determines what set of classes are traced. By default,
the key is disabled (false) and traces a standard set of classes. When enabled (true)
the key traces and additional set of low-level classes. Tracing these classes greatly
increases the number of entries in the trace file and can noticeably slow down the
system. Turning on verbose mode is only recommended when suggested by
Documentum Support.

13.4.12 Directing categories to the trace file

In a log4j.properties file, categories can be defined as the target of logging
operations. For DFC, a category specification would typically be a class or package.
However, it is recommended to record that information in the trace file generated by
the dfc.properties tracing facility, especially, when tracing a DFC class or package at
the DEBUG level.

The following dfc.properties keys can be used to redirect the trace:

• dfc.tracing.log.category
This key specifies the category that are traced. The key is a repeating key that can
have multiple entries in the dfc.properties file. Each entry has one value that
specifies a category. Each dfc.tracing.log.category entry is referenced using an
integer in brackets, with the first entry beginning at zero. For example:
dfc.tracing.log.category[0]=<class_or_package_name>
dfc.tracing.log.category[1]=<class_or_package_name>

• dfc.tracing.log.level
This key specifies the level of tracing. The dfc.tracing.log.level key defaults to
DEBUG if not specified.
• dfc.tracing.log.additivity
This key is the additivity setting for the category. The dfc.tracing.log.additivity
key defaults to 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
for category identified at the corresponding index position in
dfc.tracing.log.category.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 309

Chapter 13 Logging and Tracing

13.4.13 Log file entry format

The log files store trace information 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>

The following table describes the entries in a log file.

Table 13-7: Log entry components

Component Description
timestamp The timestamp of the entry. The format
dependents on the tracing configuration, as
defined in the dfc.tracing.timing_style key.
method_duration The total length of time to execute the
method. This value is only included if the
dfc.tracing.mode key value is 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 entry is only included if the
dfc.tracing.include_session_id key enabled
(true).
session_mgr_id The hash code identity of the session
manager associated with the entry. This
entry is only included if the
dfc.tracing.include_session_id key is enabled
(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 set to true.

310 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 13.4. DFC tracing

Component Description
entry_exit_designation Keyword that identifies source of the log
entry. The keyword is only included if the
dfc.tracing.mode key value is standard.
Valid values are:
• ENTER: The entry records a method
entry.
• EXIT: The entry records a method exit.
• !EXC!: The entry records a call that results
in an exception.
• RPC_ENTER: The entry records an RPC
call entry.
• RPC_EXIT: The entry records an RPC call
exit.
stack_depth_indicator Indicates the depth of call stack tracing. The
stack depth indicator 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 the log entry.
method Name of the traced method.
method_arguments Arguments to the specified method.
return_value The value returned by the method. This
entry is included if the dfc.tracing.mode
value is compactor if the entry records the
method exit.
exception The exception name and message, if any, of
the exception thrown by the method.

The values in each column in an entry are separated by spaces, not tabs.

13.4.14 Trace file examples

The following examples describe trace files generated by various combinations of
property settings. Due to space limitations on the page, the individual entries are
line-wrapped in these examples.

Example 13-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

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 311

Chapter 13 Logging and Tracing

Example 13-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 13-3: Settings are: dfc.tracing.enable=true;

dfc.tracing.thread_name_filter=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@618b08
1158718491150 <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 13-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()

312 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 14
Audit Management

14.1 Auditing
Auditing is a security feature for monitoring events that occur in a repository or
application. Auditing an event creates an audit trail, a history in the repository of the
occurrence of the event. Audit information can be used 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 users.
• Record all occurrences of a particular event on a given object or given object type
• Record all occurrences of a particular event in the repository, regardless of the
object to which it occurs
• Record all workflow-related events in the repository
• Record all occurrences of a particular workflow event for all workflows started
from a given process definition
• Record all executions of a particular job
• Record all events in the repository

Note: Audit management requires extended user privileges.

Auditing is managed on the Audit Management page, which can be accessed by

selecting Administration > Audit Management.

14.2 Audit events

An event is something that happens to an object in the repository or an operation
defined as an event by a user-written application. There are two types of events:

• System events
System events are events that Documentum Server recognizes and can audit
automatically. For example, checking in a document can be an audited system
event.
Documentum Server provides automatic auditing for any system event. When an
audited system event occurs, Documentum Server automatically generates the
audit trail entry. Documentum provides a large set of system events that are
associated with API methods, lifecycles (business policies), workflows, and jobs.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 313

Chapter 14 Audit Management

For a complete list of auditable system events, see Appendix A, System Events
on page 619.
• Application events
Application events are events that are recognized and audited by client
applications. For example, a user opening a particular dialog can be an audited
application event. To audit application events, an application must recognize
when the event occurs and create the audit trail entry programmatically.
Application events are not recognized by Documentum Server.

14.3 Audit trails

An audit trail is a recorded history of event occurrences that have been marked for
auditing. Each occurrence is recorded in one audit trail record. The server stores audit
trail records as objects in the repository. Depending on the event, the objects are
dm_audittrail, dm_audittrail_acl, or dm_audittrail_group objects. Auditing an event
stores pertinent data in the audit trail object, such as when the event occurred and
what object was involved.

Audit trail entries are generated after auditing is set up and can consume
considerable space in the repository. Therefore audit trail entries should be removed
from the repository periodically.

14.4 Audit properties

Object properties are audited if the properties are registered for auditing. After the
properties are registered, the property name and new value are recorded in the
attribute_list property of the audit trail entry. Old property values are only included
automatically if the audit_old_values property in the repository configuration object
is enabled. The property name and old value are recorded in the attribute_list_old
property of the audit trail entry. The audit_old_values property is enabled by
default. If the audit_old_values property is disabled, the audit trail entry does not
record changes to properties unless they are specifically registered for auditing
when the event is registered.

Aspect attributes can also be audited. Aspect attribute audits record the aspect
attribute changes attached to an object along with the object type attributes.
Auditing is available for aspect attributes attached to SysObject, user, group, and acl
objects, and any of their associated subtypes. Auditing aspect attributes requires that
auditing is also enabled for the object type or subtype.

Note: For repositories created on RDBMS platforms with a page size of less
than 8K, the audit_old_values property is always disabled and cannot be
enabled.

314 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.5. Events audited by default

14.5 Events audited by default

Documentum Server audits the following events by default:

• dm_audit and dm_unaudit

All executions of methods that register or unregister events for auditing.
• dm_signoff
All executions of a IDfPersistentObject.signoff method.
• dm_adddigsignature
All executions of an addDigitalSignature method. By default, audit trail entries
created for the dm_adddigsignature event are not signed by Documentum
Server. To sign those entries, register the event explicitly for auditing and set the
argument to require signing.
• dm_addesignature and dm_addesignature_failed
All executions, successful or unsuccessful of an addESignature method. The
audit trail entries for the dm_addesignature event are signed by Documentum
Server automatically.
• dm_purgeaudit
Removal of an audit trail entry from the repository. A dm_purgeaudit event is
generated whenever a destroy method is executed to remove an audit trail entry
from the repository or a PURGE_AUDIT administration method is executed. All
dm_purgeaudit events are audited.
• User login failure
• dm_default_set
A default set of events on objects of type dm_document and its subtypes. This
event is registered against the repository configuration object, and Documentum
Server audits the events in the set for dm_document type and its subtypes.
“Events audited by the dm_default_event” on page 315, describes the events
that are included in this set.
Table 14-1: Events audited by the dm_default_event

Object type Audited events

dm_docbase_config dm_archive dm_checkin dm_restore
dm_assembl dm_checkou dm_save
e t
dm_bp_atta dm_destroy dm_setfile
ch
dm_bp_dem dm_freeze dm_signoff
ote
dm_bp_pro dm_link dm_unfreez
mote e

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 315

Chapter 14 Audit Management

Object type Audited events

dm_bp_resu dm_lock dm_unlink
me
dm_bp_susp dm_mark dm_unlock
end
dm_branch dm_prune

14.5.1 Disabling or modifying default auditing

With the exception of user login failure and the dm_default_set events, default
auditing cannot be disabled because there are no default registry objects for these
events. Turning off auditing of the dm_default_set event for the repository
configuration type turns off auditing of all events represented by the dm_default_set
event.

Default auditing can be modified by registering against the events audited by

default. Documentum Server creates the audit trail entry based on the criteria that
are defined for the event and target. When the registration is removed,
Documentum Server returns to creating the default audit trail entry for the event
and target.

14.6 Auditing by object type

Auditing by object type creates audit trails for events for all objects of a particular
type. You can select the types, restrict the set of objects on which audit trails are
created, and select the events.

You can set audits only for one object type at a time. Complete these instructions for
each object type you audit.

You must have Config Audit privileges to use this function.

316 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.6. Auditing by object type

Table 14-2: Object auditing properties

Field Description
Application Code Enter the application code to audit only
objects with a particular application code.

The application code is a property set by the

client application that creates the object. For
example, an application sets the application
code to the value Internal. To audit objects of
the type you selected with application code
Internal, type Internal in the Application
Code field.

You cannot enter a value in the field if you

previously selected a dm_user, dm_acl, or
dm_group object type.
Lifecycle Records objects that are attached to a
lifecycle. Click Select Lifecycleto access the
Choose a lifecycle page.

Select the correct lifecycle and then click OK.

State Records only those objects attached to the
lifecycle and in a particular state. Select a
state from the drop-down list.
Attributes Records the values of particular properties of
the object in the audit trail. Click Select
Attributes to access the Choose an attribute
page.

Select the properties whose values you want

to record, click >, then click Add. To remove
any properties, select them on the right-hand
side of the page and click <.

Click OK when you are finished.

Has signature manifested Select to sign the audit trail.
Include all subtypes Select to include all subtypes of the audited
object type.
Authentication required Select to require authentication for custom
(user-defined) events that are audited.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 317

Chapter 14 Audit Management

Field Description
Add Click to access the Choose an event page and
select the events you want to register.

Select one or more events to audit and click>

to move the events to the Selected Items
column. To remove any events, select them
in the Selected Items column and click <.
Click OK when you are finished.

To unregister any events, select them in the

Event Name list and click Remove.

Documentum Administrator User Guide contains the instructions on adding,

modifying, or deleting auditing by object type.

14.7 Auditing by object instance

Auditing by object instance creates audit trails for events for a particular object in
the repository. You can set audits only for one object type at a time.

Aspect attributes can be audited if they are attached to SysObject, user, group, and
acl objects, and any of their associated subtypes. Auditing aspect attributes requires
that the related aspect type is registered for auditing.

You must have Config Audit privileges to audit object instances.

Table 14-3: Object instance auditing properties

Field Description
Attributes Records the values of particular properties of
the object in the audit trail. Click Select
Attributes to access the Choose an attribute
page.

Select the properties whose values you want

to record, click >, then click Add. To remove
any properties, select them on the right-hand
side of the page and click <.

Click OK when you are finished.

318 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.8. Auditing by events selected for all objects in the repository

Field Description
Add Click to access the Choose an event page and
select the events you want to register.

Select one or more events to audit and click>

to move the events to the Selected Items
column. To remove any events, select them
in the Selected Items column and click <.
Click OK when you are finished.

To unregister any events, select them in the

Event Name list and click Remove.

Documentum Administrator User Guide contains the instructions on adding,

modifying, or deleting auditing by object instance.

14.8 Auditing by events selected for all objects in the

repository
You can add or remove auditing events for all objects in the repository.

You must have Config Audit privileges to use this function.

Documentum Administrator User Guide contains the instructions on adding or

removing auditing by events.

14.9 Search audit

The Search Audit feature lets you search and view audit trails. You must have View
Audit extended privileges to search for and view existing audit trails.

Table 14-4: Audit search properties

Field Description
Search By Indicates whether to use the criteria specified
on the search page or a DQL query to search
for the audit trail.

Do one of the following:

• Select the Search criteria defined below
option and enter the search criteria.
• Select the DQL option and enter a DQL
query in the Where Clause field. Click
OK to display the query results.
Events Restricts the search by events. Click Select
and select one or more events and click OK.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 319

Chapter 14 Audit Management

Field Description
Object Name Restricts the search by object names. Select
Begins With, Contains, or Ends With and
type in a string.
Versions Restricts the search by version. Type in a
version.
Look In Restricts the search to a particular folder.
Click Select Folder and select the folder.
Audit Dates Restricts the search by time. Click Local
Time or UTC, then type or select a beginning
date in the From field and an ending date for
the search in the Through field.
Type Restricts the search to a particular type. Click
Select Type and select the type. To include
subtypes of the type, click Include Subtype.
Lifecycle Restricts the search to objects attached to a
lifecycle. Click Select Lifecycle and select a
lifecycle.
Application Code Restricts the search to objects with an
application code. Type the application code.
To restrict the search to those audit trails that
are signed, select Has Signature.
Controlling Application Restricts the search to objects with a
controlling application. Type the name of the
application.

Documentum Administrator User Guide contains the instructions on searching and

viewing audit trails.

14.10 Audit policies

An audit policy ensures that only the users or groups that are specified in the purge
policy can delete an audit record. If an unauthorized user or group attempts to
delete the audit record, Documentum Server throws an error message. If there are
multiple policies for same user, the policy with the highest permissions is in effect.

Audit policies specify which user, group, or role can purge audit trails. You must be
an Install Owner to access and manage audit policies. Other users can only view the
list of audit policies.

Audit policies are managed on the Audit Policies page. Select Administration >
Audit Management to display the Audit Management page, then click the Audit
Policies link to display the Audit Policies page. “Audit Policies page information”
on page 321 describes the information on the Audit Policies page.

320 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.10. Audit policies

Table 14-5: Audit Policies page information

Column Name Description

Name The name of the audit policy.
Accessor Name The name of the user, group, or role that are
assigned this audit policy.
Is Group Indicates whether the user specified in the
Accessor Name column is belongs to a
group.

14.10.1 Creating, modifying, or deleting an audit policy

You must be the Install Owner to create, modify, or delete an audit policy.

Table 14-6: Audit policy information

Field Description
Name The name of the audit policy.
Accessor Name The user, group, or role to which this audit
policy is assigned.
Audit Policy Rules Specifies the policy rules, as follows:
• Click Add to add a rule. The Create/Edit
Rule page displays. Select an attribute
and enter a value for the attribute.
• Select an attribute name, then click Edit to
modify the rule. The Create/Edit Rule
page displays. Modify the attribute.
• Select an attribute name, then click
Remove to delete the rule. There must be
at least one rule or condition to save the
audit policy.

Documentum Administrator User Guide contains the instructions on creating,

modifying, or deleting an audit policy.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 321

Chapter 14 Audit Management

14.10.2 Audit Policy example

The following audit policy example specifies the Test purge policy that enables
user1 to purge the audit record for the object_type attribute type1 and the
is_archived attribute T.

Table 14-7: Audit policy example values

Field Description
Name Test
Accessor Name user1
Audit Policy Rules
Attribute Name Attribute Value
object_type type1
is_archived T

The policy described in this example only protects audit records that satisfy the
policy. For example, the policy does not protect audit records that have the
is_archived attribute set to F. Any user with purge audit extended privilege can
delete those records.

14.11 Registering audits

The Register Audit page specifies the properties that are audited for an object or
object instance.

Select the properties as described in “Object and object instance auditing properties”
on page 323 to define the audited properties and register the object or object
instance for auditing.

The following fields are disabled:

• Application Code

• Lifecycle

• State
• Has signature manifested

• Include all subtypes

• Authentication Required

These fields are enabled only for auditing by object type.

322 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.12. Adding, modifying, or removing audits

Table 14-8: Object and object instance auditing properties

Field Description
Attributes Records the values of particular properties of
the object in the audit trail. Click Select
Attributes to access the Choose an attribute
page.

Select the properties whose values you want

to record, click >, then click Add. To remove
any properties, select them on the right-hand
side of the page and click <.

Click OK when you are finished.

Add Click to access the Choose an event page and
select the events you want to register.

Select one or more events to audit and click>

to move the events to the Selected Items
column. To remove any events, select them
in the Selected Items column and click <.
Click OK when you are finished.

To unregister any events, select them in the

Event Name list and click Remove.

14.12 Adding, modifying, or removing audits

Register Audit page lists object instances or an object type that you selected for
auditing, as well as the audited criteria and events. On this page, you can add, edit,
or remove audits.

Documentum Administrator User Guide contains the instructions on adding,

modifying, or removing audits by object type and object instance.

14.13 Verifying or purging audit trails

Audit trails are displayed on the Audit Trails page after a search query has been
issued, as described in “Search audit” on page 319.

Documentum Administrator User Guide contains the instructions on viewing,

verifying, or purging audit trails.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 323

Chapter 14 Audit Management

14.14 Interpreting audit trails of DFC method,

workflow, and lifecycle events
Audit trail entries for DFC method, workflow, and lifecycle events are stored in the
repository as audit trail objects. Each audit trail object records one occurrence of a
particular event. The audit trail object properties describe the event.

The properties that have a common purpose for entries generated by Documentum
Server include all the properties other than the string_<x> and id_<x> properties. An
audit trail object also has five ID-datatyped properties and five string properties.
These properties are named generically, id_1 to id_5 and string_1 to string_5. In
audit trail entries for workflows and lifecycle events, Documentum Server uses these
properties to store information specific to the particular kinds of events. Some of the
events generated by methods other than workflow or lifecycle-related methods use
these generic properties and some do not. A user-defined event can use these
properties to store any information wanted.

14.14.1 Audit trails for events generated by non-workflow or

lifecycle methods
The following table describes how Documentum Server uses the generic string and
id properties in audit trails generated by methods other than workflow or lifecycle
methods. Only those events that use the generic properties are listed. If an event is
not listed in this table, Documentum Server does not use the generic properties in
audit trails generated by that event.

Table 14-9: Usage of generic properties by API events

Event Generic property use

Adddigsignature string_1, User name provided as an
argument to the method or the name of the
connected user if the user argument was not
specified

string_2, Reason for the signing

324 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.14. Interpreting audit trails of DFC method, workflow, and lifecycle events

Event Generic property use

Addesignature (success) string_1, User who signed the object

string_2, Justification text

string_3, The number of the signature, the

name of the method used to generate the
signature, and the pre-signature hash
argument. For example: 2/PDFSign/pre-
signature hash_argument

string_4, Hash of the primary content (page

number 0)

string_5, Hash of the signed content. Note

that if the signed content is the primary
content (rather than a rendition), this value is
the same as the hash in string_4.
Addesignature (failure) string_1, User who signed the object

string_2, Error message indicating why the

failure occurred

string_3, The number of the signature, text

indicating the reason for the audit entry, and
the 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 is attached

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

“Save New Rendition”, depending on
whether the added rendition replaces an
existing rendition or is a new rendition.
Addretention id_1, Object ID of the retainer object
Appendcontent See Setfile
Appendfile See Setfile

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 325

Chapter 14 Audit Management

Event Generic property use

Appendpart id_1, Object ID of the virtual document to
which you are appending the component

id_2, Object ID of the component

id_3, Object ID of the containment object that

links the 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 user
authentication
Audit string_1, The audited operation
Authenticate string_1, The success or failure of the user
authentication
Bindfile See Setfile
Checkin id_1, Object ID of the version from which the
new version created by the checkin was
derived
Connect string_1, Identifies the authentication
mechanism used to authenticate the user.
Values are:
ticket, for ticketed logintrusted, for trusted
login
unified, for Windows unified login
OS password, for OS password
authentication
plug-in password, for plug-in
authenticationLDAP password, for LDAP
authentication
OS external, for authentication with OS
password by an external password checking
program
LDAP external, for authentication by an
external password checking program that
uses LDAP

string_4, Host name of the client machine

from which the user connected

string_5, IP address of the client machine

from which the user connected

326 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.14. Interpreting audit trails of DFC method, workflow, and lifecycle events

Event Generic property use

Destroy Destroy uses the generic properties only
when the object to be destroyed is a
dm_audittrail object or a subtype of
dm_audittrail. For details, see the Purge
Audit entry in this table.
Getcontent See Getfile
Getfile id_1, Object ID of the content object for the
content file
Getlogin id_1, Object ID of the user object representing
the user identified in string_1

string_1, Name of the user for whom the

ticket was requested

Note: This API contains the

server_name argument that identifies a
server for the scope of a single-use
ticket. If single_use is T and
server_name is ANY_SERVER, the
scope of the ticket is any server in a
load balancing setup.
Getpath See Getfile
Insertcontent See Setfile
Insertfile See Setfile
Insertpart id_1, Object ID of the virtual document to
which you are inserting the component

id_2, Object ID of the component

id_3, Object ID of the containment object that

links the 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

Kill id_1, Session ID of the terminated session

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 327

Chapter 14 Audit Management

Event Generic property use

Link id_1, Object ID of the folder to which the
object is linked.

id_2, Object ID of the linked object

string_1, Name of the folder to which the

object is linked

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 invalid user 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 label assigned in the Mark
method.
Move Content string_1, Name of the storage area from
which the content was moved

string_2, Name of the storage area to which

the content was moved.

id_1, Object ID of the SysObject containing

the moved content file.
Purge Audit string_1, the time_stamp value of the first
deleted audit trail entry in the transaction

string_2, the time_stamp value of the last

deleted audit trail entry in the transaction

string_3, the actual number of audit trail

entries deleted in the transaction

string_5, the list of arguments defined in the

method command line

id_1, the object ID of the first audit trail entry

deleted by the transaction

id_2, the object ID of the last audit trail entry

deleted by the transaction

328 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.14. Interpreting audit trails of DFC method, workflow, and lifecycle events

Event Generic property use

Removecontent id_1, Object ID of the content object
representing the content file removed from
the SysObject.

string_1, The page that was removed.

Removenote id_1, Object ID of the object to which the note
was attached

id_2, Object ID of the note

Removepart id_1, Object ID of the virtual document from
which you are removing the component

id_2, Object ID of the component

id_3, Object ID of the containment object that

links the virtual document and the
component

string_1, If specified, the order_no that

identifies the component to be removed
Removerendition id_1, Object ID of the content object
representing the content file of rendition

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
content file

string_1, Name of the API

string_2, Name of the file (unused for

Appendcontent, 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

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 329

Chapter 14 Audit Management

Event Generic property use

Setretentionstatus string_1, Original status of the retainer

string_2, New status of the retainer

Unaudit string_1, Name of the operation from which
auditing was removed
Unlink id_1, Object ID of the folder to which the
object is linked.

id_2, Object ID of the linked object

string_1, Name of the folder to which the

object is linked

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
which you are inserting the component

id_2, Object ID of the component

id_3, Object ID of the containment object that

links the 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, if specified

string_5, The order_no if specified

14.14.2 Lifecycle audit trails

The following table describes how Documentum Server uses the generic string and
id properties in audit trails generated by lifecycle events.

Table 14-10: Usage of generic properties by lifecycle events

Event Generic property use

Attach id_1, Object ID of the business policy

string_1, State to which object is being

attached

330 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.14. Interpreting audit trails of DFC method, workflow, and lifecycle events

Event Generic property use

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 was

promoted

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 business policy state of object at

the time of suspension
Uninstall Does not use the generic properties.
Validate string_1, Number of states in the business
policy.

14.14.3 Workflow audit trails

The following table describes how Documentum Server uses the generic string and
id properties in audit trails generated by workflow events.

Table 14-11: Usage of generic properties by workflow events

Event Generic property use

Abort workflow (dm_abortworkflow) id_1, Object ID of the workflow
Add attachment (dm_addattachment) id_1, Object ID of the workflow

id_5, Object ID of the attached object

string_5, Name of the attached object

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 331

Chapter 14 Audit Management

Event Generic property use

Add note (dm_addnote) id_1, Object ID of the workflow

id_5, Object ID of the note object

string_1, Activity sequence number

string_2, Activity name

string_5, Value of the keep_permanent flag

note
Add package (dm_addpackage) id_1, Object ID of the workflow

id_2, Object ID of the work item (used only if

addPackage is called with the work item
referenced in the arguments)

id_5, Object ID of the document in the

package. If there are multiple documents,
there are a corresponding number of audit
trail entries, each with a different value in
id_5.

string_1, Activity sequence number

string_2, Activity name

string_3, Names of the components identified

in the componentIds argument. This is only
set if package control is not enabled.

string_5, Package name

Auto Delegation of Activity Failed id_1, Object ID of the workflow
(dm_wf_autodelegate_ failure)
string_1, Activity sequence number

string_2, Activity name

Auto Transition of Activity id_1, Object ID of the workflow
(autotransactivity)
string_1, Activity sequence number

string_2, Activity name

string_5, Index position of the TRUE

condition in the dm_cond_expr object
examined for the transition.

This event is supported for backwards

compatibility. The Portselect event provides
additional or more current information about
an automatic transition.

332 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.14. Interpreting audit trails of DFC method, workflow, and lifecycle events

Event Generic property use

Change activity instance state id_1, Object ID of the workflow
(dm_changedactivity instancestate)
id_2, Object ID of the work item

id_5, Value in the r_exec_results property of

the work item

string_1, Activity sequence number

string_2, Activity name

string_5, Value of the return_value property

of the work item
Change process state string_3, Previous state
(dm_changestateprocess)
string_4, New state
Change supervisor (dm_changeworkflow id_1, Object ID of the workflow
supervisor)
string_4, New supervisor name

string_5, Old supervisor name

Change workflow state id_1, Object ID of the workflow
(dm_changestateworkflow)
string_3, Previous state

string_4, New state

Change work item priority id_1, Object ID of the workflow that contains
(dm_changepriorityworkitem) the work item

id_2, Object ID of the work item

string_1, Sequence number of the activity

that generated the work item

string_2, Name of the activity

string_3, Old priority value

string_5, New priority value

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 333

Chapter 14 Audit Management

Event Generic property use

Completed work item id_1, Object ID of the workflow
(dm_completedworkitem)
id_2, Object ID of the work item

id_5, For automatic work items: Object ID of

the document containing the results of the
execution. (This is the value in the
r_exec_results property.)

string_1, Activity sequence number

string_2, Activity name

string_3, Comma-separated list of work item

properties and their values. The properties
are: user_time, user_cost, a_wq_name,
a_wq_flag, and a_wq_doc_profile.
(a_wq_name and a_wq_doc_profile are
enclosed in double quotes)

string_5,Value in the return_value property

of work item
Create workflow (dm_createworkflow) 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
(dm_delegatedworkitem)
id_2, Object ID of the work item

string_1, Activity sequence number

string_2, Activity name

string_3, Activity type (Manual or

Automatic)

string_4, Name of the workqueue, if any, to

which the task is assigned

string_5, Name of the user to which the task

is delegated
Finish workflow (dm_finishworkflow) id_1, Object ID of the workflow
Install workflow or activity definition Does not use the generic properties.
(dm_install)
Invalidate workflow or activity definition Does not use the generic properties.
(dm_invalidate)

334 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.14. Interpreting audit trails of DFC method, workflow, and lifecycle events

Event Generic property use

Pause work item (dm_pauseworkitem) id_1, Object ID of the workflow

id_2, Object ID of the work item

string_1, Activity sequence number

string_2, Activity name

Port select (dm_portselect) id_1, Object ID of the workflow

string_1, Activity sequence number

string_2, Activity name

string_5, Selected output port. If multiple

ports are selected, a corresponding number
of audit trail entries are created, each with a
different value in string_5.
Pseudo-completed work item id_1, Object ID of the workflow
(dm_pseudocompletedworkitem)
id_2, Object ID of the work item

string_1, Sequence number of the activity

string_2, Name of the activity

string_3, State of the work item prior to

pseudo-completion

string_5, Name of the task owner

Remove attachment (dm_removeattachment) id_1, Object ID of the workflow

id_5, Object ID of the attached object that was

removed

string_5, Name of the attached object that

was removed
Remove note (dm_removenote) id_1, Object ID of the workflow

id_5, Object ID of the note object. If the

remove note event is triggered by a remove
package event that removes a package with
multiple notes attached to its components,
there are multiple remove note audit trail
entries, each with a different id_5 value.

string_1, Activity sequence number

string_2, Activity name

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 335

Chapter 14 Audit Management

Event Generic property use

Remove package (dm_removepackage) id_1, Object ID of the workflow

id_5, Object ID of the document in the

package. If there are multiple documents,
there are a corresponding number of audit
trail entries, each with a different value in
id_5.

string_1, Activity sequence number

string_2, Activity name

string_5, Package name

Repeat work item (dm_repeatworkitem) id_1, Object ID of the workflow

id_2, Object ID of the work item

string_1, Activity sequence number

string_2, Activity name

Resume work item (dm_resumeworkitem) id_1, Object ID of the workflow

id_2, Object ID of the work item

string_1, Activity sequence number

string_2, Activity name

Save a workqueue (dm_save_workqueue) id_1, Object ID of the workqueue

id_2, Value of the wq_policy_id property of

the workqueue object

string_1, Name of the workqueue

string_2, Number of users in the workqueue

Save a workqueue policy (dm_save_ id_1, Object ID of the workqueue policy
workqueuepolicy) object

string_1, Name of the workqueue policy

string_2, Maximum threshold of the policy

Selected work item (dm_selectedworkitem, a id_1, Object ID of the workflow
work item has been acquired)
id_2, Object ID of the work item

string_1, Activity sequence number

string_2, Activity name

string_4, Name of the workqueue, if any, to

which the task is assigned

336 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.14. Interpreting audit trails of DFC method, workflow, and lifecycle events

Event Generic property use

Sign off work item (dm_signoff) id_1, Object ID of the workflow

id_2, Object ID of the work item

id_5, Object ID of the document in the

package. If there are multiple documents,
there are a corresponding number of audit
trail entries, each with a different value in
id_5.

string_1, For Windows, the domain and user

name (used to validate signature) of user

string_5, Text provided by reason argument

in Signoff method
Started work item (dm_startedworkitem) id_1, Object ID of the workflow

id_2, Object ID of the work item

id_5, For automatic activities, the object ID of

the dm_method object for the method
executed by the activity. For manual
activities, this is null.

string_1, Activity sequence number

string_2, Activity name

string_3, Comma-separated list of work item

properties and their values. The properties
are: r_priority, a_wq_name, and
a_wq_doc_profile. a_wq_name and
a_wq_doc_profile are enclosed in double
quotes.

string_4, Name of the performer of the work

item.

string_5, Value in the dependency_type

property of the corresponding queue item
object.
Start workflow (dm_startworkflow) id_1, Object ID of the workflow
Suspend workqueue task id_1, Object ID of the workflow
(dm_suspendedworkqueuetask)
id_2 Object ID of the work item

string_1, Activity sequence number

string_2, Activity name

string_4, Workqueue name

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 337

Chapter 14 Audit Management

Event Generic property use

Uninstall workflow or activity definition Does not use the generic properties.
(dm_uninstall)
Unsuspend workqueue task id_1, Object ID of the workflow
(dm_unsuspendedworkqueuetask)
id_2 Object ID of the work item

string_1, Activity sequence number

string_2, Activity name

string_4, Workqueue name

Validate workflow or activity definition Does not use the generic properties.
(dm_validate)
Generate report on an activity if at least one id_1, Object ID of the workflow
package has been defined accordingly
(dm_wf_business_data) id_2 Object ID of the work item

string_1, Activity sequence number

string_2, Activity name

string_3, Process name

string_4, User name

There is always a dmi_audittrail_attrs object

associated with the audit trail of the
dm_wf_business_data event. The
dmi_audittrail_attrs object has the following
entries:

audit_obj_id: Object ID of corresponding

audit trail object.

attribute_list: An XML string containing data

from all packages.

14.15 Interpreting ACL and group audit trails

Audit trail entries generated when ACLs are created, changed, or destroyed are
recorded in dm_audittrail_acl objects. Entries generated when groups are created,
changed, or destroyed are recorded in dm_audittrail_group objects. The
dm_audittrail_acl and dm_audittrail_group object types are subtypes of the
dm_audittrail type.

The properties defined for the dm_audittrail_acl object type store information about
an audited ACL. The properties identify the event (dm_save, dm_saveasnew, or
dm_destroy), the target ACL, the ACL entries or changes to the entries. For example,
suppose you create an ACL with the following property values:

338 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 14.15. Interpreting ACL and group audit trails

r_object_id:451e9a8b0001900
r_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 :451e9a8b0001900
event_name :dm_save
string_1 :Create
accessor_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
creation of 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 describes what operation was performed on each accessor identified at the
corresponding index position in accessor_name. The accessor_permit and
accessor_xpermit properties record the permissions assigned to the user (or group)
identified in the corresponding positions in accessor_name. Finally, the is_group
property identifies whether the value in 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 access of world to None

The resulting audit trail acl object has the following properties:

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 339

Chapter 14 Audit Management

r_object_id :<audit trail acl obj ID>

audited_obj_id :451e9a8b0001900
event_name :dm_save
string_1 :Save
accessor_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

corresponding position in the accessor_operation, accessor_permit, and
accessor_xpermit properties identify 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 permissions for dm_world.

Sales is found in accessor_name[1]. The value in accessor_operation[1], I, shows that

an entry for Sales was added (inserted) into the ACL. The values in accessor_permit
and accessor_xpermit show the permissions assigned to Sales.

JohnDoe is found in accessor_name[2]. The value in accessor_operation[2], D,

indicates that the entry for JohnDoe was removed from the ACL. The values in the
corresponding positions in accessor_permit and accessor_xpermit identify the
permissions previously assigned to JohnDoe.

Audit trail group objects are interpreted similarly. The values in the corresponding
index positions in users_names and users_names_operations represent one
individual user who is a member of the audited group. The values in the
corresponding positions in groups_names and groups_names_operation represent
one group that is a member of the audited group. The operations property defines
what operation was performed on the member at the corresponding names
property.

340 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 15
Methods and Jobs

15.1 Methods
Methods are executable programs that are represented by method objects in the
repository. The program can be a Docbasic script, a Java method, or a program
written in another programming language such as C++. The associated method
object 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 from the

command line or using a job. Using a DO_METHOD allows you to execute the
method on demand. Using a job allows you to schedule the method for regular,
automatic execution. The “Jobs” on page 368 section contains more information on
creating jobs.

The executable invoked by the method can be stored in the file system or as content
of the method object. If the method is executed by the Java method server, the entire
custom or xml app jar must be stored in the $DOCUMENTUM\<WildFly>\server
\DctmServer_MethodServer\deploy\ServerApps.ear\DmMethods.war\WEB-INF
\lib directory. For workflow methods, the .jar files must be placed under the Process
Engine deployment in the $DOCUMENTUM/<WildFly>/server/
DctmServer_MethodServer/deploy/bpm.ear/bpm.war/WEB-INF/lib directory.

By default, all repositories contain methods used by Documentum Server. All

methods with object names that begin with dm_ are default methods.

15.1.1 Creating or modifying methods

The executable invoked by the method can be stored in an external file or as content
of the method object. All other programs, except Java programs, are stored on the
Documentum Server file system or in the repository as the content of the method
object.

If the program is a Java method and you want to execute it using the Java method
server, install the method on host file system of the application server. Only the
application server instance installed during Documentum Server installation can
execute Java methods. Do not store the program in the repository as the content of
the method object.

Creating methods requires superuser privileges.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 341

Chapter 15 Methods and Jobs

Table 15-1: Method Info tab properties

Field label Description

Name The method name.

Do not use the format dm_<methodname> to

name the method. This naming convention is
reserved for default Documentum objects.
Verb The method verb, including arguments.

The method verb is the command-line name

of the procedure or the name of the
interpretive language that executes the
program file.

You can specify a full path, a relative path, or

no path for the method verb. If you do not
specify a path, the server searches the
directories in the search path of the user.

To store the program as the content of the

method object, you must import the content
after you created the method.
Method Type Specifies the programming language of the
method. Valid values are:
• dmbasic: The method is written in
Docbasic.
• dmawk: The method is written in dmawk.
• java: The method is written is Java and
executed on the Java Method Server.
• program: The method is writing in a
programming language, such as C or C++.

If the method is executed using

Documentum Server or the dmbasic method
server, and the executable is stored as
content for the method, setting the method
type to dmawk or dmbasic, directs the server
to add -f in front of the filename. The server
pass all arguments specified on the
DO_METHOD command line to the
program.
Arguments Specifies method arguments. Click Edit to
add arguments.
Method Success Codes Specifies method success codes. Click Edit to
add success codes.

342 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.1. Methods

Field label Description

Method Success Status Specifies the valid value for current status in
the completed job. If this option is selected,
the current status property value of the job
must match the success status value after the
job completes. The property is ignored if the
option is not selected.
Timeout Minimum The minimum timeout that can be specified
on the command line for this procedure. The
minimum timeout value cannot be greater
than the default value specified in the
timeout default field.
Timeout Default The default timeout value for the procedure.
The system uses the default timeout value if
no other time-out is specified on the
command line.

The default timeout value is 60 seconds and

cannot be greater than the value specified in
the timeout maximum field.
Timeout Maximum The maximum timeout that can be specified
on the command line for this procedure. The
default is 300 seconds.
Launch Direct Specifies whether the program is executed by
the system call or exec API call. When the
launch direct option is selected, the server
uses the exec call to execute the procedure. In
this case, the method verb must be a fully
qualified path name.
Launch Asynchronously Specifies whether the server runs the method
asynchronously or not.

If this option is selected and the method is

launched on the application server, setting
SAVE_RESPONSE on to TRUE on the
command line is ignored.

If this option is selected and the method is

launched on the method server or
Documentum Server and SAVE_RESULTS is
set to TRUE on the command line, the
method is always launched synchronously.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 343

Chapter 15 Methods and Jobs

Field label Description

Run As Owner Specifies whether to run method to run as
the installation owner account, with the
privileges of the installation owner. If this
option is not selected, the method runs with
the privileges of the method user.

This option must be selected to execute a

method on the method server or application
server.
Trace Launch Specifies whether to save internal trace
messages generated by the method to the
session log.
Use Method Server Specifies whether to use the dmbasic method
server or Java method server to execute a
dmbasic or Java method.
Restartable Specifies whether the method can be
restarted, if the Java Method Server (JMS)
crashes or fails to respond.

This option is only available for non-system

Java methods.
Failover Awareness Specifies whether the method is enabled for
failover, if the server is associated with more
than one Java Method Server.

This option can only be configure for non-

system Java methods.

Table 15-2: SysObject Info tab properties

Field label Description

Title A descriptive title for the method.
Subject A subject associated with the method.
Keywords One or more keywords that describe the
method. Click Edit to add keywords.
Authors One or more method authors. Click Edit to
add authors.
Owner Name The name of the method owner. Click Edit to
select a different owner.
Version Label The current version label of the method.
Click Edit to change the version label.
Checkout Date The date when the method was checked out
last.
Checked Out by The name of the user who checked out the
method.

344 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.1. Methods

Field label Description

Created The date and time when the method was
created.
Creator Name The name of the user who created the
method.
Modified The date and time when the method was last
modified.
Modified By The name of the user who last modified the
method.
Accessed The time and date when the method was last
accessed.

Documentum Administrator User Guide contains the instructions on creating or

modifying methods.

15.1.2 Importing method content

If the program that a method is running is a script that requires an interpretive
language to run it, store the program as the content of the associated method object.

Documentum Administrator User Guide contains the instructions on importing method

content.

15.1.3 Running methods

You can manually run a method. To run the method periodically, create a job to
execute the method on a schedule.

If you run a default Documentum method from the Run Method page, select Run as
server unless you are logged in as the installation owner.

Documentum Administrator User Guide contains the instructions on running methods.

15.1.4 Viewing the results of a method

The results of a method are displayed only after you run a method from
Documentum Administrator.

After you run the method, the following method results appear:

• The result returned, if any

• Any document IDs that result
• The process ID
• Whether the method launched successfully
• The return value, if any

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 345

Chapter 15 Methods and Jobs

• Whether there were errors on the operating system from running the method
• Whether the method timed out
• The method timeout length

Click OK to exit the results page and return to the Methods list page.

15.1.5 Exporting method content

You can view a script imported into a method object.

Documentum Administrator User Guide contains the instructions on exporting method

content.

15.1.6 Editing method content

You can edit the content of a method.

Documentum Administrator User Guide contains the instructions on editing method

content.

15.1.7 Checking in method content

You see this page only when you check in a checked-out script that is method
content.

Documentum Administrator User Guide contains the instructions on checking in

method content.

15.1.8 Deleting methods

You can delete a method.

Documentum Administrator User Guide contains the instructions on deleting methods.

15.2 Method execution agents

The execution agents are the server processes that execute methods. There are three
execution agents:

• The dmbasic method server

The dmbasic method server is a separate process that is installed with
Documentum Server and resides on the same host. It is enabled by default. After
it is started, it runs continuously. The method server uses connection pooling,
regardless of whether connection pooling is enabled for the Documentum Server.
The dmbasic method server uses a method execution queue to manage methods
submitted for execution. When you direct a method to the method server,
Documentum Server places a method execution request on the bottom of the
method execution queue. The method server reads the queue and executes the

346 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

request at the top of the queue. The method server has a configurable number of
worker threads to execute requests. The maximum number of requests the queue
can contain is the number of threads times 100. For example, if the method server
is configured to use 5 threads, then the method execution queue can contain 250
requests.
• Java method server
The Java method server is a third-party application server, installed as a
component of Documentum Server installation. The “Java Method Servers”
on page 149 section contains more information about the Java method server.
• Documentum Server
The Documentum Server is the default execution agent for a method if the
method is not configured to execute on the method server or Java method server.

15.3 Administration methods

Administration methods are methods that perform a variety of administrative and
monitoring tasks, in categories such as process management, content storage
management, full-text indexing, and database methods. Use Documentum
Administrator to execute the administration methods interactively.

15.3.1 Viewing administration methods

Documentum Administrator User Guide contains the instructions on viewing a list of
administration methods.

15.3.2 Running administration methods

This sections contains information on the method, including the permissions you
must have to run it, the method arguments, and the results it returns.

The following sections provide more information about content methods:

• “CAN_FETCH” on page 348

• “CLEAN_LINKS” on page 349
• “DELETE_REPLICA” on page 349
• “DESTROY_CONTENT” on page 349
• “EXPORT_TICKET_KEY” on page 349
• “GET_PATH” on page 350
• “IMPORT_REPLICA” on page 350
• “IMPORT_TICKET_KEY” on page 350
• “MIGRATE_CONTENT” on page 350
• “PURGE_CONTENT” on page 356
• “REPLICATE” on page 356

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 347

Chapter 15 Methods and Jobs

• “RESTORE_CONTENT” on page 356

• “SET_STORAGE_STATE” on page 357

The following sections provide more information about database methods:

• “DB_STATS” on page 357

• “DROP_INDEX” on page 358
• “EXEC_SQL” on page 358
• “FINISH_INDEX_MOVES” on page 358
• “GENERATE_PARTITION_SCHEME_SQL” on page 359
• “MAKE_INDEX” on page 362
• “MOVE_INDEX” on page 362

The following sections provide more information about full-text indexing methods.

• “ESTIMATE_SEARCH” on page 362

• “MARK_FOR_RETRY” on page 363
• “MODIFY_TRACE” on page 363

The following sections provide more information about trace methods:

• “GET_LAST_SQL” on page 363

• “MODIFY_TRACE” on page 363
• “LIST_RESOURCES” on page 364
• “LIST_TARGETS” on page 364
• “SET_OPTIONS” on page 364

The following section provides more information about the workflow method:

• “RECOVER_AUTO_TASKS” on page 365

• “WORKFLOW_AGENT_MANAGEMENT” on page 366

15.3.2.1 CAN_FETCH
Any user can run the CAN_FETCH administration method to determine whether
the server can fetch a specified content file.

CAN_FETCH returns TRUE if the fetch is possible or FALSE if it is not.

Documentum Administrator User Guide contains the instructions on running the

CAN_FETCH administration method.

348 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

15.3.2.2 CLEAN_LINKS
The CLEAN_LINKS administration method removes linked_store links not
associated with sessions, unnecessary dmi_linkrecord objects, and auxiliary
directories.

CLEAN_LINKS returns TRUE if the operation succeeds or FALSE if it fails.

You must have superuser privileges to run CLEAN_LINKS.

Documentum Administrator User Guide contains the instructions on running the

CLEAN_LINKS administration method.

15.3.2.3 DELETE_REPLICA
The DELETE_REPLICA administration method removes a content file from a
component area of a distributed storage area.

DELETE_REPLICA returns TRUE if the operation succeeds or FALSE if it fails.

You must have superuser privileges to run DELETE_REPLICA.

Documentum Administrator User Guide contains the instructions on running the

DELETE_REPLICA administration method.

15.3.2.4 DESTROY_CONTENT
The DESTROY_CONTENT method removes content objects from the repository and
their associated content files from storage areas.

DESTROY_CONTENT returns TRUE if the operation succeeds or FALSE if it fails.

You must have system administrator or superuser privileges to run

DESTROY_CONTENT.

Documentum Administrator User Guide contains the instructions on running the

DESTROY_CONTENT administration method.

15.3.2.5 EXPORT_TICKET_KEY
The EXPORT_TICKET_KEY administration method encrypts and exports a login
ticket from the repository to a client machine.

Documentum Administrator User Guide contains the instructions on running the

EXPORT_TICKET_KEY administration method.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 349

Chapter 15 Methods and Jobs

15.3.2.6 GET_PATH
The GET_PATH administration method returns the directory location of a content
file stored in a distributed storage area.

Any user can run GET_PATH.

Documentum Administrator User Guide contains the instructions on running the

GET_PATH administration method.

15.3.2.7 IMPORT_REPLICA
The IMPORT_REPLICA administration method imports files from one distributed
storage area into another distributed storage area.

The IMPORT_REPLICA method returns TRUE if the operation succeeds or FALSE if

it fails.

You must have system administrator or superuser privileges to use the

IMPORT_REPLICA method.

Documentum Administrator User Guide contains the instructions on running the

IMPORT_REPLICA administration method.

15.3.2.8 IMPORT_TICKET_KEY
The IMPORT_TICKET_KEY administration method decrypts a login ticket from a
client machine and imports the ticket into the repository.

Documentum Administrator User Guide contains the instructions on running the

IMPORT_TICKET_KEY administration method.

15.3.2.9 MIGRATE_CONTENT
The MIGRATE_CONTENT administration method migrates content files from one
storage area to another.

The MIGRATE_CONTENT method requires superuser privileges to migrate:

• Single content objects.

• Single SysObject.
• Sets of content objects qualified by a DQL predicate against dmr_content.
• Set of content objects qualified by a DQL predicate against dm_sysobject or its
subtypes.
• All content in a file store.

Use the MIGRATE_CONTENT administration method to move content from file

stores, retention type stores, blob stores, and distributed stores to file stores,
retention type stores, and distributed stores. Documentum Administrator 6.5 SP2

350 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

and later supports migration from external stores. You cannot move files to a blob
store. The storage areas can be online, offline, or read-only.

Before running MIGRATE_CONTENT:

• Ensure that all objects to be migrated are checked in to the repository. If you
migrate any checked-out objects, check-in fails because of mismatched versions.
• Ensure that the file store to which you migrate objects has sufficient disk space
for the migration.
• Before you migrate a file store, use the SET_STORAGE_STATE administration
method to mark it READ-ONLY. If the source file store has associated full-text
indexes, the target file store must also have full-text indexes. Documentum
Administrator does not allow you to select a target file store without full-text
indexes.

The MIGRATE_CONTENT method returns an integer indicating the number of

objects migrated successfully.

Regardless of the mode in which MIGRATE_CONTENT is run, the original content

file can be removed or left in the source file store. If you do not have the file
removed, you must specify the path to a log file that logs the path of the source
content file. Those files can be removed at another time using Dmfilescan.

Note: For a read-only filestore, when you use MIGRATE_CONTENT with the
parameter remove_original set to <TRUE>, the migration fails because the
method is unable to remove the content from the SOURCE filestore. You must
make the storage area online for a successful migration.

Table 15-3: Parameters for moving a single object

Field Description
Migrate Select A single object from the drop-down
list.
Content Click Select Object, then select an object type
from the Select From drop-down list.

Specify a limiting Where clause, or leave the

Where field blank to select from all objects in
the repository. To display all object versions,
select the Use all versions checkbox and then
click Go.

Select the objects to migrate and click Add.

Select Remove the original sourceto remove

the original content file. The Remove the
original source option cannot be edited, if
the selected object belongs to an external
store.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 351

Chapter 15 Methods and Jobs

Field Description
Path Click Select Path and select a location on the
server file system for the log file path.
Target Select a target file store from the drop-down
list.
Source Direct Access Specifies whether the content files in the
source store can be directly accessed through
a full file path.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store.
Migrate With Specifies whether the source content is
copied or moved to the target store during
migration. Direct Move is applicable to file
stores only.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store.
Update Only This option is used only in conjunction with
the Direct Copy or Direct Move option.
When selected, move or copy commands are
written to the log file specified in the
Command File Name field.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store.
Command File Name A string that specifies a file path to a log file.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store and if the Update Only
option is selected.

Table 15-4: Parameters for moving all content in a store

Field Description
Migrate Select All content in a filestore from the
drop-down list.
Source Select a source file store from the Source
drop-down list.

Select Remove the original sourceto remove

the original content file. The Remove the
original source option cannot be edited, if
the selected object belongs to an external
store.

352 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

Field Description
Path Click Select Path and select a location on the
server file system for the log file path
Target Select a target file store from the drop-down
list.
Maximum Specifies the maximum number of objects to
migrate.

The default is to migrate all objects.

Batch Size Specifies the number of objects migrated in a
single transaction.

The default value is 500. Multiple

transactions are run until the maximum
number of objects to migrate is reached.
Content Migration Threads Specifies the number of internal sessions
used to execute the method.

The default value is 0, indicating that the

migration executes sequentially. The value
cannot exceed the Maximum Content
Migration Threads value in the server
configuration object.

This option is only available if a Content

Storage Services license is enabled on the
Documentum Server.
Source Direct Access Specifies whether the content files in the
source store can be directly accessed through
a full file path.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store.
Migrate With Specifies whether the source content is
copied or moved to the target store during
migration. Direct Move is applicable to file
stores only.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 353

Chapter 15 Methods and Jobs

Field Description
Update Only This option is used only in conjunction with
the Direct Copy or Direct Move option.
When selected, move or copy commands are
written to the log file specified in the
Command File Name field.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store.
Command File Name A string that specifies a file path to a log file.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store and if the Update Only
option is selected.

Table 15-5: Parameters for moving content selected by a query

Field Description
Migrate Select All content satisfying a query from
the drop-down list.
Select Object Type to Migrate Specify the object type to migrate.

If you select dm_sysobject or it’s subtype,

click Select to access the Choose a type page
to select a subtype of dm_sysobject.
Select r_object_id from dmr_content where Specify the DQL query.

Select Remove the original sourceto remove

the original content file. The Remove the
original source option cannot be edited, if
the selected object belongs to an external
store.
Path Click Select Path and select a location on the
server file system for the log file path
Target Select a target file store from the drop-down
list.
Maximum Specifies the maximum number of objects to
migrate.

The default is to migrate all objects.

Batch Size Specifies the number of objects migrated in a
single transaction.

The default value is 500. Multiple

transactions are run until the maximum
number of objects to migrate is reached.

354 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

Field Description
Content Migration Threads Specifies the number of internal sessions
used to execute the method.

The default value is 0, indicating that the

migration executes sequentially. The value
cannot exceed the Maximum Content
Migration Threads value in the server
configuration object.

This option is only available if a Content

Storage Services license is enabled on the
Documentum Server.
Source Direct Access Specifies whether the content files in the
source store can be directly accessed through
a full file path.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store.
Migrate With Specifies whether the source content is
copied or moved to the target store during
migration. Direct Move is applicable to file
stores only.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store.
Update Only This option is used only in conjunction with
the Direct Copy or Direct Move option.
When selected, move or copy commands are
written to the log file specified in the
Command File Name field.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store.
Command File Name A string that specifies a file path to a log file.

This option is only available if the Source is

an external store and the Target is either a
file store or a ca store and if the Update Only
option is selected.

If the MIGRATE_CONTENT method fails with an error, the entire batch transaction
is rolled back. If the destination has content files that were created from the
successful migrations within the batch, you can clean up those files running the
Dmfilescan job, as described in “Dmfilescan” on page 392.

Documentum Administrator User Guide contains the instructions on the following:

• Migrating a single object

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 355

Chapter 15 Methods and Jobs

• Migrating all content files in a file store

• Migrating objects selected by a query

15.3.2.10 PURGE_CONTENT
The PURGE_CONTENT administration method marks a content file as offline and
deletes the file from its storage area. The method does not back up the file before
deleting it; ensure that you have archived the file before running
PURGE_CONTENT on it.

The PURGE_CONTENT method returns TRUE if the operation succeeds or FALSE if

it fails.

You must have system administrator or superuser privileges to use the

PURGE_CONTENT method.

Documentum Administrator User Guide contains the instructions on running the

PURGE_CONTENT administration method.

15.3.2.11 REPLICATE
The REPLICATE administration method copies content files from one component of
a distributed storage area to another. This task is normally performed by the
Content Replication tool or by the Surrogate Get feature. Use the REPLICATE
administration method as a manual backup to Content Replication and Surrogate
Get.

The REPLICATE method returns TRUE if the operation succeeds or FALSE if it fails.

You must have system administrator or superuser privileges to use the REPLICATE
method.

Documentum Administrator User Guide contains the instructions on running the

REPLICATE administration method.

15.3.2.12 RESTORE_CONTENT
The RESTORE_CONTENT administration method restores an offline content file to
its original storage area. It operates on one file at a time. If you need to restore more
than one file at a time, use the API Restore method.

You can use RESTORE_CONTENT only when one server handles both data and
content requests. If your configuration uses separate servers for data requests and
content file requests, you must issue a Connect method that bypasses the
Documentum Server to use RESTORE_CONTENT in the session.

The RESTORE_CONTENT method returns TRUE if the operation succeeds or

FALSE if it fails.

You must have system administrator or superuser privileges to use the

RESTORE_CONTENT method.

356 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

Documentum Administrator User Guide contains the instructions on running the

RESTORE_CONTENT administration method.

15.3.2.13 SET_STORAGE_STATE
The SET_STORAGE_STATE administration method changes the state of a storage
area. A storage area is in one of three states:

• On line
An on-line storage area can be read and written to.
• Off line
An off-line storage area cannot be read or written to.

• Read only
A read-only storage area can be read, but not written to.

You can use SET_STORAGE_STATE only when one server handles both data and
content requests. If your configuration uses separate servers for data requests and
content file requests, you must issue a Connect method that bypasses the content file
server to use SET_STORAGE_STATE in the session.

The SET_STORAGE_STATE method returns TRUE if the operation succeeds or

FALSE if it fails.

You must have system administrator or superuser privileges to use the

SET_STORAGE_STATE method.

Documentum Administrator User Guide contains the instructions on running the

SET_STORAGE_CONTENT administration method.

15.3.2.14 DB_STATS
The DB_STATS administration method displays statistics about database operations
for the current session. The statistics are counts of the numbers of:

• Inserts, updates, deletes, and selects executed

• Data definition statements executed

• RPC calls to the database

• Maximum number of cursors opened concurrently during the session

Any user can run the DB_STATS method.

Documentum Administrator User Guide contains the instructions on running the

DB_STATS administration method.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 357

Chapter 15 Methods and Jobs

15.3.2.15 DROP_INDEX
The DROP_INDEX administration method destroys a user-defined index on an
object type. The DROP_INDEX method returns TRUE if the operation succeeds or
FALSE if it fails. You must have superuser privileges to run the DROP_INDEX
administration method.

Documentum Administrator User Guide contains the instructions on running the

DROP_INDEX administration method.

15.3.2.16 EXEC_SQL
The EXEC_SQL administration method executes SQL statements, with the exception
of SQL Select statements.

The EXEC_SQL method returns TRUE if the operation succeeds or FALSE if it fails.

You must have superuser privileges to run the EXEC_SQL method.

Note the following restrictions on how the method works:

• If you use the Apply method to execute the method and the query contains
commas, you must enclose the entire query in single quotes.
• In an EXECUTE statement, character-string literals must always be single-
quoted.

Documentum Administrator User Guide contains the instructions on running the

EXEC_SQL administration method.

15.3.2.17 FINISH_INDEX_MOVES
The FINISH_INDEX_MOVES administration method completes unfinished object
type index moves. The FINISH_INDEX_MOVES method returns TRUE if the
operation succeeds or FALSE if it fails. You must have superuser privileges to run
the FINISH_INDEX_MOVES administration method.

Documentum Administrator User Guide contains the instructions on running the

FINISH_INDEX_MOVES administration method.

358 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

15.3.2.18 GENERATE_PARTITION_SCHEME_SQL
The GENERATE_PARTITION_SCHEME_SQL administration method is available to
administrators and superusers. These additional restrictions apply:

• The method is available only on version 6.5 repositories.

Running the method generates a script, which can then be run to partition the
repository. The GENERATE_PARTITION_SCHEME_SQL administration method
has three options:

• DB_PARTITION (Database Partition)

Generate a script to upgrade or convert a non-partitioned repository to a
Documentum 6.5 partitioned repository.
• ADD_PARTITION (Add Partition)
Add a partition to a partitioned type.
• EXCHANGE_PARTITION (Exchange Partition)
Generate a script for bulk ingestion by loading data from an intermediate table
into a new partition of a partitioned table.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 359

Chapter 15 Methods and Jobs

Table 15-6: GENERATE_PARTITION_SCHEME_SQL parameters

Parameter Description
Operation Select an operation from the dropdown list
box to define the subcommand. The options
are:
• DB_PARTITION: Generates a script to
upgrade or convert a repository to a 6.5
partitioned repository. If selected:
– Select Partition Type or Table Name.
– If Table Name is defined, optionally
define the Owner Name.
– Include object type is optional. Select
to apply the partition operation to the
dmi_object_type table.
– Last Partition and Last Tablespace are
optional.
– In the Partitions section, Partition
Name, Range, and Tablespace are
required.
• ADD_PARTITION: Generates a script to
add a partition to a partitioned type. If
selected:
– Select Partition Type or Table Name.
– If Table Name is defined, optionally
define the Owner Name.
– Include object type is optional. Select
to apply the partition operation to the
dmi_object_type table.
– In the Partitions section, Partition
Name, Range, and Tablespace are
required.
• EXCHANGE_PARTITION: Generates a
script for bulk ingestion by loading data
from an intermediate table into a new
partition of a partitioned table. If selected:
– Partition Type and Table Name are
mutually exclusive.
– If Table Name is defined, optionally
define the Owner Name.
– Include object type is optional. Select
to apply the partition operation to the
dmi_object_type table.
– Partition Name, Range, and
Tablespace are required.
– Temp Table Suffix is optional.

360 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

Parameter Description
Partition Type Select a partition type from the dropdown
list box, which displays a list of the partition
types available for the repository. All is the
default for DB_PARTITION and
ADD_PARTITION, but is not available for
EXCHANGE_PARTITION. If you select
Partition Type, then you cannot select Table
Name.
Table Name Type a table name. If you select Table Name,
then you cannot select Partition Type.
Include object type Optionally, select to apply the partition
operation to the dmi_object_type table.
Owner Name Type an owner name. This field is enabled
only if Table Name is selected.
Last Partition Optionally, type a name for the last partition.
This field appears only when
DB_PARTITION is selected as the operation.
Last Tablespace Optionally, type a tablespace name for the
last partition. This field appears only when
DB_PARTITION is selected as the operation.
Partition Name Type a name for the partition. For
DB_PARTITION and ADD_PARTITION
operations, you must first click Add in the
Partitions section to add information for
each partition.
Range Type the upper limit for the partition key
range. For DB_PARTITION and
ADD_PARTITION operations, you must first
click Add in the Partitions section to add
information for each partition.
Tablespace Type the partition tablespace name. If not
specified, the default tablespace is used. For
DB_PARTITION and ADD_PARTITION
operations, you must first click Add in the
Partitions section to add information for
each partition.
Temp Table Suffix Type a temporary table suffix. This field is
enabled and optional only if
EXCHANGE_PARTITION is selected as the
operation.

Documentum Administrator User Guide contains the instructions on running the

GENERATE_PARTITION_SCHEME_SQL administration method.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 361

Chapter 15 Methods and Jobs

15.3.2.19 MAKE_INDEX
The MAKE_INDEX administration method creates an index for any persistent object
type. You can specify one or more properties on which to build the index. If you
specify multiple properties, you must specify all single-valued properties or all
repeating properties. Also, if you specify multiple properties, the sort order within
the index corresponds to the order in which the properties are specified in the
statement. You can also set an option to create a global index.

If the MAKE_INDEX method succeeds, it returns the object ID of the dmi_index

object for the new index. If the method fails, MAKE_INDEX returns F. If the
specified index already exists, the method returns 0000000000000000.

You must have superuser privileges to run the MAKE_INDEX administration

method. To run an index space query, you must have sufficient privileges in the
database.

Documentum Administrator User Guide contains the instructions on running the

MAKE_INDEX administration method.

15.3.2.20 MOVE_INDEX
The MOVE_INDEX administration method moves an existing object type index
from one tablespace or segment to another. The MOVE_INDEX method returns
TRUE if the operation succeeds or FALSE if it fails. You must have system
administrator or superuser privileges to run the MOVE_INDEX administration
method.

Documentum Administrator User Guide contains the instructions on running the

MOVE_INDEX administration method.

15.3.2.21 ESTIMATE_SEARCH
The ESTIMATE_SEARCH administration method returns the number of results
matching a particular full-text search condition.

ESTIMATE_SEARCH returns one of the following:

• The exact number of matches that satisfy the SEARCH condition, if the user
running the method is a superuser or there are more than 25 matches.
• The number 25 if there are 0-25 matches and the user running the method is not a
superuser.
• The number -1 if there is an error during execution of the method.

Errors are logged in the session log file.

Any user can execute this method. However, the permission level of user affects the
return value. The ESTIMATE_SEARCH administration method is not available, if
the connected repository is configured with the xPlore search engine.

362 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

Documentum Administrator User Guide contains the instructions on running the

ESTIMATE_SEARCH administration method.

15.3.2.22 MARK_FOR_RETRY
The MARK_FOR_RETRY administration method finds content that has a particular
negative update_count property value and marks such content as awaiting indexing.
Use MARK_FOR_RETRY at any time to mark content that failed indexing for retry.
Note that MARK_FOR_RETRY does not take the update_count argument.

When the UPDATE_FTINDEX method fails, it changes the update_count property

for the content object associated with the bad content to the negative complement of
the update_count value in the fulltext index object. For example, if the update_count
of the full-text index object is 5, the update_count property of the bad content object
is set to -5 (negative 5). Documentum Server DQL Reference Guide contains more
information.

The MARK_FOR_RETRY method returns TRUE if the operation succeeds or FALSE

if it fails.

You must have system administrator or superuser privileges to run the

MARK_FOR_RETRY administration method.

Documentum Administrator User Guide contains the instructions on running the

MARK_FOR_RETRY administration method.

15.3.2.23 MODIFY_TRACE
The MODIFY_TRACE administration method turns tracing on and off for full-text
indexing operations. The MODIFY_TRACE method returns TRUE if the operation
succeeds or FALSE if it fails. You must have system administrator or superuser
privileges to run the MODIFY_TRACE administration method.

Documentum Administrator User Guide contains the instructions on running the

MODIFY_TRACE administration method.

15.3.2.24 GET_LAST_SQL
The GET_LAST_SQL administration method retrieves the SQL translation of the last
DQL statement issued. Any user can run GET_LAST_SQL.

Documentum Administrator User Guide contains the instructions on running the

GET_LAST_SQL administration method.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 363

Chapter 15 Methods and Jobs

15.3.2.25 LIST_RESOURCES
The LIST_RESOURCES administration method lists information about the server
and the operating system environment of server. You must have system
administrator or superuser privileges to run the LIST_RESOURCES administration
method.

Documentum Administrator User Guide contains the instructions on running the

LIST_RESOURCES administration method.

15.3.2.26 LIST_TARGETS
The LIST_TARGETS administration method lists the connection brokers to which
the server is currently projecting. Additionally, it displays the projection port,
proximity value, and connection broker status for each connection broker, as well as
whether the connection broker is set (in server.ini or the server configuration object).
Any user can run LIST_TARGETS.

Documentum Administrator User Guide contains the instructions on running the

LIST_TARGETS administration method.

15.3.2.27 SET_OPTIONS
The SET_OPTIONS administration method turns tracing options on or off. You can
set the following options:

Option Action
clean Removes the files from the server common
area.
crypto_trace Cryptography information.
debug Traces session shutdown, change check,
launch and fork information.
docbroker_trace Traces connection broker information.
i18n_trace Traces client session locale and codepage. An
entry is logged identifying the session locale
and client code page whenever a session is
started.

An entry is also logged if the locale or code

page is changed during the session.

364 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

Option Action
last_sql_trace Traces the SQL translation of the last DQL
statement issued before access violation and
exception errors.

If an error occurs, the last_sql_trace option

causes the server to log the last SQL
statement that was issued prior to the error.
This tracing option is enabled by default.

It is strongly recommended that you do not

turn off this option. It provides valuable
information to OpenText Global Technical
Services if it ever necessary to contact them.
lock_trace Traces Windows locking information.
net_ip_addr Traces the IP addresses of client and server
for authentication.
nettrace Turns on RPC tracing. Traces Netwise calls,
SSL, connection ID, client host address, and
client hostname.
sql_trace SQL commands sent to the underlying
RDBMS for subsequent sessions, including
the repository session ID and the database
connection ID for each SQL statement.
trace_authentication Traces detailed authentication information.
trace_complete_launch Traces Linux process launch information.
trace_method_server Traces the operations of the method server.

The SET_OPTIONS method returns TRUE if the operation succeeds or FALSE if it

fails. You must have system administrator or superuser privileges to run the
SET_OPTIONS administration method.

Documentum Administrator User Guide contains the instructions on running the

SET_OPTIONS administration method.

15.3.2.28 RECOVER_AUTO_TASKS
Run the RECOVER_AUTO_TASKS administration method to recover workflow
tasks that have been claimed, but not yet processed by a workflow agent associated
with a failed Documentum Server.

If a Documentum Server fails, its workflow agent is also stopped. When the server is
restarted, the workflow agent recognizes and processes any work items it had
claimed but not processed before the failure. However, if you cannot restart the
Documentum Server that failed, you must recover those work items already claimed
by its associated workflow agent so that another workflow agent can process them.
The RECOVER_AUTO_TASKS administration method performs that recovery.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 365

Chapter 15 Methods and Jobs

Documentum Administrator User Guide contains the instructions on running the

RECOVER_AUTO_TASKS administration method.

15.3.2.29 WORKFLOW_AGENT_MANAGEMENT
Run the WORKFLOW_AGENT_MANAGEMENT method to start and shut down a
workflow agent.

Documentum Administrator User Guide contains the instructions on running the

WORKFLOW_AGENT_MANAGEMENT administration method.

If the workflow agent startup or shutdown process fails, the Administration Method
Results page displays an error message indicating the process failure and provides
additional information. There several reasons why a workflow agent startup or
shutdown process can fail:

• The network is down.

• The Documentum Server containing the workflow agent is down.

• The Documentum Server projects to a connection broker that is not listed in the
dfc.properties of the client running Documentum Administrator.
If the repository is not reachable, the Parameters page displays the Workflow
Agent Current Status as Unknown.

15.3.2.30 REGEN_EXPRESSIONS
By default, dmbasic expression generates the INTEGER data type. Use the following
procedure to convert INTEGER to LONG:

1. Create an environmental variable at the Documentum Server host:

DM_DOCBASIC_COND_EXPR_DATA_TYPE

2. Set the value for the variable to LONG (all uppercase).

3. Restart the repository to fetch the new variable.

4. Run the following dmbasic command:

For Windows:
dmbasic -f %DM_HOME%\install\admin\dm_recreate_expr.ebs
-e Recreate -- <repository> <username> <password> all

For Linux:
dmbasic -f $DM_HOME/install/admin/dm_recreate_expr.ebs
-e Recreate -- <repository> <username> <password> all

To generate LONG data type for dmscript of a particular activity, use the following
IAPI command:
apply,c,<activity_id>,REGEN_EXPRESSIONS

366 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.3. Administration methods

15.3.2.31 Administration Methods Results Page

This page displays the results of running an administration method. For information
on the results, click the method name.

The following are content methods:

• “CAN_FETCH” on page 348

• “CLEAN_LINKS” on page 349
• “DELETE_REPLICA” on page 349
• “DESTROY_CONTENT” on page 349
• “EXPORT_TICKET_KEY” on page 349
• “GET_PATH” on page 350
• “IMPORT_REPLICA” on page 350
• “IMPORT_TICKET_KEY” on page 350
• “MIGRATE_CONTENT” on page 350
• “PURGE_CONTENT” on page 356
• “REPLICATE” on page 356
• “RESTORE_CONTENT” on page 356
• “SET_STORAGE_STATE” on page 357

The following are database methods:

• “DB_STATS” on page 357

• “EXEC_SQL” on page 358
• “MAKE_INDEX” on page 362
• “DROP_INDEX” on page 358
• “MOVE_INDEX” on page 362
• “FINISH_INDEX_MOVES” on page 358

The following are full-text indexing methods:

• “ESTIMATE_SEARCH” on page 362

• “MARK_FOR_RETRY” on page 363
• “MODIFY_TRACE” on page 363

The following are trace methods:

• “GET_LAST_SQL” on page 363

• “LIST_RESOURCES” on page 364

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 367

Chapter 15 Methods and Jobs

• “LIST_TARGETS” on page 364

• “MODIFY_TRACE” on page 363
• “SET_OPTIONS” on page 364

The following are workflow methods:

• “RECOVER_AUTO_TASKS” on page 365

• “WORKFLOW_AGENT_MANAGEMENT” on page 366
• “REGEN_EXPRESSIONS” on page 366

15.3.2.32 Choosing a file on the server file system

This section describes how to choose a file on the server file system.

To choose a file on the server file system:

1. Navigate to the correct location on the file system.

2. Select the file.

3. Click OK to return to the Parameters page.

15.4 Jobs
Jobs are repository objects that automate method object execution. Methods
associated with jobs are executed automatically on a user-defined schedule. The
properties of a job define the execution schedule and turn execution on or off. Jobs
are invoked by the agent exec process, a process installed with Documentum Server.
At regular intervals, the agent exec process examines the job objects in the repository
and runs those jobs that are ready for execution. Any user can create jobs.

When a repository is created, it contains jobs for:

• CA Store (Centera and NetApp SnapLock stores)

• Content
• Data Dictionary
• Distributed Content
• Repository
• Federation
• Fulltext
• Other
• Replication
• Workflow

368 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

You can create additional jobs to automate the execution of any method and you can
modify the schedule for executing existing jobs.

Documentum Platform and Platform Extensions Installation Guide contains more

information on federation and replication jobs.

15.4.1 Job descriptions

The following sections describes jobs that are automatically created with each
repository. The descriptions of the jobs discusses the arguments that can be modified
for each job.

15.4.1.1 ACL replication (dm_ACLReplication)

The ACL Replication job first sets external ACLs for replication within a repository
federation and then launches ACL (permission set) replication. It is installed in an
inactive state. Documentum Platform and Platform Extensions Installation Guide contains
the information on replication and replication jobs.

15.4.1.2 ACL replication (dm_ACLRepl_repository)

The dm_ACLRepl_ job replicates ACLs to repositories in a federation. There is one
job for each member repository, and repository is the first 19 bytes of the name of
repository. It is an internal template job that is installed in an inactive state. Do not
edit or remove this job. Documentum Platform and Platform Extensions Installation
Guide contains the information on replication and replication jobs.

15.4.1.3 Asynchronous Write (dm_AsynchronousWrite)

When users import documents in asynchronous mode, there may be instances
where some or all content may not be immediately replicated from BOCS to ACS.
This might happen if the Documentum Messaging Services (DMS) server was not
available or there were network issues between BOCS, DMS, and/or ACS.

The Asynchronous Write job polls for content still in a parked state and generates
new messages for the DMS server to pass to BOCS to request the upload of the
parked content. After execution, the job lists all content objects that had yet to be
moved from the parked state and for which messages were sent to the DMS server.
If a BOCS server receives a request to migrate content that is has already processed,
it will ignore the request.

This job is inactive by default, but should be enabled whenever asynchronous mode
is allowed. The job is scheduled to run daily at 2:00 a.m. by default.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 369

Chapter 15 Methods and Jobs

15.4.1.4 Audit Management

The 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
removed periodically, the tables for the dm_audittrail object type can grow quite
large, and performance degrades when audited events occur. The Audit
Management tool automates the task of removing unneeded audit trail objects.

The tool runs under the Documentum installation owner account to execute the
dm_AuditMgt job. The job uses the PURGE_AUDIT administration method to
remove the audit trail entries from the repository. Consequently, to use this tool, the
Documentum installation owner must have Purge Audit privileges. All executions
of the tool are audited. The generated audit trail entry has the event name
dm_purgeaudit.

The cutoff_days and custom_predicate arguments determine which audit trail

objects to remove. The cutoff_days argument specifies the age of the objects to
delete. The custom_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

is set to remove only audit trail objects generated by system-defined events. (The
tool does not 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 the
custom_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=1

You cannot change the first two conditions. The third condition, r_gen_source=1,
directs the server to delete only audit trail objects generated by system-defined
events. If you want to remove only audit trail objects generated by user-defined
events, reset this to r_gen_source=0. If you want to remove audit trail objects
generated by both system- and user-defined events, remove the r_gen_source
expression from the custom predicate.

You may also add other conditions to the default custom predicate. If you add a
condition that 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 that record 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.

370 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

The Audit Management tool generates a status report that lists the deleted
dm_audittrail entries. 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
notification to the user specified by the -auditperson argument.

The Audit Management tool is installed in the inactive state. The first time you
execute the tool, it may take a long time to complete.

15.4.1.4.1 Arguments

“Audit Management arguments” on page 371, lists the arguments to the Audit
Management tool.

Table 15-7: Audit Management arguments

Argument Datatype Default Description

-window_interval integer 120 Defines the execution
window for the tool.
Value is interpreted
in minutes.
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 371

Chapter 15 Methods and Jobs

Argument Datatype Default Description

-custom_predicate string - A WHERE clause
qualification qualification for the
query that selects
audit trail entries for
deletion.

The qualification
must be a valid
qualification and can
reference only audit
trail object type
properties. For
example, a valid
qualification is
event=‘approved’ or
name=‘dmadmin’.
(Refer to the general
discussion of the tool
for details of setting
this argument.)

TheDocumentum
Server DQL Reference
Guide for complete
information about
WHERE clause
qualifications.
-cutoff_days integer 90 A minimum age, in
days, for objects to
delete. All audit trail
objects older than the
specified number of
days and that meet
the specified
qualification are
deleted.

To delete all audit

trail objects, set this
value to zero (0).

372 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.4.2 Guidelines

Audit trail entries are the result of audited events. The more events you audit, the
more audit 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. For
example, you may want to keep certain items for traceability purposes. If so, leave
this tool inactive or set the cutoff_days argument to a value that will save the audit
trail 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-

generated dm_audittrail entries older than 90 days are deleted.

15.4.1.4.3 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 5f00010080000124
Destroying audit trail item with ID 5f00010080000125
Destroying audit trail item with ID 5f00010080000126
Destroying audit trail item with ID 5f00010080000127
Destroying audit trail item with ID 5f00010080000128
Destroying audit trail item with ID 5f00010080000129
Destroying audit trail item with ID 5f0001008000012a
Destroying audit trail item with ID 5f0001008000012d
Destroying audit trail item with ID 5f0001008000012e
Destroying audit trail item with ID 5f0001008000012f
Destroying audit trail item with ID 5f00010080000130
Destroying audit trail item with ID 5f00010080000131
Destroying audit trail item with ID 5f00010080000132
Destroying audit trail item with ID 5f00010080000133
Destroying audit trail item with ID 5f00010080000134
Destroying audit trail item with ID 5f00010080000135
Destroying audit trail item with ID 5f00010080000136
Destroying audit trail item with ID 5f00010080000137
18 audit trail items deleted...

End of Audit Trail Management Report

Report End 10/19/98 12:26:33 PM

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 373

Chapter 15 Methods and Jobs

15.4.1.5 Consistency Checker

The Consistency Checker tool scans the repository and reports any inconsistencies
such as type or object corruption, objects that reference a user, group, or other object
that is nonexistent in the repository and so forth. The tool does not attempt to fix any
of the inconsistencies. Contact OpenText Global Technical Services for assistance in
correcting errors in your repository found by the consistency checker.

Appendix D, Consistency Checks on page 651, lists the consistency checks

conducted by the tool and 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 is found, 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
repository to a new version of the Documentum Server.

The Consistency Checker job is active by default, running once a day.

15.4.1.5.1 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 the
consistency checker, superuser is the user name of a repository superuser, and
password is the password for the account of superuser.

When you run the consistency checker from the command line, the results of the
checks are directed to standard output.

15.4.1.5.2 Arguments

The Consistency Checker job has no arguments.

374 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.5.3 Report sample

Here is a sample of a Consistency Checker report. This run of the tool found X
inconsistencies.
Beginning Consistency Checks.....

Repository Name: buzzard

Server Version: 5.1.0.63 Win32.SQLServer
Database: SQLServer

#################################################
##
## CONSISTENCY_CHECK: Users & Groups
##
## Start Time: 09-10-2002 10:15:55
##
##
#################################################

Checking for users with non-existent group

WARNING 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 to
non-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_user

Checking for users not listed in dmi_object_type
Checking for groups not listed in dmi_object_type
Checking for groups belonging to non-existent groups
Checking for groups with non-existent super groups

##################################################
##
##
## CONSISTENCY_CHECK: ACLs ##
##
## Start Time: 09-10-2002 10:15:55
##
##
##################################################

Checking for ACLs with non-existent users

Checking for ACLs with missing dm_acl_r table entries
Checking for sysobjects with acl_domain set to
non-existent user
Checking for sysobjects that belong to
non-existent users
Checking for sysobjects with non-existent ACLs
Checking for ACL objects with missing dm_acl_s entry
Checking for ACL objects with r_accessor_permit
value but missing r_accessor_name value
Checking for ACL objects with r_accessor_name value
but missing r_accessor_permit value
Checking for ACL objects with r_is_group value but
missing r_accessor_permit value
Checking for ACL objects with r_is_group value but
missing r_accessor_name value
Checking for ACL object with r_accessor_name value
but missing r_is_group value
Checking for ACL object with r_accessor_permit value
but missing r_is_group value

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 375

Chapter 15 Methods and Jobs

################################################
##
##
## CONSISTENCY_CHECK: Sysobjects
##
##
## Start Time: 09-10-2002 10:15:58
##
##
#################################################

Checking for sysobjects which are not referenced in

dmi_object_type
Checking for sysobjects that point to non-existent
content
Checking for sysobjects that are linked to non-existent
folders
Checking for sysobjects that are linked to non-existent
primary cabinets
Checking for sysobjects with non-existent i_chronicle_id
Checking for sysobjects with non-existent i_antecedent_id
Checking for sysobjects with missing
dm_sysobject_r entries
Checking for sysobjects with missing
dm_sysobject_s entry

#################################################
##
##
## CONSISTENCY_CHECK: Folders and Cabinets
##
## Start Time: 09-10-2002 10:16:02
##
##
#################################################

Checking for folders with missing dm_folder_r table

entries
Checking for folders that are referenced in dm_folder_r
but not in dm_folder_s
Checking for dm_folder objects that are missing an
entry in dmi_object_type
Checking for dm_folder objects that are missing
corresponding dm_sysobject entries
Checking for folders with non-existent ancestor_id
Checking for cabinet that have missing dm_folder_r
table entries
Checking for cabinets that are missing an entry in
dmi_object_type
Checking for folder objects with missing
dm_sysobject_r entries
Checking 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 entry

but no dm_document_s entry
Checking for documents with missing dm_sysobect_s
entries
Checking for documents with missing dmi_object_type
entry

376 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

#################################################
##
##
## CONSISTENCY_CHECK: Content
##
## Start Time: 09-10-2002 10:16:03
##
##
##
#################################################

Checking for content objects that reference

non-existent parents
Checking for content with invalid storage_id
Checking 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-existent

queued objects
Checking for dmi_workitem objects that reference
non-existent dm_workflow objects
Checking for dmi_package objects with missing
dmi_package_s entries
Checking for dmi_package objects that reference
non-existent dm_workflow objects
Checking for workflow objects with non-existent
r_component_id
Checking for workflow objects with missing
dm_workflow_s entry
Checking for work item objects with missing
dm_workitem_s entry

################################################
##
##
## CONSISTENCY_CHECK: Types
##
## Start Time: 09-10-2002 10:16:04
##
##
################################################

Checking for dm_type objects with a non-existen

t dmi_type_info object
Checking for dmi_type_info objects with a non-existent
dm_type object
Checking for type objects with corrupted property
positions
Checking for types with invalid property counts

#################################################
##
##
## CONSISTENCY_CHECK: Data Dictionary
##
## Start Time: 09-10-2002 10:16:04
##
##
#################################################

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 377

Chapter 15 Methods and Jobs

Checking for duplicate dmi_dd_attr_info objects

Checking for duplicate dmi_dd_type_info objects
Checking for any dmi_dd_attr_info objects that are
missing an entry in dmi_dd_common_info_s
Checking for any dmi_dd_type_info objects that are
missing an entry in dmi_dd_common_info_s
Checking for any dmi_dd_attr_info objects that are
missing an entry in dmi_dd_attr_info_s
Checking for any dmi_dd_type_info objects that are
missing 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_existent

policy objects
Checking for any policy objects that reference
non-existent types in included_type
Checking for any policy objects with missing
dm_sysobject_s entry
Checking for any policy objects with missing
dm_sysobject_r entries
Checking for policy objects with missing dm_policy_r
entries
Checking for policy objects with missing dm_policy_s
entry

################################################
##
##
## CONSISTENCY_CHECK: FullText
##
## Start Time: 09-10-2002 10:16:11
##
################################################

Checking for tdk index objects that point to

non-existent fulltext index objects
Checking for any tdk collect objects that point to
non-existent tdk index objects
Checking for any fulltext index objects that point
to non-existent tdk index objects
Checking for any tdk index objects that point to
non-existent tdk collect objects
Checking for any non-orphaned dmr_content objects
that point to types that do not exist
Checking for any non-orphaned dmr_content objects
that point to non-existent formats
Checking for any dmr_content objects that point to
a non-existent fulltext index
Checking for any fulltext index propertys that are
no longer in dm_type

#################################################
##
##
## CONSISTENCY_CHECK: Indices
##
## Start Time: 09-10-2002 10:16:11
##
#################################################

Checking for dmi_index objects that reference

non-existent types

378 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Checking for types with non-existent dmi_index

object for <type>_s table
Checking for types with non-existent dmi_index
object for <type>_r table
Checking for index objects with invalid property
positions

################################################
##
##
## CONSISTENCY_CHECK: Methods
##
## Start Time: 09-10-2002 10:16:11
##
################################################

Checking for java dm_method objects that reference

jview

Consistency Checker completed successfully

Total number of inconsistencies found: 5
Disconnected from the server.

15.4.1.6 Content Replication

The Content Replication tool automates content replication between the component
storage areas of a distributed storage area. The tool uses dump and load operations,
but unlike manual dump and load operations, only requires enough temporary disk
space to transfer the largest individual content file to be replicated.

By default, the tool processes the content files in batches. It retrieves up to 500
content files (the default batch size) and releases resources in the source database
before replicating the files. You can adjust the size of the batches by setting the -
batch_size argument. Each execution of the job may process multiple batches,
depending on the number 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

used in the query. All files to be replicated are cached in the memory of
Documentum Server and transferred individually. Set -batch_size to 0 only if you
have a very large amount of memory available.

If the -batch_size argument is set to 1, the FETCH_ALL_RESULTS hint is not used

and query results are not cached.

If the -batch_size argument is set to any value greater than 1 and content transfer
operations 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
not include 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 time and must be synchronized with the host machine on which the job
runs. The login ticket for the job is valid for 5 minutes. If the clocks are not
synchronized or the machines are using times set to different time zones, the

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 379

Chapter 15 Methods and Jobs

source server to which the job is connecting may 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 while
connected to other sites, and performs an IMPORT_REPLICA for each content file in
need of replication. The job generates a report that lists each object replicated. The
report is 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 name has the server configuration name appended with name of site.
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 argument values of job for the remote sites are
based on those of the Content Replication job for the primary site, but the job name
and target server will be unique for each site. The job name has the format:
dm_ContentReplicationserverconfig.object_name

The target_server property of job identifies the local server performing the
replication using the format repository.serverconfig@hostname.

The ContentReplication job is inactive by default.

15.4.1.6.1 Arguments

“Content Replication arguments” on page 380, describes the arguments for the tool.

Table 15-8: Content Replication arguments

Argument Datatype Default Description

-window_interval integer 120 Defines window in
which the tool can
run. Value is
interpreted in
minutes.
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-batch_size integer 500 Number of content
files to process in
each batch.

380 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Argument Datatype Default Description

-custom_predicate string - Qualification applied
to the content to be
replicated. Enter
what would normally
appear after WHERE
in a DQL
qualification (For
example,
FOLDER
('/xyz', descend)

-source_servers string - Comma-separated

list of Documentum
Servers to which to
connect. Use the
names of the servers’
server configuration
objects.

The argument
accepts a maximum
of 255 characters. The
specified names are
recorded in the
method_arguments
property of job.

If this argument is
not included, the job
attempts to connect
to all other servers in
the repository.

15.4.1.6.2 Report sample

Here is a sample of a ContentReplication report.

ContentReplication Report For repository wagnerdb
As Of 3/16/97 4:58:34 PM
Making lists of distributed components that are
local and far
Far Store: StoreC
Near Store: StoreE
Getting the source user for connecting to
other sites...
Getting the source password for connecting
to other sites...
Now connected to WagnerA
Replicated 1 KB, format text for document
DBWarning
Replicated 7 KB, format text for document
StateOfDocbase
Replicated 14 KB, format text for document
LogPurge
Replicated 2 KB, format text for document
ContentReplication
Replicated KB, format text for document
ContentReplication

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 381

Chapter 15 Methods and Jobs

Replicated KB, format text for document

ContentReplication
Replicated KB, format text for document
ContentReplication
Replicated 3 KB, format text for document
ContentWarning
Replicated 5 KB, format text for document
DMClean
Replicated 4 KB, format text for document
DMFilescan
Replicated KB, format text for document
Disconnected from WagnerA
Report End 3/16/97 4:58:53 PM

15.4.1.7 Content Warning

The Content Warning tool notifies you when disks that you use for content storage
approach a user-defined capacity. The notification is sent to the repository Inbox of
the queueperson and as an email message. The tool also generates a report that is
stored in the Reports folder under the Sysadmin folder in the System cabinet.

The tool determines where the repository is storing its content and then uses
operating system commands to determine whether these disks are reaching the
specified threshold. When the disk space used meets or exceeds the value in the
percent_full argument of tool, a notification is sent to the specified queueperson and
a report is generated and saved to the repository in /System/Sysadmin/Reports/
ContentWarning.

Notes

• If the tool was run against the content at a remote distributed site, the report
name has the server configuration name appended with name of site. For
example, if London is a remote site, its report would be found in /System/
Sysadmin/Reports/ContentWarningLondon.
• The dm_ContentWarning job may not work properly when the disk space is
in terabytes scale.

The Content Warning tool is installed in the active state by default.

15.4.1.7.1 Arguments

“Content Warning arguments” on page 382, describes the arguments for the tool.

Table 15-9: Content Warning arguments

Argument Datatype Default Description

-percent_full integer 85 Percent-full threshold
at which a message is
sent.

382 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Argument Datatype Default Description

-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 720 Execution window
for the tool,
expressed in minutes.

15.4.1.7.2 Report sample

Here is a sample of a ContentWarning report.

Object: test1_file_store
Type : dm_filestore
Path : /export/nfs2-4/dmadmin/data/test1/
test1_storage_location
Total Disk Total Used Total Free Percent Used
1,952,573 1,620,019 137,304 93

DocBasic Total Free: 1,124,794

Content File (Document) Space Utilization
In test1_file_store

-Active 2,485,090
-Deleted 81,397
-Total 2,566,487

Object: test1_file_store2
Type : dm_filestore
Path : /export/nfs2-1/dmadmin/data/test1/storage_02

Total Disk Total Used Total Free Percent Used

1,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_store
Type : dm_filestore
Path : /export/nfs2-1/dmadmin/data/test1/docs_from_test2

Total Disk Total Used Total Free Percent Used

1,952,573 1,113,666 643,657 67

DocBasic Total Free: 977,871

Content File (Document) Space Utilization In

test2_file_store
-Active 863
-Deleted
-Total 863

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 383

Chapter 15 Methods and Jobs

15.4.1.8 Data Dictionary Publisher

The Data Dictionary Publisher tool publishes the data dictionary information. The
data dictionary is information about object types and properties stored in internal
objects by Documentum Server and made available to client applications through
the publishing operation. 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 these objects and their properties. (For more information
about the data dictionary, refer to Documentum Server Fundamentals Guide.)

Data Dictionary Publisher generates a status report that is saved in the repository
in /System/Sysadmin/Reports/DataDictionaryPublisher.

15.4.1.8.1 Arguments

“Data Dictionary Publisher argument” on page 384, describes the argument of tool.

Table 15-10: Data Dictionary Publisher argument

Argument Datatype Default Description

-window_interval integer 720 Execution window
for the tool,
expressed in minutes.

15.4.1.8.2 Report sample

Connected To sqlntX.sqlntX
Job Log for System Administration Tool
DataDictionaryPublisher
-----------------------------------------------

This job log consists of three distinct parts:

1) All print statements from the execution of the job
2) The report for the tool which is saved as a
separate document in the repository 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 maintained

under the Documentum log location in:
$DOCUMENTUM/dba/log/<docbase hex id>/sysadmin
They are overwritten each time the job executes.

Start of log:
-------------
DataDictionaryPublisher Tool Completed at
11/8/2000 12:15:25. Total duration was 0 minutes.
Calling SetJobStatus function...

--- Start
c:\Documentum\dba\log\000145df\sysadmin\
DataDictionaryPublisherDoc.txt report output ----
DataDictionaryPublisher Report For repository sqlntX
As Of 11/8/2000 12:15:24
DataDictionaryPublisher utility syntax:
apply,c,NULL,EXECUTE_DATA_DICTIONARY_LOG

384 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Executing DataDictionaryPublisher...
Report End 11/8/2000 12:15:25

--- End
c:\Documentum\dba\log\000145df\sysadmin\
DataDictionaryPublisherDoc.txt report output ---

15.4.1.9 Database Space Warning

The 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 present.

The tool also recreates any indexes that are identified by dmi_index objects but not
found in the database.

Note: The Database Space Warning Tool is not needed, and therefore not
installed, for installations running against SQL Server.

If the tool finds that the space has reached the limit specified in the percent_full
argument of tool, it sends a notification to the user specified in queueperson. When
it sends a notification, it also includes a message about any RDBMS tables that are
fragmented beyond the limits specified in the max_extents argument and a message
regarding indexes, if it does not find the expected number in the RDBMS. The
notifications are sent to the Inbox of user repository and through email.

In addition to these notifications, the tool generates a status report that is saved in
the repository 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. The
isql syntax is:
sp_dboption dbname, "ddl in tran", true

where dbname is the name of the database for your repository.

15.4.1.9.1 Arguments

“Database Space Warning arguments” on page 385, lists the arguments of tool.

Table 15-11: Database Space Warning arguments

Argument Datatype Default Description

-percent_full integer 85 Percent-full threshold
at which a message is
sent.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 385

Chapter 15 Methods and Jobs

Argument Datatype Default Description

-max_extents integer 50 The number of
extents that an
RDMBS table may
have before being
reported as
fragmented.
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 720 Execution window
for the tool,
expressed in minutes.

15.4.1.9.2 Report sample

Here is a sample of a Database Space Warning report. It shows the total number of
blocks 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 the number of fragments for all tables and indexes with more than
max_extents fragments and lists the number of Documentum indexes in the
repository.
Database Block Allocation
Table Index TotalUsed Free Total %Used/Total
620 647 1,267 81,929 83,196 2

DBMS Tables With Multiple Extents

# of Segs Type Name
6 TABLE DM_TYPE_R
5 INDEX DMINDEX_1F00096380000009
4 TABLE DM_SYSOBJECT_S
3 TABLE DMI_OBJECT_TYPE
3 INDEX DMI_OBJ_TYPE_INDEX
3 INDEX DMI_OBJ_ID_INDEX
3 TABLE DM_FORMAT_S
3 TABLE DM_SYSOBJECT_R

386 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.9.3 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.001
Date: Wed, 20 Mar 1996 11:18:54 -0800
From: dmadmin@bigcat (Documentum 2.0)
To: stevex@tiger
Subject: Event FraggedTables has occurred
on DBWarning.Doc
(090000018006ee33) by dm20

DOCBASE: test1
EVENT: FraggedTables
NAME: DBWarning.Doc
SENT BY: dmadmin
TASK NAME: event

MESSAGE:
You have 18 fragmented tables in your DBMS instance
--you may want to correct this!

15.4.1.10 Distributed operations (dm_DistOperations)

The dm_DistOperations job performs inter-repository distributed operations. These
tasks include:

• Propagating distributed events (dmi_queue_items) across repositories

• Creating checkout references for remote checkout operations
• Refreshing reference links

The dm_DistOperations job is configured to run every five minutes by default. Do

not change the schedule.

It is installed in the repository in an inactive state.

15.4.1.11 Archive
The Archive tool automates archive and restore between content areas. Archive
older or infrequently accessed documents to free up disk space for newer or more
frequently used documents. Restore archived documents to make the archived
documents available when users request them. For complete information on
configuring archiving, refer to “Archiving and restoring documents” on page 536.

The Archive tool is active by default, and runs once daily.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 387

Chapter 15 Methods and Jobs

15.4.1.11.1 Arguments

“Archive arguments” on page 388 describes the arguments for the tool

Table 15-12: Archive arguments

Argument Datatype Default Description

-docbase_name string(64) - Identifies the
repository repository that
contains the
document or
documents to
archive. Use the
name of repository.
-Uusername string(64) - Identifies the user
executing dmarchive.
If unspecified, the
current user is
assumed.
-Ppassword string(64) - Password for the user
executing dmarchive.
If unspecified, the
user is prompted.
-archive_dir directory string - The location of the
archive directory.
Use a full path
specification.
-queue_name name string - Identifies the
repository operator.
Specify the repository
user name of
operator. If
unspecified, the tool
assumes the user
named in the
operator_name
property of the server
configuration object.
-queue_event event_id ID - Object ID of the
queue item object
representing an
archive or restore
event.

If set, the tool

processes only the
specified event.

388 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Argument Datatype Default Description

-do_archive _events Boolean - TRUE directs the tool
to process only
archive events.
-do_restore _events Boolean - TRUE directs the tool
to process only
restore events.
-verbose Boolean T TRUE directs the tool
to print trace
messages.
-window_interval integer 720 Defines window in
which the tool can
run. Value is
interpreted in
minutes.
-queueperson string - Identifies the user
who receives Inbox
and email
notifications from the
tool.

15.4.1.11.2 Guidelines

The Archive tool puts all the documents it is archiving in one dump file. This means
you must move the entire dump file back to the archive directory to restore a single
document in the file. If the files are extremely large, this can be a significant
performance hit for restore operations.

15.4.1.12 Dmclean
The Dmclean tool automates the dmclean utility. The utility scans the repository for
orphaned content objects and content objects. The utility generates a script to
remove these orphans. The Dmclean tool performs the operations of dmclean and
(optionally) runs the generated script.

When the agent exec program invokes the script, the tool generates a report showing
what content objects and content files are 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 name has the server configuration name is appended with the name of
the site. For example, if London is a remote site, its report would be found in /
System/Sysadmin/Reports/DMCleanLondon.

The Dmclean tool is installed in the inactive state.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 389

Chapter 15 Methods and Jobs

15.4.1.12.1 Arguments

“Dmclean arguments” on page 390, describes the arguments for the tool.

Table 15-13: Dmclean arguments

Argument Datatype Default Description

-clean_content Boolean TRUE Controls whether the
tool searches for
orphaned content
objects. Set to FALSE
if you do not want to
include content
objects in the
dmclean operation.
-clean_castore Boolean FALSE Controls whether the
tool includes
orphaned content
with expired
retention dates in
Centera storage areas
in the operation. T
means that expired,
orphaned content in
Centera storage areas
is included in the
operation.
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 120 Execution window
for the tool.

15.4.1.12.2 Guidelines

If you are using distributed content, Dmclean requires the default storage area for
dm_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 capacity

390 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.12.3 Report sample

Here is a sample of a Dmclean report:

DMClean Report For DocBase testdoc
As Of 5/14/2002 11:58:46

Arguments for the dmclean method:

objects 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:
----- Start
C:\Documentum\dba\log\000003e8\sysadmin\
080003e8800005d6.bat
output ------------------------
# 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/Links
folder.
# /System/Distributed References/Links folder
exists.
# Making /System/Distributed References/Checkout
folder.
# /System/Distributed References/Checkout folder
exists.
# Making /System/Distributed References/Assemblies
folder.
# /System/Distributed References/Assemblies folder
exists.
# Making /System/Distributed References/Workflow
folder.
# /System/Distributed References/Workflow folder
exists.
# Making /System/Distributed References/VDM folder.
# /System/Distributed References/VDM folder exists.
# Making docbase config object.
# Making server configuration object.
#
# dmclean cleans up orphan content objects and content files.
# 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.
#

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 391

Chapter 15 Methods and Jobs

# 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_CONTENT
getmessage,c
close,c,q0
# Content object 060003e880002101 has parent
# count of zero.
apply,c,060003e880002101,DESTROY_CONTENT
getmessage,c
close,c,q0
# Content object 060003e880002105 has parent
# count of zero.
apply,c,060003e880002105,DESTROY_CONTENT
getmessage,c
close,c,q0
# Content object 060003e88000210c has parent
# count of zero.
apply,c,060003e88000210c,DESTROY_CONTENT
getmessage,c
close,c,q0
# Content object 060003e880002114 has parent
# count of zero.
apply,c,060003e880002114,DESTROY_CONTENT
getmessage,c
close,c,q0
# Content object 060003e880002119 has parent
# count of zero.
apply,c,060003e880002119,DESTROY_CONTENT
getmessage,c
close,c,q0
# Count of objects with zero parent count was: 6
# Content cleanup complete.
# Starting to clean up unused subcontent objects...
# SubContent cleanup complete.
------- End
C:\Documentum\dba\log\000003e8\sysadmin\
080003e8800005d6.bat output ------------------------
Destroying DMClean script with ID 090003e880002907...
Report End 5/14/2002 11:59:16

15.4.1.13 Dmfilescan
The Dmfilescan tool automates the dmfilescan utility. This utility scans a specific
storage area or all storage areas for any content files that do not have associated
content objects and generates a script to remove any that it finds. The tool executes
the generated script by default, but you can override the default with an argument.
“The dmfilescan utility” on page 533 provides detailed information about the
dmfilescan utility.

Dmfilescan also generates a status report that lists the files it has removed. The
report is saved in the repository in /System/Sysadmin/Reports/DMFilescan.

Note: If the tool was run against the content at a remote distributed site, the
report name has the server configuration name appended with name of site.
For example, if London is a remote site, its report would be found in /System/
Sysadmin/Reports/DMFilescanLondon.

392 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Dmfilescan is installed in the inactive state.

15.4.1.13.1 Arguments

“Dmfilescan arguments” on page 393, lists the arguments for the tool. Refer to the
description of the dmfilescan utility in “The dmfilescan utility” on page 533, for
instructions on specifying values for the -from and -to arguments.

Table 15-14: Dmfilescan arguments

Argument Datatype Default Description

-s storage_name string - Specifies a target
storage area. If this
argument is not
included, all storage
areas are scanned.
-from directory_path string - Starting subdirectory
for the scan
operation.
-to directory_path string - Ending subdirectory
for the scan
operation.
-scan_now Boolean TRUE Controls whether the
generated script is
executed. TRUE (the
default) executes the
generated script. Set
this to FALSE if you
want to execute the
script manually.
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 120 Execution window
for the tool.
-force_delete Boolean FALSE Controls whether
orphan files created
within 24 hours of
the execution job are
deleted. Refer to the
Guidelines for
details.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 393

Chapter 15 Methods and Jobs

Argument Datatype Default Description

-no_index_creation Boolean FALSE Controls whether
dmfilescan creates
and destroys the
indexes on
dmr_content.data_tic
ket and
dmr_content.other
ticket or assumes
they exist.

T (TRUE) means that

the utility assumes
that the indexes exist
prior to the start of
the utility. F (FALSE)
means the utility will
create these indexes
on startup and
destroy them at the
finish.
-grace_period integer 168 Defines the grace
period for allowing
orphaned content
files to remain in the
repository. The
default is 168 hours
(1 week), expressed
as hours. The job
removes orphaned
files whose age
exceeds 1 week or the
value defined in the -
grace_period
argument.

The integer value for

this argument is
interpreted as hours.

15.4.1.13.2 Guidelines

Typically, if you run the Dmclean tool regularly, it is not necessary to run the
Dmfilescan tool more than once a year. By default, the tool removes all orphaned
files from the specified directory or directories that are older than 24 hours. If you
wish to remove orphaned 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 to clear diskspace or to remove temporary dump files created on the
target that were not removed automatically. If you execute Dmfilescan with -
force_delete set to T, make sure that there are no other processes or sessions creating
objects in the repository at the time the job executes.

394 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

If you are using distributed content, dmfilescan requires the default storage area for
dm_sysobjects to be the distributed store.

15.4.1.13.3 Report sample

The following is a sample of a Dmfilescan report.

DMFilescan Report For DocBase boston2
As Of 9/17/96 11:08:54 AM
Generated DMFilescan script will be executed...
The trace level is set to 5...
DMFilescan utility syntax: apply,c,NULL,DO_METHOD,
METHOD,S,dmfilescan
Executing DMFilescan...
Executing DMFilescan script...
sh /u106/dm/dmadmin/dba/log/00000962/sysadmin/
0900096280012800.bat
>/u106/dm/dmadmin/dba/log/00000962/sysadmin/
0900096280012800.txt
Generated 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 configuration 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'

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 395

Chapter 15 Methods and Jobs

# 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
#

396 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

# 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

15.4.1.14 Fix folder (dm_fixfolder)

This tool checks each folder in the repository for corruption in r_folder_path or
i_ancestor_id. This tool:

• Runs the dm_fixfolder_Java method.

• Checks that r_folder_path values reflect r_folder_path of the parents.
• Checks that i_ancestor_id values correctly reflect the IDs of the parents.
• Looks for (and removes) self-linked folders and attaches the orphaned folders to
the /Temp cabinet.
• Issues warnings about folder paths which exceeds the field width.

15.4.1.14.1 Arguments

The dm_fixfolder tool has the following arguments:

• docbase_name
• user_name
• password
• method_trace_level
• (optional) folderQual: ID of the folder or query.
• (optional) report_only_mode: Valid values are True or False. Default is True,
which means only a report is generated and the corrupted folders are not fixed.

15.4.1.15 Federation copy (dm_FederationCopy)

The Federation Copy tool transfers LDIF files, which contain user and group
information, to member repositories from the governing repository. The job is
installed in an inactive state. Documentum Platform and Platform Extensions Installation
Guide contains the information on repository federations and the federation jobs.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 397

Chapter 15 Methods and Jobs

15.4.1.16 Federation export (dm_FederationExport)

The Federation Export tool exports user and group information from the governing
repository to an LDIF file. The job is installed in an inactive state. Documentum
Platform and Platform Extensions Installation Guide contains the information on
repository federations and the federation jobs.

15.4.1.17 Federation import (dm_FederationImport)

The Federation Import tool imports an LDIF file that contains user and group
information into a member repository. The job is installed in an inactive state. When
you create a federation, the job is activated in the member repositories. Documentum
Platform and Platform Extensions Installation Guide contains the information on
repository federations and the federation jobs.

15.4.1.18 Federation status (dm_FederationStatus)

The Federation Status tool polls the members of a federation to determine the
current status of any Federation Import jobs running on the member repository. The
job is installed in an inactive state. When you create a federation, the job is activated
in the governing repository. Documentum Platform and Platform Extensions Installation
Guide contains the information on repository federations and the federation jobs.

15.4.1.19 Federation update (dm_FederationUpdate)

The Federation Update tool executes on the governing repository of a federation to
run all other methods in sequence, pushing user, group, and ACL changes to the
member repositories. The job is installed in an inactive state. When you create a
federation, the job is activated in the governing repository. Documentum Platform and
Platform Extensions Installation Guide contains the information on repository
federations and the federation jobs.

15.4.1.20 File Report

The File Report tool assists you in restoring deleted repository documents. It
generates a report 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 content file of a deleted document. “Using a report to restore a
document” on page 400 provides instructions on restoring a document.

If a document must be recreated, these reports identify which files must be restored
to rebuild the document. The system administrator matches lost documents to the
file names so that the content files can be recovered. This feature is especially useful
for restoring a single document (or a small set of documents) to a previous state,
which cannot be done from database backups.

The File Report tool as installed, runs a full report once a week against all file storage
areas in the repository. It is possible to run incremental reports and reports that only
examine a subset of the storage areas for the repository. “Creating incremental or
partial-repository reports” on page 399 provides instructions to set up reports.

398 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Note: File Report only provides a mechanism for restoring the document
content. The document metadata must be restored manually.

File Report saves the generated report to /System/Sysadmin/Reports/FileReport.

The File Report tool is installed as inactive.

15.4.1.20.1 Guidelines

Set up the File Report schedule on the same interval as the file system backups. For
example, if nightly backups are done, also run File Report nightly and store the
resulting report with the backups.

We recommend scheduling nightly incremental reports and generating full

repository reports on a less frequent basis (weekly or biweekly).

If your repository is so large that creating full reports is not practical or generates
cumbersome files, set up multiple jobs, each corresponding to a different storage
area.

15.4.1.20.2 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

15.4.1.20.2. Creating incremental or partial-repository reports

1

A File Report job creates an incremental report if its -incremental_report argument is

set to TRUE. Incremental reports only include documents that have changed since
the last File Report was run.

If you include the -storage_area argument, the job generates a report on the
documents in the specified storage area.

If you include the -folder_name argument, the job generates a report on documents
in the specified folder.

Including both the -storage_area and -folder_name arguments generates a report on

those 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 a job” on page 436, provides instructions for creating new jobs, and
Documentum Server System Object Reference Guide contains a description of the
properties of dm_job object. You can create or copy a job using Documentum
Administrator.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 399

Chapter 15 Methods and Jobs

15.4.1.20.2. Using a report to restore a document

2

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
the documents 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 invocation of the dm_clean utility.
If you wish, you can move these files out of the storage area directories to a
more appropriate 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
metadata and 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 an
addRendition method.
You can restore documents that have only one content file using the Import
function of client if the content files are directly accessible by the client. Because
the content files restored from file system backups are written to the server
storage areas, you must either directly access those directories from the client or
copy the restored files to a network disk and import them from there.
If the document has multiple pages, use DFC methods to restore it.

15.4.1.20.3 Arguments

“File Report arguments” on page 400, lists the arguments for the tool.

Table 15-15: File Report arguments

Argument Datatype Default Description

-folder_name string - Identifies a folder
folder_path path on which to run
the report. May be
used in conjunction
with the -storage-area
argument.

400 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Argument Datatype Default Description

-incremental_report Boolean FALSE When set to TRUE,
the report is run
incrementally. An
incremental report
only reports
documents modified
since the last time the
job ran. (A full report
is generated on the
first execution of the
job).
-storage_area string - Identifies a storage
storage_name area on which to run
the report. Use the
name of storage area.
If this argument is
not set, the report
runs against all
storage areas in the
repository.
-output_device string - Identifies a file to
which to write the
report data. The
specification must be
in the format:

directory_path/
file_name

If the file already

exists, data is
appended to it.

Use this option when

you want to write
directly to a tape
drive or other device.

If not set, the report

file is saved to:
System/Sysadmin/
Reports/FileReport
-report_renditions Boolean TRUE When set to TRUE,
rendition files are
reported as well as
the primary format
files. Set to False if
you do not wish to
report renditions.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 401

Chapter 15 Methods and Jobs

Argument Datatype Default Description

-sort_results Boolean TRUE When set to TRUE,
the file report is
sorted by
folder_path/
object_name.

Because this option

requires a database
sort of the entire data
set returned, you
may need to tune
your sort/temp space
parameters of
database if you use
this option.
-window_interval integer 120 Execution window
for the tool.
-queueperson string - Identifies the user
who receives Inbox
and email
notifications from the
tool.

15.4.1.20.4 Report sample

Each line of a File Report contains the following information:

• Document object_id
• Document folder_path and object_name
• Document owner
• Document modification date
• Document version
• Content format
• Content page number
• Content file name

The following sample report describes a two-page Word document.

100015b4800001b5 /roger/research/newproject_1 roger
4/26/95 19:07:22 1.3 msw6 0

/u120/install/dmadmin/data/rogbase2/content_storage_01
/000015b4/80/00/01/49.doc
100015b4800001b5 /roger/research/newproject_1 roger
4/26/95 19:07:22 1.3 msw6 1

/u120/install/dmadmin/data/rogbase2/content_storage_01
/000015b4/80/00/01/4a.doc

402 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

The following sample report describes a single-page Word document with a PDF
rendition.
090015b4800004f1 /roger/research/newproject_2
roger 6/16/95 20:00:47 1.7 msw6 0

/u120/install/dmadmin/data/rogbase2/content_storage_01
/000015b4/80/00/02/52.txt
090015b4800004f1 /roger/research/newproject_2 roger
6/16/95 20:00:47 1.7 pdf 0

/u120/install/dmadmin/data/rogbase2/
content_storage_01/000015b4/80/00/02/6e.pdf

15.4.1.21 Group Rename

The Group Rename tool renames repository groups. This tool works in conjunction
with Documentum Administrator. To rename a group, you must use the Groups
pages in Documentum Administrator to identify the group and its new name.
Documentum Administrator 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
tool

You cannot use a set method to change a group name. You must go through
Documentum Administrator and either a manual or automatic Group Rename
execution to change a group name. The Group Rename tool generates a report that
lists the changes made to the repository 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.

Documentum Administrator User Guide contains the instructions on changing the

method name.

15.4.1.21.1 Arguments

The Group Rename tool has no arguments.

15.4.1.22 Dm_LDAPSynchronization
The dm_LDAPSynchronization tool finds the changes in the user and group
information in an LDAP directory server that have occurred since the last execution
of the tool and propagates those changes to the repository. If necessary, the tool
creates default folders and groups for new users. If there are mapped user or group
properties, those are also set.

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

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 403

Chapter 15 Methods and Jobs

• 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 inactivation
operation. Instructions for enabling the changelog feature are found in the iPlanet
documentation.

The behavior of the tool is determined by the property settings of the

dm_ldap_config object. The tool has four arguments that you can use to override the
property settings controlling which operations the tool performs. These are listed in
“dm_LDAPSynchronization arguments” on page 404.

The dm_LDAPSynchronization tool requires the Java method server. Ensure that the
Java method server in your Documentum 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 day at 4 a.m. by default.
Before you set it to the active state, you must define the ldap config object for the
repository.

From Documentum Server 7.x versions, return codes of the

dm_LDAPSynchronization job have been modified as follows:

• SYNC RETURN SUCCESS = 0

• SYNC RETURN FAILURE = -1

• SYNC RETURN WARNING = 1

15.4.1.22.1 Arguments

“dm_LDAPSynchronization arguments” on page 404, describes the arguments for

the tool.

Table 15-16: dm_LDAPSynchronization arguments

Argument Datatype Default Description

-deactivate_user Boolean FALSE Set to TRUE, directs
_option the job to inactivate
users in the
repository that have
been deleted from the
directory server.

Setting this overrides

the
deactivate_user_opti
on property in the
ldap config object.

404 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Argument Datatype Default Description

-full_sync Boolean FALSE Set to TRUE, this
directs the job to
retrieve all entries
from the LDAP
directory that satisfy
the search criteria.
FALSE causes the job
to import into the
repository only new
or updated LDAP
entries.
-import_mode string(7) both Controls whether the
job imports users,
groups, or both into
the repository. Valid
values are: users,
groups, and both.

Setting this overrides

the import_mode
property in the ldap
config object.
import_user_ldap_dn Boolean TRUE By default, the
dm_LDAPSynchroni
zation job imports the
dm_user attribute
user_ldap_dn to the
repository.

If you do want to
import this attribute,
set the
dm_ldap_config.bind
_type to
bind_search_dn and
set the argument
import_user_ldap_dn
to FALSE.

Documentum Server
System Object
Reference Guide
contains more
information.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 405

Chapter 15 Methods and Jobs

Argument Datatype Default Description

-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
- Boolean FALSE Set to TRUE, directs
rename_group_optio the job to rename
n groups in the
repository if their
names have changed
in the directory
server.

Setting this overrides

the
rename_group_optio
n property in the
ldap config object.
-rename_user_option Boolean FALSE Set to TRUE, directs
the job to rename
users in the
repository if their
names have changed
in the directory
server.

Setting this overrides

the
rename_user_option
property in the ldap
config object.

406 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Argument Datatype Default Description

-source_directory dm_all_directories Controls which
LDAP servers are
synchronized when
the job runs.

If not set, all LDAP

servers associated
with the server
configuration object
are synchronized. If
set to particular
LDAP servers, only
those servers are
synchronized.

“Explicitly specifying
LDAP servers in -
source_directory”
on page 407,
describes how specify
multiple servers
individually.
-window_interval integer 1440 Execution window
for the tool.

15.4.1.22.2 Executing dm_LDAPSynchronization manually

You can execute the dm_LDAPSynchronization tool manually from the command
line. The syntax is
java 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 a Superuser, and <integer> is the required trace level for the method.

15.4.1.22.3 Explicitly specifying LDAP servers in -source_directory

Use the object name of LDAP server to identify the server in the -source_directory
argument. 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 for
the LDAP directory server. For example:
ldap_engr1+ldap_engr2+ldapQA

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 407

Chapter 15 Methods and Jobs

15.4.1.23 Log Purge

The Log Purge tool deletes old log files. “Files deleted by the Log Purge tool”
on page 408, lists the log files deleted by Log Purge.

Table 15-17: 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
SAVE_RESULTS argument of method 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
trace file of job 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 or
demote occurs. The files are named bp_transition_*.log or bp_schedule_*.log,
depending on 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-
defined cutoff date. By default, the cutoff date is 30 days prior to the current date.
For instance, if you 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. “Arguments” on page 409 provides instructions.

Log Purge generates a report that lists all directories searched and the files that were
deleted. 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
server configuration name appended with name of site. For example, if London

408 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

is a remote site, its report is found in /System/Sysadmin/Reports/

LogPurgeLondon.

The Log Purge tool is installed in the inactive state.

15.4.1.23.1 Arguments

“Log Purge arguments” on page 409, lists the arguments for the tool.

Table 15-18: Log Purge arguments

Argument Datatype Default Description

-cutoff_days integer 30 Controls what logs
are deleted. All logs
older than the
specified number of
days are deleted.
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 120 Execution window
for the tool.

15.4.1.23.2 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 to debug 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
never has log files older than the number of days specified in the cutoff_days
argument.

15.4.1.23.3 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
result logs from method objects and job objects (older than 30 days) and destroys
them.
LogPurge Report For DocBase boston2
As Of 7/25/96 7:18:09 PM
Parameters for removing Logs:
-----------------------------
- Inbox messages will be queued to boston2
- Logs older than 30 days will be removed...

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 409

Chapter 15 Methods and Jobs

Looking for server and connection broker logs in the log

location...
Log Location: log
Log Location File Path: /u106/dm/dmadmin/dba/log
Changing directory to server log location:
/u106/dm/dmadmin/dba/log
Looking for session logs...
The top-level session log directory is:
/u106/dm/dmadmin/dba/log/00000962
Changing directory to:
/u106/dm/dmadmin/dba/log/00000962/boston2
Removing /u106/dm/dmadmin/dba/log/00000962/
boston2/01000962800008be
Removing /u106/dm/dmadmin/dba/log/00000962/
boston2/01000962800008e0
Removing /u106/dm/dmadmin/dba/log/00000962/
boston2/0100096280000904
Removing /u106/dm/dmadmin/dba/log/00000962/
boston2/0100096280000e28
Removing /u106/dm/dmadmin/dba/log/00000962/
boston2/0100096280000e72
Removing /u106/dm/dmadmin/dba/log/00000962/
boston2/0100096280000ed7
Changing directory to:
/u106/dm/dmadmin/dba/log/00000962/dmadmin
Removing /u106/dm/dmadmin/dba/log/00000962/
dmadmin/01000962800008b9
Removing /u106/dm/dmadmin/dba/log/00000962/
dmadmin/01000962800008ba
Removing /u106/dm/dmadmin/dba/log/00000962/
dmadmin/01000962800008b7
Removing /u106/dm/dmadmin/dba/log/00000962/
dmadmin/01000962800008b8
Changing directory to:
/u106/dm/dmadmin/dba/log/00000962/tuser3
Removing /u106/dm/dmadmin/dba/log/00000962/tuser3/
01000962800008fd
Changing directory to:
/u106/dm/dmadmin/dba/log/00000962/tuser1
Changing directory to:
/u106/dm/dmadmin/dba/log/00000962/agentexec
Removing /u106/dm/dmadmin/dba/log/00000962/agentexec/
agentexec.log.save.06.11.96.09.43.37
Changing directory to:
/u106/dm/dmadmin/dba/log/00000962/tuser4
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
01000962800008fe
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
0100096280000900
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
0100096280000902
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
0100096280000944
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
0100096280000947
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
0100096280000948
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
0100096280000949
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
010009628000094a
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
010009628000094d
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
010009628000094e
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
0100096280000955
Removing /u106/dm/dmadmin/dba/log/00000962/tuser4/
trace.tmp
Changing directory to:

410 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

/u106/dm/dmadmin/dba/log/00000962/tuser2
Removing /u106/dm/dmadmin/dba/log/00000962/tuser2/
0100096280000e73
Changing directory to:
/u106/dm/dmadmin/dba/log/00000962/sysadmin
Changing directory to:
/u106/dm/dmadmin/dba/log/00000962/tuser5
Looking for result logs from dm_method objects...
Destroying Result.users_logged_in object
Destroying Result.users_logged_in object
Destroying Result.dmclean object
Destroying Result.dmclean object
Destroying Result.dmclean object
Destroying Result.dmclean object
Destroying Result.users_logged_in object
Destroying Result.users_logged_in object
Looking for result logs from dm_job objects...
Destroying 06/01/96 11:40:27 boston1 object
Destroying 05/31/96 11:40:41 boston1 object
Destroying 06/02/96 11:40:30 boston1 object
Destroying 06/03/96 11:40:15 boston1 object
Destroying 06/04/96 11:40:03 boston1 object
Destroying 06/19/96 11:40:00 boston1 object
Destroying 06/20/96 11:40:55 boston1 object
Destroying 06/22/96 11:40:32 boston1 object
Destroying 06/21/96 11:40:34 boston1 object
Destroying 06/24/96 11:40:10 boston1 object
Destroying 06/23/96 11:40:24 boston1 object
Destroying 06/25/96 11:40:07 boston1 object
Destroying 06/13/96 11:40:08 boston1 object
Destroying 06/16/96 11:40:18 boston1 object
Destroying 06/14/96 11:40:28 boston1 object
Destroying 06/15/96 11:40:27 boston1 object
Destroying 06/17/96 11:40:12 boston1 object
Destroying 06/18/96 11:40:07 boston1 object
Destroying 06/12/96 11:40:06 boston1 object
Destroying 06/11/96 11:40:11 boston1 object
Destroying 06/09/96 11:40:46 boston1 object
Destroying 06/08/96 11:40:03 boston1 object
Destroying 06/10/96 11:40:29 boston1 object
Destroying 06/06/96 11:40:01 boston1 object
Destroying 06/07/96 11:40:55 boston1 object
Destroying 06/05/96 11:40:02 boston1 object
Destroying 05/29/96 11:40:06 boston1 object
Destroying 05/30/96 11:40:49 boston1 object

End of Log Purge Report

Report End 7/25/96 7:19:13 PM

15.4.1.24 Queue Management

The Queue Management Tool deletes dequeued Inbox items. Whenever an item is
queued to the Inbox of a user, an object of type dmi_queue_item is created for that
queued item. When users forward or otherwise remove an item from their Inboxes,
the corresponding dmi_queue_item object is marked dequeued, but it is not
removed from the repository. If these dequeued items are not removed, the tables
for the dmi_queue_item type grow quite large, and performance degrades when
users access their Inboxes. The Queue Management tool automates the task of
removing these unneeded dmi_queue_item objects.

The cutoff_days and custom_predicate arguments determine which

dmi_queue_items are removed. The cutoff_days argument specifies the age of the
objects you want to delete. The custom_predicate argument is applied to those items
meeting the age requirement, allowing you to delete all or only some of them. For

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 411

Chapter 15 Methods and Jobs

example, the tool could delete all dequeued dmi_queue_items that are older than 30
days and were queued 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 execution of tool, an email and Inbox notification is sent to
the user specified by the -queueperson argument.

The Queue Management tool is installed in the inactive state.

15.4.1.24.1 Arguments

“Queue Management arguments” on page 412, lists the arguments for the tool.

Table 15-19: Queue Management arguments

Argument Datatype Default Description

-custom_predicate string - Defines a WHERE
qualification clause qualification
for the query that
selects dequeued
items for deletion.

The qualification
must be a valid
qualification and
must work against
the dmi_queue_item
object. For example, a
valid qualification is
“event=‘APPROVED’
” or
“name=‘dmadmin’”.

Refer to the
Documentum Server
DQL Reference Guide
for complete
information about
WHERE clause
qualifications.

412 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Argument Datatype Default Description

-cutoff_days integer 90 Defines a minimum
age, in days, for
dequeued items. All
dequeued
dmi_queue_items
older than the
specified number of
days and that meet
the specified
qualification are
deleted.

To include all
dequeued items in
the search, set this
value to zero (0).
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 120 Execution window
for the tool.

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.

15.4.1.24.2 Guidelines

Dequeued items are the result of moving objects out of an inbox. Objects are placed
in inboxes by workflows, event notifications, archive and restore requests, or explicit
queue methods. 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. For
example, you may want to keep dequeued items for auditing purposes. If so, leave
this tool inactive or set the cutoff_days argument to a value that will save the
dequeued items for a specified length of time.

After you have made your decisions, formulate a scheduling plan.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 413

Chapter 15 Methods and Jobs

Note: The first time you execute the Queue Management tool, it may take a
long time to complete if dequeued items have never been deleted before.

15.4.1.24.3 Report sample

Here is a sample of the report generated by the Queue Management tool.

QueueMgt Report For DocBase boston2
As Of 7/26/96 5:09:00 PM
Parameters 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 1b00096280000603
Destroying queue item with ID 1b000962800002e4
Destroying queue item with ID 1b00096280000304
Destroying queue item with ID 1b00096280000324
Destroying queue item with ID 1b00096280000344
5 dequeued items deleted...

End of Queue Management Report

Report End 7/26/96 5:09:00 PM

15.4.1.25 Remove expired retention objects

The Remove Expired Retention Objects (RemoveExpiredRetnObjects) tool removes
objects from the repository whose content, stored in an Centera storage area, has an
expired retention date. The tool does not remove the actual content files or the
associated content objects.

The tool invokes the CHECK_RETENTION_EXPIRED administration method to

determine which SysObjects to remove from the repository. By default, the tool
operates only on objects stored in Centera storage areas that require a retention date.
You can also direct the tool to operate on Centera storage areas that allow but do not
require a retention date by setting the INCLUDE_ZERO_RETENTION_OBJECTS
argument. The tool never includes objects stored in Centera storage areas that do not
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
remove them from the repository.

The tool generates a status report that provides you with a list of the deleted objects.
The report is saved in the repository in /System/Sysadmin/Reports/
RemoveExpiredRetnObjects. For each deleted object, the report lists the following
properties:

• r_object_id
• object_name
• a_storage_type
• r_creation_date
• retention_date

414 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

The retention_date property is a computed property.

The tool is installed in the inactive state.

15.4.1.25.1 Arguments

“Remove Expired Retention Objects arguments” on page 415, describes the

arguments for the tool.

Table 15-20: Remove Expired Retention Objects arguments

Argument Datatype Default Description

-query qualification string - Identifies which
objects are selected
for possible removal.

This is a DQL where

clause qualification.
- Boolean F (FALSE) Setting this to T
include_zero_retentio (TRUE) directs the
n_objects job to consider
objects stored in a
Centera storage area
that allows but does
not require a
retention period.
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 1440 Execution window
for the tool.

15.4.1.25.2 Guidelines

A Centera or NetApp SnapLock storage area can have three possible retention
period 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 is set 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_req is set to F.
• The storage area may allow but not require a retention period.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 415

Chapter 15 Methods and Jobs

In this case, the a_retention_attr name property is set , but the

a_retention_attr_req is set to F.

By default, the method does not include objects whose content has a 0 retention
period because the assumption is that such content is meant to be kept forever.
However, in a storage area that allows but does not require a retention period, a 0
retention period can 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 the
INCLUDE_ZERO_RETENTION_OBJECTS argument to allow you to include
content with 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 examines

objects in storage areas that allow but do not require a retention period and it will
remove from the repository any object with an expired or zero retention period. the
tool does not remove the actual content files or associated content objects. (You must
run dmclean to remove those.)

The Documentum Server DQL Reference Guide contains information on the underlying
method.

15.4.1.25.3 Report sample

--- Start C:\Documentum\dba\log\00002710\sysadmin\

RemoveExpiredRetnObjectsDoc.txt report output ----
RemoveExpiredRetnObjects Report For DocBase dctm52
As 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,T
Executing RemoveExpiredRetnObjects...
Object 090027108000c910 destroyed successfully.
Object 090027108000c911 destroyed successfully.
# of objects with expired retention that matched
the condition: 2
# of successfully destroyed: 2
# of objects not destroyed : 0
Report End 2/26/2004 15:39:14
--- End C:\Documentum\dba\log\00002710\sysadmin\
RemoveExpiredRetnObjectsDoc.txt report output ---

416 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.26 Rendition Manager

The Rendition Manager tool removes unwanted renditions of versioned documents.
A rendition is a copy of content of a document 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 noticeable
amounts of disk space. (For information about renditions, refer to Documentum
Server Fundamentals Guide.)

The arguments of the tool define which renditions are removed. The tool can delete
renditions based on their age, format, or source (client- or server-generated). The
tool removes the content objects associated with unwanted renditions. The next
execution of the Dmclean tool automatically removes the orphaned content files
(assuming that clean_content argument of Dmclean is set to TRUE) of rendition.

Note: Renditions with the page modifier dm_sig_template are never removed
by Rendition Manager. These renditions are electronic signature page
templates; they support the electronic signature feature available with Trusted
Content Services.

The report generated by the tool lists the renditions targeted for removal. The report
is saved in the repository in /System/Sysadmin/Reports/RenditionMgt.

The Rendition Manager tool is installed in the inactive state.

15.4.1.26.1 Arguments

“Rendition Management arguments” on page 417, describes the arguments for the
Rendition Management tool.

Table 15-21: Rendition Management arguments

Argument Datatype Default Description

-keep_slabels Boolean TRUE Indicates whether
you wish to keep
renditions with
symbolic labels.
When this is TRUE,
the -keep_current
argument is ignored
because CURRENT is
a symbolic label.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 417

Chapter 15 Methods and Jobs

Argument Datatype Default Description

-keep_current Boolean TRUE Indicates whether
you wish to keep
renditions of
documents with the
symbolic label
CURRENT. When
this is TRUE, the
CURRENT version is
always kept even if -
keep_slabel is set to
FALSE.
-keep_keep_flag Boolean TRUE Controls whether
content objects with a
rendition property
value of 3 are deleted
by the tool. T (TRUE)
instructs the tool to
not delete the objects.

The default value is F

(FALSE), meaning
the content objects
are not deleted.

Note: The
rendition
property in a
content object
is set to 3 when
a rendition is
added to
content with
the
keepRendition
argument in
the
addRendition
method set to T
(TRUE).
-keep_esignature Boolean TRUE Controls whether
renditions with the
page modifier
dm_sig_source are
removed.

T (TRUE) means to
keep those
renditions. F (FALSE)
means to remove
those renditions.

418 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Argument Datatype Default Description

-cutoff_days integer 180 The maximum age, in
days, of renditions
that you want to
keep. All renditions
older than the
specified number of
days are considered
for deletion.
-server_renditions string all Specifies which
server-based
renditions to remove.
Valid values are:

all
none

or a list of formats

If a list of formats is
specified, the format
names must be
separated by single
spaces.

The default is all.

-client_renditions string none Specifies which client
renditions to remove
(includes the
renditions added
using an
addRendition
method). Valid
values are:

all
none

or a list of formats

If a list of formats is
specified, the format
names must be
separated by single
spaces.

The default is none.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 419

Chapter 15 Methods and Jobs

Argument Datatype Default Description

-report_only Boolean TRUE Indicates whether to
generate only a
report and not delete
renditions. Set this to
FALSE if you want to
actually delete the
renditions in addition
to generating a
report.
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 120 Execution window
for the tool.

15.4.1.26.2 Guidelines

The Rendition Management tool removes all renditions that meet the specified
conditions and are older than the specified number of days. For example, if you
execute this tool on July 30 and the -cutoff_days argument is set to 30, then all
renditions created or modified prior to June 30 are candidates for deletion. On July
31, all renditions created or modified before July 1 are removed.

We recommend that you run this tool with the -report_only argument set to TRUE
first to determine how much disk space renditions are using and what type of
renditions are in 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
are generated before removing any. For example, client renditions, such as those
added explicitly by an Addrendition method, may be difficult to reproduce if they
are deleted and then needed later. Documentum Server renditions are generated on
demand by the server and are generally easier to reproduce if needed.

To ensure that your repository never has rendition files older than the number of
days specified in the -cutoff_days argument, run this tool daily.

Note: The first time you execute the Rendition Management tool, it may take a
long time to complete if the old renditions have never been deleted before.

420 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.26.3 Report sample

Here is a sample of the Rendition Management report.

RenditionMgt Report For DocBase boston2
As Of 7/27/96 3:57:01 PM
Parameters for removing renditions:
-----------------------------------
- Inbox messages will be queued to dmadmin
- No renditions accessed in the last 0 days will
be removed...
- Renditions of documents having symbolic labels
will be removed...
- Renditions for the current version will NOT
be removed...
- This will generate a report only; no renditions
will be removed...
- The following client renditions are candidates
for removal:
1) mactext
- The following server renditions are candidates
for removal:
1) crtext

NOTE: This is a report only - no renditions will be

removed

Querying for renditions...

Object NameOwner Name FormatAccess DateRendition Type
RenditionMgtdmadmincrtext07/27/96 15:44:31server
RenditionMgtdmadmincrtext07/27/96 15:45:31server
RenditionMgtdmadmincrtext07/27/96 15:45:31server
teststatus2boston2crtext07/24/96 18:40:23server
SwapInfodmadmincrtext07/11/96 16:16:16server
DBWarningdmadmincrtext07/12/96 18:31:11server
foo717bbbdmadmincrtext07/24/96 20:48:46server
ContentWarningdmadmincrtext07/18/96 18:01:19server
...
...
SwapInfodmadmincrtext07/27/96 13:20:47server
RenditionMgtdmadmincrtext07/27/96 15:48:09server
rend722 dmadminmactext07/02/96 11:00:11client/external
rend722dmadminmactext07/02/96 11:02:13client/external
rendzz2dmadminmactext07/02/96 11:05:04client/external
rendyy2dmadminmactext07/02/96 12:16:10client/external
rendww2dmadminmactext07/02/96 12:27:05client/external
foor717atuser4mactext07/17/96 17:48:25client/external
foor725atuser5mactext07/25/96 12:05:07client/external
Report Summary:
---------------
The Docbase has a total of 39,216 kbytes of content.
54 renditions were reported.
The renditions reported represent 82 kbytes of content
or 0.21%
End of Rendition Management Report
Report End 7/27/96 3:57:10 PM

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 421

Chapter 15 Methods and Jobs

15.4.1.27 SCS log purge (dm_SCSLogPurgeJob)

Only repositories where you have installed Site Caching Services 5.2 or above
contain this job and its associated method. It is similar to the Log Purge job.

Files are considered old and are deleted if they were modified prior to a user-
defined cutoff date. By default, the cutoff date is 30 days prior to the current date.
For instance, if you run SCS 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.

SCS Log Purge generates a report that lists all directories searched and the files that
were deleted. The report is saved in the repository in /System/Sysadmin/Reports/
SCSLogPurge.

The SCS Log Purge tool is installed in the inactive state.

15.4.1.28 State of Repository Report

The State of the Repository Report tool generates a report to help you troubleshoot
repository problems. A partial list of the information included in the report is:

• The property values in the repository configuration object

• Server initialization information from the server.ini file
• The directory paths defined by the location objects in the server configuration
object
• Version numbers of your server, RDBMS, and operating system

The report is saved in the repository in /System/Sysadmin/Reports/StateOfDocbase.

The State of the Repository tool is installed in the active state.

15.4.1.28.1 Arguments

“State of the Repository arguments” on page 422, describes the argument of tool.

Table 15-22: State of the Repository arguments

Argument Datatype Default Description

-window_interval integer 720 Execution window
for the tool.

422 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.28.2 Report sample

Here is a sample report from the State of the Repository tool. The example shows all
of the sections in the report of tool, but truncates entries in some sections in the
interests of space.
StateOfDocbase Report For Docbase dm_master As Of 4/12/1999 09:26:32

Docbase Configuration:
Description:The Test Repository
Federation Name:<dm_master is not in a Federation>
Docbase ID:22000
Security Modeacl
Folder Security:On
Authorization Protocol:<Not defined>
Database:SQLServer
RDBMS Index Store:<Not defined>
Mac Access Protocol:none

Server Configuration:
Server Name:dm_master
Server Version:4.0 Win32.SQLServer7
Default ACL:Default ACL of User
Host Name:bottae1
Install Owner:dmadmin
Install Domain:bottae1
Operator Name:dm_master
Agent Launcher:agent_exec_method
Checkpoint Interval:300 seconds
Compound Integrity:On - Server enforces integrity for virtual documents
Turbo Backing Store:filestore_01
Rendition Backing Store:<Not defined>
Web Server Location:BOTTAE1
Web Server Port:80
Rightsite Image:/rs-bin/RightSit

Server Locations:
events_locationD:\DOCUMENTUM\share\data\events
common_locationD:\DOCUMENTUM\share\data\common
temp_locationD:\DOCUMENTUM\share\temp
log_locationD:\DOCUMENTUM\dba\log
system_converter_location D:\DOCUMENTUM\product\4.0\convert
user_converter_location<Not defined>
verity_locationD:\DOCUMENTUM\product\4.0\verity
user_validation_location <Not defined>
assume_user_locationD:\DOCUMENTUM\dba\dm_assume_user.exe
change_password_locationD:\DOCUMENTUM\dba\dm_change_password.exe
signature_chk_locD:\DOCUMENTUM\dba\dm_check_password.exe
stage_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\packages
COLORS=white on blue
COMPUTERNAME=BOTTAE1
ComSpec=C:\WINNT\system32\cmd.exe
CVSROOT=godzilla.documentum.com:/docu/src/master
CVS_SERVER=cvs1-9
DM_HOME=D:\DOCUMENTUM\product\4.0
DOCUMENTUM=D:\DOCUMENTUM
HOMEDRIVE=C:
HOMEPATH=\
LOGONSERVER=\\BOTTAE1
NUMBER_OF_PROCESSORS=1
OS=Windows_NT
Os2LibPath=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;

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 423

Chapter 15 Methods and Jobs

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\bin
PATHEXT=.COM;.EXE;.BAT;.CMD
PROCESSOR_ARCHITECTURE=x86
PROCESSOR_IDENTIFIER=x86 Family 5 Model 2 Stepping 5, GenuineIntel
PROCESSOR_LEVEL=5
PROCESSOR_REVISION=0205
PROMPT=$P$G
SystemDrive=C:
SystemRoot=C:\WINNT
TEMP=C:\TEMP
TMP=C:\TEMP
USERDOMAIN=BOTTAE1
USERNAME=dmadmin
USERPROFILE=C:\WINNT\Profiles\dmadmin
windir=C:\WINNT

Registered tables in the Repository:

Table NameTable OwnerOwner:Group:World Permits

adm_turbo_sizedbo 1:1:1
dm_federation_logdbo 15:7:3
dm_portinfodbo 1:1:1
dm_queuedbo 1:1:1

Number of Documents by Type:

Document Type Count

dmi_expr_code 74
dm_method 66
dm_document 44
dm_folder 31
dm_job 29
dm_location 14
dm_registered 14
dm_procedure 10
dm_cabinet 6
dm_script 3
dm_smart_list 2
dm_business_pro 1
dm_docbase_config 1
dm_mount_point 1
dm_outputdevice 1
dm_query 1
dm_server_config 1
Total: -------------
299

Number of Documents by Format:

Document Format Count

crtext 11
mdoc55 9
maker55 5
<NO CONTENT> 2
msw8template 2
vrf 2
wp6 2
excel5book 1
excel8book 1
excel8template 1
ms_access7 1
ms_access8_mde 1
msw6 1
msw8 1
powerpoint 1

424 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

ppt8 1
ppt8_template 1
ustn 1
Total: -------------
44

Number of Documents by Storage Area:

Storage Area Count

filestore_01 40
dm_turbo_store 4
Total: -------------
44

Content Size(KB) by Format:

FormatLargestAverageTotal

mdoc5515885772
crtext 10115436
text19621254
vrf 192119238
maker553722114

Content Size(KB) by Renditions:

FormatLargestAverageTotal

Content Size(KB) Summary:

filestore_01
Largest Content: 196
Average Content: 31
Total Content: 2,092

dm_turbo_store
Largest Content: 8
Average Content: 5
Total Content: 34
------------------------
GTotal Content: 2,127
GTotal Rendition: (0.00% of total content)

Number of Users and Groups:

Named Users 4
Groups 2

ACL Summary:
Number of ACLs: 33
Number of Internal ACLs: 29
Number of External System ACLs: 4
Number of External Private ACLs:

Report End 4/12/1999 09:26:54

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 425

Chapter 15 Methods and Jobs

15.4.1.29 Swap Info

The Swap Info tool uses operating system commands to retrieve information about
swap space usage and availability. The tool generates a report but does not issue
warnings because there is no realistic way to determine if the swap space is too low
as this determination has too many variables. The status report is saved in the
repository in /System/Sysadmin/Reports/SwapInfo.

Note: If the tool was run at a remote distributed site, the report name has the
server configuration name appended with name of site. For example, if London
is a remote site, its report would be found in /System/Sysadmin/Reports/
SwapInfoLondon.

The Swap Info tool is installed in the active state.

15.4.1.29.1 Arguments

“Swap Info arguments” on page 426, describes the arguments for the tool.

Table 15-23: Swap Info arguments

Argument Datatype Default Description

-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 120 Execution window
for the tool.

15.4.1.29.2 Report sample

The format of the report generated by Swap Space Info varies by operating system.
Here is a sample:
SwapInfo Report For DocBase boston2
As Of 7/26/96 4:00:59 PM
Summary of Total Swap Space Usage and Availability:

total: 59396k bytes allocated + 49216k reserved =

108612k used, 287696k available
Swap Status of All Swap Areas:
swapfile dev swaplo blocks free
/dev/dsk/c0t3d0s1 32,25 8 717688 626640
Report End 7/26/96 4:00:59 PM

426 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.30 Update Statistics

The Update Statistics tool generates current statistics for the RDBMS tables owned
by the repository owner. Generating statistics is always useful, particularly after you
perform load operations or if table key values in the underlying RDMBS tables are
not normally distributed.

When you run the tool against an Oracle or Sybase database, the tool uses a file that
contains commands to tweak the database query optimizer. For Oracle, the file is
named custom_oracle_stat.sql. For Sybase, it is named custom_sybase_stat.sql. The
file is stored in %DOCUMETNUM %\dba\config
\repository_name($DOCUMETNUM /dba/config/repository_name). You can add
commands to this file. However, do so with care. Adding to this file affects query
performance. If you do add a command, you can use multiple lines, but each
command must end with a semi-colon (;). You cannot insert comments into this file.

The -dbreindex argument controls whether the method also reorganizes database
tables in addition to computing statistics. For SQL Server, you can set the argument
to either READ or FIX. Setting it to READ generates a report on fragmented tables
but does not fix them. Setting it to FIX generates the report and fixes the tables. (In
either case, the report is included in the overall job report.)

For Sybase, the -dbreindex argument is only effective if set to FIX, to reorganize the
tables. 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
tool runs) 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.
Because this tool can be CPU and disk-intensive, it is recommended that you run the
tool during off hours for database use. Consult with your RDBMS DBA to determine
an optimal schedule for this tool.

15.4.1.30.1 Arguments

“Update Statistics arguments” on page 428, lists the arguments for the tool.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 427

Chapter 15 Methods and Jobs

Table 15-24: Update Statistics arguments

Argument Datatype Default Description

-dbreindex string READ Controls whether the
tool actually updates
statistics or only
reports on RDBMS
tables that need
updating.

READ generates only

the report. This
setting is valid only
for SQL Server
database.

FIX generates the

report and updates
the tables. This
setting is valid on
SQL Server and
Sybase databases.
However, on Sybase,
it only fixes the
tables. A report is not
generated.

This argument is not

available for Oracle
databases.
-server_name string(32) - Name of the database
server.

This is a required
argument on SQL
Server and Sybase. It
is set for the job when
the administration
tools are installed in
repositories running
against a SQL Server
or Sybase database.
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 120 Execution window
for the tool.

428 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.30.2 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,
the report will say:
-dbreindex READ. If rows appear below, the corresponding
tables are fragmented.
Change to -dbreindex FIX and rerun if you want to reindex
these tables.

When the job is run with -dbreindex set to FIX, the report will say:
-dbreindex FIX. If rows appear below, the corresponding
tables have been reindexed.
Change to -dbreindex READ if you do not want to reindex
in the future.

15.4.1.30.3 Report sample

The Update Statistics report tells you when the tool was run and which tables were
updated. The report lists the update statistics commands that it runs in the order in
which they are run. Here is a sample of the report:
Update Statistics Report:

Date of Execution: 06-04-96

update statistics dmi_object_type

go
update statistics dm_type_s
go
update statistics dm_type_r
go
update statistics dm_type_r
go
update statistics dmi_index_s
go
. . .
End of Update Statistics Report

15.4.1.31 Usage tracking (dm_usageReport)

Documentum Server tracks software usage by recording login times. The
Documentum Server global registry contains a registered table, dm_usage_log. This
table contains a record of the first and the latest login time for each user of each
application that connects to Documentum Server. A user, dm_report_user, was
created when the global registry was configured. This user has read-only access to
the dm_usage_log table. The initial password for dm_report_user is the global
registry user password.

The dm_usageReport job runs monthly to generate a usage report. The “Viewing job
reports” on page 456 section contains the information to view the report. You can
also generate a current report. The “Running jobs” on page 455 section contains the
information to generate a current report.

The information stored in dm_usage_log can also be exported from the global
registry by using a utility program. Execute the following Java utility:

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 429

Chapter 15 Methods and Jobs

java com.documentum.server.impl.method.license.ExportUsageLog repository

dm_report_user password

Where repository is the global registry name and password is the dm_report_user
password. Use your OS shell tools to redirect the output to a file.

15.4.1.32 User change home repository

The UserChgHomeDb tool changes the home repository of a user. This job works in
conjunction with Documentum Administrator. To change the home repository of a
user, you must connect to the repository using Documentum Administrator and
make the change through the Users pages. Documentum Administrator gives you
two options for performing 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 the home repository of a user using a set method. When the
home repository of a user changes, the change must be cascaded to several other
objects that make use of it.

The UserChgHomeDb tool generates a report that lists the objects changed by the
operation. The report is saved in the repository in /System/Sysadmin/Reports/
UserChgHomeDb.

The User Chg Home Db tool is installed in the inactive state.

15.4.1.32.1 Arguments

The UserChgHomeDb tool has no arguments.

15.4.1.33 User Rename

The User Rename tool changes the repository name of a user. This job works in
conjunction with Documentum Administrator. To change the name of a user, you
must connect to the repository using Documentum Administrator and make the
change through the Users screens. 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 the name of a user name using the Set method. When the name
of a user changes, the change must be cascaded to many other objects that make use
of it.

430 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

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.

Note: The unlock_locked_obj argument is introduced in

dm_LDAPSynchronization job to preserve lock or unlock on objects that are
associated with the user who is affected by the UserRename job. Set the
unlock_locked_obj argument value to <False> to preserve lock.

15.4.1.33.1 Arguments

The User Rename tool has no arguments.

15.4.1.33.2 Report sample

This sample report was generated when the tool was run in Report Only mode.
Job: dm_UserRename
Report 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_1
when renaming user 'dm_autorender_mac' to 'test'.

The following user rename options were specified:

Execution Mode: Report Only
Checked out Objects: Unlock
WARNING: There are 15 sessions currently open. It is
recommended that user rename is performed in single
user connection mode.

================== DM_USER OBJECT ================

Object type : dm_user
Object id : 1100162180000103
Name : dm_autorender_mac
propertys referencing user dm_autorender_mac: user_name
-----------------------------------------------------
==== ACL Objects referencing user dm_autorender_mac ===
-----------------------------------------------------
Object type : dm_acl
Object id : 450016218000010c
Name : dm_450016218000010c
propertys 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 is

referencing dm_autorender_mac
-----------------------------------------------------
Object type : dm_user
Object id : 1100162180000103
Name : dm_autorender_mac
propertys referencing user dm_autorender_mac: acl_domain
-----------------------------------------------------
====== Sysobjects referencing user 'dm_autorender_mac',
which are not locked
**** Number of sysobjects affected: 0

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 431

Chapter 15 Methods and Jobs

====== Sysobject referencing user 'dm_autorender_mac',

which are locked (all the objects in this list will be
unlocked 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 user

dm_autorender_mac.
**** Number of dm_workflow objects affected: 0

====== Activity objects referincing user

dm_autorender_mac.
**** Number of dm_activity objects affected: 0

====== Workitem objects referincing user

dm_autorender_mac.
**** Number of dmi_workitem objects affected: 0

====== Groups referincing user dm_autorender_mac. ===

-----------------------------------------------------
Object type : dm_group
Object id : 1200162180000100
Name : docu
propertys referencing user dm_autorender_mac:
users_names[2]
-----------------------------------------------------
**** Number of group objects affected: 1

====== dmi_queue_item objects referincing user

dm_autorender_mac.
**** Number of dmi_queue_item objects affected: 0

====== dmi_registry objects referincing user

dm_autorender_mac.
**** Number of dmi_registry objects affected: 0

====== The following dm_registered objects have table_owner

property referencing user dm_autorender_mac. The script
will not update the objects. You have to modify them manualy.

====== The following dm_type objects have owner_name

property referencing user dm_autorender_mac. The scrip
t will not update the objects. You have to modify them
manualy.

====== The following dmi_type_info objects have acl_domain

property referencing user dm_autorender_mac. The script
will not update the objects. You have to modify them manually.

--------3/6/2000 12:00:28 PM--------

432 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.34 Version Management

The Version Management tool removes unwanted versions of documents from the
repository. This tool automates the destroy and prune methods. (Refer to
Documentum Server Fundamentals Guide for a discussion of how versioning works.)
The tool removes only the repository object. It does not remove content files
associated with the object. To remove content files, use the Dmclean tool, described
in “Dmclean” on page 389.

The arguments you define for the tool determine which versions are deleted. For
example, one argument (keep_slabels) lets you choose whether to delete versions
that have a symbolic label. Another argument (custom_predicate) lets you define a
WHERE clause qualification to define which versions are deleted. (Refer to the
Documentum Server DQL Reference Guide 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.

15.4.1.34.1 Arguments

“Version Management arguments” on page 433, lists the arguments for the tool.

Table 15-25: Version Management arguments

Argument Datatype Default Description

-keep_slabels Boolean TRUE Indicates whether
you wish to keep
versions of
documents with
symbolic labels. The
default is TRUE.
-custom_predicate string - Defines a WHERE
qualification clause qualification
for the query that
selects versions for
deletion.

The qualification
must be a valid
qualification. Refer to
the Documentum
Server DQL Reference
Guide for information
about WHERE clause
qualifications.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 433

Chapter 15 Methods and Jobs

Argument Datatype Default Description

-cutoff_days integer 180 The maximum age, in
days, of the versions
that you want to
keep. All versions
older than the
specified number of
days are considered
for deletion. If you
set this flag, you
cannot set the -
keep_latest flag. The
two flags are
mutually exclusive.
-keep_latest integer - Directs the tool to
keep the specified
number of versions
directly derived from
each end node of a
version branch. If
you set this flag, you
cannot set the -
cutoff_days flag. The
two flags are
mutually exclusive.
-report_only Boolean TRUE Indicates whether to
generate only the
report. Set this to
FALSE to actually
remove versions.
-queueperson string(32) - User who receives
email and inbox
notifications from the
tool. The default is
the user specified in
the operator_name
property of the server
configuration object.
-window_interval integer 120 Execution window
for the tool.

434 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.1.34.2 Guidelines

We recommend that you have a thorough knowledge of what prior versions mean
for your business requirements. If you need to keep all versions to satisfy auditing
requirements, do not run this tool at all. Individual users or departments may also
have needs and requirements for older versions. Needs for disk space may also
affect the decisions about how many older versions to keep.

Run this tool initially with the -report_only argument set to TRUE to determine how
much 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
other arguments each time to see how they affect the results.

If you are using the -cutoff days argument to ensure that your repository never has
only versions older than a specified number of days, run this tool daily. If you are
using -keep_latest argument to keep only a specified number of versions, you can
run this tool less frequently. The frequency will depend on how often new versions
are generated (thereby necessitating the removal of old versions to keep the number
of versions 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 documentation. You
must set the arguments 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
versions have never been deleted before.

15.4.1.34.3 Report sample

VersionMgt Report For DocBase boston2

As Of 9/12/96 11:33:33 AM
Parameters for deleting versions:------------------
- Inbox messages will be queued to boston2
- Keep the 3 most recent versions of each version
tree...
- Documents having symbolic labels will NOT be
deleted...
- This will generate a report and delete the
versions...
- 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 Labels
ver911c tuser1 09/12/96 11:19:30 1.7.1.2
ver911c tuser1 09/12/96 11:18:49 1.7.1.0
ver911c tuser1 09/11/96 16:18:46 1.3.1.1
ver911c tuser1 09/11/96 16:18:37 1.3.1.0
ver911c tuser1 09/11/96 16:07:40 1.5
ver911c tuser1 09/11/96 16:07:39 1.4
ver911c tuser1 09/11/96 16:07:37 1.1
ver911c tuser1 09/11/96 16:07:35 1.0
Report Summary:
---------------

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 435

Chapter 15 Methods and Jobs

The Docbase has a total of 21,986 kbytes of content.

8 versions were removed.
The versions removed represented 12 kbytes of content
or 0.05%
The documents contents are now orphaned. Use the
Dmclean system administration tool to actually remove
the contents.

15.4.1.35 WfmsTimer (dm_WfmsTimer)

The WfmsTimer tool checks running workflows for expired activity timers.
Workflow designers can set timers that send a message to the workflows supervisor
when an activity fails to start or complete within a given time frame. The tool also
sends an email message to the performer of the activity. The WfmsTimer tool is
installed in the inactive state. When activated, the tool runs every hour by default.

15.4.2 Creating a job

Before you create a job, determine which method the job runs or create a Docbasic
script, Java method, or other program to perform the task. If you create your own
script, method, or program, you must then create a method object referencing the
program. The “Methods” on page 341 section contains the information on creating
method objects.

The New Job and Job Properties pages are identical for standard jobs, replication
jobs, records migration jobs, remove expired retention objects, BOCS caching jobs,
and job sequences. The following topics contain the instructions on creating a
specific type of job:

• “Creating replication jobs” on page 443

• “Creating records migration jobs” on page 449

• “Creating remove expired retention objects jobs” on page 450

• “Creating BOCS caching jobs” on page 451

• “Creating job sequences” on page 452

Table 15-26: Job Info properties

Field label Description

Name The name of the job object.
Job Type A label identifying the job type.

If you are creating a replication job, records

migration job, remove expired retention
object, BOCS caching job, or a job sequence,
this field is automatically populated with the
associated job type.

436 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Field label Description

Trace Level Controls how much information is recorded
in trace logs. May be set from 0 to 10. The
“Viewing job trace logs” on page 456 section
contains the instructions on viewing trace
logs.
Designated Server When more than one server runs against a
repository, use to designate a server to run
the job. The default is Any Running Server.
State Determines how the job runs:
• If set to Active, the job runs as scheduled.
• If set to Inactive, the job does not run
automatically, but can be executed
manually.
Job Start Date Specifies when the job was started. This
option is a read-only field that only displays
for existing jobs.
Options
Deactivate on Failure Specifies whether to make the job inactive if
it does not run successfully.
Run After Update Specifies whether to run the job immediately
after any changes to the job are saved.
Save If Invalid Specifies whether to save the job object if
Documentum Administrator is unable to
validate the job.
Job Run History
Last Run Displays the last date and time the job ran
and was completed. This option is a read-
only field that displays for existing jobs.
Last Status Displays the last time the job completed and
the length of time the job took to run. This
option is a read-only field that displays for
existing jobs.
Last Return Code Displays the last value returned by the job.
This option is a read-only field that displays
for existing jobs.
Runs Completed Displays the number of times the job has run
to completion. This option is a read-only
field that displays for existing jobs.

Documentum Administrator User Guide contains the instructions on creating a basic

job.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 437

Chapter 15 Methods and Jobs

15.4.3 Changing the schedule of a job

You can modify a job schedule, whether the job is a standard job, replication job,
remove expired retention objects job, BOCS caching job, records migration job, or job
sequence. Schedule each job to run with a frequency that meets your business needs.
If a job is installed in the inactive state, change its status on the Job Properties - Info
page.

Caution
Set up the schedules for replication jobs so that jobs for the same target
repository do not run at the same time. Running replication jobs
simultaneously to the same target repositories causes repository
corruption.

Table 15-27: Job Schedule properties

Field label Description

Next Run Date and Time Specifies the next start date and time for the
job.

The default is the current date and time.

Repeat Specifies the time interval in which the job is
repeated.
Frequency Specifies how many times the job is repeated.

For example, if Repeat is set to Weeks and

Frequency is set to 1, the job repeats every
week. If Repeat is set to weeks and
Frequency is set to 3, the job repeats every
three weeks.
End Date and Time Specifies the end date and time for the job.

The default end date is 10 years from the

current date and time.
After Specifies the number of invocations after
which the job becomes inactive.

Documentum Administrator User Guide contains the instructions on changing a job

schedule.

438 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.4 Setting the qualifier rules for the remove retention-

expired objects job
Qualifier rules determine which objects to remove from a content-addressable store
when the remove expired retention objects (dm_RemoveExpiredRetn_Objects) job
runs.

Create standard rules or custom rules on the New Job - Qualifier Rules or Job
Properties - Qualifier Rules page for content-addressable stores. There are no
restrictions on the number of conditions in a custom rule, but the length is limited to
255 characters.

Standard rules are limited to five selection criteria defined by choosing properties
from drop-down lists. The available properties are:

• Name
• Title
• Subject
• Authors
• Keywords
• Created
• Modified
• Accessed

After selecting a property, select an operand and type or select the correct value. For
example, two rules might be Name contains Linux and Created before January 1,
2004. When the job runs, the criteria are connected with AND, so that all criteria
must apply to a particular object for it to be deleted. If you require an OR for
example, Name contains Linux OR Created before January 1, 2004 use a custom
rule.

A custom rule is entered into a text box as a DQL WHERE clause. There are no
restrictions on the number of conditions in a custom rule, but the length is limited to
255 characters. Custom rules can be based on the values of any standard SysObject
properties, provided those values are present before an object is saved. For example,
a custom rule might be object_name="Test" or object_name="Delete". Custom
rules are not validated by Documentum Administrator.

Documentum Administrator User Guide contains the instructions on setting qualifier

rules for the remove expired retention objects job.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 439

Chapter 15 Methods and Jobs

15.4.5 Assigning a method to a job

Each job executes a method to perform particular tasks. Methods are executable
scripts or programs represented by method objects in the repository. The script or
program can be a Docbasic script, a Java method, or a program written in another
programming language such as C++.

The associated method object has properties that identify the executable and define
command line arguments and the execution parameters. For example, the
dm_DMClean job executes the dm_DMClean method. Some Documentum jobs
execute a specific method that cannot be changed.

If you assign a user-defined method to a job, that method must contain the code to
generate a job report. If you turn on tracing, only a DMCL trace is generated.

Table 15-28: Job method properties

Field label Description

Method Name Specifies the name of the method that is
associated with the job.

Click Select Method to display the Choose a

method page. Select a method name and
click OK.

The “Locating a method for a job”

on page 442 section contains the instructions
to locate a method.

440 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Field label Description

Arguments Specifies the method arguments.

Click Edit to display the Method Arguments

page. Enter new arguments, remove
unnecessary arguments, or change the values
to the method by the job.

Many jobs take the queueperson and

window_interval arguments.
• The queueperson argument defines
which repository user receives the inbox
and email notifications generated by the
jobs. If you do not designate a repository
user for a specific job, the notifications are
sent to the user identified by the
operator_name property of the server
configuration object of server. This
property is set to the repository owner
name by default.
• The window_interval argument defines a
window on either side of the scheduled
run time of job in which the job can run.
This ensures that if a server must be
restarted, the startup is not delayed by
jobs that must be run.
Pass Standard Arguments Select this option to pass the standard
arguments for the method.

The standard arguments are:

• Repository owner
• Repository name
• Job ID
• Trace level

Documentum Administrator User Guide contains the instructions on assigning a

method to a job.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 441

Chapter 15 Methods and Jobs

15.4.6 Locating a method for a job

On the Choose a method page, select the method to be executed by a job.

Documentum Administrator User Guide contains the instructions on locating a method

for a job.

15.4.7 Creating, viewing, or modifying SysObject properties

The SysObject Info page displays information (metadata) about an object. To see
more or less information, click the show more or hide more links.

Table 15-29: SysObject properties

Field label Description

Title A name or title for the object.
Subject A subject that describes the object.
Keywords One or more keywords that describe the
object. Click Edit to add, modify, remove, or
change the order of keywords.
Authors One or more authors associated with the
object. Click Edit to add, modify, remove, or
change the order of authors.
Owner Name The user who owns the object. Click Edit to
add or modify the owner name.
Version Label The version number of the object. Click Edit
to add, modify, remove, or change the order
of version numbers.
Checkout Date The date on which the object was last
checked out. This is a read-only property.
Checked Out By The name of the user who checked out the
object. This is a read-only property.
Created The date on which the object was created.
This is a read-only property.
Creator Name The name of the user who created the object.
This is a read-only property.
Modified The date on which the object was last
modified. This is a read-only property.
Modified By The name of the user who modified the
object. This is a read-only property.
Accessed The date on which the object was last
accessed. This is a read-only property.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying SysObject properties.

442 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.8 Creating replication jobs

A replication job automates replication between the component storage areas of a
distributed storage area. You can use replication jobs to replicate objects (property
data and content) between repositories. By using parameters that you define, the
replication job dumps a set of objects from one repository, called the
sourcerepository, and loads them into another repository, called the target repository.
After the replication job is saved and the job runs successfully for the first time, you
cannot change the source or target repository. If you need to change the source or
target repository, set the job to inactive or delete the job, then create a new
replication job with the correct source or target repository.

If you are replicating objects from multiple source repositories into the same target
repository, or if you are replicating replica object, use a job sequence to designate the
order in which the jobs run so that they do not conflict with each other. The
“Creating job sequences” on page 452 section contains the information on creating
job sequences.

The information and instructions in this section apply only to object replication, not
to content replication. You cannot configure content replication with Documentum
Administrator.

When you create a replication job, you must choose a replication mode and a
security mode. Each security mode behaves differently depending on which
replication mode you choose. In addition, replica objects in the target repository are
placed in different storage areas depending on which security mode you choose. The
“Choosing replication and security modes” on page 447 section contains
information on choosing replication and security modes.

Documentum Platform and Platform Extensions Installation Guide contains more

information on replication jobs.

Documentum Administrator User Guide contains the instructions on creating a

replication job.

15.4.8.1 Selecting the source repository for a replication job

The From Source tab displays when you are creating or modifying a replication job
and is used to select the source repository for the replication job. The source
repository is the repository from which objects are replicated.

The “Creating replication jobs” on page 443 section contains the instructions on how
to access the New Replication Job - Source page and create new replication jobs.

Documentum Administrator User Guide contains the instructions on selecting the

source repository for a replication job.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 443

Chapter 15 Methods and Jobs

15.4.8.2 Selecting the target repository for a replication job

The To Target tab displays when you are creating or modifying a replication job and
is used to select the target repository for a replication job. The target repository is the
repository to which objects are replicated.

The “Creating replication jobs” on page 443 section contains the instructions on how
to access the New Replication Job - To Target page and create new replication jobs.

Documentum Administrator User Guide contains the instructions on selecting the

target repository.

15.4.8.3 Setting replication job options

The Replication Options tab displays when you are creating or modifying a
replication job pages are is used to set replication job options.

The “Creating replication jobs” on page 443 section contains the instructions on how
to create new replication jobs.

Table 15-30: Replication options

Field label Description

Code Page Specifies the correct code page for the
replication job. Keep the value at the default,
UTF-8, unless it must be changed.

Select Full Refresh to replicate every object

in the source cabinet or folder. By default, the
replication job is incremental and only
replicates objects that have changed since the
last execution of the job.

Select Fast Replication, to use fast

replication.

Caution
Fast replication does not replicate
all relationships. Documentum
Platform and Platform Extensions
Installation Guide contains more
information.

444 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Field label Description

Full Text Indexing Specifies the full-text indexing mode. Valid
options are:
• Use target repository settings for
indexing: The same documents are
indexed in the source and target.
• Do not index replicas: None of the
replicas are marked for indexing.
• Index all replicas: All replicas in a format
that can be indexed are marked for
indexing.
Replication Mode Specifies the replication mode.

You can select federated mode whether or

not the source and target repositories are in a
federation. The “Choosing replication and
security modes” on page 447 section
contains more information on selecting a
replication mode.

Nonfederated replication mode is called

external replication mode in the Documentum
Platform and Platform Extensions Installation
Guide.
Security Option Specifies how to handle security if there is no
matching permission set in the target
repository.
• Select Preserve to replicate the source
permission set in the target repository.
• Select Remap to reset the acl_domain of
replica to the permission set specified on
the target if the source permission set is
an external permission set.

The “Choosing replication and security

modes” on page 447 section contains more
information on choosing a security mode.
Maximum objects per transfer Specifies the maximum number of objects
dumped and transferred in each operation.

When selected, the replication job dumps

and transfers the total number of objects to
be replicated in batches of the size specified.
For example, if 100,000 objects must be
replicated and the maximum is set to 10,000,
the objects are replicated in 10 batches.

Select Manual Transfer if you intend to

manually move the dump file from the
source to the target, then click Select User
next to the Transfer Operator field.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 445

Chapter 15 Methods and Jobs

Field label Description

Transfer operator Specifies the user who manually transfers the
replication job.

Click Select User and select the user in the

target repository to notify that a replication
job is ready for manual transfer.

The system sends an email notification to the

selected user.

Caution
The replication job creates a dump
file and a delete synchronization
file. Both files must be transferred
to the target. Always transfer the
dump file first.

Documentum Administrator User Guide contains the instructions on setting replication

options.

15.4.8.4 Choosing a replication folder

You can choose a replication source or target folder on the Choose a folder page.

Documentum Administrator User Guide contains the instructions on choosing a folder.

15.4.8.5 Choosing a replication job user

Documentum Administrator User Guide contains the instructions on choosing a user.

15.4.8.6 Choosing a permission set for replica objects

You can choose a permission set.

Documentum Administrator User Guide contains the instructions on choosing a

permission set.

15.4.8.7 Choosing a storage area

On the Choose a storage page, select a storage area and then click OK.

446 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.8.8 Choosing replication and security modes

On the Replication Options tab, you select a replication mode and a security mode.

The replication modes are:

• Federated mode, which can be used whether or not the source and target
repositories are in a federation.
• Non-federated mode, which is named external replication mode in the
Documentum Platform and Platform Extensions Installation Guide. This mode can be
used whether or not the source and target repositories are in a federation.

The security modes determine how a permission set is assigned to replica objects in
the target repository. The security modes are:

• Preserve
• Remap

Depending on whether you selected federated or non-federated (external) mode, the

two security modes behave differently and replica objects are stored differently, as
described in “Security mode behavior” on page 447.

Documentum Platform and Platform Extensions Installation Guide contains information

on the two replication modes.

Table 15-31: Security mode behavior

Selection Replication Mode

Federated and Preserve • If the permission set of a replicated object
exists in the target repository, the replica
is assigned that permission set.
• If the permission set of a replicated object
does not exist in the target repository, the
permission set in the source repository is
replicated to the target repository and the
replica is assigned that permission set.
• Replica objects in the target repository are
stored in the same storage area as in the
source repository.
If the storage area does not exist in the
target repository, replica objects are
stored in the default storage area
designated in the replication job.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 447

Chapter 15 Methods and Jobs

Selection Replication Mode

Non-Federated and Preserve • If the permission set of a replicated object
exists in the target repository, the replica
is assigned that permission set.
• If the permission set of a replicated object
does not exist in the target repository, the
replica is assigned the default replica
permission set designated in the
replication job.
This is the permission set selected on the
Target tab. If no permission set is chosen,
the server creates a default permission set
that assigns RELATE permission to the
every user and group levels and DELETE
permission to the replica owner.
• Replica objects in the target repository are
stored in the same storage area as in the
source repository.
If the storage area does not exist in the
target repository, replica objects are
stored in the default storage area
designated in the replication job.
Federated and Remap • If the permission set of a replicated object
exists in the target repository, the replica
is assigned that permission set.
• If the permission set of a replicated object
does not exist in the target repository, the
replica is assigned the default replica
permission set designated in the
replication job.
This is the permission set selected on the
Target tab. If no permission set is
selected, the server creates a default
permission set that assigns RELATE
permission to the every user and group
levels and DELETE permission to the
replica owner.
• Replica objects in the target repository are
stored in the same storage area as in the
source repository.
If the storage area does not exist in the
target repository, replica objects are
stored in the default storage area
designated in the replication job.

448 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Selection Replication Mode

Non-Federated and Remap • The replica is assigned the default replica
permission set designated in the
replication job.
This is the permission set chosen on the
Target tab. If no permission set is
selected, the server creates a default
permission set that assigns RELATE
permission to the every user and group
levels and DELETE permission to the
replica owner.
• Replica objects are stored in the replica
storage area designated in the replication
job.

15.4.9 Creating records migration jobs

Records migration jobs move content files from one storage area to another. The
target storage area can be another file store storage area or a secondary storage
medium, such as an optical jukebox or a tape. If the target storage area is secondary
storage, the storage must be defined in the repository as a storage area. That is, it
must be represented in the repository by some type of storage object. When you
define the records migration job, you can define parameters for selecting the files
that are moved. For example, you might want to move all documents that carry a
particular version label or all documents created before a particular date. All the
parameters you define are connected with an AND to build the query that selects the
content files to move.

When a records migration job runs, it generates a report that lists the criteria selected
for the job, the query built from the criteria, and the files selected for moving. You
can execute the job in report-only mode, so that the report is created but the files are
not actually moved.

You must have superuser privileges to create a records migration job.

Documentum Administrator User Guide contains the instructions on creating a records

migration job.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 449

Chapter 15 Methods and Jobs

15.4.9.1 Setting the rules of a records migration job

Use the Rules tab on the New Records Migration Job - Rules or Job Properties - Rules
page to define which documents are migrated by a records migration job.

Documentum Administrator User Guide contains the instructions on setting the rules of
a records migration job.

15.4.9.2 Defining selection criteria for a records migration job

Use the Selection Criteria page to define selection criteria for a records migration job.
At least one criterion must be selected. The four primary choices are not mutually
exclusive; you can select any combination of the following:

• Select documents by location

• Select documents by age
• Select documents by attributes
• Select documents by version
• Search all versions

Documentum Administrator User Guide contains the instructions on defining selection

criteria.

15.4.9.3 Defining version criteria for records migration job

Set the version criteria for a records migration job on the Define Version page. At
least one version criterion must be selected.

Documentum Administrator User Guide contains the instructions on setting the version
criteria for a records migration job.

15.4.10 Creating remove expired retention objects jobs

This section contains information on how to create remove expired retention objects
job.

Documentum Administrator User Guide contains the instructions on creating a remove

expired retention objects job.

Note: The “Remove expired retention objects” on page 414 section contains
information on the remove expired retention objects tool.

450 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.11 Creating BOCS caching jobs

A BOCS content caching job does the following:

• Creates and schedules a job to collect a set of documents based on a query.

• Creates caching requests for the documents with the BOCS destination
information where the documents need to be.
• Sends caching requests to DMS on a predetermined schedule.

Any user type can create a BOCS caching job. DQL queries for BOCS caching jobs
are not validated by Documentum Administrator.

Documentum Administrator User Guide contains the instructions on creating a BOCS

caching job.

15.4.11.1 Setting BOCS caching rules

The caching rules specify the caching options and the content to be selected for
caching to the BOCS servers.

The “Creating BOCS caching jobs” on page 451 section contains the instructions on
how to create a BOCS caching job.

Table 15-32: Caching rules properties

Field label Description

Object Type The type of objects needed to create caching
messages. By default, dm_sysobject is
selected.

Click Select to access the Choose a type page

to select an object type.
Selection Criteria Users can write their own DQL query or use
the query builder to build the query for
selecting the documents they want to create
caching requests for.
• Select Build criteria (Maximum of 5
lines) to create up to five lines using
query builder. The first query section will
have the property name; the second
query section will have the condition
(operator); the third query section will
hold the value (operand).
• Select DQL query to create more complex
queries. There are no restrictions on the
number of conditions in a DQL query.
DQL queries for BOCS caching jobs are
not validated by Documentum
Administrator.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 451

Chapter 15 Methods and Jobs

Field label Description

Network Location The destination list of the cached content.

Click Select to access the Choose Network

Locations page to select from which network
locations the content should be cached.
Cutoff Date Select a cutoff date preference.

The caching method compares the cutoff

date to the last updated date of the document
to determine if a caching request needs to be
generated for the document.
• Select Cache all selected content to cache
all documents without considering the
last modified date of the document.
• Select Cache only selected content
added/modified after and then select a
date, hour, minute, and second to cache
documents based on the selected date and
time criteria.
Expiration Enter an expiration date at which the caching
request will expire if it is not fulfilled by that
date.
Previous Click to move to the previous page.
Next Click to move to the next page.
OK or Finish Click to save the changes and return to the
Jobs list page.
Cancel Click to return to the Jobs list page without
saving any changes.

15.4.12 Creating job sequences

A job sequence is a job that runs a series of other jobs. For each job in the sequence,
one or more predecessor jobs may be designated. Each job is run in sequence after
any predecessors run. Jobs that do not have predecessors run in parallel. Each job
sequence must contain at least one job that does not have any predecessors.

Use a job sequence when jobs must run in a particular order or the periods of time in
which jobs run must not overlap. For example, if replication jobs replicate objects
from multiple source repositories to a single target repository or if replication jobs
replicate replica objects, use a job sequence to control the order in which the jobs
execute.

The following restrictions apply to job sequences:

• You must be a superuser to create a job sequence.

• All jobs in a job sequence must be inactive or the job sequence fails. This means
you cannot use jobs that are active and scheduled to run independently of the job

452 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

sequence. However, you are not prevented from selecting a job that is in the
active state. If you select a job that is in the active state, change its state to
inactive.
• All jobs in a job sequence must execute a method where there is a method success
code or method success status in the method object, and only such jobs are
displayed in the user interface when a job sequence is created. Before you create
a job sequence, examine the jobs you plan to include and the methods executed
by those jobs to ensure that a method success code or method success status is
present.
• Each job sequence must include at least one job that has no predecessors. This job
is the first job to run. There can be more than one job in the sequence with no
predecessors.
• The jobs in the sequence run in parallel except when a job has a predecessor.
Documentum Administrator ensures that there is no cyclic dependency.

Before you create a job sequence, obtain the username and password for a superuser
in each repository where the sequence runs a job.

Documentum Administrator User Guide contains the instructions on creating a job

sequence.

15.4.12.1 Providing repository and job information for a job sequence

Use the Connection Info tab on the New Job Sequence or Job Properties page to
select repositories and to designate the jobs to run in a job sequence.

Table 15-33: Job Connection Info properties

Field label Description

Job Repositories
Add Click Add to access the Choose Repositories
page.

The system displays a list of available

repositories. Select the repositories in which
you want to run jobs, click Add, then click
OK.

If a repository where you want to run a job is

not listed, add a connection broker to which
that repository projects. The “Creating or
modifying connection broker projections”
on page 56 section contains more information
on adding a connection broker.
Remove To remove a repository from the list, select
the repository and click Remove. If jobs in
the repository are part of the sequence, you
must remove the jobs first.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 453

Chapter 15 Methods and Jobs

Field label Description

Repository The name of the repository where you want
to run the job. By default, the current
repository is listed with the currently-
connected superuser, but you are not
required to run any jobs in the current
repository.
User Name The login name for the repository.
Password The password for the repository.
Domain Specify the domain for any repository
running in domain-required mode.
Job Sequence Information
Add Click Add to add jobs to the sequence.

The system validates the connection

information entered in the Job Repositories.
When all connection information is valid, the
system displays the Choose Jobs page for one
of the repositories. It lists jobs in that
repository that can be included in the job
sequence. Select the jobs to run in the
sequence, click Add, then OK.

The selected jobs must be inactive or the job

sequence fails when it runs. If you select any
active jobs, set them to inactive before the job
sequence runs for the first time.
Job Name The name of the job that are in the job
sequence.
Job Dependencies Specifies the dependencies the job has on
other jobs.

Click Edit to designate the job dependencies

for each job that must run after another job
completes. Select the listed job(s) that must
run before the current job runs, then click
OK. Each job sequence must include one job
that has no predecessors. This job is the first
job to run. The jobs in the sequence run in
parallel except when a job has a predecessor.

To remove a dependency, click Edit in the

Job Sequence section to access the Choose
jobs dependency page, clear the checkbox for
any selected job, then click OK.
Repository The name of the repository where the job
sequence is run.

454 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Documentum Administrator User Guide contains the instructions on providing

connection and job information for a job sequence.

15.4.12.2 Selecting jobs for a job sequence

To access the Choose jobs page, click Add in the Job Sequence Information section
on the Connection Info tab of the New Job Sequence or Job Properties page.

Documentum Administrator User Guide contains the instructions on selecting jobs for a
job sequence.

15.4.12.3 Setting dependencies for a job sequence

You can designate job dependencies in a job sequence. A dependency defines which
job(s) must run before the current job is run.

Access the Choose jobs dependency page by clicking Edit in the Job Sequence
Information section on Connection Info tab of the New Job Sequence or Job
Properties page.

Note: Each job sequence must include one job that has no predecessors. This
job is the first to run. The jobs in the sequence run in parallel except when a job
has a predecessor.

Documentum Administrator User Guide contains the instructions on setting job

dependencies.

15.4.13 Running jobs

Jobs typically run at predetermined intervals. The jobs that exist in all repositories
have default schedules when they are created. The “Changing the schedule of a job”
on page 438 section contains the instructions on modifying the schedule of job.

Most jobs pass standard arguments to the method executed by the job. The
arguments are set on the Method tab for each job, and can be modified in most cases.

You can run a job manually (at a time other than the scheduled run time). Note that
a job invoked in this fashion runs when the agent exec process starts the job, not
when you click Run. The agent exec process polls the repository every five minutes,
so the start of the job is delayed up to five minutes, depending on when you clicked
Run and when the agent exec process last polled the repository.

Documentum Administrator User Guide contains the instructions on running a job.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 455

Chapter 15 Methods and Jobs

15.4.14 Viewing the status of a running job

To view the status of a running job after you start it, click View > Refresh.

The list page refreshes and the Status column for the job is updated. You may need
to click View > Refresh several times because the job does not run immediately after
you click Tools > Run.

15.4.15 Viewing job reports

When a job runs, it generates a report. The report summarizes the results of the job.
You can view the reports for one or more jobs.

Documentum Administrator User Guide contains the instructions on viewing jobs

reports.

15.4.16 Setting the trace level for a job

Trace logs contain status information logged by a job. The trace level set for a
particular job determines the amount of information logged. The default trace level
for a job is 1 (minimal trace information), with a maximum level of 10 (debug-level
tracing). A trace level of 4 through 6 provides a medium level of debugging.

Documentum Administrator User Guide contains the instructions on setting the trace
level for a job.

15.4.17 Viewing job trace logs

Trace logs contain status information logged by a job. The trace level set for a
particular job determines the amount of information logged. The default trace level
for a job is 1 (minimal trace information), with a maximum level of 10 (debug-level
tracing). The “Setting the trace level for a job” on page 456 section contains the
information on setting a different trace level.

You can view the trace log for a job.

Documentum Administrator User Guide contains the instructions on viewing job trace
logs.

456 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.18 Deleting jobs

Use the instructions in this section to delete a job.

Documentum Administrator User Guide contains the instructions on deleting jobs.

15.4.19 Managing jobs

This section contains information and procedures for managing jobs and job
sequences.

15.4.19.1 Activating or inactivating a job

When you set a job to inactive, the agent exec process ignores the job when it polls
the repository and the job is never started by agent exec. When you set a job to
active, the agent exec examines the job when it polls the repository and executes the
job on the schedule defined in the job.

The activation status of a job is recorded in its is_inactive property. Use

Documentum Administrator to change the status.

A job can be set to inactive automatically if you have set a maximum number of
executions for the job. In such cases, the job is inactivated after the specified number
of executions are completed. Similarly, if you specify an expiration date for a job, it
is inactivated on that date.

15.4.19.2 Disabling all jobs

To disable all job executions, set the agent_launcher property in the server
configuration object to an empty string (“”) and stop and restart the server. Stopping
the server stops the current running agent exec process. When you restart the server,
the agent_exec process is not launched.

15.4.19.3 Modifying agent exec behavior

The agent exec process controls the job execution. It runs continuously, polling the
repository at intervals for jobs to execute. By default, only three jobs are allowed to
execute in a polling cycle and tracing for the process is turned off.

You can change these default parameters, including the polling interval. The
behavior is controlled by command line arguments in the method_verb argument of
the method object that invokes the agent exec process. The arguments can appear in
any order on the command line. You must have Superuser privileges to change the
agent_exec_method.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 457

Chapter 15 Methods and Jobs

15.4.19.3.1 Setting the polling interval

The agent exec process runs continuously, polling the repository at specified
intervals for jobs to execute. The default polling interval is controlled by the setting
in the database_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_method command line. Use Documentum Administrator to add the
argument to the command line. For example:
.\dm_agent_exec -override_sleep_duration 120

The polling interval value is expressed in seconds (120 is 2 minutes expressed as

seconds). The minimum value is 1 second.

15.4.19.3.2 Setting the number of jobs in a polling cycle

By default, the agent exec executes up to three jobs in a polling cycle. You can
configure only to a maximum of 500 jobs in a polling cycle. To change the maximum
number of jobs that can run in a polling cycle, add the -max_concurrent_jobs
argument with the desired value to the agent_exec_method method command line.
For example:
.\dm_agent_exec -max_concurrent_jobs 5

15.4.19.3.3 Enabling the high-availability feature

You can load balance at the job scheduling level. By default, this feature is disabled.
Valid values are either 0 (false) or 1 (true). For example:
.\dm_agent_exec -enable_ha_setup 1

15.4.19.3.4 Setting the job interval

The agent exec always sleeps for 30 seconds between launching jobs. This value can
be changed using an argument. By default, the value is 30 seconds. For example:
.\dm_agent_exec -job_launch_interval 10

Use Documentum Administrator to modify the command line.

458 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.19.3.5 Turning on tracing for the agent exec process

Tracing for the agent exec process is turned off by default (trace level = 0). To turn it
on, use Documentum Administrator to add the -trace_level argument to the
agent_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.

15.4.19.4 Creating and maintaining a repository connection file for job

sequences
A repository connection file contains connection information used by the
dm_run_dependent_jobs method to connect to the repositories that contain the jobs
in the sequence. When the dm_run_dependent_jobs method executes, it searches the
repository 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
uses the 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 a
matching entry in the file or if the file does not exist, the method attempts to use a
trusted login to invoke the sequenced job.

The file is typically maintained by Documentum Administrator when you edit or

modify a job sequence. You can, however, use the dcf_edit utility to edit the file
directly. Refer to “The dcf_edit utility” on page 460 for instructions.

15.4.19.4.1 Specifying the server connect string

The dm_run_dependent_jobs method matches the value in the

server_connect_string portion of the entry to the value in the job_docbase_name
property of job sequence object when looking for a matching entry in the repository
file.

The value can be any valid value used to designate a repository or server when
connecting to a repository. For example, the following are valid formats for the
values:
repository_name

repository_name.documentum_server_name

repository.documentum_server_name@host_name

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 459

Chapter 15 Methods and Jobs

The only requirement is that the value you define for the server connection string in
the file must match the value specified in the job_docbase_property for the job in the
sequence.

15.4.19.4.2 Commas and backslashes in the entries

You can use commas or backslashes in the values specified for the server connection
string, 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.

15.4.19.4.3 The dcf_edit utility

The dcf_edit utility allows you to add, remove, or replace entries in a repository
connection file. It also allows you to backup the entire file. The utility is installed
with Documentum 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 Java
command line utility. “dcf_edit utility arguments” on page 460 lists the arguments
accepted by the method or on the command line.

Table 15-34: dcf_edit utility arguments

Argument Description
-server_config server_config_name Identifies the repository to which the utility
will connect.

This argument is required for Add and

Remove operations, but is invalid for Backup
operations.
-login_domain domain_name The domain of the user identified in the -
login_user argument

This argument is optional for the Add and

Remove operations, but is invalid for Backup
operations.
-login_user user_name Identifies the user as whom to connect.

This argument is optional for the Add and

Remove operations, but is invalid for Backup
operations.

460 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

Argument Description
-password user_password The clear-text password for the user
identified in -login_user.

This argument is required for the Add

operation, but is invalid for Remove and
Backup operations.
-f repository_filepath Path to the repository connection file.

This parameter is a required parameter for

all operations.
-operation operation_name Identifies the operation being performed.
Include only one operation on each execution
of the utility. Valid operation names are:
• add
• remove
• backup

Use add to add the connection information

specified in the server_config, user, and
password arguments to the file. If the entry
already contains an entry with a matching
server configuration value, this information
replaces that entry. The password is
encrypted before being added to the file. You
must include the -password argument for an
add operation. Including the -login_user
argument is optional.

Use remove to remove an entry from the file.

The utility 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

backup file is created in the same directory as
the original file. The name is the name of the
file with an appended time stamp, in the
format:
file_name-time_stamp

Do not include the -login_user or -password

arguments for backup operations.

When the utility executes an Add operation, it looks for an entry in the file that
matches the 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 utility replaces the existing entry with the values in the arguments.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 461

Chapter 15 Methods and Jobs

15.4.19.5 Recovering from a job sequence failure

If the controlling job exits with a status of 1, it typically means that one or more jobs
in the sequence failed to complete successfully. To recover from that situation, take
the following steps:

1. Examine the status report of controlling job to determine which jobs failed.
Use Documentum Administrator to view the status report of job. “Interpreting a
job sequence status report” on page 462 describes the entries in the report.
2. Examine the job reports of the failed jobs and the session and repository log files
to determine the cause of the failure.
3. Correct the problem.
4. Run dm_run_dependent_jobs as a method, with the -skip argument, to re-
execute the failed jobs.
“Executing dm_run_dependent_jobs independently” on page 463, describes the
arguments that you can include when you run the method independently of the
job.

15.4.19.6 Interpreting a job sequence status report

The dm_run_dependent_jobs method, called by controlling job of a job sequence,
generates a status report. You can view the status report using Documentum
Administrator. “Entries in a job sequence status report” on page 462 lists the events
recorded in the report and describes their format.

Table 15-35: Entries in a job sequence status report

Event Entry Format

Start Date Time start-sequence=job_sequence_name

Start Job Date Time start job -

docbase=repository_name job=job_id
attempt=1|2|3

End Job Date Time end job - docbase=repository_name

job=job_id result=succeed|fail
lastReturnCode=a_last_return_code
lastDocumentID=ID_of_job_report
lastJobStatus=a_current_status

End Date Time end -

job_sequence=controlling_job_id
result=succeed|fail

Error Date Time error - docbase=repository_name

job=job_id msg=error_message

462 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 15.4. Jobs

15.4.19.7 Executing dm_run_dependent_jobs independently

You can execute the dm_run_dependent_jobs method independently of the
controlling job. Use Documentum Administrator to run the method manually.

“dm_run_dependent_jobs arguments” on page 463, lists the arguments accepted by

the method. Some arguments are required and some are optional.

Table 15-36: dm_run_dependent_jobs arguments

Argument Required? Description

-docbase repository_name Yes Identifies the repository that
contains the job sequence.
-user_name user_name Yes Identifies the user executing
the job sequence.
-job_sequence sequence_name Yes Identifies the job sequence to
be executed.
-method_trace_level No Defines a trace level for the
trace_level dm_run_dependent_jobs
method. The two valid values
are 0 and 10. 0 records status
messages only. 10 provides
debugging messages in
addition to status messages.

The default trace level is 0.

-skip list_of_jobs No Identifies the jobs in the
sequence that you do not
want to execute. Provide a
comma-separated list of job
object IDs.
-dcf See description Specifies the location of the
repository connection file.

This is not required if the

method is using trusted login
to connect to the repositories
in which the jobs in the
sequence reside.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 463

Chapter 15 Methods and Jobs

15.4.20 Deactivating jobs that fail

You can configure a job so that it becomes inactive if it fails.

Documentum Administrator User Guide contains the instructions on deactivating jobs

that fail.

464 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 16
Alias Sets

16.1 Alias sets and aliases

An alias set is an object that defines one or more aliases and their corresponding
values. An alias is a placeholder for user names, group names, or folder paths.
Documentum Server provides various alias sets that are installed by default. In
Documentum Administrator, all alias sets for a repository are located in the
Administration > Alias Sets node.

Aliases can be used in:

• SysObjects or SysObject subtypes, in the owner_name, acl_name, and

acl_domain properties
• ACL template objects, in the r_accessor_name property
• Workflow activity definitions (dm_activity objects), in the performer_name
property
• A Link or Unlink method, in the folder path argument

Any user can create an alias set. However, only the owner of the alias set or a
superuser can change or delete an alias set. If the server API is used, the constraints
are different:

• To change the owner of an alias set, you must be either the owner of the alias set
or have superuser privileges.
• To change other properties or to delete an alias set, you must be the owner of the
alias set or a user with system administrator or superuser privileges.

16.2 Creating or modifying alias sets

Any user can create an alias set.

Table 16-1: Alias set properties

Field Description
Name The name of the alias set.
Description A description of the alias set.
Owner The name of the alias set owner.

Click Select to select and assign an owner to

the alias set.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 465

Chapter 16 Alias Sets

Documentum Administrator User Guide contains the instructions on creating or

modifying alias sets.

16.3 Viewing or removing aliases

You can view or remove aliases from an alias set.

Property Description
Name The name of the alias.
Category The category to which the alias belongs.
Value The value assigned to the alias.
Description A description of the alias.

Documentum Administrator User Guide contains the instructions on viewing or

removing aliases.

16.4 Adding or modifying aliases

You can add an alias to an alias set or modify an existing alias set.

You must be the owner of the alias set or have superuser privileges to add, modify,
or delete aliases.

Table 16-2: Alias properties

Field Description
Name The name of the alias.

For an existing alias, the name is a read-only

value and cannot be modified.
Category The category to which the alias belongs. The
category can have the following values:
• Permission Set
• Cabinet Path
• Folder Path
• Group
• User
• User or Group
• Unknown

For an existing alias, the category is a read-

only value and cannot be modified.

466 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 16.5. Deleting alias sets

Field Description
Value The value for the category property. Click
Get Value to select a value from a list of
values associated with the category you
previously selected.

If you selected Unkown as the category, you

must type a value in the Value field.
User Category A user-defined integer value for the Value
property. Optional property.
During DocApp Installation Select Prompt Alias value to indicate to
prompt for the alias value when a
Documentum application is installed.

If the category is a folder path or cabinet

path, you can select between prompting for
the value during application installation or
creating the folder or cabinet if it does not
exist.
Description A description for the alias.

Documentum Administrator User Guide contains the instructions on adding or

modifying aliases.

16.5 Deleting alias sets

You must be the owner of the alias set owner or have superuser privileges to delete
an alias set. The constraints are different if you are using the API. Documentum
Administrator User Guide contains the instructions on deleting alias sets.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 467

Chapter 17

Formats

17.1 Formats
Format objects define file formats. Documentum Server only recognizes formats for
which there is a format object in the repository. When a user creates a document, the
format of the document must be a format recognized by the server. If the format is
not recognized by the server, the user cannot save the document into the repository.

The Documentum Server installation process creates a basic set of format objects in
the repository. You can add more format objects, delete objects, or change the
properties of any format object. In Documentum Administrator, all formats are
located on the Administration > Formats node.

17.2 Viewing, creating, or modifying formats

You can view, create, or modify formats.

Table 17-1: Format properties

Field label Value

Name The name of the format (for example: doc,
tiff, or lotmanu).
Default File Extension The DOS file extension to use when copying
a file in the format into the common area,
client local area, or storage.
Description A description of the format.
Com Class ID The class ID (CLSID) recognized by the
Microsoft Windows registry for a content
type.
Mime Type The Multimedia Internet Mail Extension
(MIME) for the content type.
Windows Application The name of the Windows application to
launch when users select a document in the
format represented by the format object.
Macintosh Creator Information used internally for managing
Macintosh resource files.
Macintosh Type Information used internally for managing
Macintosh resource files.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 469

Chapter 17 Formats

Field label Value

Class Identifies the classes or classes of formats to
which a particular format belongs. The class
property works with all search engines.

To assign a class to a format, click Edit to

access the Format Class page. Type a value in
the Enter new value box and click Add.

Two values are used by the full-text indexing

system to determine which renditions of a
document are indexed:
• ft_always
All renditions of a document are indexed.
• ft_preferred
If a document has multiple renditions in
indexable formats and one format is set to
ft_preferred, the rendition in that format
is indexed as well as any formats with the
class value set to ft_always.
If more than one rendition of a document
is set to ft_preferred, the first rendition
processed for indexing is indexed and the
other renditions are not.
Asset Class Used by applications. Identifies the kind of
asset (video, audio, and so on) represented
by this format.
Filename Modifier The modifier to append to a filename to
create a unique file name.
Default Storage Identifies the default storage area for content
files in this format. Click Select to access the
Choose a Storage page.
Re-Initialize Server Select to reinitialize the server so changes
occur immediately.
Rich Media Indicates whether thumbnails, proxies, and
metadata are generated for content in this
format. You must have CTS Media installed
to generate the thumbnails, proxies, and
metadata.
Hide Determine whether the format object should
appear in the WorkSpace list of formats.
Select to hide the object.
Full-Text Indexing Select to enable the format for full-text
indexing.

Documentum Administrator User Guide contains the instructions on viewing, creating,

or modifying formats.

470 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 17.3. Deleting formats

17.3 Deleting formats

You can delete formats. However, you cannot delete a format if the repository
contains content files in that format.

Documentum Administrator User Guide contains the instructions on deleting formats.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 471

Chapter 18
Types

18.1 Object type categories and properties

The Documentum platform is an object-oriented system. An object is an individual
item in the repository. An object type represents a class of objects. The definition of
an object type consists of a set of properties, whose values describe individual
objects of the type. Object types are like templates. When an object is created in a
repository, Documentum Server uses the type definition as a template to create the
object and then sets the properties for the object to values specific to that object
instance.

18.1.1 Type categories

Object types are sorted into the following categories:

• Standard object type

Standard object types are all types that are not aspect, lightweight, or shareable
types.
• Aspect property object type
Aspect property object types are internal types used by Documentum Server and
DFC to manage properties defined for aspects. These types are automatically
created and managed internally when properties are added to aspects. They are
not visible to users and user applications.
• Lightweight object type
Lightweight object types are a special type used to minimize the storage footprint
for multiple objects that share the same system information. A lightweight type is
a subtype of its shareable type.
• Shareable object type
Shareable object types are the parent types of lightweight object types. A single
instance of a shareable type object is shared among many lightweight objects.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 473

Chapter 18 Types

18.1.2 Lightweight object types

A lightweight object type requires less storage space in the database. All lightweight
object types are subtypes of a shareable type. When a lightweight object is created, it
references a shareable supertype object. As additional lightweight objects are
created, they can reference the same shareable object, also called a parent object.
Each lightweight object shares the information in its shareable parent object. Instead
of having multiple nearly identical rows in the database tables to support all the
instances of the lightweight type, a single parent object exists for multiple
lightweight objects. Lightweight objects are useful for object groups with many
identical attribute values. A single copy of the shared parent object shares all the
redundant information among the lightweight objects.

18.1.3 Type properties

Properties are the fields that comprise an object definition and the field values
describe individual instances of the object type. When an object is created, its
properties are set to values that describe that instance of the object type. All
properties have a data type that determines what values can be stored in the
property.

18.2 Managing types

In Documentum Administrator, types are managed on the Types page under the
Administration > Types node. On the Types page, you can filter types by selecting
All, DCTM Types, or Custom Types from the list box. Types whose names are
displayed as underlined links have subtypes. If you click the name, the subtypes are
displayed. To navigate back to a previous list page, click a link in the breadcrumb at
the top of the page. The Category and Parent Type columns only appear on the
Types page if the High-Volume Server license is enabled and the Documentum
Server version is 6 or later.

From the Types page, you can:

• Create, modify, and delete shareable object types.

• Create, modify, and delete lightweight SysObject types.

• Convert heavyweight object types to a shareable object type.

• Convert heavyweight object types to a lightweight SysObject type.

• Convert heavyweight object types to a shareable type and lightweight SysObject
type.

Assignment policies determine the correct storage area for content files. A new type
inherits a default assignment policy from the nearest supertype in the type hierarchy
that has an active assignment policy associated with it. After the type is created,
associate a different assignment policy with the type.

474 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 18.3. Creating or modifying types

Documentum Server Fundamentals Guide contains more information on types.

Documentum Server System Object Reference Guide contains the information on the
system-defined object types, including the properties of each type.

18.3 Creating or modifying types

To create a type, you must have superuser, system administrator, or Create Type
user privileges. If you have superuser privileges, you can create a subtype with no
supertype. Only a superuser or the owner of a type can update the type.

Properties are stored as columns in a table representing the type in the underlying
RDBMS. However, not all RDBMSs allow you to drop columns from a table.
Consequently, if you delete a property, the corresponding column in the table
representing the type may not actually be removed. In such cases, if you later try to
add a property to the type with the same name as the deleted property, you receive
an error message.

Any changes made to a type apply to all objects of that type, to its subtypes, and to
all objects of any of its subtypes.

Table 18-1: Type properties

Field label Value

Info
Type Name The name of the object type. This field is
read-only in modify mode.
Model Type This field is read-only in modify mode.

Options are:
• Standard: This is the default and is for
heavy types.
• Shareable: Defines a shareable SysObject
model type for SysObject supertypes and
their subtypes.
• Lightweight: The system checks for the
existence of shareable types in the current
repository. If there are no shareable types
in the current repository, this option is
not be available. If selected, the Parent
Type, Materialize, and FullText fields
become available and the Super Type
Name field is not displayed.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 475

Chapter 18 Types

Field label Value

Super Type Name The name of the supertype. The default
supertype is dm_document. This field is:
• Not available if the Model Type is
Lightweight.
• Read-only in modify mode.

Unless you have superuser privileges, you

must identify the supertype of type. If you
do have superuser privileges and want to
create the type without a Supertype, select
NULL as the supertype.
Default Storage A default file store for the object type.
Default Group A default group for the type. Click Select
Default Group to access to add or change
the default group.
Default Permission Set A default permission set for the type. Click
Select Default Permission Set to add or
change the default permission set.
Default Assignment Policy The system displays the default assignment
policy for the type, if there is one. This field
appears only when modifying a type and if
Content Storage Services is enabled for the
repository.

Click the link to access the assignment

policy. Use the information in “Assignment
policies” on page 519 to modify the
assignment policy or to remove the type
from the assignment policy. Use the
instructions in the Assignment Policy section
to associate a different policy with a
particular type.

476 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 18.3. Creating or modifying types

Field label Value

Enable Indexing The system displays the Enable Indexing
checkbox if:
• The type is dm_sysobject or its subtype
and you are connected as a superuser to a
5.3 SP5 or later repository. If neither of
these conditions is met, the system does
not display the checkbox.
• A type and none of its supertypes are
registered. The system displays the
checkbox cleared and enabled. You can
select the checkbox to register the type for
full-text indexing.
• A type is registered and none of its
supertypes are registered. The system
displays the Enable Indexing checkbox
selected and enabled.
• A supertype of the type is registered for
indexing. The system displays the Enable
Indexing checkbox selected but disabled.
You cannot clear the checkbox.

The system does not display the Enable

Indexing checkbox when you create a type.
You must first create the type and save it.

If you are registering a particular type for

indexing, the system automatically selects all
of its subtypes for indexing. When you are
registering a type for indexing, the system
checks for any of its subtypes that are
registered. If a subtype is registered, the
system unregisters it before registering the
type.
Partitioned Displays whether a type that can be
partitioned is or is not partitioned. This field:
• Does not appear if the type cannot be
partitioned.
• Displays False if the type can be
partitioned but is not.
• Displays True if the type is partitioned.
Parent Type This option is available only when creating a
type and Model Type is Lightweight. This
field is read-only in modify mode. This field
appears only if the High-Volume Server
license is enabled and the Documentum
Server version is 6 or later.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 477

Chapter 18 Types

Field label Value

Materialize This option is available only when creating a
type and Model Type is Lightweight. This
field is read-only in modify mode.

Select one of the following options:

• Auto materialize: The lightweight object
will be automatically materialized to a
full object when the object is saved with
changes to some attributes of the parent
object.
• Materialize on request: The lightweight
object can only be materialized by
explicitly calling the materialize API. Any
changes to the parent object by the
lightweight object before materialization
will result in an error.
• Do not materialize: The lightweight object
is not allowed to be materialized. Call the
materialize API will result in an error.
Any changes to the parent object by the
lightweight object will result in an error.
Full Text This option is available only when creating a
type and Model Type is Lightweight. This
field is display-only in modify mode.

Select one of the following options:

• No fulltext: This is the default.
• Light fulltext: No attributes inherited
from the shared parent will be full-text
indexed.
• Full fulltext
Attribute
Attribute Name The name of the attribute. This field is
display-only in modify mode.
Type The property type.
Size The size of the property, if the property is the
String type.
Inherited Yes indicates that a property is inherited
from a supertype. No indicates that the
property is user-defined. You cannot remove
a property inherited from the supertype.
Repeating If selected, the property is a repeating
property.

Documentum Administrator User Guide contains the instructions on creating or

modifying types.

478 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 18.4. Selecting a type

18.4 Selecting a type

Documentum Administrator User Guide contains the instructions on selecting types.

18.5 Deleting types

You can only remove a user-defined type from the repository if:

• You are the owner of the type or have superuser privileges.

• The type has no subtypes.
• There are no existing objects of that type in the repository.

You cannot remove system-defined types from the repository. If you delete an object
type with an associated assignment policy, the assignment policy is not removed.
You can delete it manually.

You cannot delete a shareable type that is shared by a lightweight SysObject. Delete
the dependent lightweight objects first.

Documentum Administrator User Guide contains the instructions on deleting types.

18.6 Viewing assignment policies

The Assignment Policy Inheritance page displays a type, its supertypes, and the
assignment policy for each type and supertype with an active assignment policy
associated with it.

Use the Assignment Policy Inheritance page to view the assignment policies defined
for a type or to understand policy inheritance and gauge the impact of changes to
any policies. Knowing the inheritance hierarchy helps with troubleshooting if
content files are not saved in the correct storage area for that type.

The page displays a type and its supertypes in descending order, with the type
highest in the type hierarchy at the top of the list. The assignment policy associated
with each type is displayed, if the assignment policy is active. If the selected type
does not have an active assignment policy associated with it, the assignment policy
associated with its immediate supertype is applied. If its immediate supertype does
not have an active assignment policy, the policy associated with the next supertype
in the hierarchy is applied until the SysObject supertype is reached.

An assignment policy is associated with a type in one of two ways:

• Direct association, when the type is specified in the policy

• Inheritance from a supertype

Documentum Administrator User Guide contains the instructions on viewing

assignment policies associated with types.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 479

Chapter 18 Types

18.7 Converting types to shareable object types

If a type is a SysObject or subtype of SysObject, you can convert the type to a
shareable type, even if its supertype is shareable. However, you cannot convert a
type to shareable if any of its children are shareable types. This option is available
only on 6.5 repositories where the High-Volume Server license is enabled.

Documentum Administrator User Guide contains instructions on converting types to

shareable object types.

18.8 Converting types to lightweight object types

You can convert dm_sysobject types and their subtypes to shareable object types for
6.5 repositories. This option is available only on 6.5 repositories where the High-
Volume Server license is enabled.

Documentum Administrator User Guide contains the instructions on converting types

to lightweight object types.

18.9 Converting types to shareable and lightweight

object types
A heavy type object type can be converted to both a shareable object type and
lightweight SysObject type. This option is available only on 6.5 repositories where
the High-Volume Server license is enabled.

Documentum Administrator User Guide contains the instructions on converting types

to shareable and lightweight object types.

480 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 19

Storage Management

19.1 Storage management areas

In Documentum Administrator, the Storage Management node is located under the
Administration node and includes three main areas:

• Storage
The storage area contains pages for creating various store types, such as file
stores, retention stores (Centera and NetApp SnapLock), blob stores, turbo
stores, Atmos stores, ViPR stores, S3-compatible stores, mount point objects,
location objects, and storage plug-ins.
• Assignment Policies
The Assignment Policies area contains pages for creating assignment policies.
These pages only appear if the Content Storage Services feature is enabled for the
repository.
• Migration policies
The Migration Policies are contains pages for creating jobs to move content files
among storage areas based on user-defined rules and schedules. These pages
only appear if the Content Storage Services feature is enabled for the repository.

19.2 Storage
The storage area contains information about existing stores and pages for creating
various store types. To access the storage area, select Administration > Storage
Management > Storage. The Storage list page displays with a list of existing stores
and location objects. If a storage system complies with the NFS or Linux file system
or CIFS (on Microsoft Windows) file system protocols and standards, Documentum
can use this storage system. The first ten storage areas in the repository are
displayed in the order in which they were created.

A repository can contain the following storage objects:

Table 19-1: Repository storage objects

Storage Description
File Store File stores hold content as files.
Linked Store Linked stores do not contain content, but
point to the actual storage area, which is a
file store.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 481

Chapter 19 Storage Management

Storage Description
Blob Store Blob stores store files directly in the
repository in a special table.
Mount Point Mount point objects represent directories
that are mounted by a client.
External File Store External file stores do not store any content.
They point to the actual file system.
External Free Store External free stores do not store any content.
They point to a CD-ROM or user-defined
storage.

For example, the XML file store is an external

free store used specifically to optimize
performance with XML content files.
External URL Store External URL stores do not store any content.
They point to a URL.
Plug-in Plug-ins are required for access to external
stores.
NetApp SnapLock Store The NetApp SnapLock Store is a retention
store for content that is retained for a
specified time. Retention stores are often
used for storing massive amounts of
unchanging data, such as email archives or
check images.
EMC Centera Store The EMC Centera Store is a retention store
for content that is retained for a specified
time. Retention stores are often used for
storing massive amounts of unchanging
data, such as email archives or check images.
Atmos Store The Atmos store is a storage system
comprised of several distributed services
running on hardware nodes connected via a
network. The nodes run a collection of
services to store, retrieve, categorize, and
manage the data in the system or cloud.
ViPR Store ViPR is a software-defined storage platform
that abstracts, pools, and automates the
underlying physical storage infrastructure of
a data center. It provides a single control
plane to data center administrators for
heterogeneous storage systems.
OpenStack Swift Store OpenStack Swift store offers cloud storage
software to store and retrieve lots of data
with a simple API. It is optimized for
durability, availability, and concurrency
across the entire data set.

482 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

Storage Description
Amazon S3 Store Amazon Simple Storage Service (Amazon S3)
is a highly durable and available store that
can be used to reliably store application
content. It allows you to offload your entire
storage infrastructure and offers better
scalability, reliability, and speed than just
storing files on the file system.

Note: Documentum Server supports

all S3 compatible stores.
Distributed Store Distributed stores do not contain content, but
point to component storage areas that store
the content.

The component storage areas in a distributed

store can be any mixture of the file store and
linked store storage types, provided that all
have the same value in the media_type
property.
Location Location objects represent directories or files
that are accessed by Documentum Server.

19.2.1 File stores

A file store is a directory that contains content files. It is the basic storage type of a
repository. Each file store has a corresponding location object. You can create a
location object pointing to the file system directory that corresponds to the file store
before creating the file store or you can select the location while creating the file
store. In the latter case, Documentum Administrator creates the location object for
you.

19.2.1.1 Creating, viewing, or modifying file stores

You can create, view, or modify file stores.

Table 19-2: File store properties

Field label Description

Info
Name The name of the file store. The name must be
unique within the repository.
Description The description of the file store.

The description can be up to 128 bytes in

length if in English, German, Italian, Spanish,
or French. The description can be up to
approximately 64 bytes in Japanese.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 483

Chapter 19 Storage Management

Field label Description

Location Select the location on the server host.

Caution
Be sure that the storage path you
specify does not point to the same
physical location as any other file
stores. If two file stores use the
same physical location, it may
result in data loss.

Media Type The media type to store in the storage area.

Options are:
• Regular Content
• Thumbnail Content
• Streaming Content

Media type cannot be changed for an existing

file store.
Base URL The base URL used to retrieve content
directly from a storage area.
Encrypted Indicates if the files store is encrypted. This
option is only available in repositories with
Trusted Content Services enabled and cannot
be changed for an existing file store.
Make Public Indicates if the area is accessible to the public
with no restrictions.
Add Extension Indicates whether the server appends an
extension to the file when writing it into the
storage area. This option cannot be changed
for an existing file store.
Require Ticket Indicates whether the server generates a
ticket when returning the URL to a content
file.
SurrogateGet Method Installs a custom SurrogateGet method. This
field only displays for an existing file store.

To install the method, click Select Method

and browse to the method on the server host
file system.
Offline Get Method Indicates whether the server uses an offline
Get method. This field only displays for an
existing file store.

484 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

Field label Description

Status Select a radio button to change the status of
the file store to on line, off line, or read-only.
This field only displays for an existing file
store.
Digital Shredding Select to enable digital shredding.

Digital shredding is a security feature that

removes deleted content files and their
associated content objects. It overwrites the
addressable locations of the file with a
character, then its complement, and finally a
random character. Digital shredding requires
a Trusted Content Services license.

Caution
The Documentum Administrator
interface for version 6 and later
displays the Digital Shredding
checkbox for all file stores. If the
file store is a component of a
distributed store, files are not
digitally shredded even when it
appears that digital shredding is
enabled for the file store.

Content Compression Select to compress all content in the file store.

This option is only available in 5.3 SP1 and
later repositories with Content Storage
Services enabled.

Content compression is a feature that

automatically compresses a file to a smaller
size when the file is created. Content
compression requires a Content Storage
Services license. You cannot enable content
compression after the file store is created.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 485

Chapter 19 Storage Management

Field label Description

Content Duplication Select to enable content duplication checking.
This option is only available in repositories
with Content Storage Services enabled.
• When Generate content hash values only
is selected, for each piece of content
checked in to the repository,
Documentum Server calculates the value
needed to determine whether or not it is
duplicate content.
• When Generate content hash values and
check for duplicate content is selected,
for each piece of content checked in to the
repository, Documentum Server
calculates the value needed to determine
whether or not it is duplicate content and
then checks for duplicate content.

Content duplication minimizes the amount

of content file duplication in the file store.
Content duplication checking requires a
Content Storage Services license.

You cannot enable content duplication

checking after the file store is created.
Space Info The Space Info tab only displays for an
existing file store.
Active Space/Files The space used by the file store and the
number of files.
Orphaned Space/Files The amount of orphaned space in the file
store and the number of orphaned files.

Documentum Administrator User Guide contains the instructions on the following:

• Creating, viewing, or modifying file stores

• Moving file store storage area

19.2.1.2 Configuring NAS file stores

This section describes the instructions to configure Data Domain and Isilon NAS file
stores.

Note: Data Domain does not allow creation of files with Alternate Data Stream
(ADS).

Before configuring, please ensure the following for Windows:

• Documentum Server host and NAS storage host should be in same domain.

486 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

• Domain Administrator only can install Documentum Server on the Documentum

Server host.

To configure NAS file stores:

1. Log in to the Documentum Server Windows host as the domain administrator.

2. Install Documentum Server on the Documentum Server host. Documentum

Platform and Platform Extensions Installation Guide contains the installation
instructions.

3. Once the Documentum Server installation is complete, you will be prompted to

configure the repository using the Documentum Server Configuration Program.
Perform the following steps:

a. In the configuration options screen, choose Repository and click Next.

b. Enter the installation owner password where the password is the

password of Domain Administrator and click Next.

c. Choose Add a new repository and click Next.

d. Specify a data directory for storing content files and indicate whether it
resides on a SAN or NAS device.

• For Windows: Data directory path is the CIFS share path of the NAS
storage device.

• For Linux: NAS storage device NFS share path is mounted on the Linux
host as root and used as the data directory path.
root$ mount -t nfs <IP address of DD store>
:<shared NFS path><local mount path>

Note: The data directory must not be a top-level directory on a SAN

or NAS device such as \\<ip_address>. For SAN or NAS, enter the
complete path including a shared device and at least one level of
directory. Here is an example of a valid data directory on a SAN or
NAS device: \\<ip_address>\Documentum\data. The default data
directory is <$DOCUMENTUM>/data.

Click Next.

e. Select Yes for the Is this a NAS or SAN device option and click Next.

f. Continue with the options in the Documentum Server Configuration

Program and complete it. Documentum Platform and Platform Extensions
Installation Guide contains the detailed instructions.

Once the Documentum Server Configuration Program is complete, the NFS file store
share is created.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 487

Chapter 19 Storage Management

19.2.2 Linked stores

A linked store is a storage area that does not contain content files. Instead, it contains
a logical link to the actual storage area, which is a file store.

Linked stores are not available in a Documentum 6 or later repository. However,

linked stores are available in a 5.3x repository. On Windows hosts, the actual storage
area is implemented as a shared directory. On Linux hosts, the linked store contains
a logical link to the actual storage area.

19.2.2.1 Creating, viewing, or modifying linked stores

You can create, view or modify a linked store.

Table 19-3: Linked store properties

Field label Value

Name The name of the storage object. This name
must be unique within the repository.
Location The name of the directory containing the
logical link.
Linked Store The name of the storage area to which the
link is pointing.
Use symbolic links If selected, symbolic links are used.
Get Method To install a custom SurrogateGet, click Select
Method and browse to the method on the
server host file system.

This option only appears if you are

modifying an existing linked store.
Offline Get Method Select to use an offline Get method.

This option only appears if you are

modifying an existing linked store.
Status Select a radio button to change the status of
the file store to on line, off line, or read only.

This option only appears if you are

modifying an existing linked store.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying linked stores.

488 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

19.2.3 Blob stores

The content in a blob store is stored directly in the repository rather than on the host
file system of the server. The content in a blob store is stored in rows in an RDBMS
table. The content stored in a blob store must be less than or equal to 64 KB.

Content stored in a blob store is ASCII or arbitrary sequences of 8-bit characters.

This is designated when creating the blob store. To allow arbitrary sequences of 8-bit
characters, you can store ASCII in the store, but if you decide on ASCII, you cannot
store 8-bit characters.

You cannot define a blob storage area as the underlying area for a linked store or as
a component of a distributed storage area. That is, blob storage cannot be accessed
through a linked store storage area or through a distributed storage area.

19.2.3.1 Creating, viewing, or modifying blob stores

You can create, view or modify a blob store.

Table 19-4: Blob store properties

Field label Description

Name The name of the storage object. This name
must be unique within the repository and
must conform to the rules governing type
names.
Content Type Valid values are:
• ASCII
• 8-bit Characters
Get Method To install a custom SurrogateGet, click Select
Method and browse to the method on the
server host file system.

This option only displays for existing blob

stores.
Offline Get Method Select to use an offline Get method.

This option only displays for existing blob

stores.
Status Select a radio button to change the status of
the file store to on line, off line, or read only.

This option only displays for existing blob

stores.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying blob stores.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 489

Chapter 19 Storage Management

19.2.4 Distributed stores

A distributed store storage area does not contain content. Instead, it points to
component storage areas containing the content. The component storage areas in a
distributed store can be any mixture of the file store and linked store storage types,
but all the components must store the same kind of content.

Distributed storage areas are useful when repository users are located in widely
separated locations. You can define a distributed storage area with a component in
each geographic location and set up the appropriate content replication jobs to
ensure that content is current at each location.

Documentum Platform and Platform Extensions Installation Guide describes how to

implement and administer a distributed storage area. Documentum Server System
Object Reference Guide lists the properties defined for the distributed store object
type.

19.2.4.1 Creating, viewing, or modifying distributed stores

You can create, view, or modify, a distributed store.

Note: When a repository is configured to use distributed storage, it cannot be

converted back to non-distributed storage.

Table 19-5: Distributed store properties

Field label Description

Info
Name The name of the distributed store. This name
must be unique within the repository and
must conform to the rules governing type
names. This field is read only in modify
mode.
Fetch Content Locally Only Indicates whether the server fetches content
locally or from far stores that are not
available locally.

490 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

Field label Description

Get Method To install a custom SurrogateGet, click Select
Method to access the Choose a method page
to select a method on the server host file
system.

Generally, when users attempt to fetch a

document that is stored in an inaccessible far
storage area, the server returns an error
message. In such cases, the system
administrator has to replicate the content
into a storage area that is accessible. To
automate this administrative task,
Documentum provides the surrogate get
feature, which allows the server to
automatically replicate content when a fetch
fails.

Implement this feature using the surrogate

get method provided by default with the
Documentum Server system administration
tool suite (named dm_SurrogateGet), or
write your own surrogate get program. If
you write your own, fill in the method name
here.
Offline Get Method Controls whether the server regards
retrieved content as immediately available or
awaiting restoration.

This field is only meaningful when the Get

Method field contains a value.
Status Indicates whether the storage area is on line,
off line, or read only.
Components
Add Adds stores to the distributed store.

Click Add. The Choose a storage: page

displays. Select the stores in the left column
you want to add and move them to the right
column, using the right arrow button.
Remove Removes stores from the distributed store.

Select a store in the store list and click

Remove to remove the store from the
distributed store.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying distributed stores.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 491

Chapter 19 Storage Management

19.2.5 External stores

External storage areas do not store content. Instead, external stores point to the
actual storage area, which can be a CD-ROM, a file system, a URL, or a user-defined
store.

Data in an external store is not physically managed by Documentum Server. There

are significant limitations on content in an external store. For example, you cannot
index content or the properties of content in an external store.

External stores require a plug-in that you must create before you create an external
store. The plug-in can run on the server side or client side, although a client-side
plug-in could provide better performance. Documentum provides code for sample
plug-ins in the DM_HOME/unsupported/plugins directory.

There are three types of external stores:

• External file store

Use external file stores for legacy files in external file systems, optical disks, and
CD-ROM files.
• External free store
External free store storage areas allow users to specify a token that is not a file
path or a URL. An external free store enables you to define your own token
standard and means of retrieving the content associated with the token. Write
your own content retrieval mechanism through a DLL plug-in, which is
described by a plug-in object.
You can also use the external free store pages to manually create XML stores. Use
XML stores to store and query large volumes of XML content. An XML store is a
native XML database that is fully optimized for XML content.
• External URL store
External URL stores provide support for token-mode operation where the token
is a URL. The tokens specified in the Setpath operation must follow the URL
standard. The client and the server do not validate the format of the URL.

Documentum Platform and Platform Extensions Installation Guide and Documentum XML
Store Administration Guide provide more information about external XML file stores.

492 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

19.2.5.1 Creating, viewing, or modifying external stores

Create the appropriate plug-ins before configuring the external store. You can create,
view, or modify an external file store, external free store, XML store, or external URL
store.

Table 19-6: External store properties

Field label Description

Info
Name The name of the new external store.
Windows Indicates the plug-in that is used on the
Windows platform.
Solaris Indicates the plug-in that is used on the
Solaris platform.
Aix Indicates the plug-in that is used on the Aix
platform.
HP-UX Indicates the plug-in that is used on the HP-
UX platform.
Macintosh Indicates the plug-in that is used on the
Macintosh platform.
Linux Indicates the plug-in that is used on the
Linux platform.
HP-UX-Itanium Indicates the plug-in that is used on the HP-
UX-Itanium platform.
Current Client Root The name of the location object that
represents the default root of the content for
executing plug-ins on the client when the
mount is not executed. This option is only for
external file stores.
Client Root The name of the location object that
represents the default root of the content for
client side plug-in execution when mount is
not executed. The default is NULL. This
option is only available for external file
stores.

Client Root: Click Browse and select a client

root.
Server The Server tab only displays for external file
stores.
Add Click Add or select the server on which the
external file store resides, then click Edit to
access the Choose a server config page.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 493

Chapter 19 Storage Management

Field label Description

Server The name of the server where the external
store resides.
Location The location object that points to the external
file store. Click Select Location to select a
location object.
Path Specifies the file system path to the external
file store. The path displays automatically
after you selected the location object.

19.2.5.2 Editing a server root location

The Select Root Location for Server page displays the server, location, and path that
is the default root of the content for server side plug-in execution.

Documentum Administrator User Guide contains the instructions on editing a server

root location.

19.2.6 Centera stores

A Centera store is a retention store for large amounts of unchanging data such as
email archives or check images. Centera requires a Content Services for EMC
Centera (CSEC) license. CSEC must be enabled during Documentum Server
software installation.

Use only the supported storage systems.

In a Centera store:

• Store metadata values with a piece of content.

• Store files created on Macintosh platforms.
Both, Documentum Server and DFC must be on version 6.7 and there is no
backward compatibility to older versions of Documentum Server and DFC. Any
attempt to store resource forks into a Centera store using either an earlier
Documentum Server or DFC version results in an exception/error message.
• Define a retention date or, with Documentum Server 5.3 SP3 or later, a retention
period for the content.
• Index content.
• Enable content compression in 5.3 SP1 and later repositories.

A repository can have multiple Centera stores. For ease of administration,

maintenance, and management, it is recommended that you use the same plug-in for
all the Centera stores.

Set the C-clip buffer size or configure use of embedded blob storage by using
optional storage parameters. Setting the C-clip buffer size is available only in 5.3 SP3
and later repositories.

494 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

Documentum Server supports distributed Centera clusters in 5.3 SP3 and later
repositories. The Centera store plug-in must be stored depending on different server
locations:

• If all Documentum Servers are running on the same computer, the Centera store
plug-in must be in a file store.

• If the Documentum Servers are running on different hosts, the Centera store
plug-in must be stored in a file store that is shared by all Documentum Server
instances or in a distributed store in which each Documentum Server has at least
one component defined as a near store.

19.2.6.1 Creating, viewing, or modifying Centera stores

To create a Centera store, you must know the connection string of the Centera
storage system.

Table 19-7: Centera store properties

Field label Description

Name The name of the Centera store.
Description A description of the Centera store.
Plug-in Name Specifies the plug-in that is used for the
Centera store. Select one of the following
options:
• Default Plugin: Sets a null ID
(0000000000000000) in the a_plugin_id
property of the Centera store object.
• Select Plugin: Enables the default CSEC
plug-in. To use a plug-in other than the
default CSEC plug-in, click the Select
Plugin link, locate the plug-in in the
repository, select it, and click OK.

When a repository is created, a default plug-

in object for CSEC is created. If the plug-in
object is deleted from the repository, no
plug-in is displayed. Create a new plug-in
object with the content of the plug-in object
set as follows:
• Windows: %DM_HOME%\bin
\emcplugin.dll
• Linux: $DM_HOME/bin/libemcplugin.so
Storage Parameters Specifies the storage parameters, such as the
connection string, C-clip buffer size, and
embedded blob storage.

Click Edit to configure storage parameters.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 495

Chapter 19 Storage Management

Field label Description

Enable Content Compression Specifies whether content compression is
used. Select this option to compress all
content in the store.

Compression cannot be modified for existing

Centera stores.
Configure Retention Information Enables content retention.

Content retention cannot be modified for

existing Centera stores.
Retention Attribute Name The name of the retention attribute. The
value must not be one of the values specified
as a content attribute name.

The retention attribute name cannot be

modified for an existing Centera store.
Fixed Retention Specifies a fixed value for the retention
property value, as follows:
• Choose a retention period:Sets a period
of days as the retention period for all
content in the Centera store. Enter the
date and time of the retention date.
• Choose default retention days:Select and
then type the number of retention days.

Both default retention date and default

retention days can be specified. If both are
specified, the default retention days takes
precedence over default retention date. If
default retention date is selected but no value
is specified, the system ignores the retention
date option.
Event Based Retention When Configure Retention Information is
selected, the system automatically selects and
inactivates this checkbox to prevent changing
the event based retention option status.
Application Provides Retention Requires that a client application supplies the
retention date when content is saved to the
Centera store.

496 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

Field label Description

Add Click Add to add a content attribute, or select
an attribute from the list and click Edit. The
Content Attribute window displays.

Enter or modify the following information:

• Attribute Name: The name of the content
attribute. The content attribute name can
be an arbitrary name. It does not have to
correspond to any existing properties of
the objects stored in the Centera store.
• Attribute Description: A brief description
of the content attribute.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying Centera stores.

19.2.6.2 Defining the storage parameters for a Centera store

You can add or modify storage parameters for the Centera store.

To define the storage parameters for a Centera store:

1. On the Info tab of the EMC Centera Store Properties, scroll to the Storage
Parameters field and click Edit.
The Storage Parameters page displays.

2. In the Enter new value field, type the connection string for the Centera storage
system.
The connection string has the following format
<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 the Centera machine.
• Centera_profile is a full-path specification of a Centera profile and must begin
with “path=”.
The path must be accessible from the Documentum Server host machine and
the specified directory must be readable by the Documentum Server
installation owner.

The following example describes a connection string with multiple Centera

profiles:
10.241.35.27,10.241.35.28?name=profA,secret=foo,10.241.35.27,10.241.35.28?
name=profB,

secret=bar,10.241.35.110,10.241.35.111?path=C:\Temp\auth.xml

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 497

Chapter 19 Storage Management

In the following example, the SDK parses the passed-in connection string with
the resulting elements going in the outConnectionStrings array, as follows:
outConnectionStrings [0] = 10.241.35.27?name=profA,secret=foo

outConnectionStrings [1] = 10.241.35.28?name=profA,secret=foo

outConnectionStrings [2] = 10.241.35.27?name=profB,secret=bar

outConnectionStrings [3] = 10.241.35.28?name=profB,secret=bar

outConnectionStrings [4] = 10.241.35.110?path=C:\Temp\auth.xml

outConnectionStrings [5] = 10.241.35.111?path=C:\Temp\auth.xml

The following rules apply to the syntax of a connection string with multiple
profiles:

• The IP address position must precede the listing of credentials and/or path
for that profile.
• If the connection string includes a path that does not use the path= prefix but
points to a PEA file and a set of credentials, the path must precede the
credentials. Conversely, when using the path= prefix, there is no restriction
as to where the path appears in the connection string in relation to the set of
credentials.
• The credentials that appear in a connection string override those that are
held in a PEA file.
• It is best practice to use the optional path= prefix hint to specify the path to a
PEA file, to avoid confusion when evaluating the connection string. Do not
mix credential data in a connection string.

If configuring Centera clusters, the connection string format identifies primary

and secondary Centera clusters for one or more Documentum Servers:
<server_config_name>="primary=<cluster_id>{,<cluster_id>},secondary=<cluster_id>{,<c
luster_id>}[?<Centera_profile>]"

where:

• The primary <cluster_id> is the name or IP address of the Centera cluster to

which the Documentum Server writes.
• The secondary <cluster_id> is the name or IP address of the Centera cluster
from which the Documentum Server reads if it cannot read from the
specified primary cluster.

Including a Centera profile is optional. The storage parameter property has a

length of 1024 characters. Assign names to the Centera cluster nodes that are
short enough to allow the full connection string to fit within the property.
3. Click Add to move the value to the Storage Parameters section.
4. Enter more storage parameters, as necessary.
For example :

• To enable embedded blob use, enter the following parameter:

498 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

pool_option:embedded_blob:<size_in_KB>

where size_in_KB is the maximum size in kilobytes of the content that you
want to store as embedded blobs. For example, if you want to store all
content that is 60 KB or smaller as embedded blobs, set the storage
parameter value as:
pool_option:embedded_blob:60

If embedded blob use has been enabled and content is written to a

compressed Centera store, Documentum Server writes the content as linked
blob if the original content size is greater than the embedded blob threshold.
This restriction still applies if the eventual compressed content size is less
than or equal to the embedded blob threshold. If the original content size is
less than the embedded blob threshold, the content is stored as embedded
blob.
• To set the C-clip buffer size, enter the following parameter:
pool_option:clip_buffer_size:<integer>

where <integer> is an integer number representing the number of kilobytes.

For example, to set the buffer size to 200 KB, set the storage value parameter
as:
pool_option:clip_buffer_size:200

• To change the maximum number of socket connections that the Centera SDK
can establish with the Centera host, enter the following parameter:
pool_option:max_connections:<integer>

where <integer> is an integer number from 1 to 999 specifying the maximum

socket connections. By default, the maximum number of socket connections
is 99 on Windows platforms, and 1 on Linux platforms.

5. Use the up and down arrows to sort the storage parameters.

Caution
If you have entered multiple parameters, the Centera connection string
must be in the first position.

6. When finished, click OK.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 499

Chapter 19 Storage Management

19.2.6.3 Defining Centera store content attributes

Centera stores allow you to save up to 62 metadata values with each piece of content
saved in the system.

To define the content attributes saved in a Centera store:

1. On the Info tab of the EMC Centera Store Properties, scroll to the Content
Attribute section and click Add.
The Content Attribute page displays.
2. Type the name of an attribute.
The attribute name can be an arbitrary name. It does not have to correspond to
any existing properties of the objects stored in the Centera store.
3. Type a description.
4. Click OK.
5. Repeat step 1 through 4 to configure more attributes, if applicable.

19.2.7 NetApp SnapLock stores

A Network Appliance SnapLock (NetApp SnapLock) store stores large amounts of
unchanging data such as email archives. NetApp SnapLock is a licensed software
that provides storage level retention capability through the creation of Write Once
Read Many (WORM) volumes on Network Appliance storage systems. These
WORM volumes enable users to prevent altering or deleting content until a specified
retention date. NetApp SnapLock does not have advanced retention management
features such as retention hold, event based retention, or privileged delete, which is
available on a Centera store. You can define a retention date or, with Documentum
Server 5.3 SP6 or later, a retention period for the content in a NetApp SnapLock
store. You can also enable content compression for a SnapLock store.

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.

The SnapLock documentation provided by Network Appliance contains more

information about the two types of stores.

SnapLock requires:

• A Documentum Server version 5.3 SP6 or later

• A NetApp SnapLock license
• A SnapLock storage device
• A connector license

500 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

19.2.7.1 Creating, viewing, or modifying NetApp SnapLock stores

A repository can have multiple SnapLock stores. For ease of administration,
maintenance, and management, it is recommended that you use the same plug-in for
all the SnapLock stores.

On Linux, mount the SnapLock store to local disk using NFS . Use the mount point
path in the SnapLock store object path. For example:
<snaplockhost:/path/to/use> </local/mount/point>
mount snapdisk:/u01/disk1 /dctm/snapstore

When you create the SnapLock store, use the name of the local mount path, /dctm/
snapstore.

Table 19-8: NetApp SnapLock store properties

Field label Description

Name The name of the NetApp SnapLock store.
Description A description of the NetApp SnapLock store.
Plug-in Name The name of the plug-in for the NetApp
SnapLock store. Options are:
• Default Plugin: Select to set a null ID
(0000000000000000) in the a_plugin_id
property of the NetApp SnapLock store
object.
• Select Plugin: Select to use the default
Snaplock Connection plug-in.
When a repository is created, a default
plug-in object is created. If the plug-in
object is deleted from the repository, no
plug-in is displayed. Create a new plug-in
object with the content of the plug-in
object set as follows:
– Windows: %DM_HOME%\bin
\emcplugin.so

When a repository is created, a default plug-

in object is created. If the plug-in object is
deleted from the repository, no plug-in is
displayed. Create a new plug-in object with
the content of the plug-in object set as
follows:
• Windows: %DM_HOME%\bin
\emcplugin.so
Snaplock Volume Path The directory path of the NetApp SnapLock
storage system.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 501

Chapter 19 Storage Management

Field label Description

Enable Content Compression Specifies whether content compression is
used. Select this option to compress all
content in the store.

Compression cannot be modified for existing

NetApp SnapLock stores.
Configure Retention Information Enables content retention.

Content retention cannot be modified for

existing NetApp SnapLock store.
Retention Attribute Name The name of the retention attribute. The
value must not be one of the values specified
as a content attribute name.

The retention attribute name cannot be

modified for an existing NetApp SnapLock
store.
Fixed Retention Specifies a fixed value for the retention
property value, as follows:
• Choose a retention period:Sets a period
of days as the retention period for all
content in the NetApp SnapLock store.
Enter the date and time of the retention
date.
• Choose default retention days:Select and
then type the number of retention days.

Both default retention date and default

retention days can be specified. If both are
specified, the default retention days takes
precedence over default retention date. If
default retention date is selected but no value
is specified, the system ignores the retention
date option.
Event Based Retention When Configure Retention Information is
selected, the system automatically selects and
inactivates this checkbox to prevent changing
the event based retention option status.
Application Provides Retention Requires that a client application supplies the
retention date when content is saved to the
NetApp SnapLock store.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying NetApp SnapLock stores.

502 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

19.2.8 Atmos stores

An Atmos store is a software storage system that consists of several distributed
services running on a network of connected hardware nodes. Each node is attached
to one more disk enclosures. The nodes run a collection of services to store, retrieve,
categorize, and manage the data in the system or cloud.

Documentum Server uses the ACS connector to communicate with the Atmos store.
The ACS module supports storing and retrieving of content through an HTTP
interface.

19.2.8.1 Creating, viewing, or modifying Atmos stores

Table 19-9: Atmos store properties

Field label Description

Name The name of the Atmos store. The name must
be unique within the system. The name of an
existing Atmos store cannot be modified.
URL The URL the server uses to communicate
with the Atmos store.
Full Token ID A combination of subtenant ID and a UID
within that subtenant, both in the Atmos
system that is being targeted. The format is
subtenant ID/UID.
Shared Secret The password of the user accessing the
Atmos store.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying Atmos stores.

19.2.8.1.1 Managing authentication

The Web service uses a combination of the Token ID, and other request headers to
produce a signature that authenticates the user accessing the web service. It uses a
combination of various pieces of the message to validate the identity of the sender,
integrity of the message, and non-repudiation of the action. The Token ID that you
received via e-mail from the portal agent administrator consists of the subtenant ID,
and the UID separated by a slash (/). The subtenant ID is a randomly generated, 32
character alphanumeric string, which is unique to each customer. The UID, however,
is unique to a web-based application. The UID, which appears after the slash, is
comprised of a portion of the customer name, and a randomly generated string. For
example, if the customer name is ACME, then the UID string appends the additional
random characters. The whole Token ID contains 53 uppercase characters including
the slash (for example: 5f8442b515ec402fb4f39ffab8c8179a/
ACME03GF52E8D8E581B5).

To complete the authentication operation, you must generate a signature using the
shared secret, which is associated with the UID. The shared secret is a value

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 503

Chapter 19 Storage Management

generated by the Storage Utility Agent responsible for managing this application.
The shared secret appears in the same e-mail message that contains the Token ID.
The following sample represents a typical shared secret:
MBqhzSzhZJCQHE9U4RBK9ze3K7U=

19.2.8.2 Storing content in Atmos store

The prerequisite for plugin enabled stores is that ACS should always be running.
ACS read/write may be disabled through configurations, but ACS service itself
should not be stopped. Ensure local ACS is running for storing content in Atmos
store. When you stop the ACS/JMS services, DFC assumes normal content transfer
operation. However, the Documentum Server understands that the content belongs
to the plugin enabled store and uses ACS connector to communicate to ACS for
storing content. The ACS Connector identifies the dm_acs_config object for the local
ACS to access the acs_base_url for communicating with the ACS. If you stop the
ACS services, it will fail and Atmos storage will be shown as offline.

19.2.9 ViPR stores

ViPR is a software-defined storage platform that abstracts, pools, and automates the
underlying physical storage infrastructure of a data center. It provides a single
control plane to data center administrators for heterogeneous storage systems.
Above the control plane, administrators can deploy ViPR Services (Object, HDFS,
and Block Services) on array- and commodity-based storage that enable users to:

• Use ViPR file-managed storage as an object store

• Perform analytics on ViPR-managed storage
• Dynamically provision block commodity storage

ViPR enables software-defined data centers by providing the following features:

• Storage automation capabilities for multi-vendor block and file storage

environments (control plane or ViPR Controller).
• Object data management and analytic capabilities through ViPR Object and
HDFS Services, which creates a unified pool (bucket) of data across file shares
and commodity servers (data path) .
• Management of multiple data centers in different locations with single sign-on
data access from any data center.
• Data replication between geographically dispersed data centers to protect against
data center failures with active-active functionality.

504 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

19.2.9.1 Creating, viewing, or modifying ViPR stores

Before creating, viewing, or modifying ViPR stores, ensure the following:

• Install the license for ViPR Object on ViPR, including Amazon S3.
• Enable data services for object-based storage services and ensure that the
Amazon S3 store is accessible.
• Create a bucket for data services to be used by the Documentum Server.

Table 19-10: ViPR store properties

Field label Description

Name The name of the ViPR store. The name must
be unique within the system. The name of an
existing ViPR store cannot be modified.
URL The URL that the server uses to communicate
with the ViPR store. The URL format is
http://<xx.xx.xx.xx>:9020/<<bucket-name>>.
For example, http://10.31.4.172:9020/csstore.
Access Key ID The user name of the user accessing the ViPR
store. Use the ViPR Tenant Owner as the
Access Key ID.
Shared Secret The password of the user accessing the ViPR
store. Use the Object Access Key as the
Shared Secret.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying ViPR stores.

19.2.10 OpenStack Swift stores

The OpenStack Swift store offers cloud storage software to store and retrieve lots of
data with a simple API. It is optimized for durability, availability, and concurrency
across the entire data set. It is ideal for storing unstructured data that can grow
without bound. You can use OpenStack Swift as a content store for Documentum
Server.

A store plugin using REST APIs is used to allow Documentum Server to configure
OpenStack Swift as a data store. This plugin is available as dm_swift_store type in
Documentum Server.

The store is configured with the following information:

• base_url: OpenStack Swift authentication endpoint (for example, http://

10.0.0.1:35357/v2.0)
• credential_id: Format is tenantName:username (for example, (admin:admin))
• credential_key: password

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 505

Chapter 19 Storage Management

• container: Name of the container to store the content

• region: (optional) Name of the preferred region to store the content

Once it is configured, the store is accessible as any other Documentum Server store.
A new TBO is created for the plugin. All the contents uploaded to the OpenStack
Swift store have an unique key. This key, which is in the form of a Linux path, is
derived from the content-id.

19.2.10.1 Creating, viewing, or modifying OpenStack Swift stores

Table 19-11: OpenStack Swift store properties

Field label Description

Name The name of the OpenStack Swift store. The
name must be unique within the system. The
name of an existing OpenStack Swift store
cannot be modified.
Authentication endpoint URL The URL that the server uses to communicate
with the OpenStack Swift store. API version
v2.0 and auth/v1.0 endpoints are supported
for OpenStack Keystone integration and /v1
endpoint is supported for basic
authentication. For example, http://
10.0.0.1:35357/v2.0.
Account Owner The user name of the user accessing the
OpenStack Swift store.
Password The password of the user accessing the
OpenStack Swift store.
Container The name of the container to store the
content.
Region The name of the preferred region to store the
content. This is an optional field.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying OpenStack Swift stores.

Note: To perform operations in a docker environment, you must provide the

hostname details in /etc/hosts of the OpenStack Swift store in docker host
and containers.

506 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

19.2.11 Amazon S3 stores

Amazon Simple Storage Service (Amazon S3) is a highly durable and available store
that can be used to reliably store application content such as media files, static assets
and user uploads. It allows you to offload your entire storage infrastructure and
offers better scalability, reliability, and speed than just storing files on the file
system. You can use it as a content store for Documentum Server.

The store is capable of the following:

• Push or pull of data

• Migration of data to or from S3 store: You can use the content migration job to
perform the migration. Migration of data is supported as follows:

– File store to S3 and S3 to file store

– EMC Centera store to S3 and S3 to EMC Centera
– XML Store to S3 and S3 to XML Store
– Encrypted S3 to file store and file store to encrypted S3
– Encrypted S3 to XML Store and XML Store to encrypted S3
– Encrypted S3 to EMC Centera store and EMC Centera store to encrypted S3
– Encrypted file store to encrypted S3 and encrypted S3 to encrypted file store
– External file store to S3
– External file store to encrypted S3
• Configuring the store to use SSL: S3 store can be configured to use SSL
communication between S3 plugin and S3 storage service. Default SSL is
achieved by providing SSL URL in base_url attribute (for example, https://
<storageservice-hostname>:443/<bucketname>). If you want to use your
certificates, then import those certificates to the Java keystore of JDK which the
S3 plugin use.
• Using as an encrypted store: To use S3 store as an encrypted store (similar to other
Documentum stores), crypto_mode attribute needs to be set to 1. When
crypto_mode is set to 1, Documentum Server (ACS connector module of
Documentum Server) encrypts the content before pushing it to the store. When
content is retrieved, Documentum Server decrypts and sends it back to the client.

Note: TCS license is required to use Documentum S3 store as an encrypted

store.
• Retention: Documentum Server supports SysObject level retention on all S3
compatible stores.
Documentum Server operations such as insertion, modification, and deletion of
content is controlled by the object retainers. The retention date on the retainer
object is applied on the SysObject which is pushed to the file for WORM-enabled
stores. If the maximum retention date given in the retainer is later than the

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 507

Chapter 19 Storage Management

default retention date (if it exists), the default retention date is overridden. The
object cannot be modified or deleted until the specified retention date expires.

– WORM support: Starting with the 16.7 release, Documentum Server leverages
store level retention on WORM-enabled IBM Cloud Object Storage (COS)
store. Starting with the 16.7.1 release, Documentum Server supports Amazon
S3 and Hitachi Content Platform (HCP) stores. Only fixed retention is
supported.
S3 stores are cloud-based services and hence PUT/GET or POST operations
are used to manage retentions. Documentum Server acts as an HTTP client,
generates POST request with appropriate headers for pushing the retention to
the S3 store.
Common request headers are: Content-Length, Content-Type, Date, Host and
so on.
HTTP authorization header is the most common method of authenticating an
Amazon S3 request. AWS Signature Version 4 (v4) is the process to add
authentication information to AWS requests sent by HTTP. Amazon AWS
documentation contains detailed information about v4 signing.

19.2.11.1 Using the S3 store plugin

A store plugin is used to make the communication between Documentum and
External Store (S3). The store plugin implements the contract defined by DFC store
plugin interface and provides content transfer capability. This implementation acts
as a bridge/adaptor between DFC store plugin and the Amazon S3 RESTful Java API
binding.

Note: The prerequisite for plugin-enabled stores is that the ACS must always
be running. ACS read/write may be disabled through configurations, but ACS
itself must not be stopped.

Figure 19-1: Authentication flow using S3 store plugin

508 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

The plugin modules are deployed as BOF modules. The S3 plugin is available in the
java_access attribute of the dm_store subtype object (dm_s3_store). The plugin
needs the support of other external libraries. These external libraries are deployed as
Java libraries with the BOF modules. All the deployment rules pertaining to BOF
modules and TBO’s apply as is. Also, all the required BOF modules (s3-tbo-api.
jar and s3-tbo-impl.jar) and dependent Java libraries (aws s3 client libs) are
packaged as part of the S3Plugin.dar file.

The following operations are supported:

• Read Content: Calls the readObjectAsStream call of the RESTful API and pulls the
content as stream.
• Write Content: Uses the RESTful API to write the content to S3 with the supplied
metadata. The returned object identifier is passed to the upper layer wrapped as
a StoreResult Object implementation of IStoreWriteResult.
• Delete Content: Calls the S3 Delete Content API.
• Write or Update Metadata: Metadata is passed to plugin by DFC. Adds the content
id as metadata to the objects or content that are being pushed to S3. The metadata
is a key value pair. For example, the key is dmr_content_id and the value is [The
Content Object Id].

The store is configured with the following information:

• <java_access>: Name of the module (S3 plugin) which the store object represents.
The default value is S3 Plugin for dm_s3_store type objects.
• <base_url>: S3 storage service URL. Format is http://<X.X.X.X>/<BUCKET> where

– X.X.X.X: URL of S3 store service and the URL format is http://hostname:port.

– BUCKET: Name of the S3 bucket used to push the content. This name is
mandatory. Bucket should be preconfigured in S3 storage service and is
accessible using the following credentials:

○ credential_id: Access Key (user id or access key to access the store

service).
○ credential_key: Password for accessing the store. DFC encrypts or
decrypts this password before storing and passing it on to the plugin.
– <store_params>: Configuration parameters for the WORM support. The
configuration parameters are stored as key-value pair with the following
optional pre-defined keys:

○ proxy_host: The IP address of the proxy server.

○ proxy_port: The port reserved for the proxy server.
○ region: The region where S3 bucket is configured.
○ query_parameter: The URL query parameter that the corresponding S3
store vendor expects for extending retention. This is specific to the
compatible store.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 509

Chapter 19 Storage Management

○ retention_header_name: Header used for specifying the new retention

date. The date format must be in accordance to the ISO 8601 format
(YYYYMMDDThhmmssZ). This is specific to the compatible store.
○ mode: Retention mode that applies to different levels of protection.
○ vendor: Specifies the storage vendor.

Once it is configured, the store is accessible as any other Documentum Server store.
A new TBO is created for the plugin. The dm_s3_store object cannot be updated
once it is created. All the contents uploaded to the Amazon S3 store have an unique
key. This key is derived from the content-id.

19.2.11.2 Creating, viewing, or modifying S3 stores

Table 19-12: S3 store properties

Field label Description

Name The name of the S3 store. The name must be
unique within the system. The name of an
existing S3 store cannot be modified.
URL The URL that the server uses to communicate
with the S3 store. The URL format is http://
<X.X.X.X>/<<BUCKET>>.
Access Key ID The user name of the user accessing the S3
store. Use the S3 Tenant Owner as the Access
Key ID.
Shared Secret The password of the user accessing the S3
store. Use the Object Access Key as the
Shared Secret.
Proxy Host The IP address of the proxy server. This is an
optional field.
Proxy Port The port reserved for the proxy server. This
is an optional field.
Region The region where S3 bucket is configured.
This is an optional field.
Query Parameter The URL query parameter that the
corresponding S3 store vendor expects for
extending retention. This is specific to the
compatible store. This is an optional field.
Retention Header Name Header used for specifying the new retention
date. The date format must be in accordance
to the ISO 8601 format
(YYYYMMDDThhmmssZ). This is specific to
the compatible store. This is an optional field.

510 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

Field label Description

Mode Retention mode that applies to different
levels of protection. This is an optional field
used for the AmazonS3 vendor only. Valid
values are:
• null
• COMPLIANCE
• GOVERNANCE: This is the default value
for Amazon S3.
Vendor Specifies the storage vendor. This is an
optional field. Valid values are:
• null
• AmazonS3
• HCP

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying S3 stores.

19.2.11.3 Configuring S3 store properties

Set the appropriate configuration values in the s3.properties file available in
%WildFly_HOME%\server\DctmServer_MethodServer\deployments\acs.ear\lib
\configs.jar.

• For proxy settings, set the appropriate values for the following properties:

– #PROXY_HOST=
– #PROXY_PORT=
– #PROXY_USER=
– #PROXY_PASSWORD=
• For use of v4 signing for all S3 requests, set the value of enable-v4signing to
true. The default value is false.

• To include MD5 checksum value to verify the integrity of the object, set the value
of enable-md5 to true. The default value is false.

Note: When md5 is enabled, the default value of

mds-multipart-threshold is 10 MB.
• To randomize the beginning component of the object name to increase
performance, set the value of use-random-in-filename to true. The default
value is false.
• When multipart upload is chosen, the part-size reflects the size of the portion of
content that needs to be uploaded to the S3 store. Set the value of part-size to 5.
The part size is considered as megabytes. The default value is 5 MB.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 511

Chapter 19 Storage Management

• To perform parallel multipart processing, set the value of

multipart-parallel-processing to true. The default value is false.
• To set the number of threads to be used during multipart parallel processing, set
the value of multipart-processing-thread.pool-size to 5. The default value
is 5.
• To allow temporary credentials for authenticating S3 store users to access
Amazon S3 resources and within a specific time period, use the following
parameters:

– use-tempcredentials: Used to enable temporary credentials to access

Amazon S3 resources using Security Token Service (STS). Valid values are
true and false. If you set the value to true, temporary credentials are used
for authentication. If you set the value to false, permanent credentials are
configured and used for authentication.
– s3-sessiontoken-duration: Used to configure the temporary token
duration interval (in seconds). After the duration, the temporary token is
refreshed and a new token is created. The minimum value is 900 seconds and
the maximum value is 86400 seconds.

Note: If you set the value lesser than the minimum value, then the
Documentum Server takes the minimum value as 900 seconds. If you set
the value greater than the maximum value, then the Documentum
Server takes the maximum value as 86400 seconds.

19.2.11.4 Logging
Tracing is in line with the DFC tracing activity. However, there are additional log
statements at the DEBUG level that appears in the log. The DEBUG level can be
enabled using log4j.properties in ACS.

• Windows: %DOCUMENTUM%\<WildFly version>\server\

DctmServer_MethodServer\deployments\acs.ear\lib\configs.jar\log4j.
properties

• Linux: $DOCUMENTUM/<WildFly version>/server/DctmServer_MethodServer/

deployments/acs.ear/lib/configs.jar/log4j.properties

1. Open log4j.properties.

2. Update rootCategory tracing to DEBUG. For example, log4j.

rootCategory=DEBUG, A1, F1.

3. Append the following line at the end of the file: log4j.logger.com.

documentum.content.store.plugin.s3=DEBUG,ACS_LOG.

512 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

19.2.11.5 Troubleshooting
The logging and tracing information generated by DFC and ACS is sufficient for
troubleshooting. To verify if store plugins for S3 and TBO for S3 store are installed,
run the queries in IAPI to get the expected results.

• To verify if the plugin module and its dependencies are installed:

Query:
API> ?,c,select r_object_id,object_name from dm_sysobject
where FOLDER('/System/Modules/S3 Plugin',DESCEND)

Result:
r_object_id object_name
---------------- -----------------------
09xxxxxxxxxxxxxx S3 Plugin
0bxxxxxxxxxxxxxx External Interfaces
0bxxxxxxxxxxxxxx Miscellaneous
0bxxxxxxxxxxxxxx S3 Plugin Libraries
09xxxxxxxxxxxxxx aws-java-sdk-s3
09xxxxxxxxxxxxxx commons codec-s3
09xxxxxxxxxxxxxx commons logging-s3
09xxxxxxxxxxxxxx http client-s3
09xxxxxxxxxxxxxx http core-s3
09xxxxxxxxxxxxxx jackson-annotations-s3
09xxxxxxxxxxxxxx jackson-core-s3
09xxxxxxxxxxxxxx jackson-databind-s3
09xxxxxxxxxxxxxx joda-time-s3
(14 rows affected)

• To verify if the TBO for dm_s3_store is installed:

Query:
API> ?,c,select r_object_id,object_name from dm_sysobject
where FOLDER('/System/Modules/TBO/dm_s3_store',DESCEND)

Result:
r_object_id object_name
---------------- ------------------------
08xxxxxxxxxxxxxx RuntimeEnvironment.xml
09xxxxxxxxxxxxxx s3-tbo-api
09xxxxxxxxxxxxxx s3_tbo_impl
0bxxxxxxxxxxxxxx External Interfaces
0bxxxxxxxxxxxxxx Miscellaneous
(5 rows affected)

Note: The xxxxxxxxxxxxxx is the object id of the repository.

19.2.12 Mount points

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

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 513

Chapter 19 Storage Management

19.2.12.1 Creating or modifying mount points

You can create a mount point object.

Table 19-13: Mount point properties

Field label Value

Name The name of the mount point object.

Some names, such as “events” or “common”,

are reserved for Documentum Server use.
Host Name The hostname for the machine on which this
directory resides.
File System Path The location of the directory or file
represented by the location object. The path
syntax must be appropriate for the operating
system of the server host.

For example, if the server is on a Windows

NT machine, the location must be expressed
as a Windows NT path.

Caution
Be sure that the combination of the
host and path you specify does not
point to the same physical location
as any other file stores. If two file
stores use the same physical
location, data loss may result.

Security The security level for this directory location.

Options are:
• Public Open
• Public
• Private

The default value is Private.

Unix Preferred Alias Set to the directory name used to mount the
directory.
Macintosh Preferred Alias Set to the volume name chosen for the
mounted directory.

The volume name of the mounted directory

is set when the directory is exported through
the file-sharing system. It is the name that
will appear in the Chooser for that directory.

514 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

Field label Value

Windows Preferred Alias Set to the alias drive letter used to mount the
directory.

For example, t:\ or k:\.

Comments Enter any comments about the mount point.

Documentum Administrator User Guide contains the instructions on creating or

modifying mount points.

19.2.13 Locations
The directories that a Documentum Server accesses are defined for the server by
location objects. A location object can represent the location of a file or a directory.

19.2.13.1 Creating or modifying locations

A location object contains a file system location for a specific file or directory. The
server uses the information in location objects to find the files and directories that it
needs for successful operation. Create the directory on the file system before creating
a location object.

Table 19-14: Location object properties

Field label Value

Name The name of the location object.

Some names, such as “events” or “common”,

are reserved for Documentum Server use.
Choose a Mount Point for this Location Identifies the mount point underneath which
this location resides. Use the name of the
mount point object that describes the mount
point.
Mount Point Path Specifies the mount point path. Valid values
are:
• Existing: Uses the current mount point
path. Select Null to specify that the
mount point is not shared, or select share
to use this mount point as a shared
mount point.
• Create Mount Point Path: Select to create a
mount point path, then click Select Path
to browse to a mount point on the file
system.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 515

Chapter 19 Storage Management

Field label Value

Path Specifies the file system or UNC path.
• File System Path: The location of the
directory or file represented by the
location object. The path syntax must be
appropriate for the operating system of
the server host. For example, if the server
is on a Windows NT machine, the
location must be expressed as a Windows
NT path.
• UNC: Indicates the UNC path.

Caution
Be sure that the combination of the
mount point and path you specify
does not point to the same physical
location as any other file store. If
two file stores use location objects
that point to the same physical
location, data loss may result.

Path Type Indicates whether the location points to a

directory or file.
Security Type The security level for the directory or file.
Valid values are:
• publicopen
• public
• private

If the security type is not set, the default

value is the security level of the referencing
object, such an associated storage object.

Documentum Administrator User Guide contains the instructions on creating or

modifying locations.

19.2.14 Plug-ins
A plug-in is a shared library (on Linux systems) or DLL file (on Windows systems)
for retrieving content when an external store is in use.

You must create the plug-in. Documentum provides code for sample plug-ins in the
DM_HOME/unsupported/plugins directory. The sample plug-ins are examples and
are not supported by Documentum.

The API interface between the shared library or DLL and the server consists of C
functions for the plug-in library.

516 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.2. Storage

19.2.14.1 Creating or modifying plug-ins

You can create the plug-in object that represents the plug-in.

Table 19-15: Plug-in properties

Field label Value

Name The name of the plug-in object.
Hardware Platform Specifies one or more hardware platforms on
which the plug-in can run.

Click Edit to access the Hardware Platforms

page. Enter the hardware type in the Enter a
new value field, then click Add. When all
types are entered, click OK.
Operating System Specifies one or more operating systems on
which the plug-in can run.

Click Edit to access the Host Machine page.

Enter the operating system in the Enter a
new value field, then click Add. When all
operating systems are entered, click OK.
Type Select a file type. Options are:
• DLL (Windows)
• SO (UNIX)
Usage Type a comment on how the plug-in is used.

Documentum Administrator User Guide contains the instructions on creating or

modifying plug-in objects.

19.2.15 Deleting storage areas, locations, mount points, and

plug-ins
You must have system administrator or superuser privileges to delete a storage area.

Documentum Administrator User Guide contains the instructions on deleting storage

areas.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 517

Chapter 19 Storage Management

19.2.16 Setting or updating a retention date or retention period

A Centera store or NetApp SnapLock store is retention-enabled when a default
retention date is required for all objects saved to that store.

You can assign specific retention dates for content stored in a retention-enabled
store. A retention date is the date to which the content file must be retained. If a
retention date is defined for content in the storage system, the file cannot be
removed from the repository until that date. For example, if you set the retention
date for an object to February 15, 2011, the content cannot be removed until that
date.

When a retention date is set for an object, it is set for all renditions associated with
page 0 (zero) of the object. Documentum Server moves the selected object and all of
its associated renditions to a retention-enabled storage area. If there are multiple
retention-enabled storage areas in the repository, you must select the target storage
area. To set a retention date, you must belong to the Webtop administrator role and
have at least WRITE permission on the object, and the Centera or SnapLock store
must be retention-enabled.

You can alternatively assign a retention period for content stored in a retention-
enabled store. A retention period is the amount of time for which the content must
be retained. If a retention period is defined, you cannot remove the file from the
repository until that period has expired. For example, if the retention period is set to
five years and the current date is January 1, 2007, the content file cannot be removed
before January 1, 2012.

Documentum Administrator User Guide contains the instructions on setting or

updating a retention period or retention date for a document or other repository
object.

19.2.17 Supporting WORM for Data Domain and Isilon stores

Documentum Server uses the Write Once Read Many (WORM) functionality
provided by Data Domain and Isilon stores for applying retention at the file system
level. The WORM functionality is applicable only for dm_filestore objects. The
dm_location object for Data Domain and Isilon have paths mounted as CIFS
(Windows) or NFS (Linux) share locations. Retentions can be applied on the file
system as follows:

• Apply WORM automatically: By default, the documents in the file share location
are set to WORM with a default retention date as defined by the storage
administrator. Only Isilon supports the default retention using SmartLock
containers.
• Control retention using retainers: The retention date on the retainer object is
applied to the files. If the maximum retention date given in the retainer is greater
than the default retention date (if it exists), default retention date will be
overridden. Only fixed retention is supported.

518 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.3. Assignment policies

The files with retention and also enabled with WORM cannot be modified or deleted
until the expiration of the retention date.

19.2.17.1 Enabling WORM

To enable WORM at the filestore:

1. Use the following DQL to set the status of filestore to WORM:

EXECUTE set_storage_state with store='<store_name>',worm=[true | false]

2. Set the native_access attribute of dm_filestore to <isilon> (for Isilon) or

<datadomain> (for Data Domain) using the IAPI commands.
For example, to set to isilon, use the following command:
retrieve,c,dm_filestore where name = '<store_name>'
set,c,l,native_access
isilon
save,c,l

Note: WORM and non-WORM data cannot be combined on same filestore

because WORM feature cannot be applied automatically on existing
content files. Instead, create new WORM store and migrate existing
contents to new store using the RPC, MIGRATE_CONTENT.

19.2.17.2 Configuring SmartLock containers in Isilon

You need to configure the SmartLock containers (WORM folder) with the default
retention date in Isilon. Use the following command:
isi worm mkdir --path=<complete path for the new directory>
-d=<default retention offset>

To view the WORM status of a file or directory, use the following command:
isi worm info --path=<complete path of the file or directory> --verbose

19.3 Assignment policies

Assignment policies are sets of rules that DFC-based applications apply to
determine the correct file store or retention store for each new content file added to
the repository. Assignment policies require a Content Storage Services (CSS) license.
Any client application built on DFC applies assignment policies automatically if CSS
is enabled in the repository.

Assignment policies can only be applied to the SysObject type and its subtypes, and
are represented in the repository by persistent objects. A particular object type can
have only one associated assignment policy. When a new content file is added to the
repository, the assignment policy engine determines whether the object type of the
file has an active associated assignment policy. If there is no active assignment
policy for the type, the assignment policy engine determines whether the supertype
of the object has an active associated assignment policy. If there is an active
assignment policy for the file type or a supertype, the system applies the policy and

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 519

Chapter 19 Storage Management

stores the file accordingly. If no policy is found or if none of the rules match in an
applicable policy, the system uses the default algorithm to determine the correct
storage area. If none of the rules match in the applicable assignment policy, the
policy engine does not further search the type hierarchy.

Assignment policies consist of rules that define the criteria for storing content files in
the correct storage area. There are two types of rules:

• Standard rules
Standard rules determine storage area based only on the object format and
content size. Standard rules can have one to five criteria.
• Custom rules
Custom rules can be based on the values of any standard or custom SysObject
property, provided those values are present before an object is saved. There are
no restrictions on the number of conditions in a custom rule. The properties and
values are specified using methods, such as getString(), getInt(), or
getRepeatingString(). Custom rules follow the Java syntax for any conditional
statements in the rule.

There is no syntactical difference between the two types of rules. During rule
validation, a standard rule is translated into the same syntax used for custom rules.

Assignment policies are applied only to new content files, whether they are primary
content files or renditions. Rules of an assignment policy are applied in the order in
which they are listed within a policy. If a rule is met, the remaining rules are
ignored. To match a rule, all conditions in the rule must be satisfied. An assignment
policy is applied when

• A content file is first saved or imported into the repository.

• A new version of a document is created, because versioning creates a new
content file.
• A document is checked out and checked in and a new version results, the policy
is applied to the new version of the content file.
• An existing document is modified and saved as the same version of the
document.

Assignment policies are not applied or enforced under the following conditions:

• An application sets the a_storage_type SysObject property.

If a_storage_type is set by an application, assignment policies do not execute for
any of the primary content pages (content added using a Setfile). Documentum
client applications do not generally set this property.
• The application specifies the storage location for a secondary rendition during an
addrendition call.
If a storage location is already provided, the policy engine does not execute the
policy for this particular secondary rendition.

520 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.3. Assignment policies

• Assignment policies are not enabled.

• The properties of an existing documents are modified and saved the changes
without checking out and versioning the document. The content is saved into its
current storage location.

• The DFC policy engine is turned off.

• Assignment policies are enabled but a policy does not exist for an object type or
for any of the types supertypes.

• A document does not satisfy any of the conditions in the applicable policy.

• The content is replicated (content associated with a replica object).

• The content is loaded into a repository with dump and load.

• The content generated by a refresh API.

• The content is associated with storage policies.

If the assignment policy engine encounters an error in a rule at runtime (for

example, if a property name is invalid), the assignment policy engine returns an
error and the save operation on the document or object fails. This behavior can be
overridden by setting the DFC client-preference flag in the dfc.properties file on the
application server host where Webtop or Documentum Administrator is installed:
dfc.storagepolicy.ignore.rule.errors=true

If this flag is set to true, the assignment policy engine ignores the faulty rule and
attempts to apply the next rule in the policy.

19.3.1 Viewing a list of assignment policies

You can view a list of all assignment policies defined for a particular repository and
select any of the listed policies for viewing or modifying properties.

The assignment policy list page displays a list of all assignment policies in the
current repository.

The following information is displayed for each policy:

• Policy name

• A brief description of the policy

• Whether the policy is currently Active or Inactive

• The object types to which the policy applies

Documentum Administrator User Guide contains the instructions on viewing a list of

assignment policies in a repository.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 521

Chapter 19 Storage Management

19.3.2 Creating, viewing, or modifying assignment policies

To create an assignment policy, you must have the role of Administrator or, if there
are no Administrators in the repository, the user privilege level of system
administrator or superuser. Policies can only be created in repositories where
Content Storage Services is enabled.

Table 19-16: Assignment policy properties

Field Description
Name The name and a description for the
assignment policy. The name must be unique
in the repository and can be modified after
the policy is saved.
Description A description of the policy. Optional
property.
Status Specifies whether the assignment policy is
active. The default status is Inactive. Select
Active to enable the policy and automatically
validate the rule syntax. The validation
process does not check whether property
names in the rules are valid.
Validate all of the rules defined for this Validates the rules for the policy if the policy
policy is active. The default is selected. If the policy
is created in the active state, the checkbox is
selected and grayed out.

If the policy is created in the inactive state,

optionally clear the checkbox.
Object types Select the object types to which the policy
applies.

A policy can be applied to multiple object

types. If the chosen object type has subtypes,
the policy is inherited automatically at
runtime by the subtypes, except those
subtypes that are already associated with a
different assignment policy.

Click Select then select the object types to

which the policy applies and click >.
Create/Edit Rules Specifies the rules for storing content.

522 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.3. Assignment policies

Field Description
Standard Rule The Standard Rule option is selected by
default. To create a custom rule, select the
Custom Rule option.

A policy can have up to five rules, which can

be any combination of standard and custom
rules. Each rule can have up to five criteria.

Create or edit rules using the If and Then

operands and drop-down lists to specify
formats, content size, and storage areas.
Add Criteria Click to add additional conditions to the rule.

A standard rule can have up to five criteria.

Insert Rule Click to insert the completed rule.
Cancel Rule Click to delete text that has been entered in
the text box.
Custom Rule Type the custom rule in the text box.
Policy Rules Displays the existing rules defined for this
policy. Click a rule to select it, then rearrange
the order in which the rules are executed by
clicking the Up and Down links. Edit or
delete a rule by clicking the associated Edit
and Remove links.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying assignment policies.

19.3.3 Modifying the permissions of an assignment policy

You can modify the permissions of an assignment policy. An assignment policy
permission set must grant at least READ permissions to World.

Documentum Administrator User Guide contains the instructions on modifying

assignment policy permissions.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 523

Chapter 19 Storage Management

19.3.4 Custom assignment policy rule examples

Custom rules define assignment policies based on values of properties of an object.
Specify these properties in the rule using the methods available on IDfSysObject of
DFC, such as getString(), getInt(), or getRepeatingString().

Custom rules follow Java syntax for the conditional statement in the rule. The
following are examples of valid custom rules:

Example 19-1: Custom Rules for Assignment Policies

Example Rule 1:
sysObj.getString("owner_name").equals("JSmith") --> filestore_02

Example Rule 2:
sysObj.getString("subject").equals("Policies and Procedures") &&
sysObj.getOwnerName().equals("JSmith") --> filestore_03

Example Rule 3:
sysObj.getString("subject").equals("smith") &&
sysObj.getOwnerName().equals("john") --> filestore_03

Note that --> is the correct and required syntax.

For assistance in creating, implementing, or debugging custom rules, contact

OpenText Global Technical Services for service and support options to meet your
customization needs.

19.3.5 Associating an assignment policy with an object type

Assignment policies are inherited and only one policy can be associated with an
object type.

Documentum Administrator User Guide contains the instructions on associating

assignment policies with object types.

19.3.6 Deleting assignment policies

You can delete assignment policies.

Documentum Administrator User Guide contains the instructions on deleting

assignment policies.

524 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.4. Migration policies

19.4 Migration policies

Migration policies move content files from one storage area to another, based on the
rules (conditions) defined in the policy. Files are selected for migration based on
format, content size, or date criteria. The target storage area of a migration policy
can be a file store or a retention store (Centera or NetApp SnapLock).

Migration policies are jobs that execute the MIGRATE_CONTENT administration

method. The conditions are stored as job arguments. A Content Storage Services
(CSS) license is required to create content migration jobs. CSS is enabled using a
license key when Documentum Server is installed or when the Server Configuration
Program is used to update the server installation.

19.4.1 Creating, viewing, or modifying migration policies

Migration policies can be created and used only in repositories where Content
Storage Services is enabled.

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying migration policies.

Table 19-17: Migration policy Info tab properties

Field Description
Name The name of the job. Mandatory property.
Job Type The type of job. Optional property. The
default value is Content.
Trace Level The trace level from 0 (no tracing) to 10 (a
debugging level of tracing).
Designated Server The server on which the migration policy is
run. Select a server from the drop-down list.
The list displays each registered servers. The
default value is Any Running Server.
State Specifies whether the policy is active or
inactive. The default value is Active.
Options
Deactivate on Failure Select to deactivate the job after a run fails to
execute correctly.
Run after Update Select to run the job immediately after it was
updated.
Save if Invalid Select to save the job even if it is invalid.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 525

Chapter 19 Storage Management

19.4.1.1 Configuring a migration policy schedule

The migration policy schedule determines when the migration job is executed.

Table 19-18: Migration policy Schedule tab properties

Field Description
Next Run Date and Time Specifies the next start date and time for the
job.

The default is the current date and time.

Repeat Specifies the time interval in which the job is
repeated.
Frequency Specifies how many times the job is repeated.

For example, if Repeat is set to Weeks and

Frequency is set to 1, the job repeats every
week. If Repeat is set to weeks and
Frequency is set to 3, the job repeats every
three weeks.
End Date and Time Specifies the end date and time for the job.

The default end date is 10 years from the

current date and time.
After Specifies the number of invocations after
which the job becomes inactive.

19.4.1.2 Configuring migration policy rules

Rules can be standard rules, created by making choices from drop-down lists, or
they can be custom rules, which use DQL predicates. Custom rules can select
content to be migrated only from dm_sysobject and dmr_content objects. SysObject
subtypes are not supported.

Table 19-19: Migration policy Rules tab properties

Field Description
Selected Objects
Simple selection Creates a migration rule based on preset
values, such as format, creation date,
modification date, access date, or size.

526 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.4. Migration policies

Field Description
Move objects where Specifies which objects to move. Select one of
the criteria from the drop-down list, as
follows:
• format: Migrates objects of a particular
format. Click Select and then select the
correct format.
• created:Migrates objects according to
creation date.
• modified:Migrates objects according to
their modification date.
• accessed: Migrates objects according to
the date they were last accessed.
• size: Migrates objects according to their
size in bytes. Enter the number of bytes.

For the created, modified and accessed

operands, the number of days is always in
relation to the date the job is scheduled to
run. Valid operands are:
• Exactly: Migrates objects modified exactly
the number of days before.
• More than: Migrates objects modified
more than the number of days before.
• Less than: Migrates objects modified less
than the number of days before.
Renditions to include Specifies whether to migrate Primary or
Secondary renditions or both. The rendition
option is only available in conjunction with
the created, modified, or accessed selection
criteria.
DQL query selection Creates a migration rule based on a DQL
query. Custom rules can select content to be
migrated from dm_sysobject, its subtypes,
and dmr_content objects.
Move specified type Select to migrate the content associated with
SysObjects (dm_sysobject) and its subtypes.
When selected, you must also select to
migrate primary or secondary renditions, or
both.
Move content objects only Select to migrate the content associated with
content objects (dmr_content).
Where Type a rule into the text box. Specify a DQL
predicate and whether the predicate runs
against content associated with SysObjects,
its subtypes, or content objects.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 527

Chapter 19 Storage Management

Field Description
Renditions to include If you selected Move specified types, select
to migrate Primary or Secondary renditions
or both.
Move options
Target Store The destination storage area to which the
content files migrate. Select a store from the
drop-down list. The list includes file stores
and retention stores (Centera and NetApp
SnapLock).
Batch Size The number of content files to include in a
single transaction during the migration
operation. The default value is 500.
Maximum Count The maximum number of content files to
transfer. To specify an unlimited number of
documents, type a zero [0] or leave the field
blank.
Content Migration Threads The number of internal sessions to use to
execute the migration policy. The default
value is 0, indicating that migration executes
sequentially.

This field displays only if you have a Content

Storage Services license and the license is
enabled on the Documentum Server. The
Content Migration Threads value cannot
exceed the Maximum Content Migration
Threads value in the server configuration
object (dm_server_config).

Documentum Administrator User Guide contains the instructions on creating, viewing,

or modifying migration policies.

19.4.2 Configuring migration policy SysObject information

The SysObject information typically consists of metadata associated with the object.

Table 19-20: Migration policy SysObject tab properties

Field Description
Title The title of the object.
Subject The subject of the object.
Keywords Keywords that describe the object. Click Edit
to access the Keywords page. Enter a new
keyword in the Enter new value box and
click Add.

528 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.5. Orphaned content objects and files

Field Description
Authors The author of the object. Click Edit to access
the Authors page. Type a new author in the
Enter new value box and click Add.
Owner Name The owner of the object. Click Edit to access
the Choose a user page and select an owner.
Show more Click to view more SysObject properties of
the migration policy.

Documentum Administrator User Guide contains the instructions on configuring

migration policy SysObject information.

19.4.3 Viewing migration policy job reports

A job report contains information about the job, such as when the job was started
and whether the job ran successfully.

Documentum Administrator User Guide contains the instructions on viewing migration

policy job reports.

19.4.4 Deleting migration policies

You can delete migration policies.

Documentum Administrator User Guide contains the instructions on deleting migration

policies.

19.5 Orphaned content objects and files

Destroying a document or other object does not destroy any content files or content
objects associated with that document. Therefore the orphaned files and content
objects should be removed on a regular basis.

An orphaned content object is a content object that is not referenced by another

object. Objects have a property called i_contents_id that contains the object ID of the
content object representing their content. An orphaned content file is a content file
that has no associated content object.

Documentum Server provides two system administration tools for removing

orphaned content objects and files:

• dmclean
The dmclean utility scans a repository and finds all orphaned content objects
and, optionally, orphaned content files. It generates a script that removes these
objects and files from the repository.
• dmfilescan

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 529

Chapter 19 Storage Management

The dmfilescan utility scans a specified storage area (or all storage areas) and
finds all orphaned content files. It generates a script that removes these files from
the storage area. The dmfilescan should be used as a backup to dmclean.

There are multiple options to run the dmclean and dmfilescan utilities:

• Documentum Administrator
• System administration tools
• DQL EXECUTE statement
• An IDfSession.apply() method
• From the operating system prompt

Executing either utility through a DQL EXECUTE statement, an IDfSession.apply

method, or the operating system prompt is a two-step process. First, the utility must
be executed to generate a script, and the script is run to perform the actual
operations. Executing the operation in two parts allows checking which objects and
files are going to be deleted before the work is actually performed.

Note: Only the superuser can retrieve the path of the orphaned content objects.
In general, the system prevents any user to get access to the user content that
has been orphaned due to version or checkin of the objects.

19.5.1 The dmclean utility

The dmclean utility can be run in Documentum Administrator, using the DQL
EXECUTE statement, an IDfSession.apply method, or from the operating system
prompt. The syntax varies slightly, depending on how the utility is executed.
Running dmclean requires system administrator or superuser privileges.

By default, dmclean operates on content objects representing content stored in any

type of storage area except external storage, Centera storage, and NetApp SnapLock
storage. It also removes the associated content files from the storage areas. You can
include an argument on the command line to include orphaned content objects
representing files in Centera and NetApp SnapLock storage in its processing. If you
include that argument, it handles the associated orphaned content according to the
retention requirements set for the storage area and the particular content. The
“Removing orphaned content from retention type storage areas” on page 532
section contains more information.

The following table describes the arguments for the dmclean utility.

Table 19-21: dmclean arguments

Argument Description
-no_note Directs the utility not to remove annotations.
-no_acl Directs the utility not to remove orphaned
ACLs.

530 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.5. Orphaned content objects and files

Argument Description
-no_content Directs the utility not to remove orphaned
content objects and files.
-no_wf_templates Directs the utility not to remove orphaned
SendToDistribution templates.
-include_ca_store Directs the utility to include orphaned
content objects representing files stored in
Centera or NetApp SnapLock storage.

Note: This argument is not supported

when dmclean is run through
Documentum Administrator.
-clean_aborted_wf Directs the utility to remove aborted
dm_workflows and all related runtime
objects.
-clean_deleted_lwso Directs the utility to remove deleted
lightweight SysObjects and their parents.
-clean_wf_method_exec_result Directs utility to delete workflow method
output for finished workflows.
-clean_content_in_parallel Directs the utility to delete orphaned content
objects running in parallel.
-parallel_degree Directs the utility to define the degree of
parallelism. It is an integer type value and it
cannot be a negative value.

Note: The default value of

parallel_degree argument is 5.

If you need syntax help, enter the name of the utility with the -h argument at the
operating system prompt. The “Running jobs” on page 455 and “Dmclean”
on page 389 sections contain information on running dmclean using Documentum
Administrator.

The executable that runs dmclean is launched by a method that is created when you
install Documentum Server. By default, the dmclean executable is assumed to be in
the same directory as the Documentum Server executable. If you moved the server
executable, modify the method_verb property of the method that launches dmclean
to use a full path specification to reference the executable. You must be in the
%DM_HOME%\bin ($DM_HOME/bin) directory when you launch the dmclean
executable.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 531

Chapter 19 Storage Management

19.5.1.1 Removing orphaned content from retention type storage areas

The dmclean utility does not operate on content stored in Centera or NetApp
SnapLock storage areas by default. If you want to remove orphaned content files
from these retention type storage areas, and their associated content objects, you
must use run the dmclean utility from the command line and include the -
include_ca_store argument.

Removing the content object and content file fails if the storage system does not
allow deletions or if the content retention period has not expired. To find and
remove the repository objects that have expired content, use the
RemoveExpiredRetnObjects administration tool. Then use dmclean with the -
include_ca_store argument to remove the resulting orphaned content files and
content objects.

19.5.1.2 Running dmclean with an EXECUTE statement

To run dmclean with the EXECUTE statement, use the following syntax:
EXECUTE do_method
WITH method = 'dmclean',
arguments = '<list of constraining arguments>'

The dmclean utility can remove a variety of objects in addition to content files and
content objects. These objects include orphaned annotations (note objects), orphaned
ACLs, and unused SendToDistributed workflow templates. These objects are
removed automatically unless you 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 orphaned annotations and unused ACLs. If you include
multiple constraints in the argument list, use a space as a separator.

The utility automatically saves the output to a document that is stored in the Temp
cabinet. The utility ignores the SAVE argument in the DO_METHOD. The output is
saved to a file even if this argument is set to FALSE. The output is a generated IAPI
script that includes the informational messages generated by the utility.

19.5.1.3 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> [<list of constraining
arguments>]

Where <name> is the name of the repository against which to run the utility and
<init_file_name> is the name of the server.ini file for the server of repository. The
name and init_file_name arguments are required.

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 command
line when you execute dmclean.

The dmclean utility can remove a variety of objects in addition to content files and
content objects. These objects include orphaned annotations (note objects), orphaned

532 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.5. Orphaned content objects and files

ACLs, and unused SendToDistributed workflow templates. These objects are

removed automatically unless you 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 orphaned annotations and unused ACLs. If you include
multiple constraints in the argument list, use a space as a separator.

19.5.2 The dmfilescan utility

The dmfilescan utility locates content files that have no associated content object. By
default, the utility looks for all orphaned files that are older than one week. The
utility ignores content files that have a content object. The dmfilescan utility ignores
the content file if it has a content object in the repository if it has an associated
content object, even if the content object is not referenced by other objects. Executing
the utility generates a script that contains commands to remove the orphaned files
found by the utility. The utility does not actually remove the files itself. After the
utility completes, run the script to remove the files.

The dmfilescan utility should be used as a backup to the dmclean utility. It can be
executed in Documentum Administrator, using the DQL EXECUTE statement, an
IDfSession.apply() method, or from the operating system prompt. On Windows, the
utility generates a batch file (a .bat script). On Linux, the utility generates a Bourne
shell script. The executing syntax and the destination of the output vary, depending
on how the utility is executed.

The executable that runs dmfilescan is launched by a method that is created during
Documentum Server installation. By default, Documentum Server looks for the
dmfilescan executable in the same directory the Documentum Server executable is
stored. If you moved the server executable, modify the method_verb property of the
method that launches dmfilescan to use a full path specification to reference the
executable. You must be in the %DM_HOME%\bin ($DM_HOME/bin) directory
when you launch the dmfilescan executable.

The “Running jobs” on page 455 and “Dmfilescan” on page 392 sections contain the
information on running dmfilescan in Documentum Administrator.

The following table describes the dmfilescan arguments.

Table 19-22: dmfilescan utility arguments

Argument Meaning
-s storage_area_name The name of the storage object that
represents the storage area to clean. If this
argument is not specified, the utility operates
on all storage areas in the repository, except
far stores.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 533

Chapter 19 Storage Management

Argument Meaning
-from directory1 Subdirectory in the storage area at which to
begin scanning. The value is a hexadecimal
representation of the repository ID used for
subdirectories of a storage area.

The utility starts at the specified directory

and scans all the directories below it or to the
directory specified in the -to directory2
argument.
-to directory2 Subdirectory in the storage area at which to
end scanning. The value is a hexadecimal
representation of the repository ID used for
subdirectories of a storage area.

The utility starts at the top directory or the

directory specified in the -from directory1
agument.
-force_delete Removes content files that are younger than
24 hours. If the -force_delete argument is not
included, content files younger than 24 hours
are not removed.
-no_index_creation Prevents Documentum Server from creating
indexes. If the -no_index_creation argument
is not included, Documentum Server uses the
default behavior for creating indexes.
-grace_period An integer that defines the grace period for
allowing orphaned content files to remain in
the repository. The default is one week,
expressed in hours. The integer value for this
argument is interpreted as hours.

19.5.2.1 Running dmfilescan using an EXECUTE statement

To run dmfilescan with 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 Temp
cabinet. The utility ignores the SAVE argument of the do_method. The output is
saved to a file even if this argument is set to FALSE. The output is a generated script
that includes the informational messages generated by the utility.

534 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.5. Orphaned content objects and files

19.5.2.2 Running dmfilescan 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>]

The dmfilescan utility sends the output to standard output. To save the generated
script to a file, redirect the standard output to a file on the command line when you
run the utility.

The two arguments, -docbase_name and -init_file, are required, where name is the
name of the repository that contains the storage area or areas to clean and
init_file_name is the name of Documentum Server server.ini file.

19.5.2.3 The generated script

Executing dmfilescan generates a script. The script comprises a series of remove
commands that remove orphaned files found by the utility. For each file, the script
lists its data ticket and storage ID. The script also contains a template DQL SELECT
statement that can be used with the data ticket and storage ID values.

The following example describes a script that was generated on a Windows host.
rem Documentum, Inc.
rem
rem This script is generated by dmfilescan for later verification
rem and/or clean-up. This script is in trace mode by default. To
rem turn off trace mode, remove '-x' in the first line.
rem
rem To see if there are any content objects referencing a this file
rem listed below, use the following query in IDQL:
rem
rem c:> idql <docbase> -U<user> -P<pwd>
rem 1> select r_object_id from dmr_content
rem 2> where storage_id = '<storage_id>' and data_ticket =
<data_ticket>
rem 3> go
rem
rem If there are no rows returned, then this is an orphan file.
rem
rem storage_id = '280003c980000100' and data_ticket = -2147482481
del \dm\dmadmin\data\testora\content_storage_01\000003c9\80\00\04\8f
rem storage_id = '280003c980000100' and data_ticket = -2147482421
del \dm\dmadmin\data\testora\content_storage_01\000003c9\80\00\04\cb
rem storage_id = '280003c980000100' and data_ticket = -2147482211
del \dm\dmadmin\data\testora\content_storage_01\000003c9\80\00\05\9d
. . .

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 535

Chapter 19 Storage Management

19.5.2.4 Executing the dmfilescan script

Run the dmfilescan script from the operating system prompt.

On Windows:
c:> <script_file_name>

On Linux:
% <script_file_name>

Make sure that you have the user permission to execute this file. On Windows, use
File Manager to add appropriate permission to your user account. On Linux, use the
following command:
% chmod ugo+x <script_file_name>

19.6 Archiving and restoring documents

As repositories grow and age, you typically archive older or infrequently accessed
documents 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
the Archive and Restore methods and the Archive tool.

Note: If you want to archive fixed data such as email or check images that will
not be changed and must be retained for a fixed period, use the content-
addressed storage option, rather than the archiving capabilities described in
this section. The content-addressed storage option is capable of storing massive
amounts of data with a defined retention period.

19.6.1 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
• 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
(which issues an Archive method) or an application issuing the Archive
method.

536 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 19.6. Archiving and restoring documents

2. The Archive method queues a DM_ARCHIVE event in the repository operator’s

inbox.

3. The Archive tool reads the DM_ARCHIVE event in the inbox and performs the
archiving operation.
When the tool is finished, it sends a completion message to the user requesting
the operation and to the repository operator.

4. A user-defined DO_METHOD procedure moves the file from the archive

directory to 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
Documentum client or an application issuing the Restore method.

2. The Restore method queues a DM_RESTORE event to the repository operator’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 file
containing the archived file back into the archive directory.

5. After the file is back in the archive directory, the Archive tool performs the
restore operation.
When the tool is finished, it sends a completion message to the user requesting
the operation and to the repository operator.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 537

Chapter 20
InfoArchive Integration with Documentum

InfoArchive, an enterprise archiving system for long-term or permanent

preservation is designed to help address the complete information retention needs
and achieve regulatory compliance.

The existing InfoArchive integration with Documentum uses separate standalone

command line utilities like Documentum Connector and InfoArchive where
Documentum Connector is a command line data extraction and transformation
utility that allows you to export content to archive it directly from the Documentum
repository and generate Submission Information Packages (SIPs) to be ingested into
InfoArchive. Documentum Connector executes a DQL query statement defined in a
configuration file and extracts the persistent objects from the Documentum
repository. InfoArchive utility allows you to ingest SIPs into the respective
InfoArchive server.

The new Documentum Connector DAR file named DCTM2IA.dar:

• Helps to automate or schedule job archival

• Provides control to delete Documentum content after successful archiving

The new Documentum-triggered archival provides flexibility of running archival

from any of the DFC-based clients such as D2, xCP, and WDK or in Documentum
Server JMS as job or methods.

20.1 Prerequisites
You must have installed the following:

• Documentum Server
• Documentum Administrator
• InfoArchive server

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 539

Chapter 20 InfoArchive Integration with Documentum

20.2 Setting up Documentum connector

1. As part of the Documentum Server and internal DAR files installation, the new
connector DAR file named DCTM2IA.dar is also installed. The connector DAR
file is available at %DM_HOME%\install\DARsInternal.
The dars.txt located at %DM_HOME%\dba\config\db91\ provides the
installation completion status information of all the internal DAR files.

2. Navigate to %Documentum%\<supported-WildFly-version-folder>\server\
DctmServer_MethodServer\deployments\ServerApps.ear\APP-INF\
classes. This location contains the following sample properties files:

• sample_configuration_Documentum.yml
• sample_eas_documentum.extractor.properties
• sample_connection.properties

3. Take a copy of the sample_configuration_Documentum.yml file and rename

the file as configuration_Documentum.yml.

4. Open the configuration_Documentum.yml file and provide the appropriate

values for the variables as described in the following table:

Category Name Description

tenant name Specifies the name of the
target application. For
example, INFOARCHIVE.
configure The default value is use
existing.
application name Specifies the name of the
source application. For
example, Documentum.
configure The default value is use
existing.
holding name Specifies the name of the
application where the data
that needs to be migrated
exists. For example,
Documentum.
configure The default value is use
existing.

5. Take a copy of the sample_eas_documentum.extractor.properties file and

rename the file as eas_documentum.extractor.properties.

6. Open the eas_documentum.extractor.properties file and provide the

appropriate values for the variables as described in the following table:

540 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 20.2. Setting up Documentum connector

Name Description
docbase Specifies the name of the Documentum
repository. The rest of the Documentum
connection parameters must be specified
in dfc.properties available in the
CLASSPATH variable.
producer Specifies the application that generates the
SIP.
password Specifies the password to log in to the
Documentum repository. InfoArchive 4.3
Documentum Connector Guide contains
more information about password
protection and encrypted password.
By default, applications running on the
Documentum Server host are allowed to
make repository connections as the
installation owner without a password.
This is called a trusted login.
If you use the installation owner account,
and run the connector on your
Documentum Server host, leave this field
blank.
sipXslt Specifies the path to an XSL file to be
applied to each SIP file.
pdicontentschema Specifies the content schema that is
written to Pentaho Data Integration (PDI)
files.
extractTypes Specifies the object type information that
must be extracted.
If the objects belong to multiple object
types (a subtype with its supertypes; for
example, dm_document and
dm_sysobject), all these types are
extracted.
When extracted, the object type
information is stored in the types element
in element in eas_pdi.xml as part of the
generated SIP.
The default value is true.
username Specifies the user name to log in to the
Documentum repository.
holding Specifies the name of the application
where the data that needs to be migrated
exists. For example, Documentum.
sipXsd Specifies the XSD file for verifying each of
the generated SIP file.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 541

Chapter 20 InfoArchive Integration with Documentum

Name Description
workingdir Specifies the complete path of the working
directory in which to generate SIPs. If the
directory does not exist, the utility creates
it when executed. For example:
workingdir=C:\\Documentum\\IA

Note: Use the double backward

slashes (\\) as the delimiter in the
path.
xsdFileValidation Specify the path of XSD schema file, for
example /Path/DctmDocbase.xsd
(default schema) as the schema (.xsd) file
against which the PDI file generated by
the utility is validated.
Validation is not done if you do not set a
value for this parameter. If you use the
XSL transformation to transform PDI files
to your own schema, you can specify this
schema to validate the result of the XSL
transformation.
maxCiSizePerSip Specifies the maximum size in bytes for
content files per SIP.
checksum_algorithm Specifies the algorithm for calculating the
hash value. The valid algorithms are MD5,
SHA-1, or SHA-256. The default value is
SHA-1.
application Specifies the Documentum application
that contains the data to be migrated and
archived.
archiveId Specifies a string that is used to generate a
unique archive ID for each SIP. This string
may contain a pattern that is a
combination of static text, date value
pattern, and UUID part for generating ID.
In the pattern, a DateTime value is applied
and it uses the same date/time format as it
is specified in the java.lang.String#
format in the Java method. Oracle
Documentation contains more information.

542 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 20.2. Setting up Documentum connector

Name Description
extractRelations Specifies the relationship (represented by
dm_relation_type and dm_relation
objects) information associated with
selected objects, that must be extracted.
Specifies to extract information of
relationship (represented by
dm_relation_type and dm_relation
objects) associated with the selected
objects. When extracted, relationship
information is stored in the relations
element in eas_pdi.xml as part of the
generated SIP. The default value is true.
entity Specifies the application name that holds
the migrated and archived data.
extractContents Specifies the information about the content
files associated with the selected objects,
that must be extracted. When extracted,
the content file information is stored in the
contents element in eas_pdi.xml as
part of the generated SIP. The default
value is true.
sipschema Specifies the SIP schema that is written to
the SIP descriptor file.
pdischema Specifies the PDI schema that is written to
the SIP files.
maxObjectsPerSip Specifies the maximum number of objects
in a SIP.
dqlPredicate Specifies the partial DQL query string
after the FROM clause. The string you
specify here is automatically appended to
the preset string "select r_object_id
from" to form the complete DQL query
statement when you execute the utility.
For example, if you set dqlPredicate as
follows:
dm_document where object_name like
'ABCD1%'

The complete DQL query statement that is

constructed and executed is:
select * from dm_document where
object_name like 'ABCD1%'

Only objects retuned by the query

statement are extracted for archiving.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 543

Chapter 20 InfoArchive Integration with Documentum

Name Description
enableLargeXMLprocessing (Optional) Specifies that large XML files
must be processed. If you set the value to
true, it splits the large XML files in to
chunks. The default value is false.
maxTablesPerSIP Specifies the maximum number of
registered table objects per SIP.
xslt Specifies the path to the XSLT file.
includePDIHashInSIP Specifies that a hash value of each PDI file
is written to a SIP when set to true.
extractFolders Specifies that the information about the
folder (and from all the parent folders of
the folder, if any) of the selected objects,
must be extracted. When extracted, the
folder information is nested in the folders
element in eas_pdi.xml as part of the
generated SIP. The default value is false.
extractACLs Specifies that ACLs must be extracted. The
default value is false.
priority Specifies the ingestion priority of the SIP.
The greater the value, the higher the
priority.
The order in which SIPs are ingested is
determined first by ingestion priority
(higher-priority SIPs are ingested first, and
then by ingestion deadline date (SIPs with
earlier deadlines are ingested first).
extractContainments Specifies the virtual documents must be
extracted. The default value is true.
registeredTables Specifies the DQL query parts after the
FROM clause related to the registered
tables that must be extracted.
shouldDeleteDCTMObjects Specifies if the objects or data that is
migrated and archived in InfoArchive
must be deleted. The default value is
false.
isDebugModeEnabled Specifies if the debug mode is enabled.
The default value is true and it retains
the ZIP file that contains the SIP file
contents in the working directory. If you
do want to retain the ZIP file that contains
the SIP file contents, set the value to
false.

7. Take a copy of the sample_connection.properties file and rename the file as

connection.properties.

544 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 20.3. Running archive job using Documentum Administrator

8. Open the connection.properties file and provide the appropriate values for
the variables as described in the following table:

Name Description
ia.server.uri Specifies the URL of InfoArchive services.
ia.server.authentication.gateway Specifies the IP address of the
authentication gateway.
ia.server.authentication.user Specifies the email ID of the user that must
be authenticated.
ia.server.authentication. Specifies the password of the user that
password must be used for authentication.
ia.server.client_id Specifies the client ID.
ia.server.client_secret Specifies the encrypted information of the
client.

20.3 Running archive job using Documentum

Administrator
Log in to Documentum Administrator and perform the following steps:

1. Create a job.

2. Assign the dm_InfoArchive_Java method to the job.

3. Select the pass standard argument option.

4. Run the job.

5. Check the server.log file of Method Server for information about logs.

Documentum Administrator User Guide contains the detailed information.

The job migrates and archives the Documentum application data to InfoArchive.

Note: If you want to run the jobs in parallel, perform the following steps:

1. Create another copy of eas_documentum.extractor.properties and

provide a unique name.

2. Provide appropriate values for all variables.

3. Log in to Documentum Administrator, create a job and then assign the

dm_InfoArchive_Java method to the job (ensure that the pass standard
argument option is selected).

4. Assign the argument using the -filename <name of the new properties
file> command.

5. Run the job.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 545

Chapter 20 InfoArchive Integration with Documentum

20.4 Cleaning archived objects

All archived objects have the iaaspect aspect attached to them. This aspect also
contains attributes to identify the InfoArchive server where the content is archived,
the user, and the time of ingestion and so on. You can write a new job or method to
search and clean the archived objects, as applicable.

546 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 21
Content Delivery

21.1 Content delivery services

Documentum Interactive Delivery Services (IDS) and Documentum Interactive
Delivery Services Accelerated (IDSx) enable publishing and delivery of content
directly from a repository to a website. Any content can be published and updated
as documents are revised in the repository. Document versions and formats to
publish can also be specified. Publication can occur on demand or automatically on a
schedule.

IDS and IDSx offer the following capabilities:

• Replication of content and metadata that is published on an IDSx staging target

to multiple replication targets. The replication process can occur through
Documentum Server jobs or on demand.
• Bi-directional content delivery (publish/replicate) to a target and pulling content
back to the repository. This process is known as Ingestion.

For publishing, IDSx must be installed on the computer where the repository is
hosted (the source machine) and on the website host (the target machine). For
replication, the IDSx target software must be installed on all the replication targets.
IDSx uses accelerated data transfer technology for faster file transfer.

Documentum Interactive Delivery Services Accelerated Installation Guide and

Documentum Interactive Delivery Services Accelerated User Guide provides additional
information about Interactive Delivery Services Accelerated (IDSx).

Documentum Interactive Delivery Services Installation Guide and Documentum Interactive

Delivery Services User Guide provides additional information about Interactive
Delivery Services (IDS).

21.2 Locating content delivery configurations

You can locate the correct content delivery configuration.

Table 21-1: Content delivery configuration information

Label Information
Initial Publishing Date The date documents were first published
using this configuration.
Refresh Date The date of the last successful full refresh of
the content delivery configuration.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 547

Chapter 21 Content Delivery

Label Information
Last Increment Date The date of the last successful incremental
publish event for the content delivery
configuration.
Increment Count The number of successful incremental
updates since the initial publish operation or
last full refresh.
Publishing Status Indicates whether the last publishing event
succeeded or failed.
Event Number Unique number generated internally for each
publishing operation.

Documentum Administrator User Guide contains the instructions on locating content

delivery configurations.

21.3 Creating or modifying content delivery

configurations
You can create content delivery configurations. You must have superuser privileges
to create or modify a content delivery configuration. The user authentication is
mandatory in IDSx. All fields required for publishing are on the Info tab of the
Content Delivery Configuration page.

Table 21-2: Content delivery properties

Field label Value

Info
State Select Active to indicate using this content
delivery configuration is active. The default
state is Active.

Select Inactive to deactivate the

configuration.
Configuration Name Identifies the publishing configuration. The
name appears in the list of existing
configurations and the name of log files
applying to the configuration.
Publishing Folder The root repository folder from which you
are publishing. The root folder and all
subfolders are published.

If you change this setting after the initial

publication, you must re-publish the
configuration using the Full Refresh option.

548 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.3. Creating or modifying content delivery configurations

Field label Value

Version Defines which version of the document to
publish. If unspecified, the default is the
CURRENT version.

If you change this setting after you publish

the configuration initially, you must
republish the configuration using the Full
Refresh option. If you specify a symbolic
label, the case must match the label case in
the repository. To allow documents with
different version labels to be published,
specify ANY VERSION.
Target Host Name Identifies the target host machine to which
documents are published. This is the target
host, a host where the Interactive Delivery
Services (IDS) target software is installed.
Target Port The port number of the host machine of
website to use for connections. This must be
the port designated when the target software
was installed.
Target UDP Port Type the UDP port on the target host which
is used for accelerated file transfer. Use
unique UDP port for each IDSx
configurations, irrespective of using the same
or a different IDSx target.

Note: The Target UDP Port option is available

only in IDSx.
Connection Type Can be Secure or Non-secure. This is the
type of connection used for connections from
the source host to the target host. The default
is Secure.
Target Root Directory The physical directory on the target host
where the transfer agent places the export
data set for publication. Also known as the
webroot.

If you change this setting after the initial

publishing event for the configuration, you
must re-publish the configuration using the
Full Refresh option.

CAUTION: During initial publication or a

full refresh, the contents of the target root
directory are deleted. Ensure that you
designate the correct directory as the target
root directory.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 549

Chapter 21 Content Delivery

Documentum Administrator User Guide contains the instructions on creating or

modifying content delivery configurations.

21.4 Configuring the advanced properties of a content

delivery configuration
Use the properties described in theAdvanced properties for content delivery table to
configure the advanced properties of a content delivery configuration.

Table 21-3: Advanced properties for content delivery

Field label Value

Property Export Settings
Add properties as HTML Meta Tags If selected, the system inserts document
properties into HTML content files as META
tags on the target host.

If this setting changes after the initial

publishing event for the configuration,
republish using the Full Refresh option.
Export Properties If selected, the system exports a default set of
properties for each published document.

If this setting changes after the initial

publishing event for the configuration,
republish using the Full Refresh option.
Include contentless properties If selected, documents in the publishing
folder that without an associated content file
are published. Only the properties associated
with the contentless document are published.

By default, this option is not selected and is

enabled only if Export Properties is also
selected.
Include folder properties If selected, folder properties are published to
the website. This option is enabled only if
Include contentless properties is also
selected.

550 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.4. Configuring the advanced properties of a content delivery configuration

Field label Value

Additional Properties Identifies additional properties to export to
repository on target host. If Export
Properties is selected, IDS exports a set of
default properties for each published
document.

If this setting changes after initial publishing

event for the configuration, republish using
the Full Refresh option.

Click Select Attributes to identify additional

properties to export.
Property Table Name The name to use when creating the database
tables on the target host. Specify a table name
if Export Properties is selected. The table
name must not exceed 28 bytes.

If this setting changes after initially

publishing the configuration, republish the
configuration using the Full Refresh option.
Content Selection Settings
Formats The content formats to publish. If specified,
only documents with the listed formats are
published. If unspecified, all formats are
published.

If this setting changes after publishing the

configuration initially, republish the
configuration using the Full Refresh option.
Effective Label This field is used in conjunction with the
a_effective_label document property to filter
documents for publication. If Effective Label
is specified, only documents with a matching
a_effective_label value are examined as
possible candidates for publication. If
unspecified, all documents are examined as
possible candidates.

If this setting changes after initially

publishing the configuration, you must
republish the configuration using the Full
Refresh option.
Miscellaneous Settings

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 551

Chapter 21 Content Delivery

Field label Value

Export Directory The name of the local directory on the
Documentum Server host where documents
are placed after they are exported from the
repository.

The default is a subdirectory of

$DOCUMENTUM/share/temp. When
executing a publishing operation, the
directory $DOCUMENTUM/share/temp/
web_publish is created.

On Windows, the length of the repository

path to an object to publish, plus the length
of the object name, plus the length of the
export directory on the Documentum Server
host is limited to 255 characters. There is no
length limitation on Linux.
Ingest Directory The name of the directory on the source
where the documents are placed after being
pulled from the target directory. The default
is a subdirectory of $DOCUMENTUM/share/
temp. You can choose a different directory
by clicking Select Directory.
Trace Level Defines a tracing level for IDS operations.
The trace levels correspond to the trace levels
available using the Trace API methods. The
default value is 0.
Global Publishing Enabled Enables the global publishing feature of Web
Publisher. Replaces the global_publishing
extra argument that was added manually to
the content delivery configuration in prior
versions.

552 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.4. Configuring the advanced properties of a content delivery configuration

Field label Value

Website Locale Web Publisher only. Replaces the
global_locales extra argument that was
added manually to the content delivery
configuration in prior versions.
Select a locale from the drop-down list. If
using Web Publisher and a document exists
in more than one translation in the
publishing folder, the locale code indicates
which translation to publish and also points
to the Web Publisher rules that define the
second and subsequent choices of translation
to publish.

The drop-down list contains choices only

when you are using Web Publisher and the
publishing folder is configured for
multilingual use.

If you do not use Web Publisher or if your

publishing folder is not configured for
multilingual publishing, the drop-down list
does not appear.
Web Server URL Prefix This is the URL to the target root directory
and is required if using Web Publisher.

For example, if the target root directory is d:

\inetpub\wwwroot\webcache and the
website host is on a computer host_name, set
the Web Server URL Prefix to http://
host_name/webcache.

Note: Web Server URL Prefix is not applicable

to replication targets.
Synchronization Settings
Transfer is to live website If selected, Interactive Delivery Services
attempts to minimize user interruptions
during publishing. Leave cleared if users do
not have access to the site during publishing
operations.

If this setting changes after initial

publication, republish the configuration
using the Full Refresh option.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 553

Chapter 21 Content Delivery

Field label Value

Online Synchronization Directory The directory on the target host to be used as
temporary storage for the backup copy of the
Interactive Delivery Services repository
during online updates. This must be
specified if Transfer is to live website is
selected.

If this setting changes after you publish the

configuration initially, republish the
configuration using the Full Refresh option.
Pre-Synch Script on Target The name of a script, located in the product/
bin directory of target host, to run before
publishing takes place. If online
synchronization is enabled, the script runs
before online synchronization occurs. There
is a 48-character limit for information typed
into this field.
Post-Synch Script on Target The name of a script located in the product/
bin directory of target host to be run after
publishing occurs. If online synchronization
is enabled, the script runs after online
synchronization takes place. There is a 48-
character limit for information typed into
this field.
Ingest Settings
Ingest Select this option if you want to ingest
content from the target to the repository.
Target Ingest Directory Enter the directory path of the target from
where the content will be ingested.
Transfer Authentication Settings
Enable system authentication on target Select to require a transfer username and
password for authentication. Not selected
means the transfer username and password
are not required for authentication before a
data transfer occurs.
User Name Identifies the user whose account will be
used by the transfer agent to connect to the
target host.
Password The password for the user specified in User
Name.
Confirm Password Enter the password again for confirmation.
Domain Identifies the domain of the user specified in
User Name.

554 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.5. Configuring replication properties for a content delivery configuration

21.5 Configuring replication properties for a content

delivery configuration
Use the properties described in thecontent delivery replication properties table to
configure replication properties for a content delivery configuration.

Table 21-4: Content delivery replication properties

Field label Value

Replication Target Host Settings
State You can select one of the following states:
• Active in-transaction: Select this option if
you want a replication target to
participate in a transactional replication.
This is the default value.
• Active not-in-transaction: Select this
option if you want the replication target
to participate in a non transactional
replication.
• Inactive: Select this option if you want a
replication target to go for system
maintenance or out of commission.
Target Host Name Identifies the target host machine to which
documents are published. This is the
replication target host, a host where the
Interactive Delivery Services Accelerated
(IDSx) target software is installed.
Target Port The port number of the host machine of
website to use for connections. This must be
the port designated when the replication
target software was installed.
Target UDP Port The UDP port on the target host which is
used for accelerated file transfer. Unique
UDP port has to be used for every IDSx
configurations, irrespective of using the same
or different IDSx targets.
Connection Type May be Secure or Non-secure. This is the
type of connection used for connections from
the source host to the target host. The default
is Secure.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 555

Chapter 21 Content Delivery

Field label Value

Target Root Directory The physical directory on the target host
where the transfer agent places the export
data set for publication. Also known as the
webroot.

If you change this setting after the initial

publishing event for the configuration, you
must replicate the configuration again in
order to synchronize the target root
directory.
Export Properties You can select this checkbox to export
properties to the replication target.
Property Table Name Type the target host property table name,
which is required if you selected Export
Properties.
Ingest Select this option if you want to ingest
content from the replication target to the
repository.
Target Ingest Directory Enter the directory path of the source where
the content will be stored.
Transfer Authentication Settings
User Name Enter the user name for the data transfer.
Password Enter the password for the data transfer.
Domain If the target host is on windows, optionally
type in a domain where the transfer user
exists. If you type in a domain, it overrides
domain information provided on the target
host during installation.
addReplicationTarget Adds multiple replication targets.

21.6 Configuring extra arguments for a content

delivery configuration
You can configure extra arguments for a content delivery configuration using the
properties described in the extra arguments table.

556 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.6. Configuring extra arguments for a content delivery configuration

Table 21-5: Extra arguments

Key Description Default Value(s)

use_docbase_formats Determines whether the TRUE
default file format extensions
set in the repository are used
when files are published.

FALSE overrides the default

file format extensions set in
the repository. TRUE or no
setting uses the extensions
set in the repository format
objects.
use_text_file_extensions When set to TRUE, text files FALSE
that do not have a .txt
extension in the object name
are published with the .txt
extension. For example, if a
text file MyFile is published
and the parameter is set to
TRUE, the file is published as
MyFile.txt. If the parameter is
set to FALSE, the default
value, the file is published as
MyFile.
agent_connection_timeout The timeout interval in 120
seconds for the IDS publish
method connection to the
target host. For example, to
wait 90 seconds:
agent_connection_timeout=90

If the publishing operation

takes longer, Documentum
Administrator displays an
error message and the
publishing log files record
that the publishing operation
failed.
connect_thread_timeout The timeout interval in 30
seconds for the end-to-end
tester connection to the target
host. For example, to wait 90
seconds:
connect_thread_timeout=90

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 557

Chapter 21 Content Delivery

Key Description Default Value(s)

lock_sleep_interval The number of seconds for 10
which IDS waits for a webc
lock object to be unlocked.
For example, to wait 90
seconds:
lock_sleep_interval=90

lock_retry_count How many times IDS checks 30

whether the webc lock object
is unlocked. The value of this
key multiplied by the value
of lock_sleep_interval
controls the total amount of
time for which IDS waits to
lock a configuration with a
lock object.

Since the default

lock_sleep_interval value is
10 seconds, IDS retries for a
total of 300 seconds (5
minutes) by default.
disable_dctm_tag Whether you want the TRUE
Documentum META tag to
appear when you use META
tag merging.
trace_passwords Whether passwords appear FALSE
in debug tracing output.
FALSE causes passwords to
be omitted from debug
tracing output. TRUE causes
passwords to be included in
debug tracing output.
error_threshold The number of errors 0
allowable on the source side
during a single full-refresh,
incremental, or force-refresh
publishing operation.
max_cached_ssl_sockets The number of cached SLL 30
sockets between source and
all targets that are retained
for reuse. Does not restrict
the maximum number of SLL
sockets that can be open at
one time. Used only in the
scs_admin_config object in
the IDS Administration sub-
node.

558 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.6. Configuring extra arguments for a content delivery configuration

Key Description Default Value(s)

publish_contentless Whether documents can be FALSE
_documents published that do not have
associated content files.
TRUE causes publication of
documents without
associated content files.
FALSE causes documents
without associated content
files not to be published.

Note: This option can

also be selected on the
Advanced tab of the
content delivery
configuration.
publish_folder_properties Whether folder properties FALSE
can be published. TRUE
causes folder properties to be
published. FALSE causes
folder properties not to be
published. If set to TRUE,
requires that
publish_contentless_docume
nts is also set to TRUE.

Note: This option can

also be selected on the
Advanced tab of the
content delivery
configuration.
compression Whether file compression is TRUE
enabled. TRUE causes files to
be compressed. FALSE
disables file compression.
min_size_worth The threshold in bytes 5000
_compressing beneath which compression
of a particular file does not
yield performance gains
max_entries_per_zipfile The number of files whose 128
size is below
min_size_worth_compressin
g that are collected in a zip
file for transfer to the target
host.
extensions_to_compress The file types to compress, by html, jhtml, shtml, phtml,
file extension. xhtml, htm, jht,
sht, asp, jsp, xml, css, txt

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 559

Chapter 21 Content Delivery

Key Description Default Value(s)

publish_source_version_label When set to TRUE, all values FALSE
s of the r_version_label
attribute are published to the
repeating attribute table.
mssql_store_varchar SQL Server database only. FALSE
When set to TRUE, string
attributes are stored in the
source catalog database and
target database as varchar
rather than nvarchar.

When set to true, you cannot

publish multibyte data.
store_log Whether to store log files in TRUE
the repository. Valid values
are:
• TRUE: The logs are stored
in the repository.
• FALSE: The logs are not
stored in the repository.

The log is not stored in the

repository for a single-item
publishing operation when
method_trace_level is set to
0.
store_log_file Determines whether
publishing logs are deleted
or retained on the source
host. If the key is set to
TRUE, publishing logs are
preserved. If the key is set to
FALSE, the trace level is less
than 10; if the publishing
operation succeeds, the log
files are deleted.
method_trace_level The level of tracing output. 0 0
is the lowest level of tracing
and 10 is the highest level of
tracing.

Note: To get
LDAPSync debug
information, use
method_trace_level 8.
To get verbose debug
information, use
method_trace_level 10.

560 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.6. Configuring extra arguments for a content delivery configuration

Key Description Default Value(s)

export_threshold_count Indicates the number of items 100
the export operation exports
at one time.
use_format_extensions Use with format key to check FALSE
for valid format extensions.

If use_format_extensions is
set to FALSE, files are
published with the format
extensions defined in the
repository for the format.

If use_format extensions is
set to TRUE and a particular
extension is defined as valid
for a particular format, files
of that format with that
extension are published with
the extension.

If use_format_extensions is
set to TRUE and a particular
extension is not defined as
valid for a particular format,
files of that format with that
extension are published with
the format extensions defined
in the repository for the
format.
format Use with
use_format_extensions key.
Takes the format:

format.format_name=semicol
on-separated_extensions
force_serialized When set to TRUE, single- FALSE
item publishes are performed
serially rather than in
parallel.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 561

Chapter 21 Content Delivery

Key Description Default Value(s)

source_attrs_only By default, on each publish FALSE
IDS creates a properties.xml
file, which contains allthe
attributes of the objects
published. If
source_attrs_only is set, IDS
writes only the default
attributes and any additional
attributes that are published
to the XML file.
• r_object_id
• r_modified_date
• object_name
• i_chronicle_id
• r_version_label
• content_id
• i_full_format
• r_folder_path

additional_metatag_file_exts Allows exported attributes to No default value.

be added as metatags to file
formats with the extensions
asp, jsp, jht, and sht. Add
them as a semicolon-
separated list:
additional_metatag_extension
s=asp;jsp;jht;sht

export_relations When set to TRUE and FALSE

attributes are published,
relation objects (dm_relation
objects) are published to a
database table on the target.
clean_repeating_table_no_att Deprecated.
rs
export_media_properties When set to true, attributes of FALSE
the dmr_content object and
dm_format object are
exported and published to
the target.

562 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.6. Configuring extra arguments for a content delivery configuration

Key Description Default Value(s)

additional_media_properties When FALSE
export_media_properties is
set to true, used to specify
additional attributes of
dmr_content and dm_format
objects to be published. The
format is a semicolon-
separated list:
additional_media_properties=
<type1.attribute1;type2.attr
ibute2>

For example:
additional_media_properties=
dmr_content.x_range;dmr_cont
ent.z_range

exclude_folders A semicolon-separated list of

absolute repository paths,
indicates the folders to be
excluded from a publishing
operation. When set, content
files and attributes from
folders indicated are not
published. For example:
exclude_folders=/acme.com/
images;/acme.com/subdir

pre_webroot_switch_script A script to be run before

online synchronization takes
place. Documentum Interactive
Delivery Services User Guide
contains more information.
post_webroot_switch_script A script to be run after online
synchronization takes place.
Documentum Interactive
Delivery Services User Guide
contains more information.
full_refresh_backup When set to TRUE, the FALSE
content files and database
tables on the target host are
backed up before the
synchronization phase in a
full-refresh publishing
operation.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 563

Chapter 21 Content Delivery

Key Description Default Value(s)

exclude_formats Takes a semicolon-separated Not set
list of format extensions and
excludes content files with
those extensions from
publishing. For example to
exclude .xml and .wml files:
exclude_formats=xml;wml

check_valid_filename If this parameter is set to TRUE (Windows only);

TRUE, then the filename is FALSE for all other O/S
checked for Windows illegal
characters. Illegal characters
are replaced as specified by
the filename_replace_char
parameter.

The default value of

check_valid_filename is
TRUE if the IDS source is on
Windows; the default is set to
FALSE for all other operating
systems. This parameter
should be used if the target is
on a Windows host and the
source is not on Windows.
filename_replace_char Windows only. Used in _ (underscore)
conjunction with
check_valid_filename.
Defines the character to use
to replace invalid characters
in file names on Windows.
For example:
filename_replace_char=0

sync_on_zero_updates When set to TRUE, database FALSE

updates are made and pre-
and post-synch scripts are
run even if there is no new
data to publish from the
repository.
transform_type Used with Web Publisher absolute
Page Builder only.

Determines whether links in

HTML pages are resolved at
publication time to absolute
or relative paths. Valid
values are absolute and
relative.

564 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.6. Configuring extra arguments for a content delivery configuration

Key Description Default Value(s)

recovery_publish_retry_coun Controls the number of times
t IDSx tries to recover from a
failed incremental publishing
operation. The value is an
integer that represents the
number of times IDSx retries
the publishing operation.
set_tcp_delay Determines TCP protocol FALSE
behavior. With the default
setting of FALSE, packets are
sent to the target as soon as
they are written on the
source side; IDSx does not
wait until the sockets buffer
is filled or there is a timeout.
For debugging purposes, this
parameter can be set to
TRUE. The setting must
match the same key in
agent.ini.
ingest_workflow Used with Content Delivery
web service only. Specifies a
custom workflow to be used
with the ingest operation.
Documentum Enterprise
Content Services Reference
Guide contains the details on
this web service.

Note: This argument

can be set at the
repository (IDS
Administration) level
only. You cannot
specify different ingest
workflows for
individual content
delivery
configurations.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 565

Chapter 21 Content Delivery

Key Description Default Value(s)

wan_acceleration_ssh_port This is the TCP Port required 22
for accelerated data transfer
authentication. If the SSH
port has to be changed, check
the SSH service configuration
(sshd_config) for windows
for changing the default port.

The default value is

applicable to all publishing
configurations and can be
overridden for each
publishing configuration, by
setting this as an extra
argument for publishing.
wan_acceleration_disabled This parameter is used to False
disable the accelerated data
transfer and use HTTP for
file transfer.

566 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.6. Configuring extra arguments for a content delivery configuration

Key Description Default Value(s)

wan_acceleration_policy This parameter defines the A
policy used for accelerated
data transfer.
• ADAPTIVE/FAIR (A):
When set to this value,
the file transfer monitors
and adjusts the transfer
rate to fully utilize the
available bandwidth to
the maximum limit. When
there is congestion due to
other file transfers, this
mode shares bandwidth
for other flows and
utilizes a fair rate of
transfer. In this mode,
both the maximum and
minimum transfer rates
are required.
• FIXED (F): When set to
this value, the file transfer
happens at a specified
target rate, irrespective of
the actual network
capacity. In this mode, a
maximum transfer rate is
required.
• TRICKLE/STEALTH (T):
When set to this value,
the file transfer uses the
available bandwidth to
the maximum rate. When
there is congestion due to
other file transfers, the
transfer rate is reduced
down to the minimum
rate.
min_file_transfer_rate This is the minimum file 0 Mbps
transfer rate
max_file_transfer_rate This is the maximum file 1000 Mbps
transfer rate
wan_acceleration_log_details The file transfer process FALSE
status are captured in the
content delivery log files

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 567

Chapter 21 Content Delivery

Key Description Default Value(s)

wan_acceleration_file_checks This parameter is used to OFF
um resume file transfer when
there is a failure.
• FILE_ATTRIBUTES:
When set to this value,
checks for the file size of
both files. If the file size is
the same, then transfer
does not take place.
• FULL_CHECKSUM:
When set to this value,
checks for the checksum
of both files. If it matches,
then transfer does not
take place
• SPARSE_CHECKSUM:
When set to this value,
checks for the sparse
checksum of both files. If
it matches, then transfer
does not take place
• OFF: When set to this
value, the file gets
replaced
When set to OFF, the rate
of file transfer is high.

568 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.6. Configuring extra arguments for a content delivery configuration

Key Description Default Value(s)

decision_commit_rollback This parameter is used to set NA
the threshold value for
transaction capability. For
example, if there are 10
replication targets, and if the
DCR value reads as:
decision_commit_rollback 6

implies that if replication

operation succeeds on a
minimum of 6 replication
targets, then a decision is
taken to commit (File System
and RDBMS) the changes
performed by the replication
operation.

If the number_of_failures value

is greater than the
decision_commit_rollback
value, a rollback is initiated
on the replication targets.

The value assigned to this

attribute must be a positive
integer.
tc_file_count The transaction capability is 500
based on tc_file_size and
tc_file_count.

When the number of files

replicated exceeds
tc_file_count, transaction
capability feature is disabled.

The value assigned to this

attribute must be a positive
integer.
tc_file_size The transaction capability is 100 MB
based on tc_file_size and
tc_file_count.

When the size of the files

replicated exceeds tc_file_size,
transaction capability feature
is disabled. The units is
specified in MB.

The value assigned to this

attribute must be a positive
integer.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 569

Chapter 21 Content Delivery

Key Description Default Value(s)

use_replication_time Use this extra argument to TRUE
ensure that after replication
is complete, all the
replication targets will
display the same time stamp
as when the replication was
triggered.
use_repository_time Use this extra argument to TRUE
ensure that after replication
is complete, all the
replication targets will
display the same time stamp
as when the content was last
modified in the repository
(r_modified_date when the
file was replicated).
lock_exitifbusy_flag During publishing or TRUE
replication operations, IDSx
locks a configuration using a
webc lock object, so that only
one publishing or replication
operation can take place at a
time for that configuration. If
you want IDSx to exit rather
than retry when the
publishing configuration is
locked, set the
lock_exitifbusy_flag
argument to TRUE.

570 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.6. Configuring extra arguments for a content delivery configuration

Key Description Default Value(s)

auto_replication Replication can be invoked TRUE
automatically after a
publishing operation by
setting the extra argument
auto_replication to TRUE in
Documentum Administrator.

Note: Concurrent
single item publishing
at the same time as
auto replication causes
a considerable load on
the staging target.
Hence, set the extra
argument
lock_exitifbusy_flag
along with
auto_replication to
TRUE. The subsequent
replication process will
consider all the
published batches that
were left unused
during the creation of
the previous
replication batch.
full_refresh_transactional_re The replication process can FALSE
plication start a transactional
replication, even when the
replication batch being
replicated contains a full
refresh publish. Replication
Manager can be enhanced to
start a transactional
replication setting the extra
arguments,
full_refresh_transactional_re
plication and
full_refresh_backup, to TRUE
for full refresh publish.
post_replication_script_on_st Use this script to perform any No default value.
aging_target arbitrary action on the
staging target after
replication is complete on all
replication targets.

Documentum Administrator User Guide contains the instructions on creating or

modifying extra arguments.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 571

Chapter 21 Content Delivery

21.7 Deleting content delivery configurations

If a content delivery configuration is no longer needed, you can delete it. To stop
publishing using the configuration, make the content delivery configuration
inactive.

Documentum Administrator User Guide contains the instructions on deleting content

delivery configurations.

21.8 Testing content delivery configurations

After creating a content delivery configuration, test it by running the end-to-end
tester, which simulates a publishing operation without publishing any documents.
The end-to-end tester tests all parameters set in a publishing configuration and
ensures that IDS/IDSx can make the necessary connections to the database and target
host.

The end-to-end tester creates a log file in the repository whether the test fails or
succeeds. View the resulting log file after running the tester. If the test fails, examine
the log file to determine which element of your IDS/IDSx installation is not working.
You can read the file from Documentum Administrator or retrieve it directly from
the repository where IDS/IDSx log files are stored in the /System/Sysadmin/Reports/
Webcache folder.

Documentum Administrator User Guide contains the instructions on testing content

delivery configurations.

21.9 Duplicating a content delivery configuration

Create a new content delivery configuration by duplicating and then modifying a
content delivery configuration that is thoroughly tested and successfully used in
production. The IDS Configuration Template stores default values that you can use
to create new content delivery configurations.

Documentum Administrator User Guide contains the instructions on duplicating

content delivery configurations.

21.10 Deactivating a content delivery configuration

To suspend publishing operations without deleting the content delivery
configuration, deactivate it using the instructions in this section.

Documentum Administrator User Guide contains the instructions on deactivating

content delivery configurations.

572 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 21.11. Publishing objects

21.11 Publishing objects

You can manually run a publishing job from the Interactive Delivery Services
Configuration list page.

Documentum Administrator User Guide contains the instructions on the following:

• Publishing from content delivery configurations

• Replicating from content delivery configurations
• Ingesting from content delivery configurations

21.12 Content delivery configuration results

This page indicates whether a publishing or a replication operation succeeded or
failed. For details on the publishing operation, on the content delivery configuration
publish result page, click the links to view the publishing logs. Similarly, for details
on the replication operation, click the links on the content delivery configuration
replicate result page to view the replication logs. After viewing the log, click OK or
Cancel to close the log, then click OK or Cancel to return to the Interactive Delivery
Services Configuration list page.

Interactive Delivery Services version 6x can be configured for email notification of

content delivery configuration results. Documentum Interactive Delivery Services User
Guide and Documentum Interactive Delivery Services Accelerated User Guide documents
contain more information.

21.13 Content delivery logs

Each publishing operation or end-to-end test generates a log file. View these files to
determine whether publishing succeeded and to diagnose problems when a
publishing operation fails. To navigate from the publishing log list page, click the
Content Delivery breadcrumb.

21.13.1 Viewing content delivery logs

Each publishing event or publishing test generates a log file. Review the file after
publishing or testing a content delivery configuration to determine if the operation
succeeded.

Documentum Administrator User Guide contains the instructions on viewing content

delivery logs.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 573

Chapter 21 Content Delivery

21.13.2 Deleting content delivery logs

After you examine logs or as they accumulate in the repository, you may want to
delete them.

Documentum Administrator User Guide contains the instructions on deleting content

delivery logs.

21.14 Effective labels

Use effective labels to enable IDS to determine which documents to publish based on
effective and expiration dates.

The effective label specified in a content delivery configuration allows IDS to

determine when to publish a particular document and when to delete it from the
website. IDS does this by examining the repeating properties a_effective_label,
a_effective_date, and a_expiration_date, which are properties of the dm_sysobject
type. These properties are inherited by all subtypes of dm_sysobject.

Each a_effective_label corresponds to a matching a_effective_date and

a_expiration_date. Because these are repeating properties, you can specify multiple
effective labels, effective dates, and expiration dates for each document. IDS looks
for the effective and expiration dates matching a particular effective label, and uses
the dates to determine when to publish a document and when to withdraw the
document from the website.

For example, a document might have the effective label, effective date, and
expiration date properties set as follows:

Table 21-6: Using effective labels

a_effective_label a_effective_date a_expiration_date

DRAFT 03/05/08 03/15/08
REVIEW 03/16/08 03/26/08
COMMENT 03/27/08 04/10/08
APPROVED 04/10/08 04/10/09

Setting the effective label of document to REVIEW means the document will be
published on March 16, 2008 and removed from the website on March 26, 2008.
Setting the effective label to APPROVED means the document will be published on
April 10, 2008 and withdrawn on April 10, 2009.

Documents whose effective label does not match the effective label set in the content
delivery configuration are published regardless of the values set for effective date
and expiration date.

574 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 22

Indexing Management

22.1 Indexing
A full-text index is an index on the properties and content files associated with
documents or other SysObjects or SysObject subtypes. Full-text indexing enables the
rapid searching and retrieval of text strings within content files and properties.

Full-text indexes are created by software components separate from Documentum

Server. The index agent prepares documents for indexing and Documentum xPlore
creates indexes and responds to queries from Documentum Server. Documentum
xPlore Deployment Guide contains the information on installing the index agent and
xPlore.

You must have system administrator or superuser privileges to start, stop, or disable
index agents, start or stop xPlore, and manage queue items. Documentum xPlore
Administration Guide contains the information on editing the properties of the index
agent configuration object and other full-text configuration objects.

22.2 Index agents and xPlore

The Index Agents and Index Servers list page shows the index agent and index
queue associated with the repository.

The index agent exports documents from a repository and prepares them for
indexing. A particular index agent runs against only one repository. xPlore creates
full-text indexes and responds to full-text queries from Documentum Server.

Note: If you are using Documentum Server with xPlore, by default, sorting on
attribute is performed by the database on results returned from xPlore. To alter
the behavior, add dm_ft_order_by_enabled to dm_docbase_config:
retrieve,c,dm_docbase_config
append,c,l,r_module_name
dm_ft_order_by_enabled
append,c,l,r_module_mode
save,c,l
reinit,c

Ensure that the subpath is configured correctly in indexserverconfig.xml.

For example, set "sortable= true” for subpath “dmftmetadata//
object_name”. Then, using DQL, you can let xPlore to order by attribute
object_name. For example:
select r_object_id from dm_sysobject search document
contains 'john' order by object_name

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 575

Chapter 22 Indexing Management

This is applicable for sorting results supported in xPlore with the appropriate
index configuration.

22.3 Starting and stopping index agents

You can stop a running index agent or start an index agent that is stopped.

An index agent that is disabled cannot be started and is not started automatically
when its ACS server is started. You must enable the index agent before starting it.
The “Enabling index agents” on page 577 section contains the information on
enabling a disabled index agent. If the status of index agent is Not Responding,
examine the machine on which it is installed and ensure that the software is
running.

Caution
Stopping the index agent interrupts full-text indexing operations, including
updates to the index and queries to the index. An index agent that is
stopped does not pick up index queue items or process documents for
indexing.

Note: If the Documentum Server is in a projected to dormant state, then starting

or stopping the index agent works correctly. However, if the Documentum
Server is in a dormant state, then starting or stopping the index agent using
Documentum Administrator does not work correctly. The status of the index
agent appears as Not Responding. The index agent logs contain the following
error: [DM_INDEX_AGENT_UNEXPECTED_DFC_EXCEPTION] Unexpected
DfException: context: Init Connector cause:
[DM_SESSION_E_OP_DISALLOWED_IN_STATE_UNLESS_ENABLED]error:
“The operation (Opening a new transaction) is disallowed when the server is in
Dormant state unless enabled by Data Center Managers on their sessions.”

Documentum Administrator User Guide contains the instructions on starting or

stopping index agents.

22.4 Disabling index agents

An index agent that is disabled cannot be started and is not started automatically
when its ACS server is started. You can disable an index agent only after it has been
stopped. To start a disabled index agent that is not running, you must enable the
index agent first, using the instructions in “Enabling index agents” on page 577.

Documentum Administrator User Guide contains the instructions on disabling index

agents.

576 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 22.5. Enabling index agents

22.5 Enabling index agents

An index agent that is disabled cannot be started (if it is stopped) and is not started
automatically when its ACS server is started. You must first stop the index agent if it
is running.

Documentum Administrator User Guide contains the instructions on enabling index

agents.

22.6 Verifying indexing actions

You are asked to confirm stopping, starting, suspending, resuming, and reindexing
index agents, and enabling or disabling index agents. The confirmation page
displays the action you requested. Click OK to continue with the action or Cancel to
stop the action.

22.7 Viewing or modifying index agent properties

You can view the properties of an index agent. You can modify the following index
agent properties, but it is recommended that you do not change the values:

• Exporter Thread Count

This is the number of concurrent exporter threads run by the index agent. The
default value is 3. If you change the exporter thread count, you must restart the
index agent for the change to take effect.
• Polling Interval
This is the frequency, in seconds, at which the index agent polls for queue items.
The default value is 60.

All other properties are read-only.

Documentum Administrator User Guide contains the instructions on viewing or

modifying index agent properties.

22.8 Managing index queue items

Creating, versioning, or deleting a SysObject or SysObject subtype creates a queue
item indicating that the full-text indexes must be updated to account for the changes.
The index agent reads items from the queue and ensures that the required index
updates take place.

If the indexing system of the repository runs in a high-availability active-active

configuration, with multiple index agents and xPlore installations, each index agent/
xPlore federation pair supports its own index. Creating, versioning, or deleting a
SysObject or SysObject subtype creates a queue item for each pair, and each index is
updated.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 577

Chapter 22 Indexing Management

If the indexing system is in a high-availability active-active configuration, the name

of each index is displayed at the top of this page, and only the queue items for one
index at a time are displayed.

By default, the list page displays failed queue items. To filter the queue items by
status, choose the appropriate status on the drop-down list:

• Indexing Failed, which is the default status displayed

If indexing failed, information about the error is displayed in red under the name
and other properties of queue item.
• All, which displays all current queue items in the repository
• Indexing in Progress, which indicates that the object is being processed by the
index agent or xPlore federation
• Awaiting Indexing, which indicates that the index agent has not yet acquired the
queue item and started the indexing process
• Warning, which indicates that the index agent encountered a problem when it
attempted to start the indexing process for the object
If indexing generated a warning, information about the problem is displayed in
red under the name and other properties of queue item.

Queue items that have failed indexing can be resubmitted individually, or all failed
queue items can be resubmitted with one command. Documentum xPlore
Administration Guide contains the instructions on resubmitting objects for indexing.

22.8.1 Resubmitting individual objects

You can resubmit individual objects for indexing.

Documentum Administrator User Guide contains the instructions on resubmitting

individual objects.

22.8.2 Resubmitting all failed queue items

You can resubmit for indexing all documents that failed indexing. This menu choice
executes the mark_for_retry administration method. If the indexing system is
installed in a high-availability configuration, all failed queue items for all indexes
are resubmitted.

Documentum Administrator User Guide contains the instructions on resubmitting all

failed queue items.

578 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 22.8. Managing index queue items

22.8.3 Removing queue items by status

You can remove index queue items by status.

Documentum Administrator User Guide contains the instructions on removing queue

items by status.

22.8.4 Removing queue items

You can remove queue items from the indexing queue. Note that if a queue item has
already been acquired by the index agent, it cannot be removed from the indexing
queue.

Documentum Administrator User Guide contains the instructions on removing queue

items.

22.8.5 Viewing queue items associated with an object

From the cabinets of a repository, you can view the index queue items associated
with a particular object.

Documentum Administrator User Guide contains the instructions on viewing queue

items associated with an object.

22.8.6 Creating new indexing queue item

You can create a queue item to submit a particular SysObject for indexing.

Documentum Administrator User Guide contains the instructions on creating new

indexing queue item.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 579

Chapter 23
Content Transformation Services Management

A repository can be polled by multiple CTS instances. All CTS instances polling the
repository are displayed in the Content Transformation Services node in
Documentum Administrator.

Documentum Administrator User Guide contains the information on the following:

• Understanding Content Transformation Services overview

• Changing the CTS user
• Configuring a CTS instance
• Viewing a CTS log file
• Viewing details of a CTS instance
• Controlling your CTS instance
• Reporting in Content Transformation Services

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 581

Chapter 24
Content Intelligence Services

Use Content Intelligence Services (CIS) to analyze the textual content of documents
and know what the documents are about without having to read them.

By default, CIS analyzes the content of the documents, including the values of the
file properties. You can change the default behavior and have CIS analyze the values
of the Documentum object attributes in addition to, or instead of, the content of the
documents.

CIS performs several types of analysis:

• Categorization: By detecting predefined keywords in the document content, the

categorization identifies the category to which a document belongs. Categories
for a subject area are organized in a structure called a taxonomy. Categorization
enables you to organize content in a logical and consistent way.
• Entity detection: It relies on Natural Language Processing (NLP). Named entities
are detected by performing a semantic analysis of their context. If there is too
little context, or if the context is unclear, the detection can seem to be incomplete.
You can use entity detection to find named entities such as people names or
company names in documents.
• Pattern detection: Some pieces of information always have the same form. Use the
pattern detection to retrieve this information when it is disseminated in text. For
example, email addresses, because they comply with a standard, can be extracted
using pattern detection. Pattern detection retrieves all pieces of information that
match the pattern.

Documentum Administrator User Guide contains the information and instructions on

the following:

• Understanding Content Intelligence Services in Documentum applications

• Configuring Content Intelligence Services in Documentum Administrator
• Building taxonomies for classic categorization
• Selecting and submitting the documents to analyze
• Managing analysis results

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 583

Chapter 25

Resource Management

25.1 Understanding Resource Management

The Resource Management node provides an interface for viewing and managing
Documentum resources exposed in the Documentum environment as Java
Management Beans (MBeans). Documentum Administrator maintains the list of
resource agents, which includes the information necessary to access a resource
agent. The resource agent information is stored in the ResourceAgentsRegistry in the
global registry.

Users access the MBean resources in the distributed network through a resource
agent (JMX agent) to obtain a list of available MBean resources that they can
manage. The Resource Management node displays a list of the resource agents;
however, only a system administrator can create, delete, or update resource agents.

A resource agent may require authentication to access its resources (MBeans).

Documentum Administrator first attempts to authenticate the user using the current
session login information. If authentication fails, Documentum Administrator
prompts for a user name and password.

25.2 Managing resource agents

Select the Resource Management node (Administration > Resource Management) to
access the Resource Agents list page. The resource agent information is stored in the
ResourceAgentsRegistry in the global registry. If no resource agents are configured
in the global registry, the Resource Agents list page displays a message that no items
were found.

System administrators can add, delete, and edit resource agents. A resource agent
may require authentication to access its resources (MBeans). Documentum
Administrator will first attempt to authenticate the user using the current session
login information. If that fails, then Documentum Administrator prompts for a
username and password.

From the Resource Agents list page, you can:

• Add resource agents.

• Access the Resource Agent Properties - Info page to view or modify resource
agent properties.
• Delete resource agents.
• Access the Resources on Agent list page for a specific resource agent.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 585

Chapter 25 Resource Management

Documentum Administrator User Guide contains the information and instructions on

the following:

• Adding resource agents

• Viewing or modifying resource agent properties
• Deleting resource agents

25.3 Managing resource properties

The Resources on Agent list page displays MBean resources for a selected resource
agent. Select a resource to display the properties of the resource, such as attributes,
operations, notifications, and a log file, if defined.

• The Resource Properties - Info page displays key information about the resource.
The polling interval defines the frequency to poll the resource for activity. This is
not used in the current release.
• The Resource Properties - Attributes page displays the resource attributes.
Writeable attributes provide an input control to update the attribute value.
Attribute changes will be updated on the resource by clicking the Save
Changesor OK button.
• The Resource Properties - Operations page displays the operations that can be
performed. Selecting an operation displays the operations dialog, which enables
you to enter any required data, perform the operation, and view the results (if
the operation has results).
• The Resource Properties - Notifications page displays the resource notifications
you are subscribed to.
• The Resource Properties - Log page enables you to:

– Specify the log level for tracing.

– Specify the log level of messages.
– Specify the number of viewable log file lines.
• The <MBean name> Monitor page displays information for resource types that
have been configured for the server monitor interface.

Documentum Administrator User Guide contains the information and instructions on

the following:

• Managing general information for resources

• Managing resource attributes
• Managing resource operations
• Viewing resource notifications
• Viewing the notification page
• Viewing resource logs

586 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 25.3. Managing resource properties

25.3.1 Monitoring resources

The <MBean name> Monitor page displays information for resource types that have
been configured for the server monitor interface. The monitor interface is available
only for these MBean types:

• AcsServerMonitorMBean
• AcsServerConfigMBean
• JmxUserManagementMBean
• IndexAgent

Documentum Administrator User Guide contains the instructions on monitoring

resources.

25.3.2 Manual configuration steps for monitoring resources

This section details the manual configuration steps for monitoring resources.

To manually configure:

1. The following changes are required in \app\webcomponent\config\admin

\resourcemanagement\resources\mbeanresourceslist_component.xml.
Add the JMXBeans to the <mbeantypes> node list.
<mbeantypes>
<!--name denotes the exact name of MBean-->
<mbeantype name='IndexAgent'>
<!--onclickcomponent specifies the component to be invoked-->
<onclickcomponent>mbeanresourcemonitordialogcontainer</onclickcomponent>
</mbeantype>
</mbeantypes>

2. The following changes are required in \app\webcomponent\config\admin

\resourcemanagement\resources\mbeanresourcemonitor_component.xml.
Add the JMXBeans to the <mbeantypes> node list.
<mbeantypes>
<!--name denotes the exact name of the MBean-->
<mbeantype name='IndexAgent'>
<!--attributes are the list of the attributes that need
to be exposed in the monitor user interface-->
<attributes>
<attribute>Status</attribute>
<attribute>Mode</attribute>
<attribute>...</attribute></attributes>
<!--operations are the list of the operations that need to be exposed
in the monitor user interface. launchcomponent=true will launch the
operations user interface in a new window. Also if the operation
requires user input, then the user interface automatically opens in a
new window-->
<operations>
<operation launchcomponent='false'>Start</operation>
<operation launchcomponent='true'>downloadLogFile</operation>
<operation launchcomponent='true'>...</operation>
</operations>
<!--notifications are the list of notifications, ideally the
empty list will capture all notifications.-->
<notifications></notification></notification></notifications>

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 587

Chapter 25 Resource Management

<!--refreshinterval denotes the interval in miliseconds for the

monitor user interface to be refreshed. Ideal value should be 10sec.-->
<refreshinterval>10000</refreshinterval>
</mbeantype></mbeantypes>

588 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 26
Cabinets, Files, and Virtual Documents

Documentum Administrator User Guide contains the information and instructions on

the following:

• Managing cabinets, folders, and files

• Understanding home cabinets
• Creating cabinets
• Creating folders
• Creating files
• Working with files
• Deleting cabinets, folders, or files
• Moving files
• Copying files
• Viewing the clipboard
• Linking cabinets, folders, or files
• Managing subscriptions
• Enabling change notifications
• Managing relationships
• Understanding renditions and transformations
• Configuring PDF Annotation Services
• Understanding virtual documents

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 589

Chapter 27
API and DQL

27.1 API and DQL

DQL queries and server APIs can be run from Documentum Administrator pages
that contain a Tools menu. The Use the DQL query pages to run DQL queries and to
test whether DQL SELECT statements return the expected values. Use the API pages
to enter methods and to send method calls directly to the server.

27.2 DQL Editor

The Dql Enter Query page enables you to test whether a DQL SELECT statement
returns the expected values. Use this page as a tool for testing DQL.

The number of rows returned by a DQL statement is limited based on the width of
the rows requested. The query results may be truncated. When this happens, a
warning message appears.

1. Select Tools > Dql Editor.

2. Type the query in the text box.
3. To display the SQL statement produced by the query, select Show the SQL.
4. Click Execute.
The query results are returned.

27.3 API Tester

The API Tester page enables you to enter methods directly in the API text field by
typing the method name and its arguments as a continuous string, with commas
separating the parts.

For example, the following command creates a folder:

API> create,s0,dm_folder

Note: Methods entered in the API text field bypass the Documentum
Foundation Classes (DFC) and directly access the Documentum Client
Libraries (DMCL). Therefore, the DFC cannot perform its usual validation of
the methods.

To run server APIs:

1. Select Tools > Api Tester.

The API Tester page is displayed.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 591

Chapter 27 API and DQL

2. Select Single-Line Command Entry or Script (multi-line) Entry.

3. Enter the API.

• If you are in Single-Line mode, enter the command and any necessary data
in the Command and Data text boxes.
• If you are in Script Entry mode, type the method and its arguments in the
Commands text box.

4. To display the SQL statement produced by the query, select Show the SQL.

5. Click Execute.
The results are returned.

592 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 28
Search

28.1 Searches
Documentum Administrator offers different ways to search repositories and external
sources. By default, Documentum Administrator provides a simple search and an
advanced search. If Federated Search Services is installed on the Documentum
Server host, administrators also have the option to create search templates and
configure smart navigation.

Documentum Platform and Platform Extensions Installation Guide contains more

information on installing Federated Search Services.

28.2 Setting search preferences

Search preferences specify the default search locations and enable smart navigation.

Documentum Administrator User Guide contains the instructions on setting search

preferences.

28.3 Search guidelines

In general, the following guidelines apply to searches:

• If a document cannot be indexed, it also cannot be searched. For example,

documents that contain binary content cannot be indexed.
• Only certain characters can be searched, such as alphabetic, numeric, extender,
and custom characters. Custom characters include Chinese, Japanese, Korean
letters, and months.
Other characters, including punctuation, accent, and diacritical marks, and
characters such as | and #, are not indexed or searched. These characters are
removed from the indexed text and are treated as blank spaces. The xPlore
federation treats characters such as !@#$%^_,.&;:()+=< as white space.
• The plus and minus signs cannot be used as operators. You must use the AND
operator, and the OR instead.
• The asterisk, and the question mark can be used as wildcards.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 593

Chapter 28 Search

28.4 Running a simple search

When a user enters a search term (a word or phrase) in the simple search box, the
term is matched to documents or other objects that have the search term within the
document itself or within the properties of object. This kind of search is called a full-
text search.

A full-text search searches the files in default search location that the user is
specified in the search preferences. The search can include several repositories at the
same time and external sources such as external databases, web sources or the
desktop.

When displaying search results, Documentum Administrator displays files with the
most matching words first. If a repository has been indexed for parts of speech,
Documentum Administrator also displays files that include variations of the words.
For example, if a user searches for scanning, Documentum Administrator also looks
for files that contain the words scan, scanned, and scanner.

Documentum Administrator User Guide contains the instructions on running a simple

search.

28.4.1 Further define search terms

You can use the syntax in “Further define search terms” on page 594 to further
define search terms within a simple search or within the Contains field in an
advanced search.

Table 28-1: Further define search terms

Syntax Description
Quotation marks To search for an exact word or phrase, type quotation marks around
around a word or the word or phrase.
phrase: “ ”
For a simple search (including the Contains field in an advanced
search), if you do not use quotation marks, Documentum
Administrator displays files that contain both the exact words you
typed as well as variations of the words, such as scanning for the
word scanner.

This option is disabled when searching for more than one word or if
your repository has not been indexed for variations.

Quotation marks cannot be used to match the exact case of a word.

594 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 28.4. Running a simple search

Syntax Description
The AND and OR To get results that contain two search terms, type AND between the
operators terms. A term can be a word or quoted phrase.

To get results that contain at least one term, type OR between the
words or the quoted phrases.

You can string together multiple terms with the AND and OR
operators. The AND operator has precedence over the OR operator.
For example, if you type:
knowledge or management and discovery

then your results must contain either knowledge or they must

contain management, and discovery.
The NOT operator To get results that do not contain a term, type NOT before this term.
The term can be a word or a quoted phrase. Only the term that
follows the operator is taken into account.

The NOT operator can be used after the AND or OR operator,

separated by a space.

Valid syntaxes would be: Documentum NOT adapter or Documentum

AND NOT adapter, both queries will return results that contain
Documentum but do not contain adapter.

If you type Documentum OR NOT adapter, you get results that either
contain Documentum (and possibly contain adapter) or that do not
contain adapter. Use this syntax cautiously. It can generate a very
large number of results.

The NOT operator can be used alone at the beginning of the query.
For example, if you type NOT adapter, you get results that do not
contain adapter. Use this syntax cautiously. It can generate a very
large number of results.

The NOT operator is not supported for queries on external sources

when it is alone at the beginning of the query or if used with the OR
operator.

The NOT operator cannot be used with parentheses. This is invalid:

A NOT ( B OR C ). However, the NOT operator can be used inside
parentheses. This is valid: (A NOT B) OR (A NOT C).

ANDNOT (in one word) is not an operator, if you enter ANDNOT in

a query, it will be considered as a search term.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 595

Chapter 28 Search

Syntax Description
Parentheses around To specify that certain terms must be processed together, use
terms: ( ) parentheses. When using parenthesis, you must type a space before,
and after each parenthesis mark, as shown here: ( management or
discovery )

As an example, if you type knowledge and management or discovery,

then your results will contain both knowledge, and management or
they will contain discovery. But if you type knowledge and
( management or discovery ), then your results will contain knowledge,
and either management or discovery.
The multiple- If the repository is indexed, you can use the multiple-character
character wildcard: * wildcard to indicate additional characters anywhere in a word. It
matches zero or more characters. The multiple-character wildcard is
only available or a simple search (including the Contains field in an
advanced search).

The multiple-character wildcard is not available for a searches on

non-indexed repositories, for searches of property values, or for
searches of external sources. For those, you should use truncation
operators, such the Begin with operator.

Note: If you use wildcards, then Documentum Administrator will

not display results that include variations of the words you typed.
For example, if you type
d*ment

then your results must contain: document, development,

deployment, department, etc. but not documented or
documentation.
The single-character If the repository is indexed, you can use the single-character
wildcard: ? wildcard to indicate a single, unknown character anywhere in a
word.

The single-character wildcard is only available or a simple search

(including the Contains field in an advanced search).

The single-character wildcard is not available for searches on non-

indexed repositories, for searches of property values, or for searches
of external sources.

Notes

• The operators AND, OR, and NOT are reserved words. To search a term that
includes an operator, use quotation marks. For example, if you search for
“hardware and software”, Documentum Administrator returns documents
with that string of three words. If you type hardware, and software without
quotation marks, Documentum Administrator returns all of the documents
that contain both words.
• The operators AND, OR, and NOT are not case-sensitive. For example, for
your convenience, you can type: AND, and, And.

596 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 28.5. Running an advanced search

28.5 Running an advanced search

To search for a document by one of its properties, use advanced search. An
advanced search enables you to define more precisely your query on the properties
of the document. For example, you can search the current version of the documents
whose author is John Smith, and modified between November 1, 2006 and
December 31, 2006.

Documentum Administrator User Guide contains the instructions on running an

advanced search.

28.6 Search results

Documentum Administrator User Guide contains the information and instructions on
the following:

• Viewing search results

• Using smart navigation feature
• Monitoring search results in real time
• Saving search results from external sources

28.7 Additional configuration options

The search functionality described in this guide refers to the default configuration.
However, your system administrator can configure this functionality in many ways.
This list details possible configurations that can affect your search experience:

• Indexing: Indexing capabilities can be used to define more precise queries. For
example, wildcards can only be used if the repository is indexed, if not, they are
skipped. If you want to run complex queries, consult the system administrator
for details on the indexing configuration of the repository.
• Relevancy ranking: The system administrator can specify a bonus ranking for
specific sources, add weight for a specific property value or improve the score for
a specific format.
• Presets: The system administrator can define a preset to restrict the list of
available types in the Advanced search page. Presets can be different from one
repository to another. If you select only external sources, the preset of the current
repository applies.
• Customization of the Advanced search page: The Advanced search page can be fully
customized to guide you in running queries. For this reason, all the options
described in this guide may not be available, and other may appear to narrow
and/or condition your queries.
• Maximum number of results: The maximum number of results is defined at two
levels. By default, the maximum number of results, taking all sources together, is
1000 and 350 results per source. However, your system administrator can modify

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 597

Chapter 28 Search

these parameters. When querying an external source, the maximum number of

results also depends on the configuration set for this source. Results are selected
according to their ranking. This way, you always get results with the best
ranking; other results are skipped.
• Case-sensitivity: If the repository is indexed, queries are case-insensitive by
default, even using quotation marks. If the repository is not indexed, then
queries are case-sensitive. However, for non-indexed repositories, case-
sensitivity can be turned on, and off by the system administrator.
• Grammatical normalization (lemmatization): When you do not use quotation marks,
Documentum Administrator displays files that include variations of the words
you typed in addition to the exact words. These variations are based on the root
of the word. This behavior depends on the configuration of the full-text engine,
and is called grammatical normalization.
• External sources: When querying an external source, the results displayed in
Documentum Administrator depend partly on the configuration of this source.
For example, if the source does not return information on dates, then dates
cannot be filtered.
• Multiple repositories: As for external sources, the results depend on the
configuration of each repository. For example, the indexing may be set
differently on various repositories.

28.8 Saved searches

Searches can be saved so that you can launch them regularly without redefining
them, share them between users, or to quickly retrieve the corresponding results.
Documentum Administrator User Guide contains the information and instructions
saving a search, running a saved search, and editing a saved search.

28.9 Creating a search template

If Federated Search Services is installed on Documentum Server, DA provides the
option to create search templates. A search template is a predefined search in which
users can change certain search values each time they run the search. Search
templates can be private or public. Documentum Platform and Platform Extensions
Installation Guide contains information on installing Federated Search Services.
Documentum Administrator User Guide contains the instructions on creating a search
template.

598 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 29
Inbox

Documentum Administrator User Guide contains the information and instructions on

the following:

• Understanding inboxes
• Opening a task or notifications
• Performing a task
• Completing a task
• Accepting a group task
• Rejecting a task
• Delegating a task
• Repeating a task
• Changing availability of tasks
• Understanding work queue tasks

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 599

Chapter 30
Workflows, Work queues, and Lifecycles

30.1 Workflows
A workflow is an automated process that passes files and instructions between
individuals in sequence to accomplish specific tasks. When users are assigned a
workflow task, the task appears in their Inbox.

Workflows can include automatic tasks that the system performs, such as the
execution of scripts. Automatic tasks allow the integration of workflows and
lifecycles.

30.1.1 Configuring the workflow agent

The workflow agent controls the execution of automatic activities in a workflow. The
agent is comprised of a master repository session and one or more worker sessions.
The master session is dormant until the workflow agent is notified by Documentum
Server that an activity has been created or until the sleep interval expires. At that
time, the master session queries the repository for information about the activity or
activities and assigns the waiting activity to a free worker session.

30.1.1.1 Changing the number of worker sessions

The number of worker sessions available to execute automatic activities is controlled
by the workflow agent worker threads property value in the server configuration
properties. By default, this value is set to 3. You can reset the value to any positive
number to a maximum of 1000. The “Modifying general server configuration
information” on page 49 section contains more information on the server
configuration properties.

You must stop and restart Documentum Server for your change to take effect.
Reinitializing the server does not make the change effective.

30.1.1.2 Changing the sleep interval

The sleep interval determines how long the master session sleeps after querying the
repository for activity information in the absence of a notification from
Documentum Server. If the sleep interval expires without a notification, the master
session wakes up and queries the repository even though it has not received a
notification from Documentum Server. The default sleep interval is 5 seconds. You
cannot change this value in Documentum Administrator. Use IDQL to change the
value.

The sleep interval is controlled by the wf_sleep_interval property in the server

configuration object. The value is interpreted in seconds. You must stop and restart

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 601

Chapter 30 Workflows, Work queues, and Lifecycles

Documentum Server for your change to take effect. Reinitializing the server does not
make the change effective.

30.1.1.3 Changing the system shutdown timeout

The system shutdown timeout property in the server configuration object sets the
time that the workflow agent attempts to shut down work items gracefully after
receiving a shutdown command. This feature is only applicable for repositories that
use multiple Documentum Servers.

If the shutdown timeout period is exceeded (or is set to zero), the workflow agent
shuts down immediately. When the workflow agent does not shut down gracefully,
automated tasks in certain states can be corrupted. If tasks are corrupted, restarting
the Documentum Server does not result in resumption of the managed workflows.
The server log file indicates when a graceful shutdown did not occur. Use the
RECOVER_AUTO_TASKS administration method to recover the automated tasks.

Note: In some cases, restarting the Documentum Server after an ungraceful

shutdown can result in automated tasks executing again.

If the timeout period is a negative value, Documentum Server waits for the
workflow agent threads to complete the automatic tasks held by workflow agent
workers before shutting down gracefully.

The default system shutdown timeout setting is 120 seconds. The “Modifying
general server configuration information” on page 49 section contains more
information on the server configuration properties.

30.1.1.4 Enabling immediate processing of automatic activities

The notify new task attribute (wf_agent_notify_newtask) on the server configuration
object enables you to force immediate processing of automatic activities. Configure
the Documentum Server to notify the workflow agent to process automatic tasks
immediately after the system creates them by setting the wf_agent_notify_newtask
attribute to TRUE. You cannot change this value in Documentum Administrator.
Use IDQL to change the value.

When the wf_agent_newtask attribute is set to TRUE, the following occurs:

• If the system creates automatic tasks when the workflow agent is processing the
previously collected tasks, then the workflow agent ignores the
wf_sleep_interval and collects the next set of automatic activities.
• If the system has not created an automatic task when the workflow agent is
processing the previously collected tasks, then the workflow agent sleeps for the
time specified in wf_sleep_interval.

• If the system creates tasks when the workflow agent is sleeping, then the agent
wakes up immediately and collects the next set of automatic activities.

602 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 30.1. Workflows

When the wf_agent_notify_newtask attribute is set to FALSE, the workflow agent

honors the value of the wf_sleep_interval and sleeps for the time specified before the
workflow agent collects the next set of automatic activities for processing.

By default, the value for the wf_agent_notify_newtask attribute is TRUE.

30.1.1.4.1 Skipping workflow task assignment

A parameter WF_SKIP_PARALLEL_TASK_EXECUTION can be set in the

dm_docbase_config object for the following activities:

• To disallow workflow agent to query for workitems from workflows that already
have other workitems assigned.
• To create a logic to skip task assignment if one of them is assigned from the same
workflow.

To achieve, perform the following:

• Add r_module_name in dm_docbase_config to

WF_SKIP_PARALLEL_TASK_EXECUTION
• Add r_module_mode in dm_docbase_config to 1
• Save dm_docbase_config
• Restart the repository

30.1.1.5 Tracing the workflow agent

By default, tracing for the workflow agent is turned off. You can turn it on by
executing a SET_OPTIONS administration method with the -trace_workflow_agent
option specified. For more information about the SET_OPTIONS administration
method, refer to “SET_OPTIONS” on page 364.

If you execute the SET_OPTIONS administration method, tracing starts

immediately. It is not necessary to restart the server. However, if you stop and
restart the server, you must reissue the SET_OPTIONS administration method to
restart the tracing.

The trace messages are recorded in the server log file.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 603

Chapter 30 Workflows, Work queues, and Lifecycles

30.1.1.6 Disabling the workflow agent

Disabling the workflow agent stops the execution of automatic activities. To disable
the workflow agent, set the workflow agent worker threads property in the server
configuration properties to 0. The “Modifying general server configuration
information” on page 49 section contains more information on the server
configuration properties.

Stop and restart Documentum Server for the change to take effect. Reinitializing the
server does not make the change effective.

30.2 Work queue management

Work queues hold tasks that are to be performed by users who are assigned to the
queue. Work queue users receive tasks in their Inboxes. Work queue users are
assigned tasks either automatically by the server or manually by another user. To
access work queues, users must belong to one of the roles described in “User roles
for work queues” on page 604. Work queue users are also referred to as processors.

Apart from work queue users there are

• Work queue managers

Managers monitor work queues to see which queues have overdue tasks that
need to be addressed or which queues have too many tasks in the queue.
Managers can add, edit, and assign skill profiles to individual work queue users.
• Work queue administrators
Administrator create work queues, assign users to work on queue tasks, define
the skill profiles that enable the application to assign tasks to the appropriate
processor, and add, edit, or assign skill profiles to the individual work queue
users.

The administrator or manager can use the Work Queue Monitor to view the tasks in
the queue, the name of the processor assigned to the task, the status of the task,
when the task was received, and the current priority of the task.

Table 30-1: User roles for work queues

Role Description
Queue_processor Works on items that are assigned by the
system from one or more work queue
inboxes. Queue processors can request work,
suspend, and unsuspend work, complete
work, and reassign their work to others.
Queue_advance_processor Works on items that are assigned by the
system from one or more work queue
inboxes. Additionally, selects tasks to work
on from one or more work queue inboxes.

604 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 30.3. Lifecycles

Role Description
Queue_manager Monitors work queues, assigns roles to
queues, and assigns users to work on queue
items. Queue managers can reassign, and
suspend tasks.

Queue managers who have

CREATE_GROUP privileges can create work
queues.
Queue_admin Creates work queues, and queue policies.
Members of the queue_admin role do not by
default have the administrator role.

Queue administrators who have

CREATE_GROUP privileges can create work
queues.
Process_report_admin Runs historical workflow reports from the
Workflow menu.

30.3 Lifecycles
A lifecycle defines a sequence of states a file can encounter. Typically, lifecycles are
designed for documents to describe a review process. For example, a user creates a
document, sends it off to other users for review and approval. The lifecycle defines
the state of the file at each point in the process.

The lifecycle itself is created using Documentum Composer and is deployed in the
repository as part of an application. Documentum Administrator manages the
lifecycles that already exist in a repository. All lifecycle procedures are accessed
through the Tools menu in Documentum Administrator.

30.4 References
Documentum Administrator User Guide contains the information and instructions on
the following:

• Starting a workflow
• Sending a quickflow
• Viewing workflows
• Pausing a workflow
• Resuming a paused workflow
• Stopping a workflow
• Emailing the workflow supervisor or a workflow performer
• Processing a failed task in a workflow
• Changing the workflow supervisor

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 605

Chapter 30 Workflows, Work queues, and Lifecycles

• Saving workflow information as a Microsoft Excel spreadsheet

• Viewing aggregated report for workflow performance
• Creating a workflow template
• Configuring the workflow agent
• Setting up a new work queue
• Setting up work assignment matching
• Understanding work queue policies
• Defining a queue category
• Defining a work queue
• Defining work queue override policies
• Managing work queue users
• Monitoring work queues
• Creating business calendars
• Assigning a lifecycle to a file
• Removing a lifecycle from a file
• Promoting a file to the next lifecycle state
• Demoting a file to its previous lifecycle state
• Suspending a file from its current lifecycle state
• Resuming a suspended file

606 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Chapter 31
Performance and Tuning

This chapter provides recommendations and best practices to help you improve the
overall performance of the Documentum platform.

Note: The best practices and/or test results are derived or obtained after testing
the product in our testing environment. Every effort is made to simulate
common customer usage scenarios during performance testing, but actual
performance results will vary due to differences in hardware and software
configurations, data, and other variables.

31.1 Common problems with Documentum Server

performance
The most common problems in Documentum Server performance include the
following:

• Application design and customization

– Chatty or redundant application code is the most common cause of failure (40
percent in 1995 IEEE study)
– Complex object models
– Poor memory and cache management
• Network

– High latency due to physical or logical limitations

– Overburdened shared network
• Undersized Server resources (inadequate memory and CPU size)
• Unmanaged or under used RDBMS resources

– RDBMS not regularly monitored and tuned

– Performance and caching features not used
– Insufficient tablespace available after performing the upgrade
• Unrealistic expectations (did not use realistic benchmarks)

Carefully design your highly available infrastructure to fit your business

requirements. There is no single solution that fits all.

The following solutions are available to help with these problems.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 607

Chapter 31 Performance and Tuning

High availability Documentum server clusters

Server clusters (also called server sets) can be active-active or active-passive. In an
active-active cluster, there are two active load-balanced web application servers, two
active sets consisting of a Documentum Server and connection broker, one active
RDBMS with clustered standby server, one primary database with one synchronized
standby, and one primary content store with one synchronized standby. In an
active-passive cluster, everything is the same, except that there is only one active
server plus connection broker set, with another set as standby.

These cluster configurations provide partial high availability coverage with

increased scalability. The clusters can be managed with Documentum
Administrator.

Redundant connection brokers

Connection brokers (formerly known as docbrokers) can be configured to
automatically reroute users to Documentum Servers that are online. Connection
brokers can load balance user connections across multiple Documentum Servers
using identical proximity values for connection brokers. Documentum Administrator
User Guide contains more information.

Replication
Replication can be configured either as read/write or read only.

Disaster recovery
Disaster recovery is not the same as high availability. It assumes a total loss of the
production data center. Disaster recovery servers are separate and independent from
the main center. They share no resources, and each has an independent network
infrastructure for WAN replication. Both systems have the capacity to carry out full
normal and emergency workloads. They must be maintained to be compatible.

Failover for disaster recovery is manual, not automatic.

Enhancing query performance

Documentum Administrator User Guide describes how to monitor query performance
using the Update Statistics administration tool. It also describes how to limit poorly
performing subqueries for users who belong to many groups.

608 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 31.2. Type caching

31.2 Type caching

With the type caching enhancements in Documentum 7.0, every session shares types
from a global cache thereby improving memory usage, which in turn can yield
better concurrency and scalability. You can apply the following best practices for
better performance when a large number of types are used.

31.2.1 Concurrency
• Unlike earlier versions of Documentum, the concurrency in Documentum 7.0 is
not limited by the availability of memory on the Documentum Server when a
large number of types were used. With the gains in concurrency seen in
Documentum 7.0 for such use cases, additional physical memory can be added to
get more concurrency. Here is an observation using a low level DFC-based test
dealing with 1000 types of varying hierarchies.

Figure 31-1: Type caching results for a DFC-based test

• The bottleneck is more likely the server session limitation for a single
Documentum Server. The maximum number of sessions (that can run type
related operations) on a single Documentum Server is still limited by the
max_concurrent_sessions setting on the server.

• Read the database tuning guidelines as performance in type caching can be

vastly improved by database tuning.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 609

Chapter 31 Performance and Tuning

31.2.2 Deeper type hierarchy

A deeper type hierarchy (multiple levels of inheritance) can benefit from the
memory usage improvements. For example, when there are two custom types, it is
recommended to create a common parent type for the two types, with common
attributes, as shown in the following figure.

Figure 31-2: Deeper type hierarchy

31.3 LDAP synchronization

LDAP integration for automated users and group management and authentication
has become a common practice. In Documentum deployments using LDAP
integration, user and group synchronization with Documentum Server repository
has to perform well with minimal impacts to a live Documentum system. This
section covers some tuning tips and best practices for the new LDAP Nested Group
Synchronization (LDAP NG) feature in Documentum 7.0, to better utilize and
schedule LDAP NG jobs.

31.3.1 Best throughput formula

• The thread_pool_size parameter is used to determine the working threads of
LDAP NG job for concurrent processing. The default value of
thread_pool_size is 5, and the maximum value is 25. To achieve the highest
synchronization throughput (and speed), it is recommended to set a value that is
best suited for the number of CPU cores in the host where Documentum Server is
installed.

• The following table lists some observations on a host based on a Windows 2008
R2 based VM template with 8 GB of RAM.

610 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 31.3. LDAP synchronization

Table 31-1: Synchronization throughput

Throughput Number of Threads

Number of 5 10 20 25
CPU cores
2 7.4 10.5 10.2
4 7.7 12.8 16.8 14.4
8 14.6 15.7

– For a system configuration with two and four cores, the optimal thread
number is 5X cores.

– Adding more than 20 threads does not improve the throughput. It is

recommended to use a maximum of 20 threads with more than four cores.

31.3.2 Throughput and CPU utilization balance

The CPU utilization of an LDAP NG job is notably higher than a traditional
synchronization job. If the job cannot be scheduled at off-peak hours, one way to
balance the CPU and throughput is to reduce the working threads, as shown in the
following figure and table.

Figure 31-3: Documentum Server processor time over threads

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 611

Chapter 31 Performance and Tuning

Table 31-2: Documentum Server processor time over threads

Documentu Four Cores

m Server
Parameters Number of 2 5 10 20 25
threads
Heap size 1024 1024 1024 1024 1024
Performanc Sync time 90 56 33 25 30
e metrics (minutes)
Throughput 4.8 7.7 12.8 16.8 14.4
(per second)
Processor time
Document 9% 17% 27% 35% 38%
um
Java 19% 20% 22% 21% 21%
contentserv 31% 42% 53% 59% 66%
er_total
oracle_total 5% 8% 16% 19% 24%

31.3.3 Large volume and hierarchy

• In an LDAP NG Synchronization test using large volume of groups and deeper
group hierarchy as shown in the following table and figure, it was observed that
the throughput, processor time, and memory cost were relatively close between
different size of groups and hierarchy levels.
Table 31-3: LDAP NG synchronization test results

Test Case Groups Hierarchy Users Group

Level Members
Baseline spread 25,716 10 100,000 192,914
Larger spread 51,432 10 100,000 360,024
Larger and 49,152 15 100,000 344,064
deeper spread

612 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 31.3. LDAP synchronization

Figure 31-4: Large volume test

• There is very little performance impact by extending the group entry size and
hierarchy levels. CPU and memory are not affected by the larger size of LDAP.
From the test results, it can be seen that the LDAP NG synchronization speed
depends only on the number of Documentum Server cores and job working
threads.

31.3.4 Java Method Server tuning

• There are two ways to execute an LDAP NG job:

– Within Java Method Server (JMS) as a method

– As a standalone Java executable
• When executed within JMS with default configuration settings (1024 heap size),
the garbage collector ran at an acceptable range - the average garbage collection
(GC) overhead was below 3 percent, and there were no severe performance
impact. However, you must consider other Documentum jobs running on JMS at
the same time, as there should be overall performance degradation if the GC
overhead due to LDAP NG synchronization job is over 5 percent.

– It is recommended to use a larger heap, especially with more than 20 working

threads, as shown in the following table.
Table 31-4: Garbage collection at various JMS heap sizes

Documentum Server Four Cores

Parameters Number of threads 20 20

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 613

Chapter 31 Performance and Tuning

Heap size 1024 1680

Performance Sync time (minutes) 25 25
metrics
Throughput (per 16.8 16.9
second)
Processor time
contentserver_total 59% 61%
oracle_total 19% 20%
Garbage Collection
Average GC 2.40% 1.60%
overhead
Number of all GC 142 86
Number of full GC 22 6
Total GC pause (in 41 34
seconds)

– Another alternative is executing the LDAP NG job by a standalone Java

process.
• The throughput improvement is limited while enlarging the JMS heap size to
1680 MB, but the GC performance gets better.
• It was also observed during the tests that the maximum heap consumption (and
therefore garbage collection) occurred when users are processed. The LDAP NG
job will first synchronize all the users in the target nested group and then process
new groups and members. Therefore, it is recommend that you set a larger Java
heap if your registered users are more than 100,000.

31.3.5 Database tuning

• If the repository database is Oracle, then Oracle initialization parameter
Cursor sharing should be set to FORCE. It could reduce SQL hard parses,
improve library hit (from 0 to 99 percent), and reduce oracle CPU utilization
(from 50 to 20 percent). By setting this parameter, the throughput of traditional
synchronization jobs will also improve.
• High redo activity is also seen during the running of a job. You can increase the
redo log size or number of redo logs to alleviate commits times.

614 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 31.4. Intelligent Session Management

31.4 Intelligent Session Management

The Intelligent Session Management (ISM) enhancements in Documentum 7.0 helps
to improve the overall performance, scalability, and total cost of ownership (TCO). It
achieves them through:

• Lower context switches on the Documentum Server.

• Lower memory usage on the Documentum Server (cache).
• Lower number of active sessions on the Documentum Server
• Lower number of sessions on the Oracle database

The session management enhancements have different levels of gains based on how
sessions are created and used by the client transactions. The following list shows
three classes of session usage:

• A: Reuse the existing connection (server session) and no authentication

requirement (the same user).
• B: Reuse the existing connection (server session) and perform authentication.
• C: Create a new connection (server session).

The performance implications in Documentum 7.0 for the three classes if session
usages are below:

• The number of connections is much smaller in Documentum 7.0 than

Documentum 6.7 (connections will no longer be occupied in the Level-1 pool).
• A user is more likely to reuse the other user’s session (class B) than to reuse his
own session (class A).
• When you access the Documentum Server in a later transaction, your previous
connection would have been used by others already. This will slightly affect the
response time performance because additional authentication is required (the
average response time of class A is generally smaller than that of class B).
• The average time of class B transactions is reduced from Documentum 6.7 to
Documentum 7.0, due to more efficient context switching.
• For a large number of concurrent users, the number of class C transactions is
smaller because of the following two reasons:
1. The default value of the dfc.session.reuse_limit parameter is increased
from 100 to 5,000, so a connection can be reused for more times before closed.
2. The connections in the Level-1 pool will not be closed by force (thereby
saving on creating/closing of connections), by using a more graceful queue
algorithm.

In a Windows-based test involving short-living sessions, substantial gains were seen

in response times when using the following settings:

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 615

Chapter 31 Performance and Tuning

Table 31-5: Settings for the session usage test

dfc.session.reuse_limit 5000
dfc.connection.reuse_threshold 50
dfc.connection.cleanup_check_window180
dfc.connection.queue_wait_time 500
dfc.session.max_count 1000
concurrent_sessions 100

Figure 31-5: Response time test results

In the same test, Documentum 7.0 consumed less system resource than 6.7.

616 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 31.5. Multiple workflows in Linux

Figure 31-6: Resources usage

31.5 Multiple workflows in Linux

It is recommended that you follow these steps to avoid memory issues before you
run multiple workflows in Linux.

1. The operating system has restriction of only 4096 file descriptors per user.
Edit /etc/security/limits.conf and set the following:
csuser soft nofile 8192
csuser hard nofile 16384

2. The kernel limits the number of user processes per user to 40.
Edit /etc/security/limits.conf and set the following:
csuser soft nproc 2047

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 617

Appendix A. System Events
This appendix lists and describes the system events recognized by Documentum
Server. You can register most of these events for auditing. You can also use an
IDfSysobject.registerEvent method to register to receive 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.

A.1 dm_default_set event

This dm_default_set events are audited by default. The following table describes the
events.

Table A-1: dm_default_set events

Object type Audited events

docbase config dm_archive dm_checkin dm_restore

Note: The dm_default_set event is dm_assembl dm_checkout dm_save

registered against the docbase config e
object; however, it causes auditing of
dm_bp_attac dm_destroy dm_setfile
the listed events for dm_document
h
object type and its subtypes.
dm_bp_dem dm_freeze dm_signoff
ote
dm_bp_pro dm_link dm_unfreeze
mote
dm_bp_resu dm_lock dm_unlink
me
dm_bp_susp dm_mark dm_unlock
end
dm_branch dm_prune

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 619

Appendix A. System Events

A.2 DFC events

The following table describes the events arising from DFC methods. Events arising
from methods that are specific to workflows are described in “Workflow events”
on page 626.

Table A-2: DFC events

Event Target object type Event description Trigger

dm_all (or all) 0 or omitted All All auditable events
in repository
dm_sysobject
Any event on any
Sysobject or the
specified Sysobject
dm_add_dynamic_gr dm_group Add To Dynamic Execution of an
oup Group IDfSession.addDyna
micGroups call
dm_adddigsignature dm_sysobject Add electronic Execution of the
signature addDigitalSignature
method.

addDigitalSignature
methods are always
audited. It is not
possible to unregister
this event.
dm_addesignature dm_sysobject Add Electronic Execution of the
Signature addEsignature
method.

addEsignature
methods are always
audited and the
entries are always
signed by
Documentum Server.
It is not possible to
modify this behavior.
dm_addesignature_fa dm_sysobject Add Electronic An attempt to
iled Signature Failed execute the
addEsignature
method failed. These
failures are always
audited. It is not
possible to modify
this behavior.

620 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 System Events

Event Target object type Event description Trigger

dm_addnote dm_sysobject Add Note Addition of a note to
dm_process a SysObject.

When the target

object is a process
object, the SysObject
is in a workflow
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 a retention
policy
dm_appendpart dm_sysobject Apend to Virtual Addition of a
Document component to a
virtual document
dm_archive dm_sysobject Archive Objects Execution of an
archive method
dm_assemble dm_sysobject Assemble Virtual Execution of
Document assemble method
dm_assume dm_user Assume User Execution of Assume
method
dm_audit all object types Audit Event Execution of method
to register for
auditing

Registrations for
auditing are always
audited. It is not
possible to unregister
this event.
dm_authenticate dm_user Authenticate User Execution of an
authenticate method

Executing an
authenticate method
also generates a
dm_connect method
if the authentication
requires a repository
connection.
dm_branch dm_sysobject Branch Version Execution of a branch
dm_retainer method
dm_checkin dm_sysobject Checkin Object Checking in an object
dm_retainer

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 621

Appendix A. System Events

Event Target object type Event description Trigger

dm_checkout dm_sysobject Checkout Object Checking out an
dm_retainer object
dm_connect dm_user Logon Establishing a
repository connection

Note: An
authenticate
method may
also establish a
repository
connection,
which will
generate a
dm_connect
event in
addition to the
dm_authenticat
e event.
dm_destroy dm_sysobject Destroy Object Execution of a
dm_acldm_user destroy method
dm_group
dm_retainer
dm_disassemble dm_sysobject Disassemble Virtual Execution of a
Document disassemble method
dm_disconnect dm_user Logoff Terminating a
repository connection
dm_fetch dm_sysobject Fetch Object Fetching an object
dm_retainer from the repository
dm_freeze dm_sysobject Freeze Object Execution of a freeze
method
dm_getfile dm_sysobject View/Export Occurs when a
document is viewed
or exported or when
the a getContent and
getPath method is
executed.
dm_getlogin dm_user Get Login Execution of a
getLoginTicket
method
dm_insertpart dm_sysobject Insert into Virtual Execution of an
Document insertPart method
dm_install dm_policy Install Execution of an
dm_process install method
dm_activity

622 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 System Events

Event Target object type Event description Trigger

dm_invalidate dm_process Invalidate Execution of an
dm_activity invalidate method
dm_kill not applicable Kill Session Execution of a Kill
method

Note: You
cannot audit a
Kill method
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
dm_logon_failure dm_user Logon Failure User attempts to start
a repository
connection using
invalid credentials.
dm_mark dm_sysobject Add Version Label Execution of a mark
method
dm_move_content dmr_content Move Content Execution of a
MIGRATE_CONTEN
T administration
method
dm_prune dm_sysobject Prune Versions Execution of a prune
dm_retainer method
dm_purgeaudit dm_audittrail Purge Audit Execution of a
dm_audittrail_acl destroy method or
dm_audittrail_group PURGE_AUDIT
administration
method to remove
audit trail entries

Purging an audittrail
entry is always
audited. It is not
possible to stop
auditing this event.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 623

Appendix A. System Events

Event Target object type Event description Trigger

dm_readonlysave dm_sysobject no event description Generated when
provided Documentum Server
changes a property
value of an
immutable object.

This event is
generated
automatically for the
full-text user.
dm_remove_dynami dm_group Remove From Execution of an
c_group Dynamic Group IDfSession.removeDy
namicGroups call
dm_removecontent dm_sysobject Remove Content Execution of a
removeContent
method
dm_removenote dm_sysobject Remove Note Execution of a
dm_process removeNote method
dm_removepart dm_sysobject Remove from Virtual Execution of a
Document removePart method
dm_removerendition dm_sysobject Remove Rendition Execution of one of
the removeRendition
methods
dm_removeretention dm_sysobject Remove Retention Object removed from
control of a retention
policy
dm_restore dm_sysobject Restore Object Execution of a restore
method

624 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 System Events

Event Target object type Event description Trigger

dm_save dm_sysobject Save Object Execution of a save
dm_acl method.
dm_group
dm_user Note: For new
dm_retainer objects,
Documentum
Server stores
the value
Create in the
audit trail
attribute
string_1. For
existing objects,
the value in the
attribute is
Save.

For checked-
out objects that
are modified by
users in the
dm_escalated_
allow_save_on
_lock group,
Documentum
Server stores
the value
SAVE_ON_LOC
K in the
string_2
attribute.
dm_saveasnew dm_sysobject Copy Object Execution of a
dm_acl saveAsNew method
dm_retainer
dm_setfile dm_sysobject Set Content Execution of the
following methods:

appendContent
appendFile bindFile
iInsertFile
insertContent
setContent setPath
dm_setoutput dm_process Setoutput Execution of a
Setoutput method.
dm_setretentionstatu dm_retainer Set Retention Status Change to status of a
s retainer object.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 625

Appendix A. System Events

Event Target object type Event description Trigger

dm_signoff dm_sysobject Signoff Execution of a signoff
method

signoff methods are

always audited. It is
not possible to stop
this auditing.
dm_unaudit all object types Unaudit Event Removing an
auditing registration.

Methods that remove

(unregister) an audit
registration are
always audited. It is
not possible to stop
this auditing.
dm_unfreeze dm_sysobject Unfreeze Object Execution of an
unfreeze method
dm_uninstall dm_policy Uninstall Execution of an
dm_process uninstall method
dm_activity
dm_unlink dm_sysobject Unlink From Execution of an
unLink method
dm_unlock dm_sysobject Cancel Checkout Execution of a
cancelCheckOut
method
dm_unmark dm_sysobject Remove Version Execution of an
Label unMark method
dm_updatepart dm_sysobject Update in Virtual Execution of an
Document updatePart method
dm_validate dm_policy Validate Execution of a
dm_process validate method
dm_activity

A.3 Workflow events

The following table describes the events specific to workflows. Several API events
described in “DFC events” on page 620 are also applicable to workflows.

626 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 System Events

Table A-3: Workflow events

Event Target object type Event description Trigger

dm_all_workflow dm_process (or not All Workflow Events All events on
included) workflows generated
from the specified
process object or all
events in the
repository.

Note: This
does not
include
dm_validate,
dm_install,
dm_invalidate,
and
dm_uninstall
events, and
dm_changestat
eprocess
events.
dm_abortworkflow dm_process Abort Workflow Aborting a workflow
dm_addattachment dm_process Add Attachment An attachment is
added to a running
workflow or work
item.
dm_addpackage dm_process Add Workflow Execution of an
Package addPackage method
dm_autotransactivity dm_process Automatic Workflow An automatic activity
Activity Transition transition occurs
dm_changedactivity dm_process Change Workflow An automatic activity
instancestate Activity to Failed changes state because
State the error handling
flag is set to zero and
the work item returns
a non-zero value.
dm_changepriorityw dm_process Change Workitem The priority value of
orkitem Priority a work item is
changed at runtime.
dm_changestateactivi dm_process Change Workflow An activity instance
ty Activity State changes state to a
state other than failed
or changes state due
to an automatic
transition.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 627

Appendix A. System Events

Event Target object type Event description Trigger

dm_changestatework dm_process Change Workflow A workflow changes
flow State state by a method
other than a save,
execute, or abort.
dm_changeworkflow dm_process Change Workflow Execution of a
supervisor Supervisor Setsupervisor
method
dm_completedworkit dm_process Complete Workitem Execution of a
em Complete method
dm_createworkflow dm_process Create Workflow A workflow is
created.
dm_delegatedworkit dm_process Delegate Workitem A work item is
em delegated.
dm_finishworkflow dm_process Finish Workflow A workflow is
terminated.
dm_pauseworkitem dm_process Pause Workitem A work item is
paused.
dm_portselect dm_process Select Workflow Port Selection of output
ports by a user or
Documentum Server
upon completion of
an activity.

Note: This
event is not
triggered if the
activity has a
transition type
of prescribed.
dm_pseudocomplete dm_process Pseudo_Complete A work item is
dworkitem Workitem marked as pseudo-
completed by
Documentum Server
dm_removeattachme dm_process Remove Attachment An attachment is
nt removed from a
workflow or work
item
dm_removepackage dm_process Remove Workflow A package is
Package removed from a
workflow
dm_repeatworkitem dm_process Repeat Workflow A work item is
Work Item repeated.
dm_resumeworkitem dm_process Resume Workitem A work item is
resumed.

628 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 System Events

Event Target object type Event description Trigger

dm_save_workqueue Not applicable Not applicable Generated when a
workqueue object is
saved by the
Workqueue SBO.

It is not possible to
register for this event.
dm_save_workqueue Not applicable Not applicable Generated when a
policy workqueue policy
object is saved by the
Workqueue SBO.

It is not possible to
register for this event.
dm_selectedworkite dm_process Select Workitem A work item is
m acquired.
dm_startworkflow dm_process Start Workflow A workflow is
started.
dm_startedworkitem dm_process Start Workitem A work item is
generated.
dm_suspendedworkq dm_process Suspend Workqueue A task on a
ueuetask Tasks workqueue is
suspended.
dm_unsuspendedwo dm_process Unsuspend A task on a
rkqueuetask Workqueue Tasks workqueue is
resumed.
dm_wf_autodelegate dm_process Auto Delegation Automatic delegation
_failure Failed of an activity failed.
dm_wf_business_dat dm_process All workflow events An activity completes
a and at least one
package is defined to
generate a report on
the activity.

A.4 Lifecycle events

“Lifecycle events” on page 629 lists the events specific to lifecyles.

Table A-4: Lifecycle events

Event Target object type Event description Trigger

dm_bp_attach dm_sysobject Attach Lifecycle Attaching a lifecycle
dm_retainer to an object.
dm_bp_demote dm_sysobject Demote from Demoting an object
dm_retainer Lifecycle State from a lifecycle state.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 629

Appendix A. System Events

Event Target object type Event description Trigger

dm_bp_promote dm_sysobject Promote to Lifecycle Promoting an object
dm_retainer State to a lifecycle state.
dm_bp_resume dm_syobject Resume Lifecycle Resuming a
dm_retainer suspended lifecycle.
dm_bp_suspend dm_sysobject Suspend Lifecycle Suspending a
dm_retainer lifecycle.

A.5 Events sent to the fulltext user

The following events are generated automatically for the dm_fulltext_user user:

• dm_checkin
• dm_destroy
• dm_move_content
• dm_readonlysave
• dm_save

630 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Appendix B. Populating and Publishing the Data
Dictionary
B.1 Populating the data dictionary
Data dictionary files for certain locales are installed with Documentum Server (see
“Default files provided by Documentum” on page 644). When a repository is
created, dd_populate.ebs is executed. If the locale of the host machine matches an
installed, data dictionary file of locale, then dd_populate.ebs is executed with that
data dictionary file of locale; otherwise, the English data dictionary file is used.

Note: If the server_codepage property is set in the server.ini file, then you
must set that property to UTF-8.

It is recommended that you add only the required locales to the data dictionary
because additional data dictionary information can have a substantial effect on
server performance.

To add a new locale, use the population script provided by Documentum. To add to
or change the locale information for installed data dictionary locales, you can use:

• The population script provided by Documentum

• The DQL CREATE TYPE or ALTER TYPE statement

Only some of the data dictionary information can be set using a population script.
(“Summary of settable data dictionary properties” on page 635, describes the data
dictionary properties that you can set in a population script.) The information that
you cannot set using the population script must be set using the DQL statements.
Additionally, you must use DQL if you want to set data dictionary information that
applies only when an object is in a particular lifecycle state.

“Using DQL statements” on page 645, discusses using DQL to populate the data
dictionary.

To change the data dictionary locale of repository, (in Documentum Administrator)

change the Data Dictionary Locales property on the Repository Configuration
Properties - Info page of repository.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 631

Appendix B. Populating and Publishing the Data Dictionary

B.1.1 Populating a repository’s data dictionary with a

Japanese, Korean, Simplified Chinese, Russian, or
Arabic locale-specific data dictionary file
If the repository’s machine is not running on the corresponding localized operating
system (for example, the machine is running the English Windows 2008 operating
system), you must run dd_populate.ebs on the repository’s machine from another
machine that is running the desired localized operating system.

Note: The corresponding localized machine term means a computer that is

running the corresponding localized operating system.

You share and map the %DM_HOME%\bin (Windows) of repository machine or mount
the $DM_HOME\bin (Linux) of repository machine (with the appropriate permissions)
onto the corresponding localized machine; and then execute dd_populate.ebs from
the corresponding localized machine. In addition, on Windows, you can specify the
UNC path to %DM_HOME%\bin.

Note: For Russian and Arabic, if the repository machine is running the English
operating system, then you can change the regional or language settings of the
repository machine to one of the corresponding locales and then execute the
dd_populate.ebs on the repository machine.

B.2 Data dictionary population script

The data dictionary population script, dd_populate.ebs, is a Docbasic script that
reads an initialization file. The initialization file contains the names of one or more
data files that define the data dictionary information you want to set. The
“Executing the script” on page 643 section contains the instructions on executing
the script.

B.2.1 The initialization file

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 not
specific to a locale.

The NLS data dictionary files contain the information that is specific to a locale.

632 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Populating and Publishing the Data Dictionary

You can include any number of data files in the initialization file. Typically, there is
one file for the non-NLS data and an NLS data file for each locale. You can reference
the data files by name or full path specification. If you reference a data file by name
only, the data file must be stored in the same directory as the population script or it
must be in %DM_HOME%\bin ($DM_HOME/bin).

B.2.2 The data files

The data files are text files. You can create them with any text editor. There are two
kinds of data files:

• Non-NLS
• NLS

In the non-NLS data files, the information you define is applied to all locales. In
these files, you define the information that is independent of where the user is
located. For example, you would set the is_searchable or ignore_immutable setting
of the property in a non-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 attr info objects for that locale are created or changed. For example, if you set the
label text for a new property in the German locale, the system sets label_text in the
dd attr info object of new property in the German locale. It will not set label_text in
the dd attr info objects of property for other locales.

If you do set NLS information in a non-NLS data file, the server sets the NLS
information in the current locale of the session.

If you include multiple NLS files that identify the same locale, any duplicate
information in them overwrites the information in the previous file. For example, if
you include two NLS data files that identify Germany (de) as the locale and each sets
label_text for 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 sets information for the document type and one sets information for a
custom type called proposals, no information is overwritten.

Note: Future upgrades of Documentum Server may overwrite any changes

you make to the data 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 the upgrade to recreate the changes.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 633

Appendix B. Populating and Publishing the Data Dictionary

B.2.2.1 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 file must 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 line
in 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 a file, the server resets the current session locale to the specified locale
and the information in that data file is set for the given locale.

<codepage_name> is the name of the code page appropriate for the specified locale.

Table B-1: Locale-based configuration settings for the data dictionary files
installed with Documentum Server

Locale locale_name default_client_code server_os_codepag

page and e
codepage_name
Arabic ar ISO-8859-6 ISO-8859-6
English en ISO-8859-1 ISO-8859-1
Chinese (Simplified) zh MS936 MS936
Dutch nl ISO-8859-1 ISO-8859-1
French fr ISO-8859-1 ISO-8859-1
German de ISO-8859-1 ISO-8859-1
Italian it ISO-8859-1 ISO-8859-1
Japanese ja Shift_JIS On Windows:
Shift_JIS

On Linux: EUC-JP
Korean ko EUC-KR EUC-KR
Portuguese pt ISO-8859-1 ISO-8859-1
(Brazilian)
Russian ru Windows-1251 Windows-1251
Spanish es ISO-8859-1 ISO-8859-1
Swedish sv ISO-8859-1 ISO-8859-1
Hebrew iw ISO-8859-8 ISO-8859-8

To define information for an object type, the format is:

634 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Populating and Publishing the Data Dictionary

TYPE=<type_name>
<data_dictionary_property_settings>

To define information for a property, the format is:

TYPE=<type_name>property=<property_name>
<data_dictionary_property_settings>

If you want to define information for multiple properties of one object type, specify
the type only once and then list the properties and the settings:
TYPE=<type_name>property=<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 “Summary of settable data dictionary properties” on page 635 section, lists the
data dictionary properties that you can set in data files. “Examples of data file
entries” on page 641, shows some examples of how these are used in a data file.

B.2.2.2 Summary of settable data dictionary properties

Data dictionary information is stored in the repository in internal object types. When
you set data dictionary information, you are setting the properties of these types.
Some of the information applies only to object types, some applies only to
properties, and some can apply to either or both.

“Settable data dictionary properties using population script” on page 635, lists and
briefly describes the data dictionary properties that you can set using a population
script.

Table B-2: Settable data dictionary properties using population script

property name Reference in Which level NLS-specific Comments

script as: (Yes or No)
ignore_immutab IGNORE_ property No None
le IMMUTABLE
allowed_search_ ALLOWED_ property No If
ops SEARCH_OPS allowed_search_
default_search_o DEFAULT_ ops is set, you
ps SEARCH_OP must set
default_search_a DEFAULT_ default_search_o
rg SEARCH_ARG ps.

Default_search_
arg, if set, must
be set to one of
the
allowed_search_
ops.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 635

Appendix B. Populating and Publishing the Data Dictionary

property name Reference in Which level NLS-specific Comments

script as: (Yes or No)
read_only READ_ONLY property No None
is_hidden IS_HIDDEN property No None
is_required IS_REQUIRED property No None
not_null NOT_NULL property Yes Setting not_null
not_null_msg REPORT=<string sets the not_null
not_null_enf > data dictionary
ENFORCE=<stri property to
ng> TRUE.

Including
REPORT
(not_null_msg)
or ENFORCE
(not_null_enf) is
optional. If you
include both,
REPORT must
appear first.

Valid values for

ENFORCE are
application and
disable.
map_data_string MAPPING_TAB property Yes The key phrase
map_display_str LE MAPPING_TAB
ing VALUE=<integer LE must appear
map_description > before the
DISPLAY=<strin keywords that
g> set the values for
COMMENT=<str the mapping
ing> table.

COMMENT is
optional.

VALUE and
DISPLAY must
be set. Set each
once for each
value that you
want to map.
“Examples of
data file entries”
on page 641
contains an
example.

636 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Populating and Publishing the Data Dictionary

property name Reference in Which level NLS-specific Comments

script as: (Yes or No)
life_cycle LIFE_CYCLE= Object type No Valid values are:
<integer>
<Value>
<Meaning>
• Currently in
use
• For future
use
• Obsolete
label_text LABEL_TEXT Object type Yes None
property
help_text HELP_TEXT Object type Yes None
property
comment_text COMMENT_TE Object type Yes None
XT property
is_searchable IS_SEARCHABL Object type No None
E property
primary_key If defined at type Object type Yes If the primary
primary_key_ms level: property key consists of
g one property,
primary_key_enf PRIMARY_KEY you can define
=<key> the key at either
REPORT=<string the property or
> type level. At the
ENFORCE=<stri type level, you
ng> must name the
property in
If defined at <key>. If you
property level: define the key at
the property
PRIMARY_KEY
level, naming
REPORT=<string
the property is
>
not necessary.
ENFORCE=<stri
ng>

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 637

Appendix B. Populating and Publishing the Data Dictionary

property name Reference in Which level NLS-specific Comments

script as: (Yes or No)
If the primary
key consists of
multiple
properties, you
must specify the
key at the type
level. Provide a
comma-
separated list of
the properties in
<key>.

Including
REPORT
(primary_key_m
sg) or ENFORCE
(primary_key_en
f) is optional. If
you include
both, REPORT
must appear
first.

Valid values for

ENFORCE are
application and
disable.

638 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Populating and Publishing the Data Dictionary

property name Reference in Which level NLS-specific Comments

script as: (Yes or No)
unique_key If defined at type Object type Yes If the unique key
unique_key_msg level: property consists of one
unique_key_enf property, you
UNIQUE_KEY= can define the
<key> key at either the
REPORT=<string property or type
> level. At the type
ENFORCE=<stri level, you must
ng> name the
property in
If defined at <key>. If you
property level: define the key at
the property
UNIQUE_KEY
level, naming
REPORT=<string
the property is
>
not necessary.
ENFORCE=<stri
ng> If the unique key
consists of
multiple
properties, you
must specify the
key at the type
level. Provide a
comma-
separated list of
the properties in
<key>.

Including
REPORT
(unique_key_ms
g) or ENFORCE
(unique_key_enf
) is optional. If
you include
both, REPORT
must appear
first.

Valid values for

ENFORCE are
application and
disable.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 639

Appendix B. Populating and Publishing the Data Dictionary

property name Reference in Which level NLS-specific Comments

script as: (Yes or No)
foreign_key At the type level: Object type Yes “Setting foreign
foreign_key_ms property keys”
g FOREIGN_KEY= on page 640
foreign_key_enf <key> section contains
REFERENCES= the information
<type>(<attr>) to define this
REPORT=<string key.
>
ENFORCE=<stri
ng>

At the property
level:

FOREIGN_KEY=
<type>(<attr>)
REPORT=<string
>ENFORCE=<str
ing>

B.2.2.3 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 type
participates in the foreign key and which property in another type is referenced by
the foreign key. The key phrase FOREIGN_KEY defines the property in the object
type that participates in the foreign key. The keyword REFERENCES defines the
property which is referenced by the foreign key. For example, suppose a data file
contains the following lines:
TYPE=personnel_action_doc
FOREIGN_KEY=user_name
REFERENCES=dm_user(user_name)

These lines define a foreign key for the personnel_action_doc subtype. The key says
that a 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 the
following lines:
TYPE=personnel_action_doc
property=user_name
FOREIGN_KEY=dm_user(user_name)

REPORT and ENFORCE are optional. If you include both, REPORT must appear
before ENFORCE. Valid values for ENFORCE are:

• application
• disable

640 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Populating and Publishing the Data Dictionary

B.2.2.4 Examples of data file entries

Here is an excerpt from a data file that sets non-NLS data dictionary information:
#set property level information for user_name property
TYPE=dm_user
property=user_name
IS_REQUIRED
DEFAULT_SEARCH_OP=contains

#set property level information for dm_document

TYPE=dm_document
property=acl_domain
IGNORE_IMMUTABLE
property=acl_name
IGNORE_IMMUTABLE
property=title
IS_REQUIRED
DEFAULT_SEARCH_OP=contains
property=subject
DEFAULT_SEARCH_OP=contains
property=authors
IS_REQUIRED

This excerpt is from a data file that defines data dictionary information for the
English locale.
#This sets the locale to English.
LOCALE = en
CODEPAGE = ISO_8859-1

# Set property Information for dm_user

TYPE = dm_user
property = alias_set_id
LABEL_TEXT = User Alias Set ID

# Set property Information for dm_group

TYPE = dm_group
property = alias_set_id
LABEL_TEXT = Group Alias Set ID

# Set property Information for dm_process

TYPE = dm_process
property = perf_alias_set_id
LABEL_TEXT = Performer Alias Set ID

# Set property Information for dm_workflow

TYPE = dm_workflow
property = r_alias_set_id
LABEL_TEXT = Performer Alias Set ID

# Set property Information for dm_activity

TYPE = dm_activity
property = resolve_type
LABEL_TEXT = Alias Resolution Type
MAPPING_TABLE
VALUE = 0
DISPLAY = Default
COMMENT = Default Resolution
VALUE = 1
DISPLAY = Package-based
COMMENT = Resolution based on packages
VALUE = 2
DISPLAY = Previous Performer-based
COMMENT = Resolution based on last performer only
property = resolve_pkg_name
LABEL_TEXT = Alias Resolution Package

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 641

Appendix B. Populating and Publishing the Data Dictionary

# Set property Information for dm_sysobject

TYPE = dm_sysobject
property = a_effective_label
LABEL_TEXT = Effective Label
property = a_effective_date
LABEL_TEXT = Effective Date
property = a_expiration_date
LABEL_TEXT = Expiration Date
property = a_effective_flag
LABEL_TEXT = Effective Flag
property = a_publish_formats
LABEL_TEXT = Publish Formats
property = a_category
LABEL_TEXT = Category
property = language_code
LABEL_TEXT = Language Code
property = authors
FOREIGN_KEY = dm_user(user_name)
REPORT = The author is not found in the repository.
ENFORCE = application

# Set property information for dmr_containment

TYPE = dmr_containment
property = a_contain_type
LABEL_TEXT = Containment Type
property = a_contain_desc
LABEL_TEXT = Containment Description

# Set property Information for dm_assembly

TYPE = dm_assembly
property = path_name
LABEL_TEXT = Path Name

# Set property Information for dm_relation

TYPE = dm_relation
property = r_object_id
LABEL_TEXT = Object ID
property = relation_name
LABEL_TEXT = Relation Name
property = parent_id
LABEL_TEXT = Parent ID
property = child_id
LABEL_TEXT = Child ID
property = child_label
LABEL_TEXT = Child Label
property = permanent_link
LABEL_TEXT = Permanent Link
property = order_no
LABEL_TEXT = Order Number
property = effective_date
LABEL_TEXT = Effective Date
property = expiration_date
LABEL_TEXT = Expiration Date
property = description
LABEL_TEXT = Description

This final example sets some constraints and search operators for the object types
and their properties.
TYPE = TypeC
PRIMARY_KEY = Attr2, Attr3
REPORT = The primary key constraint was not met.
ENFORCE = application
UNIQUE_KEY = Attr2, Attr3
REPORT = The unique key constraint was not met.
ENFORCE = application
FOREIGN_KEY = Attr1
REFERENCES = TypeA(Attr1)
REPORT = TypeC:Attr1 has a key relationship with TypeA:Attr1

642 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Populating and Publishing the Data Dictionary

ENFORCE = disable
IS_SEARCHABLE = True
TYPE = TypeC
property = Attr1
ALLOWED_SEARCH_OPS = =,<,>,<=,>=,<>, NOT, CONTAINS, DOES NOT CONTAIN
DEFAULT_SEARCH_OP = CONTAINS
DEFAULT_SEARCH_ARG = 3
TYPE = TypeD
LIFE_CYCLE = 3
PRIMARY_KEY = Attr1
REPORT = Attr1 is a primary key.
ENFORCE = disable
LABEL_TEXT = label t TypeD
HELP_TEXT = help TypeD
COMMENT_TEXT = com TypeD
IS_SEARCHABLE = True
UNIQUE_KEY = Attr1
REPORT = Attr1 is a unique key.
ENFORCE = application
FOREIGN_KEY = Attr1
REFERENCES = TypeC(Attr1)
REPORT = Attr1 has a foreign key relationship.
TYPE = TypeE
property = Attr1
IGNORE_IMMUTABLE = True
NOT_NULL
ENFORCE = application
ALLOWED_SEARCH_OPS = CONTAINS, DOES NOT CONTAIN
DEFAULT_SEARCH_OP = CONTAINS
DEFAULT_SEARCH_ARG = 22
READ_ONLY = True
IS_REQUIRED = True
IS_HIDDEN = True
LABEL_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 = False
UNIQUE_KEY
FOREIGN_KEY = TypeB(Attr1)
REPORT = This has a foreign key relationship with TypeB:Attr1
ENFORCE = application
FOREIGN_KEY = TypeC(Attr2)
REPORT = This has a foreign key relationship with TypeC:Attr2
ENFORCE = application

B.2.3 Executing the script

The population script is named dd_populate.ebs and is found in %
\DOCUMENTUM%\product\version\bin ($DOCUMENTUM/product/<version>/
bin).

A new locale is automatically added to the dd_locales property of the

dm_docbase_config object.

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.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 643

Appendix B. Populating and Publishing the Data Dictionary

<username> is the name of the user executing the script. The user must have
system administrator or superuser privileges.
<password> is the password of the user.
<ini_filename> is the name of the initialization file that contains the data files.
This can be a full path specification or only the file name. If you include just the
file name, the file must be in the same directory as the population script.

B.2.4 Populating data dictionary on a repository from a non-

English host
To populate data dictionary on a repository from a non-English host, connect to
Documentum Server from a Windows computer in the desired locale and run the
data dictionary population script from that computer. For example, to install the
Japanese data dictionary information on a repository on a Korean host, connect to
the repository from a Japanese Windows computer and run the script from the
Japanese computer.

To install the data dictionary information on a 64-bit repository from a non-English

host, you must copy the 64-bit Java installation, which defaults to the C:
\Documentum\java64\<<JDK_version>> folder (for example, “C:\Documentum
\java64\1.6.0_31”), to the host. Otherwise, an error occurs when you run the script.

B.2.5 Default files provided by Documentum

Documentum provides the following data dictionary files with Documentum 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
object types 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 following format:
data_dictionary_<localename>.txt

where <localename> is the name of the locale. For example, the data file for the
German locale is named data_dictionary_de.txt.

644 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Populating and Publishing the Data Dictionary

B.2.6 Using DQL statements

Use the DQL CREATE TYPE and ALTER TYPE statements to set data dictionary
information 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 property

The DQL statements allow you to publish the new or changed information
immediately, as part of the operations of statement. If you choose not to publish
immediately, the change is published the next time the Data Dictionary Publisher
job executes. You can also use the publish_dd method to publish the information.
“Publishing the data dictionary information” on page 645 contains more
information on publishing.

Documentum Server DQL Reference Guide contains the details on using these
statements.

B.3 Publishing the data dictionary information

Information in the data dictionary is stored in internal object types and must be
published before applications or users can access it. Publishing creates the dd
common info, 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 published before the changes are accessible to users or applications.

Publishing can occur automatically, through the operations of the Data Dictionary
Publisher job, or on request, using the publishDataDictionary method or the
PUBLISH keyword.

B.3.1 The data dictionary publisher job

The Data Dictionary Publisher job publishes changes to the data dictionary. Each
time the 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 locale

The job uses the value of the resync_needed property of dd common info objects to
determine which data dictionary objects need to be republished. If the property is set
to TRUE, the job automatically publishes the data dictionary information for the
object type or 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

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 645

Appendix B. Populating and Publishing the Data Dictionary

• 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 defined

The Data Dictionary Publisher job is installed with the Documentum tool suite.

B.3.2 The publishDataDictionary method

The publishDataDictionary method publishes the data dictionary information. You
can use the method to publish the entire data dictionary or just the information for a
particular object type or a particular property. The Javadocs contains the information
on using this method.

B.3.3 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 immediately
publishes the new or changed information and any other pending changes for the
particular object type or property.

For example, if you include PUBLISH when you create a new object type, the server
immediately publishes the data dictionary for the new object type. If you include
PUBLISH in an ALTER TYPE statement, the server immediately publishes the
information for the altered object type or property and any other pending changes
for that type or property.

If you do not include PUBLISH, the information is published the next time one of
the following 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.

646 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Appendix C. High-Availability Support Scripts
Documentum provides a set of scripts that monitor processes to determine whether
a given process is running or stopped. These scripts are installed when a
Documentum Server installation is created. The scripts can be programmatically
invoked from any commercial system management and monitoring package. This
appendix describes the scripts and which processes they affect.

C.1 Monitoring scripts

Monitoring scripts are provided for Documentum Server, the connection broker, the
Java method server, and for the Index Agent.

The scripts must be run as the Documentum Server installation owner. Each script
returns success (the monitored process is running) as 0 or failure (the monitored
process is stopped) as a non-zero value.

“Monitoring Scripts” on page 647, lists the processes that have monitoring scripts,
the script names, and their locations and command-line syntax.

Table C-1: Monitoring Scripts

Process Script Syntax and Location

Documentum Server ContentServerStatus A Java program in the server-
impl.jar file.

The command line syntax is:

java
com.documentum.server.impl.u
tils.ContentServerStatus -
docbase_name xxxx -user_name

On Linux, the return value is

recorded in the variable $?.
On Windows, the return
value is recorded in
%ERRORLEVEL%.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 647

Appendix C. High-Availability Support Scripts

Process Script Syntax and Location

Connection broker dmqdocbroker Located in %DM_HOME%
\bin ($DM_HOME/bin)

The syntax is:

%DM_HOME%\bin\dmqdocbroker -
t <host_name> -c ping

or
$DM_HOME/bin/dmqdocbroker -
t <host_name> -c ping

<host_name> is the name of

the machine hosting the
connection broker.

On Linux, the return value is

recorded in the variable $?.
On Windows, the return
value is recorded in
%ERRORLEVEL%.
Java method server TestConnection A Java program in the server-
impl.jar file.

On Linux, the command line

syntax is:
java
com.documentum.server.impl.u
tils.TestConnection <host>
<port> /DmMethods/servlet/
DoMethod

On Windows, the command

line syntax is:
java
com.documentum.server.impl.u
tils.TestConnection <host>
<port> /DmMethods/servlet/
DoMethod

Where <host> is the Java

Method Server (JVM) host
machine, <port> is the port
the JVM is using. You must
include a space between the
port and the servlet name.

On Linux, the return value is

recorded in the variable $?.
On Windows, the return
value is recorded in
%ERRORLEVEL%.

648 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 High-Availability Support Scripts

Process Script Syntax and Location

Index Agent IndexAgentCtrl A Java program in the server-
impl.jar file.

The command line syntax is:

java
com.documentum.server.impl.u
tils.IndexAgentCtrl -
docbase_name
<repository_name> -
user_name <user_name> -
action status

<repository_name> is the name

of a repository served by the
agent and <user_name> is the
user account with which to
connect to the repository.
dm_agent_exec dm_agent_exec The agent_exec_method
method is used to configure
the dm_agent_exec process
for job scheduling. Enable the
enable_ha_setup
argument to achieve high-
availability.
1. Update the
method_verb attribute
to turn on high-
availability feature:
retrieve,c,dm_method
where object_name =
'agent_exec_method'

Methods of r_object_id is
displayed.
get,c,l,method_verb
./dm_agent_exec (Linux)
or .\dm_agent_exec.exe
(Windows)
set,c,l,method_verb
./dm_agent_exec -
enable_ha_setup 1
(Linux) or .
\dm_agent_exec.exe -
enable_ha_setup 1
(Windows)
save,c,l
2. Kill the existing
dm_agent_exec process.
On Linux, use the kill
command and on
Windows, use the Task
Manager processes tab.
dm_agent_exec restarts
after a minute.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 649

Appendix C. High-Availability Support Scripts

C.2 Processes not requiring a script

The following processes do not require a separate script are dmbasic method server,
ACS server, and Workflow agent. Documentum Server monitors these processes. If
any of these processes stops, Documentum Server restarts it automatically.

650 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

Appendix D. Consistency Checks
D.1 General information
Consistency checks executed by the consistency checker job are sorted into tables
that describe the checks on a particular area of the repository. Each table includes
the following information:

• Consistency check number

Each consistency check has a unique number. When an inconsistency is reported,
the report includes 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
• Severity level
The consistency checker script reports inconsistencies as a warning or an error.

– A warning is issued for a referential integrity inconsistency. For example, if

the check finds a document referencing an author who no longer exists in the
repository. A warning does not threaten repository operations, but should be
fixed regardless.
– An error is issued for inconsistencies requiring immediate resolution. These
inconsistencies include object corruption problems, such as missing _r table
entries or missing entries in a dmi_object_type table, and type corruption.

D.2 User and group checks

The consistency checks in the following table apply to users and groups.

Table D-1: Consistency checks for users and groups

Consistency check number Consistency check Severity

description
CC-0001 Check for users who belong Warning
to a group that does not exist.
CC-0002 Check for users who belong Warning
to groups that are not in
dm_user.
CC-0003 Check for users who are not Error
listed in dmi_object_type.
CC-0004 Check for groups that are not Error
listed in dmi_object_type.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 651

Appendix D. Consistency Checks

Consistency check number Consistency check Severity

description
CC-0005 Check for groups that belong Warning
to groups that do not exist.
CC-0006 Check for groups belonging Warning
to supergroups that do not
exist.
CC-0081 Check for groups with Warning
disconnected super groups.
CC-0082 Check for groups with Warning
disconnected subgroups.

D.3 ACL checks

The consistency checks in the following table apply to ACLs.

Table D-2: Consistency checks for ACLs

Consistency check number Consistency check Severity

description
CC-0007 Check for ACLs containing Warning
users who do not exist in the
repository.
CC-0008 Check for ACLs which are Error
missing dm_acl_r entries.
CC-0009 Check for SysObjects whose Warning
acl_domain is set to a user
who does not exist in the
repository.
CC-0010 Check for SysObjects that Warning
belong to users who do not
exist in the repository.
CC-0011 Check for SysObjects that are Warning
set to ACLs that do not exist.
CC-0012 Check for ACL objects with Error
missing dm_acl_s entry.
CC-0013 Check for ACL objects with Error
r_accessor_permit values that
are missing r_accessor_name
values.
CC-0014 Check for ACL objects with Error
r_accessor_name values that
are missing
r_accessor_permit values.

652 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Consistency Checks

Consistency check number Consistency check Severity

description
CC-0015 Check for ACL objects with Error
r_is_group values that are
missing r_accessor_permit
values.
CC-0016 Check for ACL objects with Error
r_is_group values that are
missing r_accessor_name
values.
CC-0017 Check for ACL objects with Error
r_accessor_name values that
are missing r_is_group
values.
CC-0018 Check for ACL objects with Error
r_accessor_permit values that
are missing r_is_group
values.

D.4 SysObject checks

The consistency checks in the following table apply to SysObjects.

Table D-3: Consistency checks for SysObjects

Consistency check number Consistency check Severity

description
CC-0019 Check for SysObjects that are Error
not referenced in
dmi_object_type.
CC-0020 Check for SysObjects that Warning
point to non-existent content.
CC-0021 Check for SysObjects that are Warning
linked to non-existent
folders.
CC-0022 Check for SysObjects that are Warning
linked to non-existent
primary cabinets.
CC-0023 Check for SysObjects that Warning
reference non-existent
i_chronicle_id.
CC-0024 Check for SysObjects that Warning
reference non-existent
i_antecedent_id.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 653

Appendix D. Consistency Checks

Consistency check number Consistency check Severity

description
CC-0025 Check for SysObjects with Error
dm_sysobject_s entry but
missing dm_sysobject_r
entries.
CC-0026 Check for SysObjects with Error
dm_sysobject_r entries but
missing dm_sysobject_s
entries.

D.5 Folder and cabinet checks

The consistency checks in the following table apply to folders and cabinets.

Table D-4: Consistency checks for folders and cabinets

Consistency check number Consistency check Severity

description
CC-0027 Check for folders with Error
missing dm_folder_r entries.
CC-0028 Check for folders that are Error
referenced in dm_folder_r
but not in dm_folder_s.
CC-0029 Check for dm_folder objects Error
that are not referenced in
dmi_object_type.
CC-0030 Check for dm_folder objects Error
that are missing
dm_sysobject entries.
CC-0031 Check for folders with non- Warning
existent ancestor_id.
CC-0032 Check for cabinet objects that Error
are missing dm_folder_r
table entries.
CC-0033 Check that cabinet objects are Error
not referenced in
dmi_object_type.
CC-0034 Check for folder objects that Error
are missing dm_sysobject_r
entries.
CC-0035 Check for folder objects with Error
null r_folder_path.

654 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Consistency Checks

D.6 Document checks

The consistency checks in the following table apply to documents.

Table D-5: Consistency checks for documents

Consistency check number Consistency check Severity

description
CC-0036 Check for documents with a Error
dm_sysobject_s entry but no
dm_document_s entry.
CC-0037 Check for documents with Error
missing dm_sysobect_s
entries.
CC-0038 Check for documents with Error
missing dmi_object_type
entry.

D.7 Content object checks

The consistency checks in the following table apply to content objects.

Table D-6: Consistency checks for content objects

Consistency check number Consistency check Severity

description
CC-0039 Check for content objects Warning
referencing non-existent
parents.
CC-0040 Check for content with Warning
invalid storage_id.
CC-0041 Check for content objects Warning
with non-existent format.

D.8 Workflow checks

The consistency checks in the following table apply to workflows.

Table D-7: Consistency checks for workflows

Consistency check number Consistency check Severity

description
CC-0042 Check for dmi_queue_item Warning
objects with non-existent
queued objects.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 655

Appendix D. Consistency Checks

Consistency check number Consistency check Severity

description
CC-0043 Check for dmi_workitem Warning
objects that reference non-
existent dm_workflow
objects.
CC-0044 Check for workflow objects Error
with missing
dm_workflow_s entry.
CC-0045 Check for dmi_package Error
objects with missing
dmi_package_s entries.
CC-0046 Check for dmi_package Warning
objects that reference non-
existent dm_workflow
objects.
CC-0047 Check for workflow objects Warning
with non-existent
r_component_id.
CC-0048 Check for dmi_workitem Error
objects with missing
dmi_workitem_s entry.

D.9 Object type checks

The consistency checks in the following table apply to object types.

Table D-8: Consistency checks for object types

Consistency check number Consistency check Severity

description
CC-0049 Check whether any dm_type Error
objects reference non-existent
dmi_type_info objects.
CC-0050 Check whether any Error
dmi_type_info objects
reference non-existent
dm_type objects.
CC-0051 Check whether any types Error
have corrupted property
positions.
CC-0052 Check whether any types Error
have invalid property counts.

656 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Consistency Checks

D.10 Data dictionary checks

The consistency checks in the following table apply to the data dictionary.

Table D-9: Consistency checks for the data dictionary

Consistency check number Consistency check Severity

description
CC-0053 Check whether any duplicate Error
dmi_dd_attr_info objects
exist.
CC-0054 Check whether any duplicate Error
dmi_dd_type_info objects
exist.
CC-0055 Check whether any Error
dmi_dd_attr_info objects are
missing an entry in
dmi_dd_common_info_s.
CC-0056 Check whether any Error
dmi_dd_type_info objects are
missing an entry in
dmi_dd_common_info_s.
CC-0057 Check whether any Error
dmi_dd_attr_info objects are
missing an entry in
dmi_dd_attr_info_s.
CC-0058 Check whether any Error
dmi_dd_type_info objects are
missing an entry in
dmi_dd_type_info_s.
CC-0078 Check whether any data Error
dictionary objects reference
non-existent default policy
objects.

D.11 Lifecycle checks

The consistency checks in the following table apply to document lifecycles.

Table D-10: Consistency checks for lifecycles

Consistency check number Consistency check Severity

description
CC-0059 Check for any dm_sysobject Warning
objects that reference non-
existent dm_policy objects.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 657

Appendix D. Consistency Checks

Consistency check number Consistency check Severity

description
CC-0060 Check for any policy objects Warning
that reference non-existent
types in included_type.
CC-0061 Check for any policy objects Error
with missing dm_sysobject_s
entries.
CC-0062 Check for any policy objects Error
with missing dm_sysobject_r
entries.
CC-0063 Check for any policy objects Error
with missing dm_policy_r
entries.
CC-0064 Check for any policy objects Error
with missing dm_policy_s
entries.

D.12 Object type index checks

The consistency checks in the following table apply to object type indexes.

Table D-11: Consistency checks for object type indexes

Consistency check number Consistency check Severity

description
CC-0073 Check for dmi_index objects Warning
that point to non-existent
types.
CC-0074 Check for types with non- Warning
existent dmi_index object for
_s table.
CC-0075 Check for types with non- Warning
existent dmi_index object for
_r table.
CC-0076 Check for indexes with Warning
invalid property positions.

658 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Consistency Checks

D.13 Method object consistency checks

These consistency checks in the following table apply to method objects.

Table D-12: Consistency checks for method objects

Consistency check number Consistency check Severity

description
CC-0077 Check for methods using Warning
jview rather than Java.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 659

Appendix E. Plug-in Library Functions for External
Stores
E.1 General recommendations
The following sections describe the C functions that you must implement to support
Documentum Server operations through the plug-in:

• Call dm_init_content once when the plug-in is loaded. Call dm_plugin_version

once after the plug-in is loaded.
• Use dm_open_content once for each getFile or getContent operation. Use
dm_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 is unloaded.
• You can find sample code for a plug-in the unsupported directory.

E.2 dm_close_all
The dm_close_all function is called by the plug-in when a session is terminated. The
function is called to let the plug-in library cleanup any internal data structure(s) for
the specified session.

The function definition is:

void dm_close_all (long <session>)

The following table describes arguments for the dm_close_all function.

Table E-1: dm_close_all arguments

Argument Description
session Identifies the terminated session.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 661

Appendix E. Plug-in Library Functions for External Stores

E.3 dm_close_content
The dm_close_content function is called by the plug-in to perform internal cleanup.
This function is called after the read operation for the supplied handle is completed
or or if the read operation is interrupted. The function returns a boolean value.

The function definition is:

BOOL dm_close_content (long <handle>)

The following table describes the argument for the dm_close_content function.

Table E-2: dm_close_content arguments

Argument Description
handle Identifies the read request.

E.4 dm_deinit_content
The dm_deinit_content function performs global internal cleanup operations. The
function is called just before the server or client unloads the plug-in library, to let the
plug-in perform any global internal cleanup operations.

The function definition is:

void dm_deinit_content(void)

E.5 dm_init_content
The dm_init_content function initializes internal data structures. This is the first
function called by Documentum Server after the plug-in library is loaded.

The function definition is:

BOOL dm_init_content (long <maxsession>,
int <mode>)

The following table describes the arguments for the dm_init_content function.

Table E-3: dm_init_content arguments

Argument Description
maxsession Contains the maximum number of
concurrent sessions.
mode Indicates who is invoking the plug-in. The
only valid value is 0, indicating the server.

662 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Plug-in Library Functions for External Stores

The function returns a positive value for successful initialization. A negative return
value forces the server to unload the plug-in library. This function should return a
positive value when called multiple times within the same address space.

E.6 dm_open_content
The 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>)

The following table describes the arguments for the dm_open_content function.

Table E-4: dm_open_content arguments

Argument Description
session Indicates the session that needs to retrieve
the content.
other_args Indicates the <other_args> supplied when
executing a Mount method. NULL for the
dm_extern_url, dm_extern_free storage
types and when the token specified in a
Setpath operation is an 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 library to retrieve an attribute value
for the supplied external storage object ID.
handle Identifies the read request. Filled in on
initiaization and passed 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
initialization and fills in a value for the handle. For subsequent read operations for
this token, the handle 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 thread
servicing a particular read request, with a dispatching mechanism based on the
handle value. For example, for dm_extern_file store objects, <other_args> is the root
path.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 663

Appendix E. Plug-in Library Functions for External Stores

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 the
def_client_root attribute.

For server side plug-in configurations, <other_args> points to the directory

represented by the a_location value for the current sever configuration. If no
a_location is configured for the current server configuration, it points to the
directory represented by the def_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
position parameter should be zero when requesting an attribute value for an single-
valued attribute and should be zero or greater for multi-valued attributes.

When this callback function is called for DM_TIME datatype attribute values, the
returned 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 start
caching the content for performance reasons.

E.7 dm_plugin_version
The dm_plugin_version function enables backward compatibility for enhancement
in future releases. This function is called once immediately after the plug-in is
loaded into the process address space. The plug-in protocol version is 1.0. Therefore,
the plug-in must set major to 1 and minor to 0.

The definition of this function is:

void dm_plugin_version(unsigned int *<major>, unsigned int *<minor>)

The following table describes the arguments for the dm_plugin_version function.

Table E-5: dm_plugin_version arguments

Argument Description
major The major version number of the plug-in.
The value of this argument must be 1.
minor The minor version number of the plug-in.
The value of this argument must be set to 0.

664 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Plug-in Library Functions for External Stores

E.8 dm_read_content
The dm_read_content function requires the plug-in to return the content data into
the location 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>)

The following table describes the arguments for the dm_read_content function. 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 next byte after the
previous read.

Table E-6: dm_read_content arguments

Argument Description
handle Identifies the read request.
buffer Contains the location to return the content
data; filled with zeros when there is no more
content to be read or end-of-file is 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.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 665

Appendix F. Usage Tracking
The information in this appendix is intended to assist system administrators in
interpreting the usage tracking information provided by Documentum Server.

F.1 Usage Tracking

When a user logs into Documentum Server, the system makes an entry in a table
managed by Documentum Server global registry. If this is the first time a user has
logged in, a new line is added to the table that records the login name of the user,
the name of the application used to log in, and the time of the login. Consequent
logins replace the latest use time and the login count in the table.

When a user logs into a Documentum application, that application, in turn, logs into
Documentum Server with the credentials of the user. Therefore, one login to an
application that supports usage tracking creates or modifies two lines in the table,
one line for the application login and one line for the Documentum Server login. If
you use an application that does not support usage tracking, only the Documentum
Server line is created or modified.

For example, if a user logs in to Webtop, there are two lines modified in the global
registry. One line shows the Webtop login and one line shows the Documentum
Server login, since Webtop supports usage tracking. If a user logs in to Documentum
Server using IDQL, there is only one line modified to show the Documentum Server
login, because IDQL does not support usage tracking.

F.1.1 Tracking internal user accounts

Documentum Server creates several user accounts created for internal or system
administration purposes. Usage tracking ignores these accounts, when these
accounts are used to access Documentum Server. The Documentum Server
installation owner account is also ignored when logging into Documentum Server.

However, if these accounts are used to log in to an application, the application login
is recorded. For example, if the installation owner account is used to log into
Webtop, there is a record of the Webtop login but no record of a Documentum
Server login.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 667

Appendix F. Usage Tracking

F.1.2 Tracking unique users

You can obtain a count of unique users from Documentum Server using the
dm_usageReport job. Depending on your environment, there are cases where you
have to verify whether different user login names actually belong to different users
or only one user.

When Documentum Server is set up in domain mode, the user name stored for
usage tracking includes the user domain as well as the user login name. For
example, user1 in the marketing domain is stored as marketing\user1. If there is a
login name user1 in the engineering domain, a login for this user is stored as
engineering\user1. When usage tracking counts unique users, it counts
marketing\user1 and engineering\user1 as two distinct users. Depending on
your environment, marketing\user1 and engineering\user1 could be the same or
two different individuals.

It is also possible that some of the Documentum Servers using that global registry
for usage tracking do not use domain mode, so the user name is stored without a
domain. In this case, there can be entries for user1, engineering\user1, and
marketing\user1.

You can export the usage tracking data from a global registry if you need to examine
the individual entries and verify the unique user counts.

F.1.3 Tracking login times

Usage tracking record logins, but it does not provide user tracking in real-time.
Usage tracking keeps a cache of previous logins that is retained by each application
and Documentum Server for approximately one day. If a user logs in multiple times
in a day, the usage tracking information is typically only updated once. The purpose
of software usage tracking is to provide a long term view of usage without
impacting Documentum Server and application performance.

Specific login times for a user can be obtained from the user object on the
Documentum Server that the user logged into. That particular Documentum Server
is not necessarily the global registry that is used for usage tracking.

F.1.4 Usage tracking and software compliance

Usage tracking tracks login information for certain software over time. Software
compliance is using the software in conformance with the agreements governing the
software license. While the information provided by usage tracking can assist with
software compliance, you cannot rely upon it as your only source of compliance
information.

Usage tracking reports are provided on an “AS IS” basis for informational purposes
only. Inaccuracies can arise due to a number of factors such as inconsistencies in the
setup of the global registry, access rights, customizations, availability of usage
information within the software asset, and other similar issues. This can result in the
collection and reporting of erroneous information. We shall not be liable for any

668 OpenText™ Documentum™ Server EDCCS200200-AGD-EN-01

 Usage Tracking

errors or omissions in the data, its collection and/or reporting by usage tracking.
Regardless of the information provided by usage tracking, customers remain fully
liable for utilizing the affected software in full compliance with the authorizing
terms and quantities specified in the contract(s), quotes and purchase orders that
governed the customer procurement of the software.

EDCCS200200-AGD-EN-01 Administration and Configuration Guide 669