· 2020-03-10 · TableofContents WorkingwithpartsofaDocApp................................................................. 44 CheckingobjectsintotheDocbase

Application Builder User Guide

Version 5.3 SP1September 2005

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

Table of Contents

Preface .......................................................................................................................... 15

Part 1 Building Applications .................................................................................... 17

Chapter 1 Introduction ........................................................................................... 19Planning an application .............................................................................. 19Packaging applications as DocApps ............................................................. 20Upgrading DocApps................................................................................... 20Documentation........................................................................................... 22

Chapter 2 Working With DocApps ......................................................................... 25Connecting to a Docbase ............................................................................. 25Creating and opening a DocApp ................................................................. 26Checking the DocApp into the Docbase ....................................................... 26Saving changes to and loading changes from a local file ................................ 27Making a copy of a DocApp ........................................................................ 28Viewing and modifying properties of a DocApp or its parts .......................... 28About the Properties XML Application tab............................................... 29About the Properties Application tab ....................................................... 30About the Properties General tab ............................................................. 31About the Properties Location tab............................................................ 31About the Properties Permissions tab....................................................... 31About the Properties Reference tab .......................................................... 31About the Properties Version tab ............................................................. 32

Changing the locale .................................................................................... 32Changing the locale ................................................................................ 32Locale ................................................................................................ 33

Publishing locale-specific information to the data dictionary ..................... 33Data Dictionary .................................................................................. 34

Locale-sensitive object type fields ............................................................ 35Locale-sensitive attribute fields................................................................ 35

Setting installation options .......................................................................... 36Upgrade Options.................................................................................... 36Data Object Transfer ............................................................................... 38Renditions Included With DocApp ...................................................... 39Cannot Insert Entire Virtual Document ................................................ 39

Permission Set Alias ............................................................................... 39Location Alias ........................................................................................ 40Default Installation Locations .............................................................. 40

Owner Alias........................................................................................... 42Procedures ............................................................................................. 42

Creating a DocApp Archive ........................................................................ 43Best practices.......................................................................................... 44

Application Builder User Guide 3

Table of Contents

Working with parts of a DocApp ................................................................. 44Checking objects into the Docbase ........................................................... 44Checking objects out of the Docbase ........................................................ 45Cancelling object checkout ...................................................................... 45Cutting, copying, and pasting objects....................................................... 46Deleting objects from a Docbase .............................................................. 47Removing objects from the DocApp......................................................... 47Choosing a permission set for a SysObject or the application ..................... 47Creating and removing links to sysobjects and the application .................. 48Creating or modifying a document lifecycle (DLC) ................................... 48Document lifecycles............................................................................ 48

Adding or modifying a workflow template .............................................. 49Modifying the global components list ...................................................... 49Global components list........................................................................ 49

Turning prompts and XML application validation on and off ........................ 49

Chapter 3 Using Aliases to Make DocApps Portable ............................................. 51About alias sets .......................................................................................... 51Creating new alias sets or adding existing ones from Docbases...................... 52Specifying an alias object in an alias set ........................................................ 53Changing the DocApp’s default alias set ...................................................... 54

Chapter 4 Working With Data Objects ................................................................... 55Inserting documents ................................................................................... 55Renditions Included With DocApp .......................................................... 55Cannot Insert Entire Virtual Document .................................................... 56

Inserting a cabinet or folder hierarchy.......................................................... 56

Chapter 5 Working with Form Templates ............................................................... 57About Form Templates ............................................................................... 57Adding existing form templates from repositories ........................................ 58

Chapter 6 Working With Formats ........................................................................... 59About formats ............................................................................................ 59formats .................................................................................................. 59

Creating or modifying a format object.......................................................... 59Specifying digital asset management and full-text indexing........................... 61

Chapter 7 Working With Forms .............................................................................. 65About qualified components and forms ....................................................... 65Creating new forms or adding existing ones from Docbases .......................... 66Setting up dynamic download of 4.x and 5.x components with thesame functionality ...................................................................................... 67

Chapter 8 Working With Groups ............................................................................ 69About groups ............................................................................................. 69Adding existing groups from Docbases........................................................ 69

Chapter 9 Working With Java Libraries ................................................................. 71About Java libraries .................................................................................... 71JAR files..................................................................................................... 71

4 Application Builder User Guide

Table of Contents

Libraries and sandboxing ............................................................................ 72Adding and removing Java libraries ............................................................ 72

Chapter 10 Working With Jobs ................................................................................ 75About jobs ................................................................................................. 75Creating new jobs or adding existing ones from Docbases ............................. 75Creating or modifying a job schedule (Schedule tab) ..................................... 77Viewing job information ............................................................................. 77

Chapter 11 Working With Methods .......................................................................... 79About methods .......................................................................................... 79Creating new methods or adding existing ones from Docbases ...................... 79

Chapter 12 Working With Modules .......................................................................... 81About modules........................................................................................... 81BOF ........................................................................................................... 81Overview of BOF.................................................................................... 82BOF infrastructure .................................................................................. 82Modules and registries........................................................................ 82Dynamic delivery mechanism ............................................................. 84Global registry ................................................................................... 84Planning for the global registry ....................................................... 85Accessing the global registry ........................................................... 85

Deploying module interfaces............................................................... 86Service based objects (SBOs).................................................................... 86SBO introduction................................................................................ 86SBO architecture................................................................................. 87Implementing SBOs ............................................................................ 87Stateful and stateless SBOs .............................................................. 88Managing Sessions for SBOs............................................................ 89Overview ................................................................................... 89Structuring Methods to Use Sessions ........................................... 90Managing repository names ........................................................ 90Maintaining State Beyond the Life of the SBO............................... 90Obtaining Session Manager State Information .............................. 91

Using Transactions With SBOs......................................................... 91SBO Error Handling ........................................................................... 94SBO Best Practices .............................................................................. 94Don’t Reuse SBOs ........................................................................... 94Make SBOs Stateless ....................................................................... 94Rely on DFC to Cache Repository Data ............................................ 94

Type based objects (TBOs) ....................................................................... 94TBO introduction ............................................................................... 95Type based objects (TBOs) ................................................................... 95TBO architecture ................................................................................ 97Implementing TBOs............................................................................ 97Define an interface.......................................................................... 97Define an implementation class ....................................................... 98Implement methods of IDfBusinessObject ........................................ 98Implement the TBO’s business rules................................................. 99Overriding methods in TBOs........................................................... 99Implement COM interfaces if needed............................................. 100Avoid carrying state information ................................................... 101

TBO best practices ............................................................................ 101Avoid extending DFC interfaces .................................................... 101


Table of Contents

Design extendable TBOs or make them final................................... 101Do not replace implementation classes for Documentumtypes............................................................................................ 101Do not use UPDATE queries.......................................................... 102

Calling TBOs and SBOs......................................................................... 102Calling SBOs .................................................................................... 102Returning a TBO from an SBO ........................................................... 103Calling TBOs .................................................................................... 103

Web Services ............................................................................................ 104Overview of Web Services ..................................................................... 104SOAP and Apache Axis .................................................................... 105WSDL.............................................................................................. 105Runtime flow ................................................................................... 106Setup ........................................................................................... 106

Development flow ............................................................................ 106Installing the Web Services Framework .................................................. 107Developing a Web Service ..................................................................... 108Designing an SBO for Web Services ................................................... 108Avoid chatty interactions .............................................................. 108Do not overload methods .............................................................. 108Conform to JAX-RPC type restrictions for arguments andreturn values ................................................................................ 108Do not use Java collections ............................................................ 109Do not use interfaces for repository objects..................................... 109

Content Transfer fromWeb Services .................................................. 109Enabling a service-based business object as a Web Service ....................... 110Deploying a Web Service....................................................................... 111Updating a Web Service ........................................................................ 111Using a Web Service ............................................................................. 112

Creating new modules or adding existing ones from Docbases .................... 113Module editor: Implementation tab ....................................................... 114Module editor: Runtime Environment tab.............................................. 117Module editor: Dependencies tab .......................................................... 118Adding, removing, modifying Java libraries ....................................... 118Adding, deleting, and modifying required modules............................ 121

Module editor: Miscellaneous tab .......................................................... 122Module editor: Web Services tab ........................................................... 123

Chapter 13 Working With Object Types ................................................................. 125About object types .................................................................................... 125Naming object types ............................................................................. 127Available supertypes............................................................................. 127

Creating or modifying an object type ......................................................... 127Displaying attributes in Documentum clients ............................................ 129Creating, deleting, and modifying scopes............................................... 132Creating, deleting, and modifying the available scope definitions ............ 133

Specifying the default permission set for an object type............................... 134Specifying constraints for an object type..................................................... 134Creating and modifying application events ................................................ 135Removing an object type from a DocApp ................................................... 136Viewing data dictionary information for types and attributes ...................... 136Functionality ............................................................................................ 137Specifying the functionality of an object type.......................................... 138Specifying a new implementation for an inherited functionalityclass for an object type .......................................................................... 138


Table of Contents

Disabling an inherited functionality class for an object type..................... 139Restoring the inherited implementation of a functionality classfor an object type .................................................................................. 139Adding a functionality class and an implementation to anobject type............................................................................................ 139Specifying functionality for a component ............................................... 140Modifying qualifications for component implementing afunctionality class for an object type ...................................................... 140Removing an added functionality class from an object type ..................... 140

Creating and modifying application events ................................................ 141

Chapter 14 Working With Object Type Attributes .................................................. 143Adding or modifying an object type attribute ............................................. 143Adding or modifying an object type attribute (Advanced tab) ..................... 145Input Mask field for an object type attribute ........................................... 146

Specifying search characteristics for object type attributes ........................... 147Search operators ....................................................................................... 147Specifying a constraint expression for an object type attribute ..................... 150Specifying value assistance for an object type attribute................................ 151Specifying conditional value assistance ...................................................... 151$value kyword ..................................................................................... 152Repeating value attribute keywords....................................................... 154

Creating or modifying a value mapping table for an object typeattribute ................................................................................................... 155Removing an attribute from an object type ................................................. 156

Chapter 15 Working With Permission Set Templates ............................................. 157About permission set templates................................................................. 157Creating new permission set templates or adding existing onesfrom Docbases.......................................................................................... 158

Chapter 16 Working With Procedures .................................................................... 161About procedures..................................................................................... 161Creating new procedures or adding existing ones from Docbases ................ 161Creating pre- and post-installation procedures ........................................... 162Pre-installation procedure ..................................................................... 163Post-installation procedure.................................................................... 163

Chapter 17 Working With Queue Management Objects: Doc Proles,User Proles, and Work Queues ......................................................... 165About Doc Profiles ................................................................................... 165About User Profiles .................................................................................. 165About Work Queues ................................................................................. 166Adding existing doc profiles, user profiles, and work queues fromDocbases.................................................................................................. 166

Chapter 18 Working With Relation Types .............................................................. 167About relation types ................................................................................. 167Relation types ...................................................................................... 167

Creating or modifying a relation type object ............................................... 167


Table of Contents

Chapter 19 Working With Roles ............................................................................. 171About roles .............................................................................................. 171Adding existing roles from Docbases ......................................................... 171

Chapter 20 Working With XML Applications .......................................................... 173Introduction to XML content management ................................................. 173XML application components.................................................................... 174Creating XML applications........................................................................ 175Confirming the specifications for creating an XML application ................ 177

Checklist for creating an XML application .................................................. 177Tasks to perform before creating an XML application.................................. 179Specifying validation options for XML documents using an XMLapplication ............................................................................................... 180Specifying XML application detection and DTD patching options................ 181Specifying a supporting files folder for an XML application......................... 183Specifying a sample XML documents folder ............................................... 183Validating XML applications ..................................................................... 184XML application validation results ............................................................ 185Tasks to perform after creating XML applications ....................................... 187Modifying XML applications..................................................................... 187Viewing and editing the XML application configuration file ........................ 188

Chapter 21 Understanding Document Lifecycles .................................................. 191About document lifecycles ........................................................................ 191DLCs, workflows, and business processes .................................................. 192States and transitions ................................................................................ 193How document lifecycle states model document life stages ..................... 193Document lifecycle state diagram ...................................................... 193

Transitions ........................................................................................... 194Attachment ...................................................................................... 195Promotion and demotion .................................................................. 195Suspension and resumption .............................................................. 195Returning versioned or saved objects to the base state......................... 195

Attribute constraints ............................................................................. 196Functionality ........................................................................................ 196

Aliases ..................................................................................................... 197Alias sets.............................................................................................. 197Using scopes to resolve aliases............................................................... 197Document lifecycle scope .................................................................. 197Session scope ................................................................................... 198User scope ....................................................................................... 198System scope.................................................................................... 198

Versions ................................................................................................... 199

Chapter 22 Creating and Modifying Document Lifecycles ..................................... 201Creating or modifying a DLC .................................................................... 201Specifying a document lifecycle validation procedure ............................. 204Designing the validation procedure ................................................... 204

Editing a document lifecycle state .............................................................. 205Specifying attachment, demotion, and schedule transition settings .............. 206


Table of Contents

Specifying a state type .............................................................................. 207Specifying entry criteria and procedure for a document lifecyclestate......................................................................................................... 208Designing entry criteria......................................................................... 209Writing the entry procedure .................................................................. 209Evaluating entry criteria........................................................................ 210

Specifying actions and a procedure for a DLC state..................................... 210Writing action procedures ..................................................................... 214

Specifying the Change Content Storage action to move content tostorage areas ............................................................................................ 215Specifying or modifying a post-change procedure for a documentlifecycle state............................................................................................ 216Designing the post-change procedure .................................................... 216

Specifying changes to attribute properties in a document lifecyclestate......................................................................................................... 217Specifying functionality ............................................................................ 217Editing document lifecycle state functionality (overview)........................ 218Modifying functionality in a document lifecycle state.............................. 218Modifying inherited functionality in a document lifecycle state ............... 219Disabling inherited functionality in a document lifecycle state................. 219Restoring Inherited Functionality in a Document Lifecycle State .............. 219Adding functionality in a document lifecycle state.................................. 220Specifying component functionality in a document lifecyclestate................................................................................................. 220

Removing added functionality in a document lifecycle state.................... 220

Part 2 Installing Applications ................................................................................. 223

Chapter 23 Overview ............................................................................................. 225

Chapter 24 How to Use .......................................................................................... 227How to Use .............................................................................................. 227Preparing the Target Docbase .................................................................... 229How to use Application Installer From the Command Line ......................... 229Specifying Aliases in the Properties File ................................................. 231

Chapter 25 Installation Process ............................................................................. 233Installation Process ................................................................................... 233How Duplicate Objects Are Installed ......................................................... 236Upgrade Options.................................................................................. 236

Where Objects Are Installed ...................................................................... 237Location Alias ...................................................................................... 238Default Installation Locations ............................................................ 238

How Object Owners Are Assigned ............................................................ 239Owner Alias......................................................................................... 240

How Permission Sets Are Assigned to Objects ............................................ 240Permission Set Alias ............................................................................. 240

How Cabinet, Folder, and XML Application Content Is Installed ................. 241Data Object Transfer ............................................................................. 241Renditions Included With DocApp .................................................... 242Cannot Insert Entire Virtual Document .............................................. 242

How Pre- and Post-Installation Procedures Are Used.................................. 242


Table of Contents

Procedures ........................................................................................... 242

Chapter 26 Troubleshooting .................................................................................. 245Solving errors that occur while running Application Installer ...................... 245Installation Log File .................................................................................. 246

Part 3 Tutorials ...................................................................................................... 247

Chapter 27 Basic Tutorial: Creating DocApps ....................................................... 249Overview ................................................................................................. 249Prerequisites ........................................................................................ 250Software requirements .......................................................................... 250Source files........................................................................................... 250

Application Builder user interface ............................................................. 251Design of the ProductBase DocApp ........................................................... 252Using the ProductBase DocApp............................................................. 253Installing the DAB525Tutorial DocApp .................................................. 253

Module 1: Designing object types and displaying attributes to users ............ 254Creating a new DocApp........................................................................ 254Designing a new type ........................................................................... 255Summary ............................................................................................. 260Testing your DocApp............................................................................ 260

Module 2: Designing a user and security environment................................ 261Creating users ...................................................................................... 262Creating users and modifying groups in the Docbase.............................. 263Adding aliases to alias sets .................................................................... 265Creating permission set templates ......................................................... 266Applying permission set templates to cabinets and folders ...................... 268Summary ............................................................................................. 268

Module 3: Designing document lifecycles .................................................. 269Summary ............................................................................................. 272Testing your lifecycle ............................................................................ 272

Module 4: Designing workflows................................................................ 274Summary ............................................................................................. 278Testing your workflow .......................................................................... 278

Module 5: Configuring Installation Options and DeployingDocApps to Other Docbases ...................................................................... 279Summary ............................................................................................. 283

Chapter 28 Intermediate Tutorial: Creating DocApps ............................................ 285Overview ................................................................................................. 285Prerequisites ........................................................................................ 286Software requirements .......................................................................... 286Source files........................................................................................... 287Creating users ...................................................................................... 287

Module 6: Adding Docbasic code using jobs and methods .......................... 288Creating a method ................................................................................ 288Creating a job ....................................................................................... 290Job failed to execute .............................................................................. 291Summary ............................................................................................. 292Testing your job.................................................................................... 292Other troubleshooting tips .................................................................... 294


Table of Contents

Module 7: Retiring object types and specifying object typeconstraints ............................................................................................... 294Adding the sales_info_dates type .......................................................... 294Specifying constraints ........................................................................... 295Retiring the sales_info type ................................................................... 296Summary ............................................................................................. 296Testing the sales_info_dates type ........................................................... 297

Module 8: More on attributes—search options, input masks,constraints, value mapping, and conditional value assistance ...................... 298Specifying search options ...................................................................... 299Specifying input masks ......................................................................... 299Specifying constraints ........................................................................... 300Adding a constraint .......................................................................... 300

Specifying value mapping ..................................................................... 301Specifying a DQL query for default value assistance ............................... 302Summary ............................................................................................. 303Testing your customized type ................................................................ 303

Module 9: More on document lifecycles—post-changes, attributeproperties, functionality ............................................................................ 305Implementing post-change procedures .................................................. 305Modifying attribute properties and functionality .................................... 307Summary ............................................................................................. 308Testing ................................................................................................. 308

Module 10: A more complex workflow—triggers, transitions,dynamic next performer and spanning multiple states ................................ 308Specifying that one input flow can trigger an activity .............................. 310Specifying that a performer of one activity specifies theperformers of a following activity .......................................................... 311Summary ............................................................................................. 311Testing ................................................................................................. 312

Module 11: Using document lifecycles and workflows withmultiple sets of users ................................................................................ 313Modifying the document lifecycle and workflow template ...................... 314Summary ............................................................................................. 316Testing ................................................................................................. 316

Part 4 Quick Reference .......................................................................................... 319

Chapter 29 Error Messages ................................................................................... 321


Table of Contents

List of Figures

Figure 27–1. EMC | Documentum Application Builder ..................................................... 251Figure 27–2. SalesInfoCycle document lifecycle ................................................................ 270Figure 27–3. ReviewWkflow workflow ............................................................................ 274Figure 28–1. Approval workflow ..................................................................................... 309


Table of Contents

List of Tables

Table 1–1. Modifications to Your DocApp that Require Pre- or Post-installationChanges..................................................................................................... 21

Table 1–2. Documentation of Special Interest to Application Developers ............................ 22Table 9–1. Java libraries dialog box fields ......................................................................... 73Table 12–1. IDfBusinessObject methods to implement ........................................................ 98Table 12–2. Java libraries dialog box fields ....................................................................... 119Table 12–3. Java libraries dialog box fields ....................................................................... 120Table 12–4. Required Modules Dialog Box Fields ............................................................. 121Table 12–5. Required Modules Dialog Box Fields ............................................................. 122Table 14–1. Valid Mask Characters .................................................................................. 146Table 20–1. Checklist for creating an XML application ...................................................... 178Table 21–1. Alias set attributes in session config object...................................................... 198Table 21–2. User scope attributes in dm_user ................................................................... 198Table 21–3. System scope attributes in dm_server_config.................................................. 199Table 27–1. Products in each product line ........................................................................ 252Table 27–2. Values for product_name attribute................................................................. 256Table 27–3. First value assistance clause for product_name attribute.................................. 258Table 27–4. Second conditional value assistance clause for product_name attribute ............ 258Table 27–5. Third conditional value assistance clause for product_name attribute .............. 259Table 27–6. Attribute values for Author user ................................................................... 264Table 27–7. Values for SalesInfoCycle documentlifecycle .................................................. 270Table 27–8. Actions for SalesInfoCycle document lifecycle ................................................ 271Table 27–9. Actions of ReviewWkflow workflow flows and activities ................................ 275Table 27–10. Attribute values for Approve-to-Review reject flow ....................................... 276Table 28–1. Attribute balues for notifyArchiveSalesInfo method........................................ 289Table 28–2. Attribute values for notifyArchiveSalesInfo job............................................... 291Table 28–3. Values for product_line attribute ................................................................... 301Table 28–4. Values for distribution attribute ..................................................................... 302Table 28–5. Performer title for Engineering Review activity .............................................. 315Table 28–6. Performer title for Dept. Head Approval activity ............................................ 315


Table of Contents


Preface

This manual explains how to develop DocApps, which are Content Server applications. This manualdescribes the concepts and provides instructions for developing DocApps and deploying themto Docbases. It includes tutorials that develop basic and intermediate DocApps that include allthe parts of a DocApp.

For information about customizing Desktop components, see the Desktop Development Kit DevelopmentGuide.

Intended AudienceThis manual is for application programmers who have a general idea of how EMC| Documentum systems work.

Revision HistoryThe following changes have been made to this document.

Revision History

Revision Date Description

September 2005 Initial release for version 5.3 SP1.


Preface


Part 1

Building Applications

These topics are included:• Chapter 1, Introduction• Chapter 2, Working With DocApps• Chapter 3, Using Aliases to Make DocApps Portable• Chapter 4, Working With Data Objects• Chapter 5, Working with Form Templates• Chapter 6, Working With Formats• Chapter 7, Working With Forms• Chapter 8, Working With Groups• Chapter 9, Working With Java Libraries• Chapter 10, Working With Jobs• Chapter 11, Working With Methods• Chapter 12, Working With Modules• Chapter 13, Working With Object Types• Chapter 14, Working With Object Type Attributes• Chapter 15, Working With Permission Set Templates• Chapter 16, Working With Procedures• Chapter 17, Working With Queue Management Objects: Doc Profiles, User Profiles,

and Work Queues• Chapter 18, Working With Relation Types• Chapter 19, Working With Roles• Chapter 20, Working With XML Applications• Chapter 21, Understanding Document Lifecycles• Chapter 22, Creating and Modifying Document Lifecycles


Building Applications


Chapter 1Introduction

These topics are included:• Planning an application, page 19• Packaging applications as DocApps, page 20• Upgrading DocApps, page 20• Documentation, page 22

Planning an applicationA typical DocApp involves one or more new document types and document lifecycles(DLCs). Before you begin to work on such a DocApp in Application Builder, answerthe following questions:• What kinds of content does your customization apply to?

The objects that you deal with are probably documents. Choose a unique name foreach object type that your customization handles differently from dm_document.Choose names that are not in use in any Docbase in which you plan to install yourcustomization.

If you introduce more than one object type, decide whether a hierarchy existsamong them. Draw a picture of the hierarchy to refer to when you create the typesin Application Builder.

Identify and name any new attributes of the types you introduce.• What DLCs apply to your object types?

If unique business policies apply to the types you introduce, plan to create one ormore DLCs to reflect these policies. Choose unique DLC names not in use in anyDocbase in which you plan to install your customization.

Sketch out the states, entry criteria, and actions of your DLCs.• What are the parameters of the customization?


Introduction

If you intend to deploy your customization in different environments, identifyand choose names for the aspects of the customization that change from oneenvironment to the next. User names, permission sets, and Docbase locations fallinto that category.

The parameters of your customization become the alias names in your DocApp’sdefault alias set.

• Does your customization require special user interaction, validation, or Docbaseaccess?

If the answer is yes, you may need to develop Desktop components that apply onlyto your types, possibly only in certain states of their DLCs. You may wish to do thisbefore building the DocApp with Application Builder.

• Does your customization include elements (for example, SmartLists) that areindependent of object type?

If the answer is yes, make note of them to ensure that you include them in theDocApp and designate them as global.

After this planning work, you are ready to begin using Application Builder. TheApplication Builder online help explains how to carry out specific tasks.

Packaging applications as DocAppsThe Docbases in which EMC | Documentum applications run are often key businesssupport elements. Their integrity and continuing operation can be vital to an enterprise’ssuccess. As a result, developers usually develop and thoroughly test their applicationson development Docbases before deploying them to production Docbases. To supportthis model, EMC | Documentum packages application elements into a single entitycalled a DocApp. A DocApp archive is a portable representation of a DocApp in a file onthe file system. DocApps simplify developing and redeploying applications. You needonly keep track of one entity, the DocApp. For example, EMC | Documentum Desktophas a DocApp, called DcDesktopClient. In order to use Desktop to access a Docbase,you must first install DcDesktopClient in that Docbase.

Because a DocApp primarily consists of Content Server objects, you should have athorough understanding of Content Server. For more information about Docbase objects,see the Documentum Content Server Fundamentals.

Upgrading DocAppsYou can use Application Installer to upgrade existing DocApps. After modifying theDocApp in the source (or development) Docbase, create a DocApp archive and install


Introduction

it into the target Docbase. Use the installation options to establish whether to run apre- or post-installation procedure, how to upgrade existing objects, which cabinet andfolder objects are installed, and the location, permissions, and owners of sysobjects in thetarget Docbase. A pre-installation procedure is a Docbasic script (called a procedure)that Application Installer runs before it begins installation of the DocApp archive. Apost-installation procedure is a Docbasic script that Application Installer runs after itcompletes installation of the DocApp archive.

Note: Some modifications require that you use a pre-installation procedure or makefurther modifications after you install the DocApp in the target Docbase (manually or byusing a post-installation procedure). These modifications and the pre- or post-installationrequirements that they require are described in Table 1–1, page 21. Although you canmake the required pre- or post-installation changes using other methods, the methodsshown in Table 1–1, page 21 are recommended by EMC | Documentum.

Table 1-1. Modications to Your DocApp that Require Pre- or Post-installation Changes

Modifications Recommended Pre- or Post-installation Changes

You created new aliases (that do not existin the target Docbase) used in permissionset templates that are assigned to objectsof type dm_sysobject or a subtype (usingthe installation options) at installationtime.

Set the default alias set of the object owner to theDocApp alias set (usually the DocApp’s default aliasset) that contains the new aliases. Use installationoptions to set the object owner, which can be eitherthe user account installing the DocApp archive or anowner alias that you specified. This ensures that thealiases will be correctly resolved at installation time. Ifthe user specified using the installation options doesnot exist in the target Docbase, use a pre-installationscript to create the user and specify the DocApp aliasset as the user’s default alias set.

You chose the “all content” or“hierarchical structure” installationoption to install subfolders that do notexist in the target Docbase and you wantto assign a permission set template orother attribute values to the subfolders.

Use a post-installation procedure to set those attributevalues.

You chose the “all content” or“hierarchical structure” installationoption to install subfolders that do notexist in the target Docbase and that arespecified as location aliases in otherobjects (for example, document lifecycles).

Set the location aliases to prompt the installer forthe paths (upon installation, the installer choosestemporary paths) and then use a post-installationprocedure to change the aliases to the correct paths.

Note: If the alias set is specified in an installeddocument lifecycle, the post-installation proceduremust uninstall the document lifecycle, save changes tothe alias set, and then reinstall the document lifecycle.


Introduction

The createUsers procedure in the basic tutorial’s ProductBase DocApp is an example ofa pre-installation procedure that modifies the DocApp’s alias set and the installationuser. The modifyUserFolders procedure in the basic tutorial’s ProductBase DocApp isan example of a post-installation procedure that modifies the installed folders and theDocApp’s alias set.

DocumentationTable 1–2, page 22 lists the online and printed documentation for related subjects.

Table 1-2. Documentation of Special Interest to Application Developers

Documentation Description

Application BuilderOnline Help

Instructions on how to use the Application Builder interface.Access via the Application Builder Help menu.

Workflow ManagerOnline Help

Information about building workflow templates usingWorkflow Manager.

XML ConfigurationEditor Online Help

Information about creating and modifying EMC |Documentum XML application configuration files using theXML Configuration Editor.

Business ProcessManager Online Help

Information about building workflow templates usingBusiness Process Manager.

Content ServerFundamentals

PDF manual that describes the basic features of the ContentServer and how to use them in an application environment.

Object Reference Manual PDF manual that contains basic information about objects,types, and attributes and a full object type reference.

DQL Reference Manual PDF manual that describes basic elements of DocumentQuery Language (DQL) and provides a full DQL reference.

API Reference Manual PDF manual that lists server API methods by task andprovides a full server API reference.

Docbasic User’s Guide Printed reference for all elements of Docbasic.

Docbasic Reference Language reference for all elements of Docbasic. Access viaApplication Builder online help.

DocumentumFoundation ClassesDevelopment Guide

Printed guide to developing EMC | Documentumapplications using DFC.


Introduction

Documentation Description

DFC Javadocs HTML format reference for DFC interfaces. Access viaApplication Builder online help.

Desktop Development KitDevelopment Guide

PDF manual for customizing Desktop and Desktopintegrations, and customizing standard and developing newDesktop components.

Also includes the reference for EMC | Documentum ActiveXcontrols that you can use in Visual Basic and the referencefor Desktop interfaces and enumerations.

WorkspaceCustomizations toDocumentum DesktopMigration Guide

Printed guide to migrating customizations of Workspace toDesktop.


Introduction


Chapter 2Working With DocApps

These topics are included:• Connecting to a Docbase, page 25• Creating and opening a DocApp, page 26• Checking the DocApp into the Docbase, page 26• Saving changes to and loading changes from a local file, page 27• Making a copy of a DocApp, page 28• Viewing and modifying properties of a DocApp or its parts, page 28• Changing the locale, page 32• Setting installation options, page 36• Creating a DocApp Archive, page 43• Working with parts of a DocApp, page 44• Turning prompts and XML application validation on and off, page 49

Connecting to a DocbaseYou must be connected to a Docbase to run Application Builder. When you startApplication Builder, it presents the Login dialog box automatically.

To connect to a Docbase:

1. Perform one of these actions:• To start Application Builder, choose Start → Documentum → Application

Builder.• If you have already started Application Builder, choose File→ Disconnect.

You can only be connected to one Docbase at a time.The Login dialog box is displayed.

2. Select the Docbase to which you want to connect.


Working With DocApps

3. Enter your user name and password.

4. If you are using a Windows server and your domain name is required, enter it.

5. Click Connect.To connect to a different Docbase, choose File → Disconnect. Application Builderdisconnects you from the Docbase and presents the Login dialog.

Creating and opening a DocAppTo create a new DocApp:

1. Choose File → New (or click the New DocApp icon on the toolbar).

2. Specify the DocApp name.

To open an existing DocApp from the Docbase:

1. Choose File → Open from Docbase (or click the Open from Docbase icon onthe toolbar).

2. Navigate to the DocApp (in /System/Applications/DocAppName) and double-clickits icon.

Each DocApp resides in its own subfolder of the Applications folder in the Systemcabinet of the Docbase. The DocApp and its folder have the same name.

After creating a new DocApp or opening an existing one, use the Insertmenu and theDocApp explorer to create and display the parts of the DocApp. Double-click a namein the DocApp explorer to open the appropriate editor.

To save your changes, you can either check them into the Docbase (see Checking theDocApp into the Docbase, page 26 or Checking objects into the Docbase, page 44) or savethem to a file on the local file system if you are not yet ready to check them in (see Savingchanges to and loading changes from a local file, page 27).

Checking the DocApp into the DocbaseTo check a DocApp into the Docbase:

1. Choose DocApp → Check In DocApp.The Check In All Objects dialog box appears.

2. For the DocApp and each checked out object in it, fill in the entries in thecorresponding row.



• Clicking a column header opens a drop-down menu. The menu items help youfill in the entries in the column. Each menu is specific to the kind of informationin its column.

• The Check In column menu has no effect in this dialog box. In the Check InObject dialog box, it lets you specify Yes or No for the selected row.

• The Version column menu lets you specify Same, Minor, or Major. These are thestandard EMC | Documentum client checkin options.

• In the Description and Label columns, the single menu item enables you to fillthe column with the contents of the entry in the top row.

• The Retain Lock menu enables you to specify Yes or No. If you specify yes,Application Builder updates the Docbase version of the item but leaves itchecked out.

Saving changes to and loading changes froma local le

DocApps exist only within Docbases. A DocApp archive allows you to move a DocAppfrom one Docbase to another.

You cannot save a complete, functional DocApp to the file system. The Open, Save, andSave As choices on the Filemenu enable you to save and restore changes that you arenot yet ready to check in.

When you use Open to restore saved changes from a file, the system synchronizes thesaved changes with the DocApp in the Docbase. This can force you to choose betweenchanges that exist in the file and changes that someone made to the Docbase after youcreated the file.

To save changes to a le on the local le system:

1. Choose File→ Save (or click the Save icon on the toolbar) or File→ Save As.

2. Navigate to a folder on the local file system, name your file, and click Save.

To load a DocApp’s changes previously saved to a le on the local le system:

1. Choose File→ Open (or click the Open from Filesystem icon on the toolbar).

2. Navigate to the DocApp on your local filesystem and double-click its icon.



Making a copy of a DocAppTo make a copy of the current DocApp in the Docbase:

1. Check in the current DocApp.

2. Choose File → Save As in Docbase.

3. Enter the name of the copy of the current DocApp.

4. Click Create.The new DocApp is created in the Docbase and opened in Application Builder. Thenew DocApp consists of:• References to the same objects, except for global components, in the original DocApp• New copies of all global components (and their associated dm_qual_comp objects)

in the original DocApp• A new default alias set for the copy• The same installation options and properties for the DocApp (except for the location

and default alias set) and objects as in the original DocApp

Viewing and modifying properties of a DocAppor its parts

To view the properties of a DocApp or its parts:

1. Select the DocApp or one of its parts in the DocApp explorer.

2. Choose View→ Properties or Properties from the context menu (right-click).

To modify the properties of a DocApp or its parts:

1. Select the DocApp or one of its parts in the DocApp explorer.

2. Choose DocApp → Check Out Object(s) or Check Out Object(s) from the contextmenu (right-click).

3. Choose File→ Properties or Properties from the context menu (right-click).The properties window has two, four, or five tabs, depending on whether the selectedobject is a persistent object, a sysobject in the DocApp, or the DocApp itself.

For a persistent object, the tabs are:• General – Displays the object name, owner, lock owner, and time of last modification.• Reference – Displays the references to the object.For a sysobject, the tabs are General and Reference as above, plus:



• Version – Displays the Docbase version label.• Location – Displays the Docbase folder containing the object and links to the object;

you can change the links.• Permissions – Displays the associated permission set or ACL; you can choose the

associated permission set or ACL.For an XML application, the tabs are the same as for a sysobject, but without a Versiontab and with an XML Application tab:• XML Application – Displays application detection options that you can change.For the DocApp itself, the tabs are the same as for a sysobject, but with an Applicationtab instead of the Reference tab:• Application – Displays the version, copyright notice, and default alias set; you can

change these properties.

About the Properties XML Application tab

The XML Application tab appears in the Properties dialog box when the object youselect is an XML application. It displays, and allows you to modify, the XML applicationdetection and system ID patching options:

Field Description

System ID If you have specified a DTD, the DTD name is displayed here andyou cannot change it. Otherwise, you can change the DTD name,which is retrieved from the <sys_id> value in the XML applicationconfiguration file; you also must change it in the XML applicationconfiguration file.

If you want the system ID of an XML document to be replaced (orpatched) with the location of the downloaded DTD on export orcheck out, then you must specify the DTD in this field.

Public ID The universal resource identifier (URI) is retrieved from the<pub_id> value in the XML application configuration file. You canchange it here, but you also must change it in the XML applicationconfiguration file.



Field Description

Schema If you have already specified a schema, the path and schema name isdisplayed here and you cannot change it. Otherwise, you can changethe path and schema name, which is retrieved from the <schema>value in the XML application configuration file; you also must changeit in the XML application configuration file.

Root elements You include elements--you must include at least one-- that you expectto be the root elements of XML documents that users will import byadding them to the "Selected items" list:

Add a root element to the "Selected items" list by selecting a rootelement from the "Select items from this list" field (the root elementsare retrieved from the <app_pattern><element> elements in the XMLapplication configuration file) and clicking the right-pointing doublearrowheads.

Add root elements to the "Selected items" list that are not in the"Select items from this list" list by entering them in the "Type in anitem to add" field and clicking the right-pointing double arrowheads.

Remove root elements from the "Selected items" list by selecting themand clicking the left-pointing double arrowheads.

About the Properties Application tab

The Application tab appears in the Properties dialog box when the object you select isthe DocApp itself. It displays, and allows you to modify, the following properties ofthe DocApp:• The application version (as distinguished from the Docbase version) - Enter any text

that represents the version of the application.• Copyright notice - Enter any text that represents a copyright notice.• Default alias set - Select an alias set in the DocApp as the default alias set.

When you change the default alias set, you must include all existing aliases in the newdefault alias set.



About the Properties General tab

The General tab of the Properties dialog box displays the following properties of theobject:• Name• Date and time of the most recent change• Owner• Lock owner (if it is checked out)You cannot use the dialog box to alter the properties.

About the Properties Location tab

The Location tab of the Properties dialog box displays the location of the sysobject andits links in the current Docbase. You can change any of the sysobject’s links, but youcannot remove its primary location.

Note: Any changes that you make on this tab only apply to the Docbase in which youdevelop the DocApp. Use the Installation Options feature to change the object’s locationin any Docbase to which you deploy the DocApp.

About the Properties Permissions tab

The Properties Permissions tab allows you to choose the permission set for a sysobjectin the current Docbase.

Note: Any changes that you make on this tab only apply to the Docbase in which youdevelop the DocApp. Use the Installation Options feature to change the object’s locationin any Docbase to which you deploy the DocApp.

About the Properties Reference tab

The Reference tab of the Properties dialog box displays a list of DocApps (other thanthis one) in the current Docbase that include this object.

You cannot use the dialog box to alter the list.



About the Properties Version tab

The Version tab of the Properties dialog box displays a list of the versions of the objectthat are part of the DocApp.

You cannot use the dialog box to alter the list.

Changing the localeThese topics are included:• Changing the locale, page 32• Publishing locale-specific information to the data dictionary, page 33• Locale-sensitive object type fields, page 35• Locale-sensitive attribute fields, page 35

Changing the locale

When connecting to a Docbase, Application Builder, by default, uses the locale defined inthe dmcl.ini file’s client_locale setting; otherwise, it uses the locale from your computer’sRegional Settings in the Control Panel.

If the locale is not published in the Docbase’s data dictionary when connecting to aDocbase or changing locales, you are prompted to choose one that is published. Whenyou connect to a 4.2.x or 4.4.x Docbase, the nls_key attribute’s values of the dm_domainobject determines the locales that are published. When you connect to a 5.x Docbase,the dd_locales attribute’s value in the dm_docbase_config object determines the localesthat are published.

Changing your DocApp’s locale changes the locale for some object type attribute valuesand attribute values (most of which can be displayed to a user through a client interfaceto your DocApp). You enter these attribute values in the specified locale. You canspecify as many different locale values for a single attribute as you want—all of anattribute’s locale values are saved to the Docbase. When you check in an object type,these attribute values are saved to the Docbase with their locale-specific text. When youchange to another locale, you enter attribute values in that locale and save them to theDocbase—without overriding the previous locale’s attribute values.

To change the locale:

1. Check in any modified object types.



2. Select View → Locale and then select one of the locales.By default, English, French, German, Japanese, Korean, Italian, and Spanish aredisplayed. Use DQL to add your own locales—see the Content Server Fundamentals forinformation about the data dictionary and localized text. To be able to select a locale, thelocale-specific information must be published in the data dictionary. Use the Docbasicscript dd_populate.ebs and server API publish_dd method to publish the locale-specificinformation in the data dictionary.

Note: The current locale for the DocApp is shown with a check mark next to it in theLocale submenu as well as in the bottom right-corner of the status bar.

If you specified locale-specific information for a type and that locale is not enabled(specified in the dm_docbase_config object’s dd_locales attribute for a version 4.2.x or4.4.x Docbase and in the nls_key attribute’s values of the dm_domain object for a 5.xDocbase) on the target Docbase, then the type is installed, but without the locale-specificinformation. You will also be given a choice to continue or abort the DocApp installation.

Locale

A locale represents a specific geographic region or linguistic group; for example, anational language such as Japanese.

Publishing locale-specic information to the datadictionary

The Docbase administrator needs to perform these steps.

To publish locale-specic information to the data dictionary:

1. From the command prompt on the computer on which Content Server is installed,run this dmbasic command:dmbasic -f dd_populate.ebs -e LoadDataDictionary --

docbase_name user_name password data_file

where:

docbase_name The name of the Docbase.

user_name Your user name.

password Your password.

data_file The data file that contains data dictionary information that isspecific to the locale you want to publish.



After you run this command, a series of messages is displayed, which indicates thatthe command was successful and the data dictionary was successfully updated.

2. Open the IAPI utility by using one of these techniques:• Choosing Start → Programs → Documentum → IAPI and connecting to the

Docbase using the appropriate user name and password.• Choosing Start → Run, entering the path to the iapi32.exe program and

connecting to the Docbase using the appropriate user name and password.3. Enter this command at the prompt:

publish_dd,session[,locale][,type][,attribute]

where:

session The session for IAPI (usually s0).

locale The locale for which you want to publish datadictionary information. For example, ja for Japanese.The default is the locale that is specified for thecurrent client session.

type The specific object type for which you want topublish data dictionary information.

attribute The specific attribute for which you want to publishdata dictionary information. You must enter the typeargument for which the attribute is defined.

Note: Do not use any spaces when entering the command.

See the Content Server API Reference Manual for detailed information about using thepublish_dd method. See the Content Server Fundamentals for detailed informationabout the data dictionary, locales, and using the dd_populate.ebs Docbasic script.

Data Dictionary

The data dictionary is a collection of information about object types and their attributesstored in internal data types in Content Server. Applications use data dictionaryinformation to ensure that they all adhere to the business rules and standards thedesigner establishes for the object type.

The information in the data dictionary includes restrictions, called constraints, on thevalues of and relationships among the attributes of objects of the types that can occur inthe Docbase.

The data dictionary also contains standard versions of text (also known as labels)for object types and attributes that appears on the user interface (for example, thedescription “Document” for the object type dm_document). This helps to keep the user



interface consistent, and it assists in localization, that is, translation of the user interfaceinto other languages.

You can also define value assistance for an attribute, store error messages, and help text.

Locale-sensitive object type elds

The locale settings for the following object type fields are changed when you change thelocale settings for the DocApp:

Application Builder fieldsData dictionary attributes(dm_nls_dd_info)

Label label_text

User Help help_text

Comment for developers comment_text

Error message string to use when aboveconstraint is violated

val_constraint_msg

Event Label Value-mapping table

Functionality Label Value-mapping table

Locale-sensitive attribute elds

The locale settings for the following attribute fields are changed when you change thelocale settings for the DocApp:

Application Builder fields Data dictionary attributes (dm_nls_dd_info)

Label label_text

User Help help_text

Comment for developers comment_text

Error message string to use whenabove constraint is violated

val_constraint_msg

Input mask format_pattern

Attribute category category_name

Value mapping tab: Display String map_display_string



Application Builder fields Data dictionary attributes (dm_nls_dd_info)

Value mapping tab: Data map_data_string

Value mapping tab: Description map_description

Setting installation optionsYou use the Target Docbase Installation Options dialog box to set options that theApplication Installer uses when installing a DocApp archive to a target Docbase.These options specify whether to run a pre- or post-installation procedure, how toupgrade existing objects, which cabinet and folder objects are installed, and the location,permissions, and owners of sysobjects in the target Docbase.

To set installation options:

1. To check out the DocApp, choose DocApp → Check Out DocApp.

2. Select DocApp → Set Installation Options.

3. In the left pane, select the objects for which you want to set the installation options.To select multiple objects, hold down the CTRL key and click on each object.

4. In the right pane, select the options that correspond to the objects you selected:• Upgrade Options – See Upgrade Options, page 236.• Data Object Transfer – See Data Object Transfer, page 241.• Permission Set Alias – See Permission Set Alias, page 240.• Location Alias – See Location Alias, page 238.• Owner Alias – See Owner Alias, page 240.• Procedures – See Procedures, page 242.

Because not all options in this dialog box are available for every type of object, someoptions might be grayed out when you select more than one type of object. Becausean XML application consists of a top-level folder (with the same name as the XMLapplication) that contains all the other files and a supporting files folder, it is treated as afolder for installation purposes.

Upgrade Options

Select one of these options to determine the action that the Application Installer takeswhen a duplicate object already exists in the target Docbase.



If an object that can be versioned does not already exist in the target Docbase, the object isinstalled as version 1.0 and is made the current version (if the object cannot be versioned,it is installed without a version number). XML applications, cabinets, and folders are notoverwritten or versioned; instead, the content in the XML application folder, cabinets,and folders is overwritten or versioned.

Note: As of 5.3 SP1, Java libraries do not have their own upgrade options. Instead,they use these upgrade options.

• Overwrite in the target Docbase - (Default for non-sysobjects; that is, object types,permission set templates, alias sets, groups, and roles) The object in the Docbase isreplaced by the new object and all attribute values are overwritten with the newobject’s attribute values even when they are the same. The new object is made thecurrent version.

• Version in the target Docbase - (Default for sysobjects) The new object’s version isincremented by .1 and is made the current version.

Use of this option is limited to sysobjects; however, even though methods aresubtypes of sysobject, form templates (dm_xfm_form) are subtypes of dm_document,and Java libraries (dmc_java_library) are subtypes of sysobject, methods, forms,and Java libraries cannot use this option.

• Overwrite if newer - (Default for modules) If the module in the DocApp is newerthan the one in the target Docbase, then the module (including all the objects in itsfolder) in the Docbase is replaced by the new module—this option only applies tomodules. The new module is made the current version. The module’s objects thatwere originally in the target Docbase but are not in the new module will be deleted.Module objects that were in the target Docbase and also in the new module areoverwritten.

• Do not overwrite; leave target object(s) alone - The object in the Docbase is notoverwritten or versioned, and remains the current version. The new object is notinstalled.

For more information about setting installation options, see Setting installation options,page 36.

The following table shows the criteria that the Application Installer uses to determinewhen an object is a duplicate:



If object is Then criteria for duplicate is

object typealias setmethodgrouproleform templateformatJava librarymodulerelation type

Same name anywhere in Docbase

document lifecycleworkflow templatejobprocedurecomponentXML application

Same name and location in Docbase

data object Same name, location, language_code attribute, andobject type in Docbase

permission set template Same name and owner in Docbase

Data Object Transfer

Select one of these options to determine the action that the Application Installer takeswhen it installs XML applications, cabinets, and folders:• All content - (Default) The specified XML application, cabinet, or folder, subfolders,

and objects in the cabinet and these folders are installed.• Object only - Only the specified XML application folder, cabinet, or folder is installed.• Hierarchical structure - The specified XML application folder and its subfolders, or

cabinet or folder and subfolders are installed; no objects are installed.• Top-level content - Only the specified XML application folder or folder and objects

in that folder are installed.The type of any object to be installed can only be dm_sysobject or any of itssubtypes—except for dm_process, dm_component, dm_qual_comp, dm_activity,dm_job, dm_method, and dm_policy. If you created a custom type (that is a subtypeof dm_sysobject), you must include it in the DocApp for any object of the custom typeto be included in the DocApp.



The XML application, cabinet, or folder hierarchy always appears in the target Docbasewith the same names it has when you insert it into the DocApp. If the target Docbasealready has a cabinet of the same name or the specified location already contains a folderof the same name as that of the top of the folder hierarchy, the Application Installercombines the contents of the two similarly named items, and does so recursivelythroughout the hierarchy.


Note: These are some important considerations for objects:• Renditions Included With DocApp, page 242• Cannot Insert Entire Virtual Document, page 242• Although Java libraries are subtypes of dm_folder, the Data Object Transfer option

for Java libraries is always All content.

Renditions Included With DocApp

If renditions have been created for this document, the renditions are also included withthe DocApp—however, only the original document is displayed in Application Builder.

Cannot Insert Entire Virtual Document

You cannot insert an entire virtual document at one time. If you insert any documentthat is part of a virtual document (the root or any child documents), only that documentis inserted. Furthermore, if you insert the virtual document’s root document, only theroot document is inserted—the child documents are not inserted.

Permission Set Alias

Select a permission set alias for a sysobject. Only the permission set aliases that havebeen inserted into the default alias set are displayed in the drop-down listbox. You canalso click New to create a new permission set alias in the default alias set and specify itas the owner alias for the sysobject.

If the developer does not select a permission set alias for a sysobject, then the defaultpermission set is the permission set of:



• The user who installs the DocApp if the dm_server_config object’s default_aclattribute is set to 3. This setting is the default for any Content Server installation.

• The folder to which the sysobject is installed if the dm_server_config object’sdefault_acl attribute is set to 1.

• The sysobject’s type if the dm_server_config object’s default_acl attribute is set to 2.No permission set is associated with the sysobject if the dm_server_config object’sdefault_acl is set to 4.

For more information about the default_acl attribute, see the Content Server AdministrationGuide.

Since object types, workflow templates, permission set templates, alias sets, and groupsare not sysobjects, the developer cannot select permission set aliases for them.


For more information about aliases, see Chapter 3, Using Aliases to Make DocAppsPortable.

Location Alias

Select a location alias for a sysobject. Only the cabinet or folder aliases that have beeninserted into the default alias set are displayed in the drop-down listbox. You can alsoclick New to create a new cabinet or folder alias in the default alias set and specify it asthe owner alias for the sysobject.

Since object types, permission set templates, alias sets, and groups are not sysobjects,you cannot select location aliases for them. Also, you cannot select a location alias fora method or cabinet. Because a cabinet always appears at the top level of a Docbasehierarchy, there is no need to specify a location alias for it.



Default Installation Locations

This table describes the default installation location for each DocApp part in the targetDocbase.



Note: N/A (not applicable) means that the DocApp part is not installed into the cabinetor folder hierarchy.

DocApp part Default installation location

application object(dm_application)

Applications/DocApp_name folder in the System cabinet;DocApp_name is the name of the DocApp archive folder.

Object types(dm_type)

N/A

Document lifecycles(dm_policy)


Workflow templates(dm_workflow)

Workflow activities(dm_activity)


Permission set templates(dm_ACL)

N/A

Alias sets(dm_alias_set)

N/A

Jobs(dm_job)


Form templates(dm_xfm_form)

Forms folder in the System cabinet

Forms(dm_component)

Qualified component(dm_qual_comp)


Procedures(dm_procedure)


Methods(dm_method)

Methods folder in the System cabinet

Java libraries(dmc_java_library)

/System/Java Libraries

Modules(dmc_module)

/System/Modules/module_type. module_type is the type ofmodule (for example, TBO, SBO)

Groups (and Roles)(dm_group)

N/A




Formats(dm_format)

N/A

Relation types(dm_relation_type)

N/A

XML Applications Applications/DocApp_name folder in the System cabinet;DocApp_name is the name of the DocApp archive folder.

Data objects Applications/DocApp_name folder in the System cabinet;DocApp_name is the name of the DocApp archive folder.

Owner Alias

Select an owner alias for the sysobject. Only the “dm_dbo” user, "user" and "user orgroup" aliases that have been inserted into the default alias set are displayed in thedrop-down listbox. You can also click New to create a new user alias in the default aliasset and specify it as the owner alias for the sysobject.

The default for sysobjects is the user who installs the DocApp.

Since object types, permission set templates, alias sets, and groups are not sysobjects,you cannot select owner aliases for them.



Procedures

Select a pre-installation procedure (and its version) that you want to execute before theApplication Installer begins installation and a post-installation procedure that you wantto execute after the installation completes. Only procedures that have been inserted intothe DocApp are displayed in the drop-down listboxes.

If you choose CURRENT in the version field, then the current Docbase version—notnecessarily the version of the procedure in the DocApp—of the procedure is archived.

If the pre-installation procedure fails, then Application Installer aborts the installation ofthe DocApp archive. If the DocApp archive installation fails, then the post-installation



procedure is not executed. If the post-installation procedure fails, then only thatprocedure fails (since the installation of the DocApp archive has already completed).

For more information about pre- and post-installation procedures, see Creating pre-and post-installation procedures, page 162.


Creating a DocApp ArchiveTo create a DocApp archive:

1. Make sure that you have included all of the appropriate objects in your DocApp.For more information about general best practices for creating DocApps archives,see Best practices, page 44; for more information about best practices for upgradingDocApps, see Upgrading DocApps, page 20.

2. Set the options (upgrading objects, cabinet/folder hierarchies and content, permissionset aliases, location aliases, user aliases, pre- and post-installation procedures) forinstalling to a target Docbase.

3. Choose DocApp → Create DocApp Archive.

4. Navigate to and select a folder on the file system.Application Builder creates a subfolder (with the same name as the DocApp) ofthe specified folder and creates the DocApp archive files in the subfolder. EMC |Documentum recommends that you do not change the name of the DocApp archivefolder because Application Installer uses it to install the DocApp archive and theDocApp archive folder might be specified in paths (such as in the XML applicationconfiguration file or location aliases).

In addition to archiving all the objects that have been included in a DocApp, these objectsare also are archived and will be installed by Application Installer:• ACX forms (components) associated with an included type’s functional classes. This

action ensures that the type functions properly in target Docbases. For example, ifyou inserted the dm_document type--but not any of the ACX forms associated withits functional classes--into a DocApp, several ACX forms, including DcView, DcEdit,and DcOpen, would still be archived.

• dm_activity objects and their content (if any) that are part of an included workflowtemplate.

• Email templates (which are of the dm_sysobject object type or one of its subtypes)associated with an included workflow template or one of its dm_activity objects.



Best practices

If you have installed a workflow template created with Business Process Manager (BPM)and want to use BPM to modify the workflow template in the target Docbase:• Insert the System/Workflow/Activity Templates/palettes folders and specify the All

Content option for the Data Object Transfer section and the same location in thetarget Docbase. Including the activity templates (which are of the dm_activity objecttype) ensures that their relationships to the workflow template’s dm_activity objectsare archived as well. palettes is any palette folder.

• Insert associated email templates (which are of the dm_sysobject object type or oneof its subtypes) and specify their target installation locations; otherwise, they will beinstalled in the DocApp’s target folder.

Insert any EMC | Documentum Forms Builder forms into the Docapp as data objectsby choosing Insert → Object from Docbase → Document and browsing to the form;forms are located in /System/Forms.

Working with parts of a DocAppThese topics are included:• Checking objects into the Docbase, page 44• Checking objects out of the Docbase, page 45• Cancelling object checkout, page 45• Cutting, copying, and pasting objects, page 46• Choosing a permission set for a SysObject or the application, page 47• Creating and removing links to sysobjects and the application, page 48• Creating or modifying a document lifecycle (DLC), page 48• Adding or modifying a workflow template, page 49• Modifying the global components list, page 49

Checking objects into the Docbase

To check objects into a Docbase:

1. In the DocApp explorer, select the objects you wish to check in (use control-click toselect non-adjacent objects), and choose DocApp → Check In Objects (or click theCheck-in icon on the toolbar).The Check In Objects dialog box appears.



2. For each object, fill in the entries in the corresponding row.• Clicking a column header opens a drop-down menu. The menu items help you

fill in the entries in the column. Each menu is specific to the kind of informationin its column.

• The Check In column menu lets you specify Yes or No for the selected row.• The Version column menu lets you specify Same, Minor, or Major. These are

the standard check-in options.• In theDescription and Label columns, selecting Copy as first row fills all cells in

the column with the contents of the entry in the top cell.• The Retain Lock menu enables you to specify Yes or No. If you specify Yes,

Application Builder updates the Docbase version of the item but leaves itchecked out.

Checking objects out of the Docbase

To check objects out of the Docbase:

1. Select the object in the tree pane.

2. Choose DocApp → Check out Object(s).

Tip: You can also click the check-out icon on the toolbar.

Alternatively, you can double-click the object in the tree pane, and then click Edit in themessage box that is displayed.

Cancelling object checkout

When you cancel the checkout of objects, any changes you made to the objects are notsaved and the objects are placed back into the checked in state.

To cancel the checkout of objects:

1. Select the checked out objects.

2. Choose DocApp → Cancel checkout selected object(s).

Tip: You can also click the cancel checkout icon on the toolbar.



Cutting, copying, and pasting objects

You can cut or copy sysobjects, alias sets, and permission set templates in one DocAppto the clipboard and paste the objects into another DocApp within the same Docbase.You can select more than one object at a time. The clipboard can only hold one set ofsysobjects, alias sets, or permission set templates cut or copied at the same time; whenyou cut or copy another set of sysobjects, alias sets, or permission set templates to theclipboard, it replaces the previous set on the clipboard.

Note: You cannot cut, copy, or paste workflow templates, XML applications, XMLapplication configuration files, or data objects (cabinets, folders, and documents).

• To cut sysobjects, alias sets, or permission set templates from the current DocAppto the clipboard, select the objects in the tree pane and choose Edit → Cut (or clickthe Cut icon on the toolbar).

Note: To cut a sysobject, alias set, or permission set template, you must have atleast Browse permissions on it if it does not have content (an external file, such as adocument) and at least Read permissions if it has content.

• To copy sysobjects, alias sets, or permission set templates from the current DocAppto the clipboard, select them in the tree pane and choose Edit → Copy (or click theCopy icon on the toolbar).

Note: To copy a sysobject, you must have at least Browse permissions on it if itdoes not have content and at least Read permissions if it has content. To copy analias set or permission set template, you must have at least Write permissions themand their folder.

• To paste sysobjects, alias sets, or permission set templates from the clipboard, openanother DocApp (in the current Application Builder or start another ApplicationBuilder session by selecting it from the Start menu) and select Edit → Paste (orclick on the Paste icon on the toolbar). The new object name is: Copy of object.object is the original object name.

If the object is pasted multiple times into the same location, the object name is: Copyn of object. object is the original object name and n is an integer that is assigned avalue of 2 when the object is pasted for the second time into the same location and isincremented thereafter.

Note: To paste a sysobject, you must have at least Write permissions on theapplication folder of the DocApp. To paste an alias set or permission set template,you must have at least Write permissions on it and the folder.

To select multiple sysobjects, alias sets, or permission set templates that are notimmediately next to each other, hold down the CTRL key and click on each object.

To select a series of sysobjects, alias sets, or permission set templates that are next to eachother, hold down the Shift key and click on the first and last of them.



Deleting objects from a Docbase

You can use DAB to delete any object from a Docbase, except for these ones:• Object types• XML applicationsIf you delete the DocApp’s default alias set, you must select another default alias set.

To delete objects from the Docbase:

1. Select the objects in the left pane.

2. Choose Edit → Delete Object(s) from Docbase.

3. Check in the DocApp as the same version.

Removing objects from the DocApp

If you remove the DocApp’s default alias set, you must select another default alias set.

Note: Removing objects from a DocApp does not delete them from the Docbase.

To delete objects from a Docbase, see Deleting objects from a Docbase, page 47.

To delete objects from the DocApp:

1. Select the objects in the left pane.

2. Press Delete.

Choosing a permission set for a SysObject or theapplication

To choose a permission set:

1. Check out the sysobject or application.

2. Right-click on the sysobject or application, choose Properties, and click on thePermissions tab.

3. Choose a permission set template from the Permissions drop-down listbox.

4. Check in the sysobject or application to save your changes.



Creating and removing links to sysobjects and theapplication

To add a link:


2. Right-click the sysobject or application and choose Properties.

3. In the Properties dialog box, click Link.

4. Navigate to and select the folder in which you want to create a link and click Select.


To remove a link:


2. Right-click the sysobject or application and choose Properties.

3. In the Properties dialog box, select the link and click Unlink.


Note: The application (dm_application) is a subtype of a sysobject.

Creating or modifying a document lifecycle (DLC)

To create a new DLC, choose Insert → Document lifecycle.

To modify an existing DLC, double-click its name in the DocApp explorer to open theDLC editor.

Document lifecycles

A document lifecycle (DLC) encodes business rules for changes in the properties ofan object as it moves through the stages of its life (for example, in draft, in review,operational, obsolete). A DLC can apply to subtypes of its principal object type. Youdesignate those subtypes when you specify the DLC. Use the DLC editor to specifyor modify a DLC.

An object type can have only one default DLC. To specify a DLC as the default documentlifecycle for a type, the type must be specified as the DLC’s primary type or an acceptablesubtype of the DLC.



Adding or modifying a workow template

To add an existing workow template to the DocApp:

1. Choose Insert → Object from Docbase → Workflow Template.

2. Navigate to the desired workflow template.To modify a workflow template, double-click it in the DocApp explorer; WorkflowManager or Business Process Manager (if you have installed it) is opened and you canmodify the workflow template using Workflow Manager or Business Process Manager(BPM).

For more information about Workflow Manager and BPM, see their online help.

For more information about archiving DocApps with workflow templates created usingBPM, see Best practices, page 44.

Modifying the global components list

When you create a DocApp, DAB creates an empty global components list for it.

To modify the list, double-click the global components icon in the DocApp explorer toopen the global components editor.

Global components list

The DocApp maintains a list of components that it makes accessible to programs outsidethe DocApp. These are called global components. They are not type-specific.

Turning prompts and XML applicationvalidation on and off

You can prevent these prompts from being automatically displayed at the appropriatetime:• The New Application dialog box when starting up Application Builder• The View/Edit prompt when double-clicking an object that is not checked out--if it

is unchecked, it will always open in view only mode• The Validate XML Application on Checkin? prompt when checking in existing

XML applications



By default, they are automatically displayed.

You can also prevent the validation of an XML application before checking in the XMLapplication. By default, the XML application is validated whenever a new or existingone is checked in. If you turn it off, validation will not occur when you check in anexisting XML application or create a new one and check it in. In addition, the Validatethe DocApp before checking in the XML application option of the XML ApplicationCreation dialog box’s General tab will be unchecked; however, you can check it tooverride the preference and validate the new XML application on check in.

Note: Regardless of whether you turned validation of the XML application on or off,if you turned on the option to display the Validate XML Application on Checkin?prompt, you will always be prompted to choose to validate or not when checking in anexisting XML application (but not a new one).

To prevent these prompts from being automatically displayed and turning off validation ofthe XML application before checking it in:

Tip: You can also check the checkbox on the prompt when it appears.

1. Choose Tools → Preferences.

2. Uncheck the prompt that you want to prevent from automatically displaying or theXML validation option.

3. Click OK.

To automatically display these prompts at the appropriate time:

1. Choose Tools → Preferences.

2. Check the prompt that you want to automatically display.

3. Click OK.


Chapter 3Using Aliases to Make DocAppsPortable

These topics are included:• About alias sets, page 51• Creating new alias sets or adding existing ones from Docbases, page 52• Specifying an alias object in an alias set, page 53• Changing the DocApp’s default alias set, page 54

About alias setsMany aspects of DocApps involve references to specific users, groups, permission sets,and Docbase cabinets and folders. For example, the reviewers in one state of a documentlifecycle might be Linda, Ed, and Denise. If the lifecycle refers to these employees byname, you must modify the lifecycle to use it in a different context.

EMC | Documentum designed DocApps to be easily portable from one context toanother. Aliases make this possible. For example, you might design a lifecycle usingsymbolic user names Reviewer1, Reviewer2, Reviewer3. In one context you can specify:Reviewer1 = LindaReviewer2 = EdReviewer3 = DeniseIn another context, you can assign different user names to these symbolic names. Theassignment of an actual user, group, permission set, or Docbase cabinet or folder to asymbolic name is called an alias. The symbolic name is called the alias name. The actualvalue is called the alias value. A collection of aliases is called an alias set.

Whenever you design a DocApp to be used in a different context from the one in whichyou develop and test it, you must use alias names for all context-specific entities and usealias sets to supply alias values.


Using Aliases to Make DocApps Portable

In this way a DocApp is analogous to a procedure in a programming language. The aliasnames of the DocApp are the parameters of the procedure. The alias values are actualarguments for the specific procedure call.

While a DocApp cannot function without values for all of its alias names, you do nothave to provide all of the values from the same alias set. You provide values for allaliases when you bind a document lifecycle to a document in the context of the DocApp.The values can come from different alias sets. You can specify alias sets when you:• Install the DocApp in a new context.• Establish the active user.• Begin a Docbase session.

Creating new alias sets or adding existing onesfrom Docbases

When prompted for an alias value during DocApp installation, selecting a value thatincludes multi-byte characters is not supported. If you need to use multi-byte charactersin an alias value, enter the alias value into the DAI properties file and run DAI again.

For more information about the running DAI and the properties file, see the ApplicationInstaller online help.

To create a new alias set:

1. Choose Insert → Alias set.

2. Enter a name and description for the new alias set.

3. Click Add to create new aliases and complete the Alias Object dialog box.See Specifying an alias object in an alias set, page 53

4. To change an alias that you just added, select it, click Edit, and make changes in theAlias Object dialog box.See Specifying an alias object in an alias set, page 53

To add an existing alias set from the Docbase, choose Insert→ Object from Docbase→Alias Set. If desired, modify the alias set as instructed in the following section.

To modify an alias set:

1. Double-click its name in the DocApp explorer and click Edit to open the Alias Seteditor.

2. If desired, change the name of the alias set.



Tip: Another way to change the alias set’s name is to select the alias set name in thetree pane (the alias set must be checked out) and then click its name.

3. To create a new alias, click Add, and complete the Alias Object dialog box.See Specifying an alias object in an alias set, page 53

4. To modify an existing alias, select it, click Edit, and make changes in the AliasObject dialog box.See Specifying an alias object in an alias set, page 53

Note: When you create a new DocApp, DAB creates a default alias set for it. Unless youhave a specific reason for doing otherwise, EMC | Documentum recommends that youuse this set for all aliases pertaining to the DocApp. If you specify another alias set as thedefault alias set, make sure that you have the same aliases in the new alias set.

Specifying an alias object in an alias setYou arrive at the Alias Object dialog when adding or editing a line in the alias set editor.

To specify an alias object in an alias set:

1. Enter the alias name in the Name text box.

2. Select the alias type (unknown, user, group, user or group, cabinet path, cabinet orfolder path, permission set) from the Type drop-down list.

Note: If you are using either a user or group alias in a workflow template, do notselect the User or Group alias type—you must select either the User alias type or theGroup alias type. Workflow Manager cannot resolve the User or Group alias typefor the Specific User, All Users in Group, or Single User From Group performeroptions when the workflow initiator is prompted to specify the performer.

3. Enter the alias value in the Value text box. You can use the ellipsis button to displayand choose from the legal values for the current Docbase.

4. To require the installer to prompt for a value for this alias at installation, check thecheckbox.

5. Specify an alias category and description.Alias category is a tool for developers to use to organize the aliases in their DocApps.EMC | Documentum software does not use this field.



Changing the DocApp’s default alias setTo change the DocApp’s default alias set:

1. Add an existing alias set or create a new one.To create a new one, see Creating new alias sets or adding existing ones fromDocbases, page 52.

2. Right-click on the DocApp in the tree pane and select Properties.

3. Click the Application tab and select an alias set to be the default alias set in theDefault Alias Set field.If the new default alias set has any aliases that the previous default alias set does nothave, a warning message is displayed.

4. Click Details to display a list of the aliases missing from the newly chosen alias set.

5. Click Close, and then click the Close button of the DocApp’s Properties dialog box.

6. For your aliases to be resolved correctly, add the missing aliases to the new defaultalias set.


Chapter 4Working With Data Objects

These topics are included:• Inserting documents, page 55• Inserting a cabinet or folder hierarchy, page 56

Inserting documentsTo insert a document:

1. Choose Insert → Object from Docbase → Document.

2. Navigate to the desired document (including smartlists).Only a document whose type is dm_sysobject or any of its subtypes—except fordm_process, dm_component, dm_qual_comp, dm_activity, dm_job, dm_method,and dm_policy—or any custom type of dm_sysobject is displayed.

3. Specify the upgrade option, location alias, owner alias, and permission set alias forthe document in the target Docbase. See Setting installation options, page 36.

Note:• Renditons included with DocApp (see Renditions Included With DocApp, page 242)• Cannot insert entire virtual document (see Cannot Insert Entire Virtual Document,

page 242)




Working With Data Objects



Inserting a cabinet or folder hierarchyTo insert a cabinet or folder hierarchy:

1. Choose Insert → Object from Docbase → Cabinet or Insert → Object fromDocbase → Folder.

2. Navigate to the desired cabinet or a folder.

3. Specify the cabinet or folder’s upgrade option, location alias, owner alias, permissionset alias, and contents and subfolders to transfer to the target Docbase. See Settinginstallation options, page 36.


Chapter 5Working with Form Templates

These topics are included:• About Form Templates, page 57• Adding existing form templates from repositories, page 58

About Form TemplatesA form template is a Web form template and is stored as a dm_xfm_form object in theDocbase. Form templates contain an intersection of two different layers:• The user interface (UI) model, which defines what appears on the form page and

how it looks.• The data model, which defines the data items, or groups of data items, that will be

used to store the information that the user submits.You can insert a form template from the Docbase into the DocApp, but you cannot createor modify a form template from within Application Builder.

See the Documentum Forms Builder User Guide for more information.


Working with Form Templates

Adding existing form templates fromrepositories

To add an existing form template from a Docbase, choose Insert→Object from Docbase→ Form Template and select a form template.


Chapter 6Working With Formats

These topics are included:• About formats, page 59• Creating or modifying a format object, page 59• Specifying digital asset management and full-text indexing, page 61

About formatsDefines a file format, such as text for a text file or xml for an XML file, that ContentServer recognizes. For a format, you usually define a name for it, a DOS extension,and digital asset management attributes.

See Creating or modifying a format object, page 59 for instructions on how to createand modify format objects.

formats

Defines a file format, such as text for a text file or xml for an XML file, that ContentServer recognizes.

Creating or modifying a format objectTo create a format (dm_format) object:

1. Choose Insert → Format.

2. In the Format object dialog box, specify the desired fields on the General (describedbelow) and Advanced tabs.


Working With Formats

Field nameAttributename Valid values Description

Name name A stringwitha maximumof 64characters.

Name of the format. The charactersmust be ASCII.

Description description A stringwitha maximumof 64characters.

A brief description of the format.

Default FileExtension

dos_extension

A stringwitha maximumof 10characters.

Defines the DOS extension to use whencopying a file with this format intothe common area, client local area, orstorage.

COM ClassID

com_class_id


The class ID recognized by theWindows registry for a content type.

Mime Type mime_type


The Multimedia Internet MailExtension (MIME) for the content type.

MacintoshCreator

mac_creator

A stringwith amaximum of4 characters.

Information used internally formanaging Macintosh resource files.

MacintoshType

mac_type

A stringwith amaximum of4 characters.

Information used internally formanaging Macintosh resource files.

Is Hidden is_hidden

Checked orunchecked.

Used by client applications todetermine whether to display thisformat object in the client application’suser interface.

Class format_class

32-characterstring

Identifies the class or classes (which canbe user-defined) of formats to whichthe format belongs. For example, thexml, xsd, and xsl formats belong tothe XML and MSOffice classes. In 5.3and later repositories, the ftalwaysand ftpreferred values are used



Field nameAttributename Valid values Description

by the full-text indexing system todetermine which renditions of adocument are indexed. See the ContentServer Administration Guide for moreinformation.

To add a class, enter its name in thetext field and click Add.

To remove a class, select its name in thelistbox and click Remove.

To reorder the sequence in which theclasses are called, click the Up andDown arrows.

To modify a format (dm_format) object:

1. Double-click the format object in the left pane.If you have not inserted the format object into your DocApp, then choose Insert→ Object from Docbase → Format, select the desired format object, and thendouble-click the format object.

2. In the Format object dialog box, modify the desired fields on the General andAdvanced tabs.

Specifying digital asset management andfull-text indexing

To specify digital asset management and full-text indexing for a format (dm_format) object:

1. Double-click the format object in the left pane (or choose Insert→ Format to insert anew format or Insert→Object fromDocbase→ Format to insert an existing format).

2. Select the Advanced tab and specify values for these fields:



Field name Attributename

Validvalues

Description

Asset Class asset_class A stringwith amaximumof 32characters.

Applications use this valueto classify the asset type (forexample, audio, video, image) ofthe contents of objects with thisformat.

Default Storage default_storage

Anobject ID(object_id),includinga null ID.

Specifies the default storage area(identified by its object_id) wherethe contents of the objects with thisformat are stored. For sysobjects,if a_storage_type is not specifiedfor the object, then default_storagefor the associated format is used;if you do not specify the defaultstorage here in the format, thena_storage_type specified for theobject type is used; if none of theseare specified, then turbo storage isused as the default storage.

FilenameModifier

filename_modifier

A stringwith amaximumof 16characters.

Specifies a string that a clientapplication can append to a filename when multiple renditions(of an object) having the sameextension are exported. Forexample, if you specify "_th" as thefilename_modifier for the jpeg_thformat, then when a rendition,my_picture.jpeg with a jpeg_thformat, is exported, the rendition’sfile name is my_picture_th.jpeg.

Note: The client application (forexample, WebCache)--not theContent Server--appends the



Field name Attributename

Validvalues

Description

filename_modifier value to the filename.

RichmediaEnabled

richmedia_enabled

Checkedorunchecked.

Indicates whether ContentServer automatically generatesthumbnails, auto proxy andmetadata for its contents.

Can be Indexed can_index Checkedorunchecked.

Indicates whether an object’scontent with the format can befull-text indexed.

Index withFilter

topic_filter None orUniversal.

Name of the Verity topic filterto use for full-text indexing.When this field is selected, thetopic_transform attribute is set toFalse.

Index withRendition

topic_format_name

A stringwith amaximumof 64characters.

Name of the format objectrepresenting the format to whichthis format must be transformedfor full-text indexing. When aformat object is specified in thisfield, the topic_transform attributeis set to True and the topic_formatattribute is set to the object_id ofthe specified format object.




Chapter 7Working With Forms

These topics are included:• About qualified components and forms, page 65• Creating new forms or adding existing ones from Docbases, page 66• Setting up dynamic download of 4.x and 5.x components with the same functionality, page 67

About qualied components and formsA form, as specified in the Component Editor dialog, identifies a functional element foruse within a DocApp. The most common kind, an ACX form, identifies an ActiveXexecutable by providing one of the following:• The class ID of a component assumed to be installed in the target client system.• The identity of a cabinet file containing the executable and its class ID.DAB uses ActiveX class IDs from the Windows registry to identify components on DABforms. Use the component editor to specify or modify class IDs.

The Component Editor dialog also allows you to specify dependencies, that is, othercomponents that the system must load when it loads this one.

A qualified component, as specified in the Functionality Description dialog, associatesthe following with a functionality class:• A label• A functional element• PermissionsQualified components use DocApp elements called groups to specify permissions. Theydo not use permission sets.

The Functionality Description dialog box allows you to identify any number of groupsand assign to each any combination of the following user capabilities:• Consumer


Working With Forms

• Contributor• Coordinator• Administrator

Creating new forms or adding existing onesfrom Docbases

Before beginning this procedure you must have one of the following ready:• The class ID of the underlying component• The name of a CAB file containing the component.

Note: Windows Executable is not fully functional in the current release.

To create a new form:

1. Choose Insert → ACX Form, Insert → Data Module, or Insert → WindowsExecutable.

2. Enter the component name.

3. Perform one of these actions:• For an ACX form, specify the component’s class ID or the CAB file containing it.• For a Windows executable, specify its version and ActiveX class ID.• For a data module, click Add and navigate to the location of the file on the file

system containing the component.4. Check or uncheck the Compatible only with Documentum Desktop 5 option as

follows:• If this component is binary compatible only with DFC 5 or greater, check this

option.

The value DFC5.1 is appended to the r_component_label attribute.• If this component is binary compatible only with DFC 4.x or lower, uncheck

this option.

The DFC5.1 value in the dm_qual_comp object’s r_component_label attributeis removed.

Note: A component can be binary compatible with either DFC 5 (and greater) orDFC 4.x (and lower)—not both.

You can also set up dynamic download of 4.x and 5.x components with the samefunctionality See Setting up dynamic download of 4.x and 5.x components with thesame functionality, page 67.


Working With Forms

To add an existing form from the Docbase, choose Insert → Object from Docbase →Form. If desired, modify the form as follows.

To modify an existing form:

1. Double-click its name in the DocApp explorer to open the component editor.

2. Modify the appropriate fields.

Setting up dynamic download of 4.x and 5.xcomponents with the same functionality

To dynamically download components with the same functionality to client machinesrunning either Desktop 4.x or 5.x

1. Build your DFC 5.x binary-compatible DLL or EXE from your existing DFC 4.xcomponent, assigning it a new class ID by breaking binary compatibility, andcompress it into a cabinet (.CAB) file.For more information about enabling components for dynamic component delivery(DCD), see the Documentum Desktop Development Kit Development Guide.

2. To version the ACX form to use the DFC 5.x binary-compatible DLL or EXE:

a. In DAB, open the existing 4.x ACX form.

b. Click Add to add the .CAB file containing the DFC 5.x binary-compatible DLLor EXE.

c. Check the Compatible with Documentum Desktop 5 option.

d. Check it in as the next version of the existing DFC 4.x component.

3. Use the Desktop Component Compatibility Utility to set the version label of the DFC4.x-compatible component to "CURRENT".The file name of the Desktop Component Compatibility Utility is DesktopComponent Utility.exe and is located in the bin directory of the DAB installation(usually, C:\Program Files\Documentum\Application Builder).


Working With Forms

Note: Because version label settings are not preserved when you deploy DocApps toother Docbases, you will need to rerun the Desktop Component Compatibility Utilityon the DocApp in the Docbases to which you deploy it.


Chapter 8Working With Groups

These topics are included:• About groups, page 69• Adding existing groups from Docbases, page 69

About groupsA group is a collection of Docbase users, groups, or alias set members. It exists withinthe DocApp solely for the purpose of assigning permissions to qualified componentsin the Functionality Description dialog.

You can insert a group from the Docbase into the DocApp, but you cannot create ormodify a group from within Application Builder.

Adding existing groups from DocbasesTo add an existing group from a Docbase, choose Insert → Object from Docbase →Group and select a group.


Working With Groups


Chapter 9Working With Java Libraries

These topics are included:• About Java libraries, page 71• JAR files, page 71• Libraries and sandboxing, page 72• Adding and removing Java libraries, page 72

About Java librariesA third-party set of related files (for example, JAR files and properties files) on whichyour module depends. These files are stored in a dmc_java_library folder.

JAR lesDAB packages JAR files into repository objects of type dmc_jar. The Object ReferenceManual describes the attributes of the dmc_jar type. Those attributes, which DAB setsusing information that you supply, specify the minimum Java version that the classesin the JAR file require. They also specify whether the JAR contains implementations,interfaces, or both.

DAB links the interface and implementation JARs for your module directly to themodule’s top level folder, that is, to the dmc_module object that defines the module. Itlinks the interface JARs of modules that your module depends on into the ExternalInterfaces subfolder of the top level folder.


Working With Java Libraries

Libraries and sandboxingDAB links JARs (in the form of dmc_jar objects) for supporting software into folders oftype dmc_java_library, which are created in the /System/Java Libraries folder. It links thedmc_java_library folder to the top level folder of each module in which the Java library isincluded. The Object Reference Manual describes the attributes of the dmc_java_librarytype. The single attribute of this type specifies whether or not to sandbox the JAR fileslinked to that folder.

The verb sandbox refers to the practice of loading the given Java library into memoryin such a way that other applications cannot access it. This can have a heavy cost inmemory use, but it enables different applications to use different versions of the samelibrary without conflicts. A module with a sandboxed Xerces library, for example, usesits own version, even if there is a different version on the classpath and a third version inuse by a different module.

DFC achieves sandboxing by using a shared BOF class loader and separate class loadersfor each module. These class loaders try to load classes first, before delegating to theusual hierarchy of Java class loaders.

Note: Java libraries can contain interfaces, implementations, or both. Do not includeboth in your own Java libraries. If the library is a third party software package, youmay have to include both. In this case, do not use interfaces defined in that libraryin the method signatures of your classes.

If you prepare a separate JAR for your module’s interfaces but fail to remove thoseinterfaces from the implementation JAR, you will encounter a ClassCastException whenyou try to use your module.

You can sandbox libraries that contain only implementations. You can sandbox thirdparty libraries. Never sandbox a library that contains an interface.

DFC automatically sandboxes the implementation JARs of modules.

DFC automatically sandboxes files that are not JARs. You can access them as resources ofthe associated class loader.

Adding and removing Java librariesTo add a Java library from your local machine:

1. Choose Insert → Java library.

2. Specify this information:



Table 9-1. Java libraries dialog box elds

Name (Required) Name of the Java library,which will be the dmc_java_library foldername and must be unique in the Docbase.

Min VM Version (Optional) Specifies the minimum versionof the Java virtual machine required torun this Java library.

Sandbox (Optional) Whether you want DFC tosandbox this Java library. Check toindicate that you want DFC to sandboxit; uncheck it to indicate you don’t.Unchecked by default.

For more information about sandboxing,see Libraries and sandboxing, page 72.

JARs and artifacts Add or remove JARs and other artifacts.

For more information about JARs, see JARfiles, page 71.• To add a JAR or other artifact, clickAdd, navigate to, and select the file.

• To remove a JAR or other artifact, selectthe file and click Remove.

File Type (Optional) Click this field to select oneof these values for the file type of theassociated file: interface, implementation,both interface and implementation, andfile. The default for JARs is “both”; defaultfor all other files is “file”.

3. Choose Edit > Check in.

To add a Java library from the Docbase:

1. Choose Insert > Object from Docbase > Java library.




Chapter 10Working With Jobs

These topics are included:• About jobs, page 75• Creating new jobs or adding existing ones from Docbases, page 75• Creating or modifying a job schedule (Schedule tab), page 77• Viewing job information, page 77

About jobsA job is the scheduled invocation of a method. It is not associated with a specific type.Use the job editor to specify or modify the method, schedule, permission set, and otherproperties of a job.

Creating new jobs or adding existing ones fromDocbases

The Info tab is for information only. For more information, see Viewing job information,page 77

To create a new job:

1. Choose Insert → Job.

2. To modify an existing job, double-click its name in the DocApp explorer.

3. On the Property tab, enter the appropriate values in these fields:• Name – A name for the job.• Subject – This is a comment field (for more information, see the Object Reference

Manual).


Working With Jobs

• Designated Server – A job’s underlying method runs on a specific server. This isthe job’s target_server attribute (for more information, see the Object ReferenceManual).

4. Select a method from theMethod drop-down list.You can only select methods that are part of the current DocApp and have beenchecked in to the Docbase.

5. Enter the method data in theMethod Data text box.Use this text box to override the method data. This is the job’s method_data attribute(for more information, see the Object Reference Manual). The method uses this fieldfor persistent storage.

6. Use the radio buttons to request standard arguments or to specify argumentsexplicitly in the Arguments text box.The definition of the job’s underlying method contains default calling arguments.You can use these or specify arguments explicitly.The radio buttons choose between the job attributes pass_standard_arguments andmethod_arguments (for more information, see the Object Reference Manual).

7. Enter appropriate values in these fields:• Deactivate on Failure – Click this box to direct the DocApp to stop running

the job if the underlying method fails. This is the job’s inactivate_after_failureattribute (for more information, see the Object Reference Manual).

• Inactive – This is the job’s is_inactivate attribute (for more information, see theObject Reference Manual).

• Trace Level – This is a value from 0 to 10 (for more information, see the ObjectReference Manual).

8. Specify a schedule and permissions for the job.See Creating or modifying a job schedule (Schedule tab), page 77.

To add an existing job from the Docbase:

1. Choose Insert → Object from Docbase → Job.If the job uses a method, you are prompted to add the method as well.

2. Click Yes to add the method or No to add the job without the method.

Note: If you do not add the method and the same method does not exist in the targetDocbase, then the job will not run correctly in the target Docbase.

3. If desired, modify the job as instructed in the previous section.


Working With Jobs

Creating or modifying a job schedule (Scheduletab)

To create or modify a job schedule:

1. On the job’s Schedule tab, enter appropriate values in the Starting Date and EndingDate text boxes.A job runs at specified intervals, starting at a specified date and time and ending at aspecified date and time.

2. Enter the appropriate values for these options:• Run upon Saving – Checking this checkbox causes the job to run as soon as

you check it into the Docbase.• Max Runs – You can specify an upper limit on the number of times the DocApp

runs the job. This works in addition to the ending date. Whichever occurs firstcauses the DocApp to stop running the job. A value of zero means no limit.This is the job’s max_iterations attribute (for more information, see the ObjectReference Manual).

3. Use the radio buttons and the appropriate fields to specify the job’s run interval aseither “every n minutes, hours, days, weeks, or months” or “on the nth day of everyweek (which begins on Sunday), month, or year.”

Viewing job informationAs it runs the job, the DocApp keeps track of job ownership, the last modification, andmethod run times, results, and statistics and displays it here for your information only.For more information, see the Object Reference Manual.

To view job information:

1. Double-click the job name in the DocApp explorer.

2. Select the Info tab to view the job information.


Working With Jobs


Chapter 11Working With Methods

These topics are included:• About methods, page 79• Creating new methods or adding existing ones from Docbases, page 79

About methodsA method is the representation within a DocApp of the identity, run characteristics, andrestrictions on the use of a server API call. Methods cannot be versioned.

Use the method editor to specify or modify a method.

Creating new methods or adding existing onesfrom Docbases

To create a new module:

1. Choose Insert → Module.

2. In the left pane, double-click the module.

3. On the Implementation tab:

a. Enter a name for the module in the Name text box.

b. To check in the components of the module, such as JARs and other documents,as Major, Minor, or the Same version, select the Check in objects as field.

c. Select the JARs that contain your implementation classes in the ImplementationJARs text box.


Working With Methods

d. Select a primary Java implementation class for this module in the Class Namefield. This field displays all of the fully qualified Java class names in theImplementation JARs textbox.

4. Enter text or choose values for the remaining optional fields; see these topics formore information:• Module editor: Implementation tab, page 114• Module editor: Runtime Environment tab, page 117• Module editor: Dependencies tab, page 118• Module editor: Miscellaneous tab, page 122• Module editor: Web Services tab, page 123

5. To check in the module, select it and choose DocApp→ Check In Object(s).To add an existing method from the Docbase, choose Insert→ Object from Docbase→Method. If desired, modify the method as instructed in the previous procedure.


Chapter 12Working With Modules

These topics are included:• About modules, page 81• BOF, page 81• Web Services, page 104• Creating new modules or adding existing ones from Docbases, page 113

About modulesModules are units of executable code represented in the Docbase as the folder structureof a dmc_module object type folder; EMC | Documentum business objects (which area part of EMC | Documentum’s Business Object Framework (BOF)) are one kind ofmodule. For more information about BOF, see BOF, page 81.

You can also create a web service from a EMC | Documentum service-based object (SBO).For more information about web services, see Web Services, page 104.

BOFThese topics are included:• Overview of BOF, page 82• BOF infrastructure, page 82• Service based objects (SBOs), page 86• Type based objects (TBOs), page 94• Calling TBOs and SBOs, page 102


Working With Modules

Overview of BOF

BOF’s main goals are to centralize and standardize the process of customizing EMC |Documentum functionality. BOF centralizes business logic within the framework. UsingBOF, you can develop business logic that• Always executes when it is supposed to, regardless of the client program• Can extend the implementation of core EMC | Documentum functionality• Runs well in an application server environmentIn order to achieve this, the framework leaves customization of the user interfaceto the clients. BOF customizations embody business logic and are independent ofconsiderations of presentation or format.

If you develop BOF customizations and wish to access them from the .NET platform,you must take additional steps. We do not provide tools to assist you in this. You can,however, expose some custom functionality as web services. You can access web servicesfrom a variety of platforms (in particular, .NET). TheWeb Services Framework DevelopmentGuide provides information about deploying and using the web services.

BOF infrastructure

These topics are included:• Modules and registries, page 82• Dynamic delivery mechanism, page 84• Global registry, page 84• Deploying module interfaces, page 86

Modules and registries

To understand BOF, first look at how it stores customizations in a repository. Amodule is a unit of executable business logic and its supporting material (for example,documentation, third party software, and so forth).

DFC uses a special type of repository folder (dmc_module) to contain a module. TheObject Reference Manual describes the attributes of this type. The attributes identify themodule type, its implementation class, the interfaces it implements, and the modules itdepends on. Other attributes provide version information, a description of the module’sfunctionality, and the developer’s contact information.



Every repository has a System cabinet, which contains a top level folder called Modules.Under Modules are the following folders, corresponding to the out-of-the-box moduletypes:• /System/Modules/SBO

Contains service based objects (SBOs). An SBO is a module whose executablebusiness logic is Java code that extends DfService. Refer to Service based objects(SBOs), page 86 for more information about SBOs.

• /System/Modules/TBO

Contains type based objects (TBOs), that is, customizations of specific repositorytypes. A TBO is a module in which the executable Java code extends a DFC repositorytype (normally, DfDocument) and implements the IDfBusinessObject interface. Referto Type based objects (TBOs), page 94 for more information about TBOs.

• /System/Modules/Aspect

Contains aspects, a type of module used internally by EMC | Documentum software.Aspects are not available for use by developers. This manual does not discussaspects.

Caution: Because EMC | Documentum software uses aspects internally, themethods getObjectWithInterface and getObjectByQualificationWithInterface aredeprecated. You should not use them with DFC 5.3. If you feel that you need touse the capabilities these methods provide, contact EMC | Documentum TechnicalSupport for assistance.

You can create other subfolders of /System/Modules to represent other types of module.For example, if the repository uses Java-based evaluation of validation expressions (see ),the associated modules appear under System/Modules/Validation.

The bottom level folders under this hierarchy (except for aspects) are of typedmc_module. Each contains an individual module.

A module that is in other respects like an SBO but does not implement the IDfServiceinterface is called a simple module. You can use simple modules to implement repositorymethods, such as those associated with workflows and document lifecycles. Theimplementation class of a simple module should implement the marker interfaceIDfModule. Use the newModule method of IDfClient to access a simple module.

The hierarchy of folders under /System/Modules/ is the repository’s module registry, orsimply its registry.

Note: Earlier versions of DFC maintained a registry of TBOs and SBOs on each clientmachine. That registry is called the EMC | Documentum business object registry(DBOR). The DBOR form of registry is deprecated, but for now you can still use it, evenin systems that contain repository based registries. Where both are present, DFC givespreference to the repository based registry.



Dynamic delivery mechanism

Starting with DFC 5.3, BOF delivers the implementation classes of TBOs, SBOs, and othermodules dynamically from repository based registries to client machines. A TBO, anaspect, or a simple module is specific to its repository. An SBO is not. BOF can deliverSBO implementation classes to client machines from a single repository. Global registry,page 84 explains how DFC does this.

Delivering implementation classes dynamically from a repository means that you don’tneed to register those classes on client machines. It also means that all client machinesuse the same version of the implementation class. You deploy the class to one place,and DFC does the rest.

The delivery mechanism supports hot deployment, that is, deployment of newimplementations without stopping the application server. This means that applicationscan pick up changes immediately and automatically. You deploy the module to theregistry, and all clients quickly become aware of the change and start using the newversion. DFC works simultaneously with the new version and existing instantiations ofthe old version until the old version is completely phased out.

The delivery mechanism relies on local caching of modules on client machines (wherethe term client machine often means the machine running an application server and,usually, WDK). DFC does not load TBOs, aspects, or simple modules into the cache untilan application tries to use them. Once DFC has downloaded a module, it only reloadsparts of the module that change.

DFC checks for updates to the modules in its local cache whenever an application tries touse one or after an interval specified in seconds in dfc.bof.cacheconsistency.interval inthe dfc.properties file. The default value is 30 seconds.

If DFC tries to access a module registry and fails, it tries again after a specified interval.The interval, in seconds, is the value of dfc.bof.registry.connect.attempt.interval in thedfc.properties file.

DFC maintains its module cache on the file system of the client machine. You can specifythe location by setting dfc.cache.dir in the dfc.properties file. The default value is thecache subdirectory of the directory specified in dfc.data.dir. All applications that usethe given DFC installation share the cache. You can even share the cache among morethan one DFC installation.

Global registry

In a system with more than one repository, DFC can deliver SBOs from a centralrepository. That repository’s registry is called the global registry.



Planning for the global registry

Using global registries presents many possibilities. BOF places few restrictions on howyou choose to deploy SBOs within your enterprise. Most of your considerations willarise from your own practices and policies. It is important to think through the issuesbefore you establish a global repository.

Every client needs to establish sessions with the repository that contains its globalregistry. We recommend that you create a user specially for this purpose and that yourestrict the access permissions of that user to the minimum necessary. The EMC |Documentum software that sets up repositories enables you to create a such a user, calledan inline user. You should set this up before installing DFC.

Accessing the global registry

The identity of the global registry, if any, is a property of the DFC installation. DifferentDFC installations can use different global registries, but a single DFC installation canhave only one global registry.

The dfc.properties file contains the following properties relating to accessing the globalregistry:• dfc.bof.registry.repository

The name of the repository. The repository must project to a connection brokerthat DFC has access to.

• dfc.bof.registry.username

The user name part of the credentials that DFC uses to access the global registry.Refer to Planning for the global registry, page 85 for information about how to createthis user.

• dfc.bof.registry.password

The password part of the credentials that DFC uses to access the global registry. TheDFC installer encrypts the password if you supply it. If you wish to encrypt thepassword yourself, use the following instruction at a command prompt:java com.documentum.fc.tools.RegistryPasswordUtils password

In addition to efficiency, local caching provides backup if the global registry repository isunavailable. By default, DFC preloads all SBO implementation classes from the globalregistry to the local cache. That is, DFC downloads these classes, regardless of whetheror not any application has tried to instantiate them. DFC does this only once. Thereafter,it downloads an implementation only if it changes – presumably an infrequent event.Restarting DFC does not cause it to lose the contents of its local cache. This providesbackup if the application loses its connection to the repository containing the globalregistry.



If your system has only one repository, you may wish to turn off preloading. You can doso with the following setting in dfc.properties:dfc.bof.registry.preload.enabled = false

Deploying module interfaces

You must deploy the interface classes of your modules to each client machine, that is, toeach machine running an instance of DFC. Typically, you install the interface classes withthe application that uses them. They do not need to be on the global classpath.

A TBO that provides no methods of its own (for example, if it only overrides methodsof DfDocument) does not need an interface. For a TBO that does not have an interface,there is nothing to install on the client machines.

In order to use hot deployment of revised implementation classes (see Dynamic deliverymechanism, page 84), you must not change the module’s interface. Otherwise, you canextend module interfaces without breaking existing customizations.

Service based objects (SBOs)

This section contains the following main sections:• SBO introduction, page 86• SBO architecture, page 87• Implementing SBOs, page 87• Calling SBOs, page 102• SBO Error Handling, page 94• SBO Best Practices, page 94

SBO introduction

A service based object (SBO) is a type of module designed to enable developers to accessEMC | Documentum functionality by writing small amounts of relevant code. Theunderlying framework handles most of the details of connecting to EMC | Documentumrepositories. SBOs are similar to session beans in an Enterprise JavaBean (EJB)environment.

SBOs can operate on multiple object types, retrieve objects unrelated to EMC |Documentum objects (for example, external email messages), and perform processing.You can use SBOs to implement functionality that applies to more than one repository



type. For example, a EMC | Documentum Inbox object is an SBO. It retrieves items froma user’s inbox and performs operations like removing and forwarding items.

You can use SBOs to implement utility functions to be called by multiple TBOs. A TBOhas the references it needs to instantiate an SBO.

You can implement an SBO so that an application server component can call the SBO,and the SBO can obtain and release repository sessions dynamically as needed.

SBOs are the basis for the web services framework.

SBO architecture

An SBO associates an interface with an implementation class. Each folder under/System/Modules/SBO corresponds to an SBO. The name of the folder is the name of theSBO, which by convention is the name of the interface.

SBOs are not associated with a repository type, nor are they specific to the repositoryin which they reside. As a result, each DFC installation can use a global registry (seeModules and registries, page 82). The dfc.properties file contains the informationnecessary to enable DFC to fetch SBO implementation classes from the global registry.

You instantiate SBOs with the newService method of IDfClient, which requires you topass it a session manager. The newService method searches the registry for the SBO andinstantiates the associated Java class. Using its session manager, an SBO can accessobjects from more than one repository.

You can easily design an SBO to be stateless, except for the reference to its sessionmanager.

DFC does not impose constraints on service names, except that names must be uniquewithin a registry. We recommend that you use the fully qualified service interface nameas the service name. If you do this, the call to instantiate an SBO becomes simple.For example, to instantiate an instance of the SBO that implements the IAutoNumberinterface, simply writeIAutoNumber autonumber = (IAutoNumber)client.newService(

IAutoNumber.class.getName(), sMgr);

Implementing SBOs

This section describes the basic structure of an SBO.



An SBO has an interface that extends IDfService and an implementation class thatextends DfService. This ensures that the service provides several methods for revealinginformation about itself to DFC and to applications that use the SBO.

To create an SBO, extend the DfService class and implement the IDfService interface.DfService is an abstract class that defines common methods for services.

Override the following abstract methods of DfService to provide information aboutyour service:• getVersion returns the current version of the service as a string.

The version is a string and must consist of an integer followed by up to threeinstances of dot integer (for example, 1.0 or 2.1.1.36).

• getVendorString returns the vendor’s copyright statement (for example, "Copyright© 1994-2005 EMC Corporation. All rights reserved.") as a string.

• isCompatible checks whether the class is compatible with a specified service version

This allows you to upgrade service implementations without breaking existing code.Java does not support multiple versions of interfaces.

• supportsFeature checks whether the string passed as an argument matches a featurethat the SBO supports.

The getVersion and isCompatible methods are important tools for managing SBOs in anopen environment. The getVendorString method provides a convenient way for you toinclude your copyright information. The supportsFeature method can be useful if youdevelop conventions for naming and describing features.

After implementing the abstract methods of DfService, define the service’s publicinterface, and develop the methods to implement the interface. SBO programmingdiffers little from programming for other environments. The following sections addressthe principal additional considerations.

Stateful and stateless SBOs

SBOs can maintain state between calls, but they are easier to deploy to multithreadedand other environments if they do not do so. For example, a checkin service needsparameters like retainLock and versionLabels. A stateful interface for such a serviceprovides get and set methods for such parameters. A stateless interface makes you passthe state as calling arguments. The following sample interfaces for a checkin serviceillustrate these approaches:// Stateful checkin serviceinterface ICheckin extends DfService {

public void setRetainLock( boolean retainLock );public void setVersionLabels( String newVersionLabels );

. . .



public void checkin( IDfSysObject object )throws DfServiceException;

. . .}

// Stateless checkin serviceinterface ICheckin extends DfService {

. . .

public void checkin( IDfSysObject object, boolean retainLock,String newVersionLabels, . . .)

throws DfServiceException;

. . .}

// Stateless checkin service with a configuration objectinterface ICheckin extends DfService {

public ICheckinConfig newConfig();

. . .

public void checkin( IDfSysObject object, ICheckinConfig config )throws DfServiceException;

. . .}

Notice how the third example combines the stateless approach with the convenience ofthe first example. An ICheckinConfig object holds all parameters required for checkinand provides methods to get and set them. This is a convenient way to design a statelessinterface when the calling program must provide more than a few parameters to theservice.

Managing Sessions for SBOs

This section presents session manager related considerations for implementing SBOs.

Overview

When implementing an SBO, you normally use the getSession and releaseSessionmethods of DfService to obtain a DFC session and return it when finished. Once youhave a session, use the methods of IDfSession and other DFC interfaces to implementthe SBO’s functionality.



If you need to access the session manager directly, however, you can do so from anymethod of a service, because the session manager object is a member of the DfServiceclass. The getSessionManager method returns this object. To request a new session, forexample, use the session manager’s newSession method.

Structuring Methods to Use Sessions

Each SBO method that obtains a repository session must release the session when it isfinished accessing the repository. The following example shows how to structure amethod to ensure that it releases its session, even if exceptions occur:public void doSomething( String strRepository, . . . ) {

IDfSession session = getSession ( strRepository );try { /* do something */ }catch( Exception e ) { /* handle error */ }finally { releaseSession( session ); }

}

Managing repository names

To obtain a session, an SBO needs a repository name. To provide the repository name,you can design your code in any of the following ways:• Pass the repository name to every service method.

This allows a stateless operation. Use this approach whenever possible.• Store the repository name in an instance variable of the SBO, and provide a method

to set it (for example, setRepository (strRepository)).

This makes the repository available from all of the SBO’s methods.• Extract the repository name from an object ID.

A method that takes an object ID as an argument can extract the repository namefrom the object ID (use the getDocbaseNameFromId method of IDfClient).

Maintaining State Beyond the Life of the SBO

The EMC | Documentum architecture enables SBOs to return persistent objects to thecalling program. Persistent objects normally maintain their state in the associated sessionobject. But an SBO must release the sessions it uses before returning to the callingprogram. At any time thereafter, the session manager might disconnect the session,making the state of the returned objects invalid.

The calling program must ensure that the session manager does not disconnect thesession until the calling program no longer needs the returned objects.



Another reason for preserving state between SBO calls occurs when a program performsa query or accesses an object. It must obtain a session and apply that session to anysubsequent calls requiring authentication and Content Server operations. For applicationservers, this means maintaining the session information between HTTP requests.

The main means of preserving state information are setSessionManager and transactions.describes the setSessionManager mechanism and its cost in resources. Using TransactionsWith SBOs, page 91 provides details about using transactions with SBOs.

You can also use the DfCollectionEx class to return a collection of typed objects from aservice. DfCollectionEx locks the session until you call its close method.

Obtaining Session Manager State Information

For testing or performance tuning you can examine such session manager state asreference counters, the number of sessions, and repositories currently connected. Use thegetStatistics method of IDfSessionManager to retrieve an IDfSessionManagerStatisticsobject that contains the state information. The statistics object provides a snapshot of thesession manager’s internal data as of the time you call getStatistics. DFC does not updatethis object if the session manager’s state subsequently changes.

The DFC Javadocs describe the available state information.

Using Transactions With SBOs

DFC supports two transaction processing mechanisms: session based and sessionmanager based. describes the differences between the two transaction mechanisms. Youcannot use session based transactions within an SBO method. DFC throws an exceptionif you try to do so.

Use the following guidelines for transactions within an SBO:

• Never begin a transaction if one is already active.

The isTransactionActive method returns true if the session manager has a transactionactive.

• If the SBO does not begin the transaction, do not use commitTransaction orabortTransaction within the SBO’s methods.

If you need to abort a transaction from within an SBO method, use the sessionmanager’s setTransactionRollbackOnly method instead, as described in the nextparagraph.

When you need the flow of a program to continue when transaction errors occur,use the session manager’s setTransactionRollbackOnly. Thereafter, DFC silentlyignores attempts to commit the transaction. The owner of the transaction does



not know that one of its method calls aborted the transaction unless it calls thegetTransactionRollbackOnly method, which returns true if some part of the programever called setTransactionRollbackOnly. Note that setTransactionRollbackOnly does notthrow an exception, so the program continues as if the batch process were valid.

The following program illustrates this.void serviceMethodThatRollsBack( String strRepository, IDfId idDoc )

throws DfNoTransactionAvailableException, DfException {

IDfSessionManager sMgr = getSessionManager();IDfSession = getSession( strRepository );if( ! sMgr.isTransactionActive() ) {throw new DfNoTransactionAvailableException();

}

try {IDfPersistentObject obj = session.getObject( idDoc );obj.checkout()modifyObject( obj );obj.save();

}

catch( Exception e ) {setTransactionRollbackOnly();throw new DfException();

}}

When more than one thread is involved in session manager transactions, callingbeginTransaction from a second thread causes the session manager to create a newsession for the new thread.

The session manager supports transaction handling across multiple services. It does notdisconnect or release sessions while transactions are pending.

For example, suppose one service creates folders and a second service stores documentsin these folders. To make sure that you remove the folders if the document creation fails,place the two service calls into a transaction. The DFC session transaction is bound toone DFC session, so it is important to use the same DFC session across the two servicescalls. Each service performs its own atomic operation. At the start of each operation, theyrequest a DFC session and at the end they release this session back to the session pool.The session manager holds on to the session as long as the transaction remains open.

Use the beginTransaction method to start a new transaction. Use the commitTransactionor abortTransaction method to end it. You must call getSession after you callbeginTransaction, or the session object cannot participate in the transaction.

Use the isTransactionActive method to ask whether the session manager has a transactionactive that you can join. DFC does not allow nested transactions.

The transaction mechanism handles the following issues:



• With multiple threads, transaction handling operates on the current thread only.

For example, if there is an existing session for one thread, DFC creates a new sessionfor the second thread automatically. This also means that you cannot begin atransaction in one thread and commit it in a second thread.

• The session manager provides a separate session for each thread that callsbeginTransaction.

For threads that already have a session before the transaction begins, DFC creates anew session.

• When a client starts a transaction using the beginTransaction method, the sessionmanager does not allow any other DFC-based transactions to occur.

The following example illustrates a client application calling two services that must beinside a transaction, in which case both calls must succeed, or nothing changes:

IDfClient client = DfClientX.getLocalClient();IDfSessionManager sMgr = client.newSessionManager();

sMgr.setIdentity(repo, loginInfo);

IMyService1 s1 = (IMyService1)client.newService(IMyService1.class.getName(), sMgr);

IMyService2 s2 = (IMyService2)client.newService(IMyService2.class.getName(), sMgr);

s1.setRepository( strRepository1 );s2.setRepository( strRepository2 ) ;

sMgr.beginTransaction();

try {s1.doRepositoryUpdate();s2.doRepositoryUpdate();sMgr.commitTransaction();

}

catch (Exception e) {sMgr.abortTransaction();

}

If either of these service methods throws an exception, the program bypasses commitand executes abort.

Each of the doRepositoryUpdate methods calls the session manager’s getSession method.

Note that the two services in the example are updating different repositories.Committing or aborting the managed transaction causes the session manager to commitor abort transactions with each repository.

Session manager transactions involving more than one repository have an inherentweakness that arises from their reliance on the separate transaction mechanisms of



the databases underlying the repositories. Refer to for information about what sessionmanager transactions can and cannot do.

SBO Error Handling

The factory method that instantiates SBOs throws a variety of exceptions. For example, itthrows DfServiceInstantiationException if DFC finds the requested service but is unableto instantiate the specified Java class. This can happen if the Java class is not in theclasspath or is an invalid data class. Security for Java classes on an application server canalso cause this exception.

SBO Best Practices

This section describes best practices for using SBOs.

Don’t Reuse SBOs

Instantiate a new SBO each time you need one, rather than reusing one. Refer to CallingSBOs, page 102 for details.

Make SBOs Stateless

Make SBOs as close to stateless as possible. Refer to Stateful and stateless SBOs, page88 for details.

Rely on DFC to Cache Repository Data

DFC caches persistent repository data. There is no convenient way to keep a privatecache synchronized with the DFC cache, so rely on the DFC cache, rather thanimplementing a separate cache as part of your service’s implementation.

Type based objects (TBOs)

This section contains the following main sections:• TBO introduction, page 95



• TBO architecture, page 97• Implementing TBOs, page 97• Calling TBOs, page 103• TBO best practices, page 101

TBO introduction

Type based objects (TBOs) are extensions of basic DFC types, such as IDfPersistentObject,IDfSysObject, IDfDocument, IDfFolder, or any other class that extendsIDfPersistentObject. They can encapsulate business logic that is specific to a given objecttype. The main reasons for creating a TBO are to:• Provide a new behavior for existing or new object types

For example, you can add get and set methods for attributes, or create new methods,such as addProduct for a Catalog TBO.

• Customize low level operations to enforce data validation, referential integrity andbusiness rules

For example, you can override the doSave and doCheckin methods to validateattributes before updating the object in the repository.

Type based objects (TBOs)

A type based object (TBO) associates a user-defined EMC | Documentum type (normally asubtype of dm_document) with an implementation class that extends the appropriateDFC class (normally, DfDocument). For example, if you have documents in yourrepository that describe standard operating procedures, you can take the following stepsto apply special business logic to them (this procedure omits many details):

1. Create a repository type (for example, sop_document) as a subtype of dm_document.

2. Develop a Java class (for example, StandardOpProcedureDoc) to implement thebusiness logic as an extension of DfDocument.

3. Optionally, create an interface (for example, ISOP) to describe the public functionalityof StandardOpProcedureDoc.

4. Use EMC | Documentum Application Builder (DAB) to package theStandardOpProcedureDoc class, its interface, and its documentation into a DocApp.

5. Install the DocApp into the given repository.



Performing this procedure creates the folder /System/Modules/TBO/sop_document inthe repository. This folder contains everything necessary to ensure that the businesslogic in StandardOpProcedureDoc executes at the appropriate times.

A TBO is specific to the repository in which it resides. Two repositories can haveuser-defined types with the same name (for example, sop_document). Each can havea /System/Modules/TBO/sop_document folder, but the folders in the two repositoriescan have different contents. For example, the implementation in one repository mightoverride the standard EMC | Documentum checkin functionality to link the documentinto a special folder when you check it in. The implementation in the other repositorymight start a workflow when you check in the document.

TBOs provide a way for you to extend DfDocument, the EMC | Documentum class thatimplements IDfDocument. You can define a hierarchy of subtypes of the dm_documenttype and a corresponding hierarchy of implementation classes that extend DfDocument.

A TBO’s implementation class must implement IDfBusinessObject andIDfDynamicInheritance. IDfDynamicInheritance is a marker interface. ImplementingIDfDynamicInheritance allows your class hierarchy to adjust itself at run time to matchchanges to the repository type hierarchy, even if those changes occur after you writeyour code.

For example, suppose that you create sop_document as a subclass of dm_documentand create an associated TBO with implementation class StandardOpProcedureDoc,which extends DfDocument. Further suppose that someone subsequently changes thehierarchy of types in the repository to make sop_document a subtype of a new userdefined type, controlled_document, which is a subtype of dm_document. Finally,suppose that someone creates a TBO for controlled_document with an implementationclass ControlledDoc, which extends DfDocument. In this case, DFC modifies the classinheritance at run time, so StandardOpProcedureDoc extends ControlledDoc rather thanDfDocument as it originally did.

Note: Classes that implement IDfDynamicInheritance are incompatible with DFCversions prior to version 5.2.

The factory methods of IDfSession take the user defined type as an argument andinstantiate the TBO’s implementation class. The resulting object performs tasks specificto the user-defined type, possibly overriding methods of DfDocument.

A TBO object has references to:• The IDfSession object that created the TBO

Use the getSession method to obtain a reference to the IDfSession object. If thecalling program releases the session, that reference may become invalid.

• The IDfClient object that created the session

Use the getClient method to obtain a reference to the IDfClient object.• The IDfSessionManager object that manages the TBO’s session



Use the getSessionManager method to obtain a reference to the IDfSessionManagerobject. If the session that created the TBO is not under control of a session manager,DFC creates a session manager to manage the session. This is helpful whenmigrating legacy applications to the current version of DFC.

TBO architecture

The object factory of IDfSession constructs TBOs at runtime. You define TBOs bydefining custom repository types (for example, subtypes of dm_document). You definetheir behavior in an implementation class that extends the corresponding DFC classes(for example, DfDocument). When you develop and deploy a TBO on your system,the framework guarantees that all software accessing this object instantiates yourimplementation class.

TBOs allow you to create and enforce business rules for custom types. For this tosucceed, all programs that access repository objects of the given type must use themethods that implement those rules.

Use the standard DFC factory methods to construct an instance of a TBO. For example,ISOP sop = (ISOP)session.newObject ( "sop_document" );

ISOP sop = (ISOP)session.getObject ( idDoc );

Whenever a program calls methods like newObject or getObject, DFC constructs aninstance of the Java class for the TBO. The factory method checks the registry in therepository to ensure that it instantiates the correct class.

For example, the registry might map the sop_document type to theStandardOpProcedureDoc.Java class, which implements the ISOP interface. The clientapplication can use this interface to handle and control a standard operating procedureobject.

Implementing TBOs

The following sections describe tasks you must perform when implementing TBOs.

Dene an interface

Optionally, define an interface (for example, ISOP) to the TBO to include the methodsthat you recommend programmers use with objects of this type. You need not define aninterface if you only intend to use the TBO to override existing methods of the parenttype.



We recommend against defining the type’s interface to extend the interface of itscorresponding repository supertype (refer to Avoid extending DFC interfaces, page101 ). The interface for your TBO should be separate from and not extend theIDfBusinessObject interface.

Dene an implementation class

Extend the DFC superclass that matches the repository supertype. Implement theIDfBusinessObject interface and the TBO interface of the new class if you have definedone. Implement IDfDynamicInheritance to ensure that the class hierarchy can adjustdynamically to changes in the repository type hierarchy.protected class StandardOpProcedureDoc extends DfDocumentimplements ISOP, IDfBusinessObject, IDfDynamicInheritance{ }

Implement methods of IDfBusinessObject

Implement the methods of the IDfBusinessObject class: getVersion, getVendorString,isCompatible, supportsFeature.

Table 12-1. IDfBusinessObject methods to implement

Method Description

getVersion Return a String (for example, "1.0") that describesthe version of the Java class for this object type. Itcan be up to four integers separated by periods.Application Builder returns an error if you tryto deploy a TBO that returns an invalid versionstring.

getVendorString Return a constant String that provides copyrightinformation (for example, "Copyright 2003, EMC| Documentum, Inc.")

isCompatible Return True if the String passed as an argumentmatches a supported version. Otherwise returnFalse.

supportsFeature Return True if the String passed as an argumentmatches a supported feature. Otherwise returnFalse.



Implement the TBO’s business rules

When you design a TBO, you can• Create new methods (for example, to get or set custom attributes or to provide new

functionality)• Override inherited methods (for example, to validate attributes or to implement

abstract methods)To override a method of the superclass, it is usually simplest to include a call to themethod you are overriding as part of your code. For example,

protected void doSave() {validate(); // new functionalitysuper.doSave(); // inherited functionality

}

We do not provide the detailed internal documentation of EMC | Documentumimplementation classes that would be necessary for you to know precisely how toextend them. You can use tracing to help with specific questions. For most purposes,however, the following section,Overriding methods in TBOs, page 99, gives a good ideaof which methods to override.

Another method you may wish to override when implementing a TBO is the init methodof the DfPersistentObject implementation class. The factory method calls init duringinstantiation of the TBO. When it calls init, it has already completely instantiated thepersistent object, so you can use the session and the object ID of the TBO in yourinitialization code.

Remember that a future TBO might extend the class you write. Be sure to documentany problems that programmers might encounter in extending your class. If you mustprevent such extensions, consider defining the class to be final.

Overriding methods in TBOs

Creating a type based object (TBO) sometimes entails overriding methods of DfSysObject.DFC 5.3 introduces a set of methods designed to make this easier to do.

The process for overriding methods of DfSysObject prior to DFC 5.3 poses the followingproblems:• Because different client programs sometimes invoke different methods to perform

the same task, you may need to override more than one method with the sameoverride code.

For example, if you override the save method to customize checkin behavior, youmust also override the savelock method.



• Subsequent changes to DFC internals may render your customization obsolete.

For example, you may have overridden the getFileEx2 method to customize exportbehavior. A subsequent version of DFC may introduce a method called getFileEx3that behaves the same as getFileEx2 but takes an additional argument. If getFileEx3does not call getFileEx2, then any clients that call getFileEx3 will bypass yourcustomization.

The override process introduced in DFC 5.3 eliminates these problems. The remainder ofthis section explains how it works.

The DFC Development Guide for DFC 5.2.5 SP2 contains a table that tells you whichmethods to override for some common tasks you might wish to customize.

With DFC 5.3, we deprecate the practice of overriding the methods that appear in theDFC 5.2.5 table. Existing customizations that override those methods will still work, soyou can move gradually to the new method. The deprecated overrides may not continueto work if you upgrade to versions of DFC beyond 5.3.

To replace the deprecated practice, we provide a set of protected domethods (doCheckin,doCheckout, and so forth). These are the only methods of DfSysObject for which wesupport overrides. All of the old methods now delegate the meat of their tasks to thedo methods. Thus, rather than overriding save and savelock, you need only overridedoSave. The save and savelock methods call doSave, the checkinEx method callsdoCheckin, and so forth. The final argument of each do method is an object array, whichallows for future enhancements without breaking existing customizations.

lists the signatures of the do methods.

To safely override any of the do methods, imitate the following pattern:

class MyTBO extends DfSysObject {// . . .protected void doSave (

boolean saveLock,String versionLabel,Object[] extendedArgs)throws DfException

{//optional preprocessingsuper.doSave (saveLock, versionLabel, extendedArgs);//optional post-processing

}}

Implement COM interfaces if needed

Construct a COM interface if a module adds new methods to a TBO.



The IDispatch interface makes the classes and methods of modules available to COM.You can also create an IDL file or a TLB file.

Avoid carrying state information

For efficient operation in an application server environment, make your TBO as closeto stateless as possible.

A TBO has a reference to its session as a data member. That reference can becomeinvalid if the requesting method releases the pooled session. You can use the TBO’ssetSessionManager method to separate the TBO from its session and put the TBO undercontrol of the session manager. This is required in cases where a stateless SBO createsa TBO, which is stateful, to return to the caller. Refer to for information about howto do this.

TBO best practices

This section describes best practices for developing TBOs.

Avoid extending DFC interfaces

Define simple interfaces for your TBOs. For example, if your TBO’s implementation classextends DfDocument, do not define its public interface to extend IDfDocument. Instead,restrict the interface to those methods you expect users of the TBO to call directly.

Because the TBO’s class extends DfDocument, you can still use all DfDocument methods.

Design extendable TBOs or make them nal

Others may wish to extend your TBO to add additional features. Provide documentationthat supports this use, or consider making your implementation classes final if you donot want others to extend them.

Do not replace implementation classes for Documentum types

We do not support remapping of standard repository types to custom classes.



Do not use UPDATE queries

DFC does not call the methods of your TBO class if you use UPDATE queries to modifythe attributes of a TBO. Thus, using UPDATE queries circumvents the business logic thatthe TBO implements and can lead to inconsistencies and errors. In general, you shouldnot use UPDATE queries.

Calling TBOs and SBOs

This section describes special considerations for using TBOs and SBOs.

The BOF deployment mechanism introduced with DFC 5.3 requires you to take stepsto ensure that your applications have access to the interfaces of your modules. Refer toDeploying module interfaces, page 86 for more information.

Calling SBOs

This section provides rules and guidelines for instantiating SBOs and calling theirmethods.

The client application should instantiate a new SBO each time it needs one, rather thanreusing one. For example, to call a service during an HTTP request in a web application,instantiate the service, execute the appropriate methods, then abandon the service object.

This approach is thread safe, and it is efficient, because it requires little resourceoverhead. The required steps to instantiate a service are:

1. Prepare an IDfLoginInfo object containing the necessary login information.

2. Instantiate a session manager object.

3. Call the service factory method.

The following code illustrates these steps:IDfClient client = DfClient.getLocalClient();

IDfLoginInfo loginInfo = new DfLoginInfo();loginInfo.setUser( strUser );loginInfo.setPassword( strPassword );if( strDomain != null )

loginInfo.setDomain( strDomain );

IDfSessionManager sMgr = client.newSessionManager();sMgr.setIdentity( strRepository, loginInfo );IAutoNumber autonumber = (IAutoNumber)

client.newService( IAutoNumber.class.getName(), sMgr);



An SBO client application uses the newService factory method of IDfClient to instantiatea service:public IDfService newService ( String name, IDfSessionManager sMgr )

throws DfServiceException;

The method takes the service name and a session manager as parameters, and returns theservice interface, which you must cast to the specific service interface. The newServicemethod uses the service name to look up the Java implementation class in the registry. Itstores the session manager as a member of the service, so that the service implementationcan access the session manager when it needs a DFC session.

Returning a TBO from an SBO

The following example shows how to return a TBO, or any repository object, fromwithin an SBO method.

public IDfDocument getDoc( String strRepository, IDfId idDoc ) {IDfSession session = null;IDfDocument doc = null;try {session = getSession ( strRepository );doc = (IDfDocument)session.getObject( idDoc );doc.setSessionManager (getSessionManager());

}finally { releaseSession( session ); }return doc;

}

Because getDoc is a method of an SBO, which must extend DfService, it has accessto the session manager associated with the service. The methods getSession,getSessionManager, and releaseSession provide this access.

Refer to for information about the substantial costs of using the setSessionManagermethod.

Calling TBOs

Client applications and methods of SBOs can use TBOs. Use a factory method ofIDfSession to instantiate a TBO’s class. Release the session when you finish with theobject.



Within a method of an SBO, use getSession to obtain a session from the session manager.DFC releases the session when the service method is finished, making the session objectinvalid.

Use the setSessionManager method to transfer a TBO to the control of the sessionmanager when you wish to:

• Release the DFC session but keep an instance of the TBO.• Store the TBO in the SBO state.Refer to for information about the substantial costs of using the setSessionManagermethod.

When calling an SBO method that returns a TBO, use client control, as described inAvoid carrying state information, page 101.

Web ServicesThese topics are included:• Overview of Web Services, page 104• Installing the Web Services Framework• Developing a Web Service, page 108• Enabling a service-based business object as a Web Service, page 110• Deploying a Web Service, page 111• Updating a Web Service, page 111• Using a Web Service, page 112

Overview of Web Services

The term web services refers to an arrangement whereby an organization makescertain capabilities available to be accessed remotely in a platform-independent,language-independent manner. For example, Amazon.com lets you to requestavailability and pricing information about books by sending hypertext transfer protocol(HTTP) requests to their server.

The EMC | Documentum web services framework provides a way to make EMC |Documentum capabilities available as web services on your intranet. Web services canbe useful in the following cases:• To provide information stored in EMC | Documentum repositories to enterprise

applications that do not have an integral integration with EMC | Documentumsoftware.



• To enable employees to access EMC | Documentum repositories even if they have nodirect access to EMC | Documentum client software.

Nothing in the framework prevents you from making web services available outsideyour corporate intranet, but the framework does not explicitly support that use case, andis not optimized for it. In particular, EMC | Documentum web services provide onlyminimal security above the transport level. You might wish to analyze the security issuesthat web services present in your environment.

As you consider how to deploy web services in your organization, you might wish torefer to a short essay called Eight Fallacies of Distributed Computing, which computerscientist L. Peter Deutsch first published some time around 1990.

SOAP and Apache Axis

EMC | Documentum web services use the simple object access protocol (SOAP), aproposed standard of the World Wide Web Consortium (W3C). SOAP normally sits ontop of HTTP, although it can use other underlying transfer protocols. It has the followingparts:• An envelope for describing what is in a message and how to process it• A set of encoding rules for datatypes• A remote procedure call mechanismThe web services framework uses the Apache Axis implementation of SOAP. Axistakes care of the details of the envelope, the encoding rules, and the procedure callingconventions. The web services framework uses EMC | Documentum ApplicationBuilder (DAB) and the capabilities of Axis to transform service based objects (SBOs) intoa form that Axis can use.

WSDL

While Axis takes care of the server side of SOAP interactions, we rely on the capabilitiesof different programming environments to handle the client side. To facilitatedevelopment of the client side of SOAP interactions, the web services frameworkproduces descriptions of web services using the Web Services Description Language(WSDL). Clients can request WSDL descriptions and use them to produce client sideproxies for the corresponding web services.

The web services framework produces WSDL descriptions, not client side proxies.All supported client environments have mechanisms for creating proxies fromWSDL descriptions. The mechanisms and the resulting proxies vary from one clientenvironment to another.



Runtime ow

At run time, an Axis-generated web service object (a SOAP wrapper for the original SBO)runs on the application server. A proxy runs on the client. When a client applicationcalls the proxy, the proxy uses SOAP to send the client application’s request to the webservice object. The web service object translates the request into a call to the original SBO.When the web service object receives a response from the SBO, it uses SOAP to send theresponse to the client side proxy, which passes the response to the client application.

For services that access a repository, the SBO’s session manager must have appropriatecredentials. The web services framework accomplishes this by providing a credentialsservice. The client application uses the credentials service to authenticate the useragainst the repository. The credentials service instantiates a session manager with theuser’s credentials and passes back a token to allow the client’s next service call to connectthe service’s SBO to the session manager that has the user’s credentials. The credentialsservice also enables the client application to update the credentials or to provide thesession manager with credentials to more than one repository.

Setup

For all of this to work, you must do the following:• Install the web services framework.

This includes installing the credentials service and its WSDL description on anapplication server.

• Develop an SBO suitable for use as a web service, and deploy it to the global registry.• Produce the corresponding web service object and its WSDL description, and deploy

them to the application server.• From the client, request the WSDL descriptions from the application server, and

use them to generate client side proxies.• From the client application program, call the client side proxies to authenticate the

user and access the web service.

Development ow

For each new web service that you wish to provide, perform the following steps:

1. Develop an SBO as the basis for a web service.

Developing an SBO for web services follows the same development pattern as forother SBOs, but you may need to make different design decisions.



2. Use EMC | Documentum Application Builder (DAB) to produce an appropriate webservices description language (WSDL) description and create a new war file thatmerges your SBO and its supporting elements (including its WSDL description) withthe contents of the war file already in the global registry.

3. Use DAB to check the updated war file into the global registry as a new version.

4. Deploy the new war file to your application servers, replacing the previous one.

This is a manual step. It includes running a tool that patches the WSDL in the warfile to change the URL to match that of the application server to which you aredeploying it.

Most application servers provide a simple mechanism for hot deployment, that is,updating a war file without stopping the application server.

After you have carried out this procedure, the WSDL description of your web service isavailable from the application server. The documentation you provide for the underlyingSBO is available from the global registry.

Installing the Web Services Framework

To install the web services framework, run the web services installer on your applicationserver machine. The DFC Installation Guide contains instructions for performing theinstallation.

The installer performs the following tasks:• Install DFC on the application server machine (if it is not there already).• Ensure that DFC has the information and credentials necessary to access the global

registry.

Refer toGlobal registry, page 84) for details about global registries.• Install a war file that contains the basic runtime support servlets for web services.

The basic support includes establishing and maintaining the necessary repositoryconnections.

• Install the war file into the global registry.

The war file in the global registry becomes the basis for future development. Whenyou develop new web services, you add them to the war file in the global registry,then deploy the modified war file to the application server.

• Create and install a key for use in encrypting user credentials.If your system uses a cluster of application server machines, you must run the installeron each. The installer provides a means to ensure that all machines in the cluster use thesame key for encrypting user credentials.



Developing a Web Service

Developing a web service follows the same steps as developing an SBO, but not everySBO is suitable for use as a web service. Also, SBO developers do not normally need tohandle content transfer issues explicitly, but this is not true for web services.

Designing an SBO for Web Services

This section describes the way to design an SBO (or modify an existing one) so that it issuitable for use as a web service.

Avoid chatty interactions

Design your SBO in such a way that it accepts a simple request and returns the desiredresult.

Do not overload methods

In the web service environment, there is no way to distinguish between methods thathave the same name but different signatures.

Conform to JAX-RPC type restrictions for arguments and return values

The Java API for XML-based remote procedure calling (JAX-RPC) is an integral part ofSOAP. JAX-RPC supports the following types:• Primitive types (boolean, byte, short, int, long, float, double) and the corresponding

wrapper Java classes.• Standard Java classes (String, Date, Calendar, and others).• Java arrays of supported Java types.• JAX-RPC value types (for example, JavaBeans).You can also use java.io.file as an argument or return type, because the frameworkconverts it to a byte array for base 64 encoded transfers or to a String for UCF transfers(see Content Transfer from Web Services, page 109). You cannot use a file array. You canuse IDfTime, which the web services framework converts to Calendar.



Do not use Java collections

Java collections do not translate well into the .NET environment.

Do not use interfaces for repository objects

Pass IDfId rather than IDfPersistentObject or any of its subclasses (for example,IDfDocument). The framework converts IDfId to a String.

The framework converts many DFC interfaces to types that work with SOAP.

Content Transfer from Web Services

This section describes the options for transferring content within a web service.

If a method of your SBO has a parameter or return type of java.io.File, DAB generatescode for content transfer. You must tell it which of the following options to use:• Base64 encoded data

This method works without additional software. However, it requires the entire fileto be in memory, which is problematic for large files.

• UCF

This method carries out a buffered content transfer in a way that requires only aportion of a file to be in memory at once. However, it requires you to install a smallportion of the unified client facilities (UCF) software on the client machine. Theweb services framework installer installs the required UCF code on the applicationserver machine. Add ucf-installer.jar to the application server’s classpath, and runthe following code:IInstallerService srv = LauncherFactory.newInstallerService(new URL("http://localhost:8080/dfcws/ucf.installer.config.xml"));

srv.install();This places the UCF client JARs required to compile client code that runs UCF intothe following location:. . .\Documentum\ucf\machineName\shared\bin

The code sent to run on the client machine includes a small UCF initialization step.Caution: Once the UCF client JARs are on the application server machine, you can seemany public interfaces that are not yet released. These are subject to change withoutnotice.



You can specify both Base64 and UCF. DAB uses this information to create theappropriate WSDL description of the SBO. It appends XferBase64 to the operation namefor base64 encoded data. It appends XferUcf to the operation name for a UCF transfer.

Enabling a service-based business object as a WebService

A EMC | Documentum Web Service is wrapper around an SBO (service-based object)business object that enables the SBO to run on an application server as a cross-platform,cross-language, distributed application.

Before enabling an SBO as a web service, you must install the EMC | DocumentumWeb Services Framework. See theWeb Services Installation and Release Notes, andWebServices Development Guide for more information about the EMC | Documentum WebServices Framework.

To enable a business object as a Web Service:

1. Create a new module for an SBO or insert an existing one into the DocApp.See Creating new modules or adding existing ones from Docbases, page 113.

2. On the Web Service tab, check the Enable as Web Service option.For more information about this tab, see Module editor: Web Services tab, page 123

3. To enable EMC | Documentum UCF (Unified Client Facilities) content transfer(checkin) of attachments, check the Enable UCF attachment option.

Note: UCF is a EMC | Documentum feature that has more advantages—includingbetter performance—over Base 64 encoding. See the DFC Development Guide formore information.

4. To enable Base 64 encoding of attachments for content transfer (checkin), check theEnable Base 64 encoding attachment option.

Note: Base 64 encoding is a technique used to serialize binary data (that is,attachments) in an XML document (that is, a SOAP message).

5. Include the web service in specific WARs.Use Add and Remove to add the appropriate WARs to the Selected WARs textbox.These WAR files are added to the DocApp.

Caution: If the SBO and web service remain in the DocApp, do not remove thecorresponding WAR files otherwise, creating a DocApp archive will fail.



6. To include the web service’s non-JAR files that you want to be downloaded from therepository to the client machine, select them in the Downloadable objects field onthe Miscellaneous tab.

Deploying a Web Service

After you use DAB to produce a DocApp containing the updated war file, use thefollowing procedure to deploy the service:

1. Install the DocApp to update the war file in the global registry as a new version

2. Export the war file to the file system.

3. Run com.documentum.bof.webservices.deploy.DeploymentPreprocessor to patchthe WSDL description in the war file, so that the URL matches the one you wantclients to use to access the service.

Pass it the URL of the /services directory on the application server (for example,http://www.mycompany.com/dctm) and the file system path to the war file. Ifthe service name is myService, for example, the URL in the war file becomeshttp://www.mycompany.com/dctm/services/myService.

4. Deploy the patched war file to the application servers, using whatever techniquesthe application servers provide for adding or replacing war files.

Once you have done this, the WSDL is available from the application server, so that clientapplication programs can use the service.

Updating a Web Service

To update a web service, modify the SBO implementation as desired and deploy it to theglobal registry. If the modifications do not entail changes to the method signatures ofthe SBO, the existing WSDL need not change, so there is no need to change anythingon the application server.

If your SBO changes require WSDL changes, the update procedure is exactly the sameas creating a new web service.



Using a Web Service

After you have obtained the WSDL and generated proxies, your client application codeshould look like the following pseudocode:

If you plan to use UCF, set it upPass a credentials info object to the credentials serviceReceive a credentials tokenPlace the token into the SOAP header of the web serviceCall the web service

Different client environments produce different forms of this code. For example, supposean SBO has the following interface:public interface ISuperEcho{

public IDfTime getTime() throws DfException;public String echo(String s) throws DfException;

}

If you are working in VisualStudio.NET, you might open web references called cred forthe DocbaseCredentials service and se for the SuperEcho service. Doing this is sufficientto cause VisualStudio.NET to create the proxies.

The C# code for accessing the SuperEcho service might look like the following:cred.DocbaseCredentialsInfo info =

new cred.DocbaseCredentialsInfo();info.docbaseName = "FinancialRecords";info.user = "Comptroller";info.password = "InTheBank";

cred.DocbaseCredentialsService credsvc =new cred.DocbaseCredentialsService();

string ticket = credsvc.newCredentials(info, true);

se.DocumentumSecurityToken securityToken =new se.DocumentumSecurityToken();

securityToken.token = ticket;

se.SuperEchoService echosvc =new se.SuperEchoService();

echosvc.DocumentumSecurityTokenValue = token;Console.WriteLine(echosvc.echo("ooh aah"));

System.DateTime time;bool notNull;echosvc.getTime(out time, out notNull);Console.WriteLine(time);



The reason that the proxy for getTime has two arguments is that a System.DateTimecannot be null, but an IDfTime can.

This chapter does not provide all of the details necessary to use web services. It assumesthat you are experienced in using web services and can figure out the quirks of WSDLand proxy generation in your programming environment.

Creating new modules or adding existing onesfrom Docbases

Before creating a new module for a EMC | Documentum business object:

1. Create a JAR file that contains only the business object’s implementation classes andanother JAR file that contains only its interface classes.

2. Make sure you have the JAR files containing the interfaces of any other modules onwhich your module depends.You will need to specify them in DAB.

3. Make sure you have any documentation and third-party Java libraries that youwant to include in the module.DAB can package items, such as configuration files, that are not in JARs. Youcan access these files from a business object’s implementation by using the class’sgetResourceAsStream method.

Creating a new module checks the business object into a 5.3 or 5.2.x Docbase and enablesit for dynamic download from the Docbase to a local machine.

5.2.x repositories must be enabled for use with this feature; see your Content Server 5.3Release Notes and Installation Guide for more information.

After creating and checking in your module for the first time, ensure that the module’sinterface JAR file is installed on each client machine—the module’s implementation JARfile is dynamically deployed to each client machine. Unless the interface changes, you donot need to reinstall the module’s interface JAR file. See Dynamic delivery mechanism,page 84 and Deploying module interfaces, page 86 for more information.

For more information about BOF, see BOF, page 81.

To create a new module:

1. Choose Insert → Module.

2. In the left pane, double-click the module.

3. On the Implementation tab:

a. Enter a name for the module in the Name text box.



b. To check in the components of the module, such as JARs and other documents,as Major, Minor, or the Same version, select the Check in objects as field.

c. Select the JARs that contain your implementation classes in the ImplementationJARs text box.

d. Select a primary Java implementation class for this module in the Class Namefield. This field displays all of the fully qualified Java class names in theImplementation JARs textbox.

4. Enter text or choose values for the remaining optional fields; see these topics formore information:• Module editor: Implementation tab, page 114• Module editor: Runtime Environment tab, page 117• Module editor: Dependencies tab, page 118• Module editor: Miscellaneous tab, page 122• Module editor: Web Services tab, page 123

5. To check in the module, select it and choose DocApp→ Check In Object(s).

To add an existing module from the Docbase:

1. Choose Insert → Object from Docbase → Module.When you insert a TBO or generic module (a module that is not a TBO or SBO),the corresponding object type and any other TBOs—but not SBOs or other genericmodules—upon which the TBO or generic module depends are also inserted. Whenyou insert an SBO, any other SBOs, TBOs, or generic modules upon which the SBOdepends are also inserted.

Caution: If the TBO remains in the DocApp, do not remove the corresponding objecttype; otherwise, creating a DocApp archive will fail.

2. If desired, modify the module as instructed in the preceding procedure.

Module editor: Implementation tab


For the full procedure on creating a module, see Creating new modules or addingexisting ones from Docbases, page 113.



Name (Required) Module name (which is uniquewithin a Docbase) that is identical to:• For SBOs, typically, the primaryinterface name (fully qualified)of the SBO. For example,com.documentum.mySBO

• For TBOs, the name of thecorresponding object type. Forexample, dm_document

Maximum length is 255 characters. Youcannot change the module name after ithas been checked in for the first time.

Module Type (Optional) Identifies the type ofthe module. Corresponds to thea_module_type attribute of thedmc_module object type. The standardtypes are TBO and SBO; in addition,developers can define their own moduletypes.

Maximum length is 64 characters.

When the type is specified, the moduleand its components are stored in thisDocbase path: /System/Modules/module_type/module_name.. When the typeis not specified, the module and itscomponents are stored in this Docbasepath: /System/Modules/module_name. Ifthe module type of an existing module ischanged, the module and its componentsare moved to the appropriate Docbasefolder.



Check in objects as (Required) Indicates whether to checkin the components of the module, suchas JARs and other documents, as Major,Minor, or the Same version. Default isMinor. You specify this option on everymodule checkin. (The value in this field isnot saved with the module itself.)

Note: The core implementation andinterface JARs are removed and addedback into the module, so they are notshown as versioned.

Interface JARs (Optional) Java interfaces that this moduleimplements. Corresponds to the dmc_jarobjects with a jar_type attribute set to 1in the dmc_module folder. Add interfaceJARs from your local machine to theDocbase.

Implementation JARs (Required) Implementation of the module.Corresponds to the dmc_jar objects witha jar_type attribute set to 2 in thedmc_module folder. Add implementationJARs from your local machine to theDocbase.

Class Name (Required) Primary Java implementationclass for the module. Corresponds tothe dmc_module object’s primary_classattribute. This field displays all ofthe fully qualified Java class names inthe implementation JARs specified onthe Implementation tab. The primaryclass is validated to make sure that itimplements the required interfaces.For example, TBOs must implementthe IDfBusinessObject interface; SBOsmust implement the IDfService interface;and all modules must implement theIDfModule interface.



BOF Version (Optional, Read-Only) Programmaticversion of a business object. Correspondsto the dmc_module object type’sa_bof_version attribute. Only applies tobusiness objects. The BOF version valueis validated to make sure that the versionstring conforms to the standard format:integer[. integer] [. integer]. [integer]

Interfaces (Optional, Read-Only) All interfacesimplemented by the primary class.Corresponds to the dmc_module objecttype’s a_interfaces attribute. If theimplementation JARs are modified afterthe initial check-in, they are validated toensure that the updated primary class stillimplements all of the existing interfaces.

Module editor: Runtime Environment tab



Min DFC Version (Optional) The minimum DFCversion on the client machine forthis module to work properly.Corresponds to min_dfc_version ofdmc_module. Modification of thisvalue triggers the regeneration of theRuntimeEnvironment.xml file.

Min VM Version (Optional) The minimum Java VM versionon the client machine for this module towork properly. The value of this field issaved to the min_vm_version attribute ofall the dmc_jar objects (including all thecore interface and implementation jars.)directly under the dmc_module folder.



Statically deployed class names (Optional) Fully qualified Java classnames. When the module is downloaded,the classpath is checked to see if all theJava classes specified here are on it.

Local file presences (Optional) Full file path. When themodule is downloaded, the client machineis checked to see if all the files specifiedhere are present.

Java system properties (Optional) Java properties as name-valuepairs. When the module is downloaded,the client machine is checked to see if allthe Java system properties specified herematch the ones on the client machine.

Post download message (Optional) The message that will belogged on the client machine after thedynamic download.

Log level (Optional) The level at which thepost-download message is logged.Default is INFO for informational only.

Module editor: Dependencies tab



These topics are included:• Adding, removing, modifying Java libraries, page 118 — (Optional) Add, remove, or

modify external Java libraries on which this module depends.• Adding, deleting, and modifying required modules, page 121 — (Optional) Add,

delete, or modify other modules required by this module for it to function properly.

Adding, removing, modifying Java libraries

To add a Java library from your local machine or link to an existing one:

1. Perform one of these actions:• To add a Java library from your local machine, click Add and select Create New.



• To link to an existing Java library in the Docbase, click Add, select Link Existing,navigate to, and select a Java library.

2. For new Java libraries, specify this information:










3. Click OK.

To remove a Java library:

1. Select the Java library and click Remove.If the Java library is shared between multiple modules, the link will be removed. Ifthe Java library is not shared, the entire Java library will be deleted from the Docbase.

2. Click OK.



To modify a Java library:

1. Click Edit.

2. Modify this information:










3. Click OK.



Adding, deleting, and modifying required modules

To add a required module:

1. Click Add.

2. In the Required Modules dialog box, specify this information:

Table 12-4. Required Modules Dialog Box Fields

Name (Required) Required module name thatcorresponds to the req_module_nameattribute of the dmc_module object type.Each required module within a module isuniquely identified by its name.

Min VM Version (Optional) Specifies the minimum versionof the Java virtual machine required torun this module.

Required Interface JARs (Editable) Required module’sinterface JARs that correspond tothe a_req_module_interfaces attribute ofthe dmc_module object type.• To copy interface JARs from the localmachine, click Add and select Copyfrom Local File System.

• To copy interface JARs from theDocbase, click Add and select Copyfrom Docbase.

• To remove interface JARs, select theJAR and click Remove.

To delete a required module:

1. Select the module and click Remove.Deleting a required module removes the entries in the dmc_module attribute anddeletes the actual interface JARs in the “External Interfaces” folder under thedmc_module folder.

To modify an existing required module:

1. Click Edit.

2. In the Required Modules dialog box, modify these fields, except for the Name field:



Table 12-5. Required Modules Dialog Box Fields

Name (Required) Required module name thatcorresponds to the req_module_nameattribute of the dmc_module object type.Each required module within a module isuniquely identified by its name.

Min VM Version (Optional) Specifies the minimum versionof the Java virtual machine required torun this module.

Required Interface JARs (Editable) Required module’sinterface JARs that correspond tothe a_req_module_interfaces attribute ofthe dmc_module object type.• To copy interface JARs from the localmachine, click Add and select Copyfrom Local File System.

• To copy interface JARs from theDocbase, click Add and select Copyfrom Docbase.

• To remove interface JARs, select theJAR and click Remove.

Module editor: Miscellaneous tab



Contact (Optional) Contact information for themodule provider. Corresponds to thecontact_info attribute of the dmc_moduleobject type. Maximum length is 255characters.

Description (Optional) Description for the module.Corresponds to the module_descriptionattribute of the dmc_module object type.Maximum length is 255. characters.



Javadoc (Optional) Javadocs for this module.Resides in the dmc_module folder withthe name, javadoc.zip. To upload a newerjavadoc.zip, click the… button, navigateto and select the zip file. To view the zipfile with a local application associatedwith the zip format, click View.

Downloadable Objects (Optional) Select the web service’snon-JAR files that you want to bedownloaded from the Docbase to theclient machine.

Miscellaneous objects (Optional) Miscellaneous supportingdocuments for the module, such aslicenses, configuration files, or “readme”files. Corresponds to the objects insidethe Miscellaneous folder under thedmc_module folder.

To add files, click Add, and choose Linkfrom Docbase to link to an existing filein the Docbase, Copy from Docbase tocopy an existing file in the Docbase, orCopy from Local File System to check ina file from your local machine. The fullpath on your local machine is displayedonly for those files you have not checkedin; otherwise, only the name of the file isdisplayed.

Module editor: Web Services tab

For more information about Web Services, see Web Services, page 104.


Enable as Web Service (Optional) To enable this SBO as a webservice, check this option.

Namespace (Optional) Enter a string that represents anamespace that uniquely identifies yourWeb service’s WSDL file.



Enable UCF attachment (Optional) To enable EMC | DocumentumUCF (Unified Client Facilities) contenttransfer (checkin) of attachments, checkthis option.

Note: UCF is a EMC |Documentum feature that hasmore advantages—including betterperformance—over Base 64 encoding.See the DFC Development Guide for moreinformation.

Enable Base64 encoding attachment (Optional) To enable Base 64 encoding ofattachments for content transfer (checkin),check this option.

Note: Base 64 encoding is a techniqueused to serialize binary data (that is,attachments) in an XML document (thatis, a SOAP message).

Selected WARs (Optional) To include the web servicein specific WARs, use Add and Removeto add the appropriate WARs from theAvailable WARs textbox to the SelectedWARs textbox.These WAR files are addedto the DocApp.

Caution: If the SBO and web serviceremain in the DocApp, do not removethe corresponding WAR files otherwise,creating a DocApp archive will fail.

Available WARs (Read-only) These WAR files reside in theDocbase.


Chapter 13Working With Object Types

These topics are included:• About object types, page 125• Creating or modifying an object type, page 127• Displaying attributes in Documentum clients , page 129• Specifying the default permission set for an object type, page 134• Specifying constraints for an object type, page 134• Creating and modifying application events, page 135• Removing an object type from a DocApp, page 136• Viewing data dictionary information for types and attributes, page 136• Functionality, page 137

About object typesAn object type is a template for objects (usually documents) that play a special role in aDocApp. An object type inherits properties from its supertype (usually dm_document orone of its subtypes). The additions or modifications you make to these properties definethe object type. Use the type and attribute editors to define or modify object types. Formore information about the available supertypes, see Available supertypes, page 127.

Object type names are global within a Docbase. EMC | Documentum recommends thatyou adopt a naming strategy that enables you to deploy applications to other Docbaseswithout encountering naming conflicts. For more information about the naming objecttypes, see Naming object types, page 127.

Application Builder relies on facilities of the Docbase and its data dictionary for access toinformation about object types. Therefore, you must check changed object types into theDocbase in order to make those changes available to other editors within ApplicationBuilder. Object types cannot be versioned.

You can view or modify the following aspects of an object type:


Working With Object Types

• Properties of an object:

— Attributes: Associated data (for example, author’s name).

— Security: Who can access or modify the object.

— Constraints: Internal consistency requirements.

— Functionality: Methods, procedures, or components.• Attributes – Data items that accompany an object of a given type. Use the attribute

editor to specify or modify the attributes of an object type. Attributes are also calledproperties in client applications.

• Security – The default permission set that the system attaches to new objects ofthat type. The permission set you specify applies only in the Docbase in whichyou develop the DocApp. Permission sets are also called access control lists (ACLs)in a Docbase.

• Constraints – Internal consistency requirements in the form of Docbasic expressionsthat relate the type’s attribute values to one another or to constant values. Use thetype editor to add or modify constraints.

Note: In an object type constraint expression, you can use one or more attributesdefined for the object type; whereas, in an attribute constraint expression you canuse only that attribute.

• Functionality – A set of associations between functionality classes and specificcomponents that implement that functionality. An object type in a typical DocAppinherits most of its functionality classes from its supertype and uses the componentsof the Desktop default DocApp (DcDesktopClient) to implement most of thatfunctionality. For more information about functionality, see the Desktop DevelopmentKit Development Guide.

A functionality class is the name (for example, DcAnnotate) by which the applicationrecognizes the kind of operation to be performed at a certain point in its execution.The specific functional component that performs the operation may vary. Forexample, a subtype may use a different component from the one that the supertypeuses to implement the functionality class.

Use the object type editor to make the following changes to a DocApp’s functionality:

— Disable an inherited functionality class. See Disabling an inherited functionalityclass for an object type, page 139.

— Specify a different component to implement an inherited functionality class.See Modifying qualifications for component implementing a functionality classfor an object type, page 140.

— Add a functionality class and specify a component to implement it. See Addinga functionality class and an implementation to an object type, page 139.



If you add a functionality class, you must provide access to it via an applicationmenu item or a call within a component that you supply. Desktop uses only theinherited functionality classes.

For more information about object types, see the Object Reference Manual, the ContentServer Fundamentals, and the Content Server Administration Guide.

Naming object types

Object type names are global within a Docbase. EMC | Documentum recommends thatyou adopt a naming strategy that enables you to deploy applications to many Docbaseswithout encountering naming conflicts.

Object type names must conform to these restrictions:• Object type names cannot begin with dm_ , dmi_, dmr_, a numeral, space, or single

quote.• Object type names cannot be the same as any Document Query Language (DQL)

reserved word (see the Content Server DQL Reference Manual for a list of words).• Must be no more than eighteen characters in length.Once you have checked the object type into the Docbase, you can no longer changeits name.

Available supertypes

In addition to any custom types, you can select any of these EMC | Documentum typesas a supertype for your new custom type:

dm_audittrail, dm_cabinet, dm_component, dm_document, dm_folder, dm_java,dm_job, dm_locator, dm_email_message (server 5.2.5 or greater only), dm_note,dm_plugin, dm_procedure, dm_process, dm_query, dm_relation, dm_relation_type,dm_script, dm_smart_list, dm_staged, dm_state_extension (server 5.2.5 or greateronly), dm_sysobject, dm_user,

Creating or modifying an object typeTo create a new object type:

1. Choose Insert → Object Type.

2. On the Type editor’s General tab, enter a name in the Type Name field.



For more information about naming object types, see Naming object types, page 127.

3. Enter the type’s supertype in the Supertype field.For more information about super types, see Available supertypes, page 127.

4. Optionally, select a default document lifecycle and its version in the DefaultDocument Lifecycle field.

5. Enter a label in the Label field.EMC | Documentum client applications use this field as an identifier or user promptfor objects of the given type.

6. Enter appropriate text in the User Help and Comment for Developers fields.

Note: Desktop does not use these fields.

7. Select a storage area from the Default Storage Area drop-down list and a lifecyclestage from the Type Lifecycle drop-down list.Valid values for the Type Lifecycle drop-down list are Current, Future, and Obsolete.This field is a hint to applications. A well-behaved application does not display thisobject type unless the value is Current.

8. Optionally, specify security, constraints, and functionality for the object type.To specify security, see Specifying the default permission set for an object type,page 134.To specify constraints, see Specifying constraints for an object type, page 134.To specify functionality, see Functionality, page 137.

9. If you wish, check in the object type.

10. For the new object type to appear in a client application after creating or installing it:• For a WDK-based application, stop and restart the application server• For Desktop, choose File >Work Offline, and then choose File >Work Offline.

To modify an existing object type, double-click the object type’s name in the DocAppexplorer and modify any of the fields and options in the Type editor. You cannot modifystandard EMC | Documentum object types (which are usually prepended with dm_).For the modifications to the object type to appear in a client application after creatingor installing it:• For a WDK-based application, stop and restart the application server• For Desktop, choose File >Work Offline, and then choose File >Work Offline.

Note:• You must check a new object type into the Docbase before other Application Builder

editors can recognize it. Once you have checked the object type into the Docbase,you can no longer change its name or its supertype.

• You can specify as many different national language values for the Label, User Help,Comment for Developers, and Error message string to use when the object type



constraint is violated fields as you want—all of each field’s national language valuesare saved to the Docbase. For more information about changing national languages,see .

Displaying attributes in Documentum clientsThis technique of displaying an object type’s attributes and attribute values in EMC |Documentum clients is only valid for Desktop 5.2 (or greater) and WDK 5.2 (or greater)applications, including but not limited to Webtop, Web Publisher, and your own customapplication, connected to a 5.2 (or greater) Docbase.

See theWeb Development Kit and Applications Tutorial for more information specific toWDK and WDK applications (such as Webtop and Web Publisher).

In addition to specifying the attributes to display, you also specify under what conditionsthey are to be displayed. This set of conditions is called scope and each condition iscalled a scope definition. In one of the simplest scopes, only the application name, suchas Webtop, is specified as a scope definition. That is, attributes are only displayedin Webtop. In another scope, user role, such as Administrator, could be specified inaddition to application name. You must design your custom applications to retrieve theappropriate scope from the server. WDK 5.2.5 or greater applications are designedto retrieve scope for applications and roles; WDK 5.2.5 or greater itself provides aframework for retrieving any kind of scope. For Desktop 5.2 (or greater), applicationscope definition with a value of DcDesktopClient (that is, application=’DcDesktopClient’)is the only valid scope.

Note: You can still use the attribute category field to define a custom tab on which todisplay attributes in Desktop 5.2.5 (or greater), 4.3.x, and 4.2.x. For more informationabout the attribute category field, see Adding or modifying an object type attribute(Advanced tab), page 145.

To display an object type’s attributes and attribute values in Documentum clients:

1. Double-click the object type’s name in the DocApp explorer to open the type editor,and select the Display Configuration tab.

2. In the Scope field, select the scope (for example, application=’webtop’ for Webtop)for which you want to display attributes.

Tip: Each row in the Scope field represents one scope. A scope does not have a nameand is instead identified by its set of scope definitions.

To create, modify, and delete scopes, see Creating, deleting, and modifying scopes,page 132.



3. To create and modify tabs on which to display the attributes, perform these actionsin the Display Configuration List:

Note:• The object type’s parent’s tabs are inherited. Adding, deleting, editing tabs, or

changing the order of the tabs breaks inheritance--that is, changes made to theparent’s tabs will not be reflected in this type’s tabs.

• In Desktop 5.2.5 (or greater), a type attribute’s Attribute Category field valuesare used as long as you have not broken inheritance with the parent type’sdisplay configuration or if a display configuration is not specified for eitherthe type or its parent.

• Tab names are also localizable.• Web Publisher does not have tabs, so it displays the display configurations as

sections on the same page.• For WDK applications, to display attributes (particularly mandatory ones) on the

object properties’ Info page, specify the Info category.To add a new tab:

a. Click Add.

b. Enter a new tab name or choose one of the defaults from the drop-down list.

c. To add the tab to all EMC | Documentum clients, check Add to all applications.This tab is shared between all application and any changes to it are reflected inall applications.

d. Click OK.

Note: When you create tabs with identical names in different applications, DABcreates new internal names for the second and subsequent tabs by appendingan underscore and integer (for example, dm_info_0)--because the internal namesmust be unique for a type. The identical names are still displayed because they aremapped to their corresponding internal names. When you change locales, DABdisplays the internal names, because you have not specified a name to be displayedin that locale. EMC | Documentum recommends that you change them to moremeaningful names in the new locales.

Using one of the defaults automatically creates a tab with an identical name, becausethe default is already used by another application.

Checking Add to all applications results in only one tab being created--not severaltabs with different internal names and identical display names--and all displaynames are mapped to that one tab.

To remove a tab, select the tab name and click Remove.To rename a tab, select the tab name and click Rename.



To change the order in which tabs are displayed, select the tab and click the upand down arrows.

4. To modify the attributes displayed on a tab, perform these actions in the Attributesin Display Configuration:

a. In the Display Configuration List, select the tab in which the attributes youwant to modify are displayed.The attributes that are currently displayed on the tab are shown in the Attributesin Display Configuration text box.

b. Click Edit.

c. To specify which attributes are displayed on the tab and how they are displayed,perform these actions in the Display Configuration dialog box:• To display attributes on the tab, select the attribute in the Available

attributes text box and click Add.• To delete attributes from the tab, select the attribute in the Current attribute

list text box and click Remove.• To change the order in which the attributes are displayed on the tab, select

the attribute in the Current attribute list text box and click the up or downarrows.

Note: Although you can change the order in which attributes are displayedon a tab in the Desktop Properties dialog box, you cannot change the taborder (that is, the sequence in which you can move the cursor from field tofield by pressing the Tab key).

• To display a separator between two attributes, select the attribute abovewhich you want to add a separator and click Add Separator.

• To delete a separator between two attributes, select the separator and clickRemove Separator.

If you have more attributes than can fit on a tab, force some attributes to bedisplayed on a secondary page in Webtop, select the attribute and clickMakeSecondary.

Note: Desktop does not use this setting—a vertical scrollbar is used when allattributes cannot be displayed in the dialog box at the same time.

To move a secondary attribute back onto the primary tab, select the attributeand clickMake Primary.



Creating, deleting, and modifying scopes

To create or modify a scope:

1. Double-click the object type’s name in the DocApp explorer to open the Type editor,and select the Display Configuration tab.

2. To make a copy of an existing scope and then modify it, select the scope in the Scopefield, click the Add icon ( ), and choose Copy.

3. To create a blank scope, click and select New.

4. To modify a scope, select the scope in the Scope field and click the pencil ( ).

5. To add or modify scope definitions in the Scope Definitions dialog box, performthese actions:• To modify a row, double-click its Scope Name or Scope Value column and select

a name and value (or enter a value).• To add a row, click Add, double-click the empty row’s Scope Name or Scope

Value column and select a name or value (or enter a value).• To delete a row, select a row and click Remove.By default, only application and role scope definitions are available. Valid valuesfor the application scope definition are DocApp names in the Docbase. Valid valuesfor the role scope definition are role names (group names with their group_classattribute set to role) in the Docbase.To create, modify, or delete the available scope definitions, see Creating, deleting,and modifying the available scope definitions, page 133.A scope consists of one or more scope definitions, which, in turn, consist of one ormore valid values. Although you can only specify one value per row, you can defineadditional values for a scope definition by adding another row with the same scopename but a different value.A scope must be unique among all of this object type’s scopes. A scope is notunique if another scope has the same scope definitions and each one has at leastone identical value.

6. Click OK.

To delete a scope:

1. Double-click the object type’s name in the DocApp explorer to open the Type editor,and select the Display Configuration tab.

2. Select the scope in the Scope field and click the trash can ( ).



Creating, deleting, and modifying the available scopedenitions

To create, delete, or modify the scope denitions that are available in DAB:

1. Open the scope_definitions.xml file in your DAB installation’s bin directory in atext or XML editor.

2. To add a new scope definition, add a new <scope_definition> element after the endof the last <scope_definition> element (that is, after the last occurrence of this text:</scope_definition>) but before the </scope_definitions> close tag as follows:

Note: Following these instructions will ensure that the scope_definitions.xml file iswell-formed, which is required for it to be parsed by the XML parser.

<scope_definition><name>name</name><values>

<value_list><value>value_1</value><value>value_2</value><value>value_n</value>

</value_list></values>

</scope_definition></scope_definitions>where:• name is the scope definition name that will be displayed in the Scope Name

column of the Scope Definitions dialog box. Only ASCII characters (includingspaces) are valid.

• value_1, value_2, value_n are the values that will be displayed in the Scope Valuecolumn of the Scope Definitions dialog box. You can specify any number of<value> elements. Only ASCII characters (including spaces) are valid.

Tip: Instead of hard-coding values using <value_list>, you can use one of thesetechniques for displaying values:• Dynamically retrieve a list of values from the Docbase with a DQL select

statement by replacing the <value_list> element with the <query> element asfollows:<query>query</query>

query is a DQL select statement that retrieves values from the Docbase anddisplays them in the Scope Value column of the Scope Definitions dialog box.You can only specify one <query> element in the <values> element. Only ASCIIcharacters (including spaces) are valid.

• Allow any string to be entered for the scope value by replacing the <values>element with an empty <values> element as follows:<values/>



3. To modify a scope definition, find the name of the scope definition in the <name>element and make any changes to the subsequent <values> element as describedin Step 2.

4. To delete a scope definition, delete the <scope_definition> element and itscontent (that is, all the text between and including <scope_definition> and</scope_definition>).

Specifying the default permission set for anobject type

A default permission set determines security for an object type.

To specify the default permission set for an object type:

1. Double-click the object type’s name in the DocApp explorer to open the Type editor,and select the Security tab.

2. Select the desired permission set from the Name drop-down list.

Note:• You cannot modify any other information on the Security tab. Application Builder

displays it for your information only.• This assignment only applies to the Docbase in which you develop the DocApp.

Specifying constraints for an object typeTo specify constraints for an object type:

1. Double-click the object type’s name in the DocApp explorer to open the Type editor,and select the Constraints tab.

2. Use the Back and Next buttons to navigate to a constraint you wish to modify or toa blank constraint to create a new one.

3. Using the Check Syntax and Reset Expression buttons to help you, enter a validDocbasic expression that resolves to true or false into the Constraint Expressiontextbox.The Check Syntax button checks the syntax of the Docbasic expression in theConstraint Expression textbox. It does nothing if the syntax is OK. Otherwise, itdisplays an Invalid Constraints Expression error message.The Reset Expression button returns the contents of the Constraint Expressiontextbox to the last value that passed a syntax test.



Note: For repeating value attributes, you must use repeating value attributekeywords.

4. In the Error Message textbox, enter a message for applications to display when theconstraint evaluates to False.

5. Use the Enforce Constraint checkbox to specify whether applications should enforcethis constraint or not.The Enforce Constraint checkbox is a hint to applications. A well-behavedapplication enforces the constraint if it is checked.

6. Use the Ignore Supertype Constraints checkbox to specify whether applicationsshould enforce supertype constraints for objects of this type.This checkbox is a hint to applications. A well-behaved application ignoressupertype constraints if it is checked.

7. Click Add Constraint.

Note: The Add Constraint button is enabled when the constraint expression is valid.

Creating and modifying application eventsYou can only create and modify application events--not system events. System events aredisplayed for informational purposes only. You can only create and modify applicationevents on version 5.2 servers.

Events are operations performed on objects in a Docbase or something that happens inan application. System events are events that Content Server recognizes and can audit.Application events are user-defined events. They are not recognized by Content Serverand must be audited by an application.

To create an application event:

1. Double-click the object type’s name in the DocApp explorer to open the type editor,and select the Events tab.

2. Click Add.

3. Enter the name of the event and the display string.

4. Click OK.

To modify an application event:


2. Select the event.



Note: You cannot modify events that are inherited from the object type’s parent.

3. Click Edit.

4. Change the name of the event or its label.

5. Click OK.

To remove an application event:


Note: You cannot remove events that are inherited from the object type’s parent.


3. Click Remove.

Removing an object type from a DocAppTo remove an object type from a DocApp, right-click the object type in the DocAppexplorer and choose Delete.

Using this action to remove an object type from a DocApp does not delete it fromthe Docbase. To delete an object type from a Docbase, use EMC | DocumentumAdministrator—you cannot use DAB to remove an object type from a Docbase.

Viewing data dictionary information for typesand attributes

Application Builder stores information about types and their attributes in the datadictionary. Developers do not have direct access to the data dictionary, but you can usethe IAPI tool or DFC to obtain this information about the types you define.

Note that the type exists in the Docbase as a type description object with attributes of itsown, like the type’s name, supertype, and owner. These are NOT the attributes that youspecify for the type. The attributes you specify exist as names in the type descriptionobject’s repeating attribute attr_name.

To obtain information about a type via the IAPI tool:

1. Enter the following command at the prompt:type,c,typename



IAPI responds with the name of the type description object (for example,tdm_document). For example: type,c,dm_document

2. Use the name of the type description object in the next command:dump,c,typedescriptionobjectnameIAPI lists the properties of the type description object. For example:dump,c,tdm_document

To obtain information about an attribute of the type:

1. Enter:

type,c,typename,attributename

For example: type,c,dm_document,object_nameIAPI responds with the name of the attribute description object (for example,tdm_document.object_name).

2. Use the name of the attribute description object in the next command:

dump,c,attribdescriptionobjectnameFor example: dump,c,tdm_document.object_name

To obtain information about dm_document via DFC, use code like the following:IdfTypedObject tdesc = sess.getTypeDescription("dm_document",null,null,null)orIdfTypedObject tdesc = sess.getTypeDescription("dm_document",object_name,null,null)Where sess is an IdfSession object.

FunctionalityThese topics are included:• Specifying the functionality of an object type, page 138• Specifying a new implementation for an inherited functionality class for an object

type, page 138• Disabling an inherited functionality class for an object type, page 139• Restoring the inherited implementation of a functionality class for an object type,

page 139• Adding a functionality class and an implementation to an object type, page 139• Specifying functionality for a component, page 140• Modifying qualifications for component implementing a functionality class for an

object type, page 140



• Removing an added functionality class from an object type, page 140

Specifying the functionality of an object type

To specify the functionality of an object type:

1. Double-click the object type’s name in the DocApp explorer to open the type editor.

2. Select the Functionality tab.

3. Perform these tasks:• To disable an inherited functionality class. See Disabling an inherited

functionality class for an object type, page 139.• To specify a different implementation for an inherited functionality class. See

Specifying a new implementation for an inherited functionality class for anobject type, page 138.

• To restore the inherited implementation of a functionality class. See Restoringthe inherited implementation of a functionality class for an object type, page 139.

• To add a functionality class and specify a component to implement it. SeeAdding a functionality class and an implementation to an object type, page 139.

• To remove an added functionality class. See Removing an added functionalityclass from an object type, page 140.

• To modify the qualifications of the component that implements a functionalityclass. See Modifying qualifications for component implementing a functionalityclass for an object type, page 140.

Specifying a new implementation for an inheritedfunctionality class for an object type

To specify a new implementation for an inherited functionality class for an object type:

1. Ensure that the implementing component already exists within the DocApp (forexample, as an ActiveX component).

2. Double-click the object type’s name in the DocApp explorer to open the type editor,and select the Functionality tab.

3. Select the row containing the functionality class to receive the new implementation.

4. Click the Edit Functionality button.



5. Complete the Functionality Description dialog box to attach the implementingcomponent to the functionality class. See Specifying functionality for a component,page 140.

Disabling an inherited functionality class for an objecttype

To disable an inherited functionality class for an object type:


2. Select the row containing the functionality class to be disabled.

3. Click Remove.

Restoring the inherited implementation of afunctionality class for an object type

To restore the inherited implementation of a functionality class for an object type:


2. Highlight the entry for the functionality class and click Remove.

Adding a functionality class and an implementation toan object type

To add a functionality class and an implementation to an object type:



3. Click Add.

4. Complete the Functionality Description dialog to attach the implementingcomponent to the functionality class. See Specifying functionality for a component,page 140.



Specifying functionality for a component

You arrive at the Functionality Description dialog whenever you perform an operationthat requires attaching an implementing component to a functionality class.

To complete the Functionality Description dialog box:

1. If the name field does not have the desired value, enter it.

2. Enter a value in the Label field.

3. Specify permissions for as many groups as you wish:

4. Click Add Group, and select the group from the selection box.

5. Click the checkboxes in the User Capability section for the permissions you wish toassign to members of this group.

Modifying qualications for component implementing afunctionality class for an object type

To modify qualications for component implementing a functionality class for an objecttype:


2. Select the row containing the functionality class.

3. Click Edit Functionality.

4. Complete the Functionality Description dialog box to modify the qualifications ofthe implementing component.See Specifying functionality for a component, page 140.

Removing an added functionality class from an objecttype

To remove an added functionality class from an object type:


2. Select the row containing the functionality class to be removed.

3. Click Remove.



Creating and modifying application eventsYou can only create and modify application events--not system events. System events aredisplayed for informational purposes only. You can only create and modify applicationevents on version 5.2 servers.

To create an application event:


2. Click Add.

3. Enter the name of the event and the display string.

4. Click OK.

To modify an application event:



Note: You cannot modify events that are inherited from the object type’s parent.

3. Click Edit.

4. Change the name of the event or its label.

5. Click OK.

To remove an application event:


Note: You cannot remove events that are inherited from the object type’s parent.


3. Click Remove.




Chapter 14Working With Object Type Attributes

These topics are included:• Adding or modifying an object type attribute, page 143• Adding or modifying an object type attribute (Advanced tab), page 145• Specifying search characteristics for object type attributes, page 147• Search operators, page 147• Specifying a constraint expression for an object type attribute, page 150• Specifying value assistance for an object type attribute, page 151• Specifying conditional value assistance, page 151• Creating or modifying a value mapping table for an object type attribute, page 155• Removing an attribute from an object type, page 156For more information about attributes, see the Object Reference, the Content Server Fundamentals, andthe Content Server Administration Guide.

Adding or modifying an object type attributeAn attribute of a type is a property (for example, author’s name) of all objects of that type.

To add a new attribute:

1. Select the object type in the DocApp explorer, and choose Insert→Attribute.

2. On the attribute editor’s General tab, enter a name in the Attribute Name field.An attribute name must conform to these restrictions:• Cannot begin with dm_, a_, i_, r_, a numeral, space, or single quote• Cannot be named select, from, or where.• Must use all lowercase letters.

Note: For more information about naming guidelines, see the Object ReferenceManual.


Working With Object Type Attributes

3. Enter a label in the Label field.DAB stores this value in the data dictionary as label_text.Desktop uses this field as an identifier or user prompt for this attribute. For Desktop5.2.5 or greater, you should not enter a single string that exceeds 2152 pixels—if youdo, then it breaks to the next line at that point when displayed in the Propertiesdialog box.

4. Select a datatype from the Datatype drop-down box, and (for strings) enter a length(the maximum number of characters) in the Length field.Using DAB, the maximum length for an attribute of data type string is 2000.However, if your database supports a greater length, you can use DQL to increasethe length.For more information about using DQL, see the Content Server DQL Reference orthe Content Server Administration Guide.For more information about data types, see the Object Reference.

5. Check the Repeating checkbox to specify a repeating attribute.

6. For a single-value attribute, enter a default value for the attribute in the DefaultValue(s) field. For a repeating value attribute:

a. Click Edit.

b. To add a default value, enter the value in the upper textbox and click Add.

c. To remove a default value, select the value in the lower textbox and clickRemove.

d. Repeat steps b and c until you have specified all the desired default values andclick OK.

7. Enter appropriate text in the Comment for Developers and User Help fields.DAB stores these values in the data dictionary as help_text. Desktop does not usethese fields.

8. Click the appropriate checkboxes in the User Interface Hints section.These values are hints to applications. A well-behaved application obeys these hints.

Note:• To cancel all your changes and close the dialog box, click Cancel.• DAB stores the checkbox values in the data dictionary as dmi_dd_attribute:xx,

where xx = is_required, is_hidden, read_only, not_null, or ignore_immutable.• The Content Server does not use these values.

9. Specify more attribute properties. See Adding or modifying an object type attribute(Advanced tab), page 145.

To modify an inherited attribute that does not appear in the tree view, choose View →List All Attributes.



To modify an attribute that appears in the DocApp explorer, double-click its name toopen the attribute editor.

Note:• After you check in the object type, you cannot change the attribute name or datatype,

or whether the attribute is repeating; you can only increase the lengths of stringattributes.

• There are RDBMS-dependent restrictions on the length of an attribute name and onthe sizes of attributes.

• For some attribute fields, you can specify as many different national language valuesas you want—all of an attribute’s national language values are saved to the Docbase.For more information about changing national languages, see Changing the locale,page 32.

Adding or modifying an object type attribute(Advanced tab)

To specify more attribute properties:

1. On the attribute editor’s Advanced tab, specify search options. See Specifying searchcharacteristics for object type attributes, page 147.

2. Enter appropriate values in the Input Mask and Attribute Category text fields.Desktop adds a tab to its Properties dialog for each attribute category you definefor the type. This field is only valid in Desktop 4.3.x and lower (or Desktop 5.2.5and higher).In Desktop 5.2.5 (or greater), a type attribute’s Attribute Category field values areused as long as you have not broken inheritance with the parent type’s displayconfiguration or if a display configuration is not specified for either the type or itsparent. For more information about display configurations, see Displaying attributesin Documentum clients , page 129.DAB stores this Attribute Category value in the data dictionary as category_name.For more information about input masks, see Input Mask field for an object typeattribute, page 146.

3. Select a lifecycle stage from the Attribute Lifecycle drop-down box.DAB stores this value in the data dictionary as life_cycle. The possible values areCurrent, Future, and Obsolete. This field is a hint to applications. A well-behavedapplication does not display this object type attribute unless the value is Current.

4. On the Constraint tab, specify a constraint expression and constraint enforcementoptions. See Specifying a constraint expression for an object type attribute, page 150.



5. On the Value Assistance tab, specify value assistance lists.

Note: Value assistance is not valid for attributes of the Boolean data type.

See Specifying value assistance for an object type attribute, page 151.

6. On the Value Mapping tab, create a value mapping table for the attribute.See Creating or modifying a value mapping table for an object type attribute, page155 .

Input Mask eld for an object type attribute

A pattern consists of mask characters and literals. A backslash (\) converts the characterfollowing it to a literal.

Table 14-1. Valid Mask Characters

Character Meaning

# Numeric (0-9)

A Alphanumeric (0-9, a-z, A-Z)

& Any ASCII character

? Alphabetic (a-z, A-Z)

U Alphabetic, and converts to uppercase

L Alphabetic, and converts to lowercase

The DFC Validation API uses this field. The DfwComboBox and DfwTextBox inputwidgets implement the DFC Validation API.

Example 14-1. MasksThis table shows a mask in the first column, an example of valid user input in the secondcolumn, and a description of the mask in the last column. The last mask example limitsthe number of characters to thirteen.

Mask User Input Description

##/##/####12/25/1999 Date

##:## UU12:35 AM Time

###-##-####123-45-6789 US social security number

(SSN)

(###)###-####(999)555-1212 US phone number



Mask User Input Description

#####-####12345-6789 US zip code

?????????????John Name (limited to thirteen

characters)

Specifying search characteristics for objecttype attributes

You can make an attribute searchable, that is, enable clients to allow users to search aDocbase for attribute values in objects, where the objects are derived from the typeto which the attribute belongs.

To make an attribute searchable:

1. Double-click the attribute’s name in the DocApp explorer to open the attribute editor,and select the Advanced tab.

2. Check the Searchable checkbox (default is checked).This checkbox makes this attribute searchable.

3. Use the Add and Remove buttons to build the list in the Allowable SearchOperators box.The Allowable Search Operators box lists the search operators that clients displayfor this attribute. See Search operators, page 147.

4. Select a default search operator from the drop-down list.When this attribute is selected, by default clients display this search operator.

5. Enter a default search value into the textbox.When this attribute is selected, by default clients display this value as the valuefor which to search attributes of objects.

Search operatorsThis table provides a short description for each search operator (organized alphabetically)and shows the ones that are valid for each attribute data type.

Note: In these tables, the term, attributes, refers to the attributes of objects—not types.



Operator StringInteger/Double Time ID Boolean Description

after No No Yes No No Searches for dates/times after thespecified date/time.

before No No Yes No No Searches for dates/times before thespecified date/time.

begins with Yes No No No No Searches for the specified substring atthe beginning of strings.

between Yes Yes Yes No No Searches for values between thespecified values. The order of stringsis determined alphabetically (by whichcharacter is closer to the beginning ofthe alphabet), starting with the firstcharacter.

contains Yes No No No No Searches for the specified substringanywhere in strings.

doesn’tcontain

Yes No No No No Searches for attributes that do not havestrings with the specified substringanywhere in the strings.

ends with Yes No No No No Searches for the specified substring atthe end of strings.

greater than Yes Yes No No No Searches for values greater than thespecified value. The order of strings isdetermined alphabetically (by whichcharacter is closer to the beginning ofthe alphabet), starting with the firstcharacter.

greater than orequal

Yes Yes No No No Searches for values greater than orequal to the specified value. The orderof strings is determined alphabetically(by which character is closer to thebeginning of the alphabet), starting withthe first character.



Operator StringInteger/Double Time ID Boolean Description

is Yes Yes No Yes Yes Searches for values that are identical tothe specified value. For Boolean, thevalue for which to search is either trueor false.

is defined Yes No Yes Yes No Searches for attributes that have valuesdefined for them.

is in Yes Yes No No No Searches for any single value inrepeating value attributes that isidentical to the specified value.

is not Yes Yes No Yes No Searches for attributes with values thatare not identical to the specified value.

is not defined Yes No Yes Yes No Searches for attributes that do not havevalues defined for them.

is not in Yes Yes No No No Searches for repeating value attributesthat do not have any single value that isidentical to the specified value.

is not on No No Yes No No Searches for dates/times different thanthe specified date/time.

is on No No Yes No No Searches for dates/times that are thesame as the specified date/time.

less than Yes Yes No No No Searches for values less than thespecified value. The order of strings isdetermined alphabetically (by whichcharacter is closer to the beginning ofthe alphabet), starting with the firstcharacter.

less than orequal

Yes Yes No No No Searches for values less than or equal tothe specified value. The order of stringsis determined alphabetically (by whichcharacter is closer to the beginning ofthe alphabet), starting with the firstcharacter.

on or before No No Yes No No Searches for dates/times on or before thespecified date/time.

on or after No No Yes No No Searches for dates/times on or after thespecified date/time.



Specifying a constraint expression for anobject type attribute

To specify a constraint expression for an object type attribute:

1. Double-click the attribute’s name in the DocApp explorer to open the attribute editor,and select the Constraint tab.

2. Using this attribute as a variable, enter the constraint into the Constraint Expressiontextbox as a Docbasic expression that evaluates to True or False.

Note: For repeating value attributes, you must use repeating value attributekeywords.

3. Enter an error message for applications to display when this constraint evaluatesto False.

4. Use the Enforce Constraint checkbox to specify whether applications should enforcethis constraint or not.Application Builder stores the Enforce Constraint value in the data dictionary asval_constraint_enf. The field is a hint to applications. A well-behaved applicationenforces the constraint if the field is set.

5. Use the Ignore Supertype Constraints checkbox to specify whether applicationsshould enforce supertype constraints for this attribute.Application Builder stores this value in the data dictionary as ignore_constraints.The field is a hint to applications. A well behaved application ignores supertypeconstraints if the field is set.

Note:• The Insert Value Range Check button opens a wizard to help you include a

constraint that specifies that the value of an Integer or Double attribute lies within aspecified range of values.

• The Check Syntax button checks the syntax of the expression in the ConstraintExpression textbox. It does nothing if the syntax is OK. Otherwise, it displays anInvalid Constraints Expression error message.

• The Reset Expression button returns the contents of the Constraint Expressiontextbox to the last value that checked OK.



Specifying value assistance for an object typeattribute

Value assistance is a list of values that a client program (such as Desktop) displays atruntime for an object attribute. A user can select a value from this list (or, if allowed, adda new one to it). There are two kinds of value assistance:• Default value assistance − Values displayed when no value is selected; for example,

when a new object is created.• Conditional value assistance − Values displayed when a specific condition is satisfied;

for example, when the values displayed in one attribute depend on the value selectedin another attribute.

Value assistance for an attribute takes the form:Condition 1: List of Values 1...Condition n: List of Values nDefault list of values (required)

Each condition is a Boolean Docbasic expression involving attributes of the type.

Note:• Value assistance is not valid for attributes of the Boolean data type.• Because of an underlying Docbasic limitation, you can only specify up to thirty-five

conditional value assistance statements. If you require more than thirty-fiveconditional value assistance statements, you can use either a query or $value.

To specify value assistance for an object type attribute:

1. Double-click the attribute’s name in the DocApp explorer to open the attribute editor,and select the Value Assistance tab.

2. Click Add Default to enter the required default list of values.See Specifying conditional value assistance, page 151.

3. Click Add Conditional to add conditions and their associated lists.See Specifying conditional value assistance, page 151.

4. Use the U (up) and D (down) buttons to arrange the conditional elements.

Specifying conditional value assistanceYou arrive here to specify either the default value assistance list or a conditional valueassistance list.



To specify conditional value assistance:

1. For a conditional list, specify the condition as a Docbasic expression that resolves totrue or false.

Note: For repeating value attributes, you must use repeating value attributekeywords. For more information about repeating value attribute keywords, seeRepeating value attribute keywords, page 154.

2. Select a radio button to specify the source of the list:• If Fixed List, enter the list into the text box, one value per line. Go to step 5.• If Query, Enter the query in the Query textbox. You can use the $value keyword

to resolve attribute values at runtime. For more information about the $valuekeyword, see $value kyword, page 152.

3. Enter the query attribute that provides the list values in the Query Attribute textbox(optional).

4. If you specified a default value, make sure that you have entered it in the fixedlist or it is returned as part of the query.

Note: DAB does not validate whether the default value is included in the fixed list orreturned as part of the query.

5. Use the checkbox to specify whether or not cached queries are acceptable.

6. Use the checkbox to specify whether users can enter values that are not in the list.

$value kyword

You use the $value keyword to resolve values of single-value attributes in conditionalvalue assistance queries at runtime.

Note: If you use this keyword with a repeating-value attribute, the value in the firstindex position is always returned.

The syntax is:

$value(attribute)where:

attribute is the name of the attribute.

There cannot be any spaces before the opening parenthesis.

At runtime, the $value(attribute) phrase is replaced with the specified attribute’s currentvalue (for example, the value selected for the attribute in the document’s Propertiesdialog box). In some cases, you can use the $value keyword instead of multiple



conditional value assistance statements. In addition, using $value dynamically allocatesvalues instead of using hard-coded values in the conditional value assistance statements.

Example 14-2. Using the $value keywordA dm_document subtype, dozen_roses, has stem_length, color, and company attributes.If you want to display the names of companies (florists) depending on whether theyhave roses of the desired color and stem length, use this query (against a registered table)for the value assistance:select florist_name from florists where total_length = ’$value(stem_length)’and true_color = ’$value(color)’If the registered table, florists, has these columns and values:

total_length true_color florist_name

80 Red Fragrant Florists

80 Red Lyrical Lilies

60 White Flower Power Florists

and you select stem_length to be 80 centimeters and the color to be Red in a dozen_rosesdocument’s Properties dialog box, then this value assistance is displayed in the companyattribute’s field:

Fragrant FloristsLyrical Lilies

If, instead, you select stem_length to be 60 centimeters and the color to be White, thenthis value assistance is displayed in the company attribute’s field:

Flower Power Florists

Because the $value keyword dynamically allocates values, you do not need to change thequery when more rows with new values are added to the registered table. For example,if two rows are added to the registered table so that it has these values:

total_length true_color florist_name

80 Red Fragrant Florists

80 Red Lyrical Lilies

60 White Flower Power Florists

80 Red Flower Power Florists

70 Hot Pink Fragrant Florists

then the same query displays this value assistance when you select stem_length to be 70centimeters and the color to be Hot Pink:

Fragrant Florists

To create the value assistance that corresponds to the previous example without usingthe $value keyword, you would need to create:



Value AssistanceStatement

Condition Query

Statement 1 length = 60 and color =’White’

select florist_name from florists wheretotal_length = 60 and true_color =’White’

Statement 2 length = 70 and color =’Hot Pink’

select florist_name from florists wheretotal_length = 70 and true_color = ’HotPink’

Statement 3 length = 80 and color =’Red’

select florist_name from florists wheretotal_length = 80 and true_color = ’Red’

Default ValueAssistance

N/A select florist_name from florists

Notice that if you do not use the $value keyword and more rows with new values areadded to the florists registered table, you need to add more value assistance statementsto query for the new values.

Repeating value attribute keywords

You use repeating value attribute keywords to specify which runtime values in an object’srepeating value attribute to use in constraint or conditional value assistance expressions.

The syntax is:

attribute_name (keyword) operator {attribute_name | value}

{attribute_name | value} operator attribute_name (keyword)where:

attribute_name is the name of the attribute. keyword is one of the repeating value attributekeywords—ANY, ALL, FIRST, LAST. operator is a valid Docbasic operator. value is avalid value for the attribute.

Keyword Description

ANY Uses any runtime value of an object’s attribute in the expression.

ALL Uses all of the runtime values of an object’s attribute in the expression.

FIRST Uses the runtime value of the first array position (that is, array positionzero) in the expression.

LAST Uses the runtime value of the last array position in the expression.



For example, the following condition and corresponding value assistance for the booksattribute of a custom type called literature:

Condition Value Assistance

literature_authors (ANY) = "Basho" Narrow Road to the Deep North

The Poetry of Matsuo Basho

displays the choices, "Narrow Road to the Deep North" and "The Poetry of MatsuoBasho," if at least one of the runtime values of a literature object’s literature_authorsattribute is the Haiku poet’s name, Basho.

Creating or modifying a value mapping tablefor an object type attribute

Value mapping occurs when you associate or map attribute values to strings to bedisplayed in a client program, such as Desktop. When a mapped string, which isdisplayed in the client program, is selected and the object is saved to the Docbase, thecorresponding value is saved—not the mapped string.

To create or modify a value mapping table for an object type attribute:

1. Double-click the attribute’s name in the DocApp explorer to open the attribute editor,and select the Value Mapping tab.

2. For each mapping, follow steps 3 through 5 to build a line of the value mapping table.

3. In the Data column, enter the attribute value (for example, CA).The Data column value is the value that you want to be saved to the Docbase. Thisvalue corresponds to the string in the Data String column.

4. In the Display String column, enter the mapped value (for example, California).The Display String column value is the string that you want to display in the clientinterface. This string corresponds to the attribute value in the Data column.

5. In the Description column, enter a short, descriptive comment (for example, TheGolden State—home to 55 million Americans) about the corresponding valuemapping.



Removing an attribute from an object typeTo remove an attribute from an object type, in the DocApp explorer, right-click theattribute and choose Delete.

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


Chapter 15Working With Permission SetTemplates

These topics are included:• About permission set templates, page 157• Creating new permission set templates or adding existing ones from Docbases, page 158

About permission set templatesAlthough a permission set template is defined as a permission set that has its acl_classattribute set to 1, in practice, a permission set template also has one or more aliases. Usea permission set template when:• The users or groups to which it applies will be different at runtime depending on

the object type, workflow template, business policy, session, user, or group to whichthe permission set template is assigned.

• You need to install the permission set template in other Docbases that might havedifferent users or groups.

Use a permission set when the users or groups will be the same at runtime regardlessof which business policy, session, user, or group the permission set is assigned to andthey will be the same in other Docbases.

To help ensure maximum flexibility at runtime and portability between Docbases, DABsupports creating new and inserting existing permission set templates only (you can stilluse EMC | Documentum Administrator to create permission sets). Although you canuse DAB to specify either a permission set or permission set template for many objects,DAI will not install permission sets that are specified for an object in the DocApp; whenyou specify a permission set for an object, you must specify an alias in an alias set forthat permission set and that DAI prompt for a value so that the person who installs theDocApp selects an appropriate permission set in the target Docbase.


Working With Permission Set Templates

Creating new permission set templates oradding existing ones from Docbases

To create a new permission set template:

1. Choose Insert → Permission Set Template.

2. Enter appropriate values for the permission set template name, owner, anddescription.

3. To add permissions for a user, group, or alias to the permission set template:

a. Display all alias sets in the DocApp, all alias sets in the Docbase, or all Docbaseusers and groups in the drop-down list by setting the corresponding radiobutton.

b. Display users and groups in an alias set, all groups in the Docbase, or users in agroup by selecting the corresponding alias set or group or <Show All Groups>from the drop-down list.

c. Select a user, group, or alias in the list box.

d. Specify permissions for the selected user, group, or alias in the Permissionsdrop-down list and the checkboxes.

e. Add the selected user, group, or alias with the specified permissions to thepermission set template by clicking Add to Set.

4. To modify permissions for a user, group, or alias, follow the same steps for addingpermissions and specify the new permissions.

5. To remove permissions for a user, group, or alias, select the alias in the list box onthe right and click Remove from Set.

Note: When you create a new permission set template, DAB automatically addspermissions for dm_owner and dm_world. A permission set template must containentries for dm_owner and dm_world.

To add an existing permission set template from the Docbase:

1. Choose Insert → Object from Docbase → Permission Set Template and select apermission set template.Aliases in the selected permission set template that do not exist in the default aliasset are created and added to the default alias set. The aliases are added to the aliasset as "User or Group" alias types without a value and without enabling the "Promptfor value at Installation" option. You are prompted to check in the permission settemplate and default alias set.

2. Click Yes in each of the dialog boxes to check in the permission set template anddefault alias set or No to keep them checked out.



3. Open the default alias set and modify the new aliases.

4. If desired, modify the permission set template as instructed in the followingprocedure.

To modify a permission set template:

1. Double-click its name in the DocApp explorer to open the permission set templateeditor.

2. If desired, change the name and description of the permission set template.

Tip: Another way to change the permission set template’s name is to select thepermission set template name in the tree pane (it must be checked out) and thenclick its name.

3. Perform steps 3 to 5 in the procedure for creating a new permission set template.




Chapter 16Working With Procedures

These topics are included:• About procedures, page 161• Creating new procedures or adding existing ones from Docbases, page 161• Creating pre- and post-installation procedures, page 162

About proceduresA procedure is the representation within a DocApp of the identity and the restrictions onthe use of a Docbasic program designed to run within the client.

Use the Docbasic editor to specify or modify the Docbasic program.

Creating new procedures or adding existingones from Docbases

To create a new procedure:

1. Choose Insert → Procedure.

2. Double-click its name in the DocApp explorer to open the Docbasic editor.

3. Add Docbasic code, debug, save, and check in the procedure.

To modify an existing procedure:


2. Add Docbasic code, debug, save, and check in the procedure.


Working With Procedures

3. To add an existing procedure from the Docbase, choose Insert → Object fromDocbase → Procedure and selecting it. If desired, modify the procedure asinstructed in the previous paragraph.

Note:• For complete instructions on how to use the Docbasic editor, see the Docbasic editor

online help (choose Help → Help Topics).• For information about Docbasic, see the Docbasic Help in the Application Builder

master help and the Docbasic Reference Manual (in PDF and print).

Creating pre- and post-installation proceduresFor more information about pre- and post-installation procedures, see:• Pre-installation procedure, page 163• Post-installation procedure, page 163If you have already created a pre- or post-installation procedure, add it from the Docbaseby choosing Insert → Object from Docbase → Procedure and selecting it.

To create a new pre-installation procedure or post-installation procedure:

1. Choose Insert → Procedure.


3. Add Docbasic code, debug, save, and check in the procedure.You should not use DFC in pre- and post-installation procedures—instead useServer API calls.

4. Set the procedure as either a pre-installation procedure or a post-installationprocedure by setting the DocApp’s installation options.For more information about setting installation options, see Setting installationoptions, page 36.

Note:• The pre-installation procedure must have this signature:

Sub PreInstall( docbaseName As String, userName As String,loginTicket As String)

• The post-installation procedure must have this signature:

Sub PostInstall (docbaseName As String, userName As String,loginTicket As String)



• Use Print statements to print debugging or status messages to the DocApp archive’slog file.

• You must use the dmExit function to send the return status to the ApplicationInstaller. If you do not, then the Application Installer assumes that the proceduresucceeded.

Pre-installation procedure

A pre-installation procedure is a procedure that you want to be executed before theApplication Installer begins installation. For example, you can use a pre-installationprocedure to create users and groups. If the pre-installation procedure fails, then theApplication Installer aborts the installation of the DocApp archive; however, if thepre-installation procedure successfully executes but later the Application Installer abortsthe installation, the effects of the actions that the procedure performed in the targetDocbase remain. For example, if the procedure adds groups to the target Docbase butthe installation fails later, the newly added groups still remain in the target Docbase.

Post-installation procedure

A post-installation procedure is a procedure that you want to be executed after theinstallation completes. If the DocApp installation fails, then the post-installationprocedure is not executed. If the post-installation procedure fails, then only thatprocedure fails (since the installation of the DocApp archive has already completed).




Chapter 17Working With Queue ManagementObjects: Doc Proles, User Proles,and Work Queues

These topics are included:• About Doc Profiles, page 165• About User Profiles, page 165• About Work Queues, page 166• Adding existing doc profiles, user profiles, and work queues from Docbases, page 166

About Doc ProlesA work queue doc profile (of the dmc_workqueue_doc_profile object type) containsinformation that describes a particular kind of document. The objects are used to managework items placed on work queues. Work queues, and consequently, work queue docprofiles, are created using Webtop.

The object type is installed using a script at the time Content Server is installed.

About User ProlesA work queue user profile (of the dmc_workqueue_user_profile object type) describes auser who performs tasks taken from a work queue. The information includes the user’sskill level. The user profiles are created when the work queue is created.

You must have installed Business Process Manager to use work queues and theassociated user profiles.


Working With Queue Management Objects: Doc Proles, User Proles, and Work Queues

About Work QueuesA work queue user profile (of the dmc_workqueue_user_profile object type) describes auser who performs tasks taken from a work queue. The information includes the user’sskill level. The user profiles are created when the work queue is created.

You must have installed Business Process Manager to use work queues and theassociated user profiles.

Adding existing doc proles, user proles, andwork queues from Docbases

To add an existing doc profile, user profile or work queue, choose Insert→ Object fromDocbase → Doc Profile or User Profile orWork Queue and select one.

After adding a work queue to the DocApp, specify its location alias as /System/QueueManagement/Work Queue Categories in the Installation Options dialog box (see Settinginstallation options, page 36).

You cannot use DAB to create, modify, or delete existing doc profiles, user profiles, orwork queues.


Chapter 18Working With Relation Types

These topics are included:• About relation types, page 167• Creating or modifying a relation type object, page 167

About relation typesRelation types define types of relationships between two objects in a Docbase. It definesthe direction, delete behavior, and security of the parent-child relationship. A relation(dm_relation) is the actual relationship between two objects. A relation only defines theparent and child objects and references a relation type to describe the behavior actualrelationship.

See Creating or modifying a relation type object, page 167 for instructions on how tocreate or modify relation types.

Relation types

Relation types define types of relationships between two objects in a Docbase. It definesthe direction, delete behavior, and security of the parent-child relationship.

Creating or modifying a relation type objectTo create a relation type (dm_relation_type) object:

1. Choose Insert → Relation Type.

2. In the relation type object dialog box, specify the desired fields:


Working With Relation Types

Field name Attribute name Valid values Description

Name relation_name A string with amaximum of 255characters.

Name of the relation type.

Description description A string with amaximum of 250characters.

A brief description of the relation type.

SecurityType

security_type Valid values are:

System

Parent

Child

None

Defines the security applied to objectsof type dm_relationship whoserelation_name attribute value matchesthe relation_name attribute for thedm_relation_type objects.

System: Only users with Superuseror Sysadmin privileges can create,modify, or drop dm_relation objectshaving this relation name.

Parent: Security is determinedby the object type of the parentobject participating in this kind ofrelationship.

Child: Security is determined bythe object type of the child objectparticipating in this relationship.

None: No security is applied to thedm_relation objects representinginstances of this relationship.

Child Type child_type A string with amaximum of 32characters. Can beempty.

Defines the object type of a valid childobject in the relationship

Parent Type parent_type A string with amaximum of 32characters. Can beempty.

Defines the object type of a validparent object in the relationship.

RelationshipDirection

direction_type 0 - from parent to child1 - from child to parent2 - bidirectional Thedefault is 0.

The direction of the relationship.



Child-to-ParentLabel

child_parent_label

A string with amaximum of 255characters.

A label for a child-to-parentrelationship.

Parent-to-Child Label

parent_child_label

A string with amaximum of 255characters.

A label for a parent-to-childrelationship.

ReferentialIntegrity

integrity_kind 0 - allow delete 1- restrict delete 2 -cascade delete Thedefault is 0.

Indicates how to enforce referentialintegrity.

To modify a relation type (dm_relation_type) object:

1. Double-click the relation type object in the left pane.If you have not inserted the relation type object into your DocApp, then chooseInsert → Object from Docbase → Relation Type, select the desired relation typeobject, and then double-click the relation type object.

2. In the relation type object dialog box, modify the desired fields.




Chapter 19Working With Roles

These topics are included:• About roles, page 171• Adding existing roles from Docbases, page 171

About rolesA role (also known as a role group) is a type of group containing a set of users, othergroups, or both that perform a defined set of tasks within a client application.

You can insert a role from the Docbase into the DocApp, but you cannot create or modifya role from within Application Builder.

Adding existing roles from DocbasesTo add an existing role from a Docbase, choose Insert → Object from Docbase → Roleand select a role.


Working With Roles


Chapter 20Working With XML Applications

These topics are included:• Introduction to XML content management, page 173• XML application components, page 174• Creating XML applications, page 175• Checklist for creating an XML application, page 177• Tasks to perform before creating an XML application, page 179• Specifying validation options for XML documents using an XML application, page 180• Specifying XML application detection and DTD patching options, page 181• Specifying a supporting files folder for an XML application, page 183• Specifying a sample XML documents folder, page 183• Validating XML applications, page 184• XML application validation results, page 185• Tasks to perform after creating XML applications, page 187• Modifying XML applications, page 187• Viewing and editing the XML application configuration file, page 188

Introduction to XML content managementXML documents can be stored in a repository just like any other document. However,you can greatly increase the functionality of your XML documents by creating one ormore XML applications that will help you customize and automate how XML objectsand linked unparsed entities are stored in a repository.

Here are some examples of the type of XML content management that is available withinthe EMC | Documentum system.• You want separate groups in the company to manage separate chunks of content,

with different permissions assigned to each chunk.


Working With XML Applications

• You want to share chunks of content with other authors or departments in anon-proprietary file format.

• You want to reuse chunks of content in more than one document or publish it tomore than one location.

• You want to automate processing of XML content chunks using features availablein the standard EMC | Documentum content management system, such as sourcecontrol, metadata, document lifecycles, workflows, and security.

• You use XML as a wrapper for non-XML documents in order to assign metadatato those documents in the repository.

• You want to create XML files that can be used to create folders, assign properties, andso on, without creating any content chunks.

• You want to construct Web pages dynamically with XML content chunks.XML applications can be configured to automatically recognize different types of XMLdocuments and set up rules to determine where they are to be stored, whether theyshould be divided into smaller chunks, how to extract and assign metadata to an objectin the repository, what level of security to assign, whether to attach a document lifecycle,and so on. On import or checkin, the XML content is automatically processed accordingto these rules. These automated procedures help to increase efficiency and reduce errorin XML content management.

XML documents can also be generated from XML content using XDQL/XSLT. This isespecially useful when the structure is fixed but the content frequently changes, suchas for Web pages.

XML application componentsYou can use EMC | Documentum Application Builder to create an XML applicationfor you in the repository, or you can create one manually with a client such as EMC| Documentum Desktop. You can create the XML application configuration file firstand then create the XML application, or vice versa. If you create the XML applicationfirst using EMC | Documentum Application Builder, you can use the associated XMLConfiguration File Editor to create the configuration file.

A EMC | Documentum XML application consists of a set of folders and files that definethe processing rules for a particular kind of XML document. These folders and files are:• A folder with the name of the XML application, (required), with properties that

are used to detect whether the XML application applies to XML documents beingtransferred into and out of the repository and (optionally) to manage download ofthe DTD or schema along with the XML document.

• An XML application configuration file (required), which is located in the XMLapplication folder and has the same name. It defines the rules for processing XML



documents during content transfer into and out of the repository. This configurationfile is validated against config_5.2.dtd (or an earlier version, according to what youspecify as the system ID in the configuration file), located in the EMC | DocumentumDefault XML Application folder.

• A folder (optional) named Application Support Documents, containing files such asa DTD or schema, CSS, FOSI, and stylesheets. The DTD is optionally used to validateXML documents during content transfer operations. The contents of this folder aredownloaded to local systems when XML documents are downloaded (checkout,export) or uploaded (import, checkin). In Webtop, these support documents aredownloaded in all the aforementioned cases except when an XML document isimported.

• A folder (optional) named XML Sample Documents, containing XML instances of thetype that will be processed by the XML application. These sample documents canhelp you modify the XML application configuration file in the XML ConfigurationFile Editor associated with EMC | Documentum Application Builder.

• Other optional folders that you create, in which you can store supporting files thatdo not want to be downloaded to local systems.

Creating XML applicationsBefore creating an XML application, make sure that you have the information in thischecklist and perform these tasks.

For more information about XML applications, see Introduction to XML contentmanagement, page 173.

For more information about creating XML applications, see the XML ApplicationDevelopment Guide.

To create an XML application:

1. Choose Insert → XML Application.

2. In the Create XML Application dialog box’s General tab, specify a name for theXML application in the Name field.The XML application name must be unique in the Docbase. The name of theapplication must be the same as the XML application configuration and the valueof the <name> element (which is a child of the <application> element) in the XMLapplication configuration file.

3. Create an XML application configuration file for the XML application by selectingone of these options:

Note: Deselecting the checkbox enables the radio buttons.



Option Description

Create a newconfigurationfile fromtemplate

An XML application configuration file with minimalconfiguration information and based on the standard EMC |Documentum XML application configuration template will becreated. The XML application configuration file name and valueof the <name> element (which is a child of the <application>element) in the XML application configuration file must be thesame as the XML application name.

In the XML application configuration file you will need todevelop the rules for processing your XML documents.

Use anexistingconfigurationfile from theDocbase

Click the Browse button to find and select an XML applicationconfiguration file in the Docbase. The XML applicationconfiguration file will be copied into the DocApp folder andrenamed to the name of the XML application.

If you have not already done so, you must change the value of the<name> element (which is a child of the <application> element) inthe XML application configuration file to the name of the XMLapplication.

In the XML application configuration file you might need tomodify the rules for processing your XML documents.

Use anexistingconfigurationfile fromthe local filesystem

Click the Browse button to find and select an XML applicationconfiguration file on your local file system. The XML applicationconfiguration file will be checked in to the DocApp folder andrenamed to the name of the XML application.

If you have not already done so, you must change the value of the<name> element (which is a child of the <application> element) inthe XML application configuration file to the name of the XMLapplication.

In the XML application configuration file you might need tomodify the rules for processing your XML documents.

4. Check or uncheck theValidate the DocApp before checking in the XML applicationoption.Checking this option specifies that your XML application will be validated against itsXML application configuration file before it is checked in; otherwise, it will not bevalidated before it is checked in. However, you can manually validate it at a latertime by selecting the XML application and choosing Tools → XML Application →Validate.



You might not want to check this option when you know that the XML applicationconfiguration file is invalid (for example, when you choose to use an existingconfiguration file and the <application><name> element is not the same name as theXML application) and you will be updating it later.

5. Specify values and select options on the Validation, XML App Detection, andSupporting Folder tabs.

6. To validate (if you chose to validate it) and check in the XML application, click OK.

Tip: To make sure that you have entered a unique XML application name andselected an XML application configuration file before validating and checking in theXML application, click Apply.

7. Confirm your XML application specifications.For more information about this dialog box, see Confirming the specifications forcreating an XML application, page 177.

Conrming the specications for creating an XMLapplication

Before creating the XML application, Application Builder displays a dialog box thatdescribes the options you have specified for the XML application.

To confirm the options and create the XML application files and folders, click OK.

To cancel the creation of the XML application files and folders, click Cancel.

To find out what the next tasks are after creating your XML application, click Show NextSteps. See Tasks to perform after creating XML applications, page 187.

Checklist for creating an XML applicationThis checklist describes the required and optional information and files that you needfor creating an XML application.



Table 20-1. Checklist for creating an XML application

CompletedInformation orFile

Required orOptional Where to find

XML applicationname

Required

XML applicationconfigurationfile

Required Same name as XMLapplication folder.

DTD filename (systemidentifier)

Required if yourDTD is managedby an XMLapplication.

Specified in <!DOCTYPE>declaration of XMLdocuments to be processedby the application.

Public identifier Required if publicidentifier is used inXML documentsand DTD ismanaged by XMLapplication

Specified in <!DOCTYPE>declaration of XMLdocuments to be processedby the application.

DTD memberfiles

Required ifdeclared in theDTD and DTD ismanaged by XMLapplication.

Declared in DTD as externalparameter entities

Schema filename

Required ifyour schema ismanaged by XMLapplication.

Name of W3C schema, ifused in XML documents.

Schemamembers

Required ifreferenced fromthe schema

Specified by the <import>element in the schema.

Root elementnames

Required todetermine whichXML applicationswill apply

All elements that can serve asthe root element of the XMLdocument.



CompletedInformation orFile

Required orOptional Where to find

Supporting files Required forDTD or schemamembers ifmanaged by theXML application;otherwise optional

External parameter entitiesor schema members for amanaged DTD or schema(required); any other filessuch as CSS, FOSI, XSLstylesheets (optional)

XML sampledocuments

Optional XML documents in the/System/Applications/docapp_name/xml_app_name/XML Sample Documentsfolder in the repository.docapp_name is the name ofthe DocApp in which theXML application resides andxml_app_name is the name ofthe XML application.

Tasks to perform before creating an XMLapplication

Before creating your XML application, perform these tasks so that you will have a validXML application and all objects will be correctly installed into the target Docbases (ifyou create a DocApp archive to install on other Docbases).

To make sure that your XML application is valid and all objects will be correctly installedinto the target Docbases:

1. Insert all objects specified in the XML application configuration file into the DocApp.Performing this step makes your DocApp portable.

2. Make sure that all initial states specified in the XML application configuration fileexist in the corresponding document lifecycles.

3. Make sure that no document lifecycles that are specified in the XML applicationconfiguration file with the same names exist in the same location. Performing thisstep ensures that the XML application uses the correct document lifecycle; otherwise,if you have duplicate document lifecycles, the XML application might not use thecorrect one.



4. You can also specify the object ID of the appropriate document lifecycle in the XMLapplication configuration file, but when you install it to another Docbase, you willneed to change its object ID to the new one.

5. Make sure that the document lifecycles specified in the XML applicationconfiguration file are the originals or copies--do not link them (links might not beinstalled in target Docbases).

6. Make sure that the alias set name and the alias names specified in the XMLapplication configuration file are the same names as those included in the DocApp;alias names are not validated.

Specifying validation options for XMLdocuments using an XML application

To specify validation options for the XML documents in a new XML application:


2. Click the Validation tab.

3. Specify a DTD file against which the XML application will validate XML documentsby selecting one of these options:

Option Description

Copy an existingDTD from theDocbase

Click Browse to find and select a DTD in the Docbase. TheDTD is copied into the Application Support Documentsfolder.

Link an existingDTD from theDocbase

Click Browse to find and select a DTD in the Docbase. TheDTD is linked into the Application Support Documentsfolder.

Copy an existingDTD from thelocal file system

Click Browse to find and select a DTD on your local filesystem. The DTD will be checked in to the ApplicationSupport Documents folder

Note: To clear all your selections without any DTD being specified, click Reset.

4. Select members (external parameter entities in the DTD) from the Docbase or localfile system to be copied into the XML application folder by clicking Add and findingand selecting the files.

5. Delete members to be copied into the XML application folder by selecting a memberand clicking Remove.



6. Specify a schema file against which the XML application will validate XMLdocuments by selecting one of these options:

Option Description

Copy an existingschema from theDocbase

Click Browse to find and select a schema in the Docbase. Theschema is copied into the Application Support Documentsfolder.

Link an existingschema from theDocbase

Click Browse to find and select a schema in the Docbase. Theschema is linked into the Application Support Documentsfolder.

Copy an existingschema from thelocal file system

Click Browse to find and select a schema on your local filesystem. The schema will checked in to the ApplicationSupport Documents folder

Note: To clear all your selections without any schema being specified, click Reset.

7. Select members (specified by import elements in the schema) from the Docbase orlocal file system to be copied into the Application Support Documents folder byclicking Add and finding and selecting the files.

8. Delete members to be copied into the Application Support Documents folder byselecting a member and clicking Remove.

9. If you have completed the specifications for your XML application, click OK;otherwise, specify values and select options on the other tabs: General, XML AppDetection, and Supporting Folder.

Specifying XML application detection and DTDpatching options

When you import XML documents into a Docbase, you can choose an XML application.A client can display XML applications that match the DTD, schema, or both specifiedin the XML document and its root element. When an XML document is exported orchecked out, the system ID in the XML document can be replaced (or patched) with thelocation of the DTD that is also downloaded.

To specify the DTD, schema, and root elements of the XML documents with which the XMLapplication can be used and whether to patch the system ID:


2. Click the XML App Detection tab.

3. Specify these fields.



If a system ID, public ID, or schema will be present in the XML documents to whichyou want to apply the XML application, you must specify them.

Field Description

System ID If you have specified a DTD, the DTD name is displayed hereand you cannot change it. Otherwise, you can change the DTDname, which is retrieved from the <sys_id> value in the XMLapplication configuration file; you also must change it in theXML application configuration file.

If you want the system ID of an XML document to be replaced(or patched) with the location of the downloaded DTD on exportor check out, then you must specify the DTD in this field.

Public ID The universal resource identifier (URI) is retrieved from the<pub_id> value in the XML application configuration file. Youcan change it here, but you also must change it in the XMLapplication configuration file.

Schema If you have already specified a schema, the schema name isdisplayed here and you cannot change it. Otherwise, you canchange the schema name, which is retrieved from the <schema>value in the XML application configuration file; you also mustchange it in the XML application configuration file.

4. Include elements--you must include at least one-- that you expect to be the rootelements of XML documents that users will import by adding them to the Selecteditems list:• Add a root element to the Selected items list by selecting a root element from

the Select items from this list field (the root elements are retrieved from the<app_pattern><element> elements in the XML application configuration file) andclicking the right-pointing double arrowheads.

• Add root elements to the Selected items list that are not in the Select items fromthis list list by entering them in the Type in an item to add field and clickingthe right-pointing double arrowheads.

• Remove root elements from the Selected items list by selecting them and clickingthe left-pointing double arrowheads.



Specifying a supporting les folder for an XMLapplication

A supporting files folder named "Application Support Documents" resides in theDocbase as a subfolder of the XML application folder. You specify the files, such as aDTD or schema, CSS, FOSI, and stylesheets, to place in this folder.

To create a supporting les folder:


2. Click the Supporting Folder tab.

3. To create a new supporting files folder and copy files from the file system:

a. Check the Create a new supporting folder option.

b. To specify the files to copy from the local file system, click Add, finding andselect the files.

c. To prevent files from being copied, select the file in the textbox and click Remove.

4. To create a link to an existing supporting files folder, uncheck the Create a newsupporting folder option, click Browse to locate the folder in the Docbase, andthen select the folder.

Specifying a sample XML documents folderA sample XML documents folder named "XML Sample Documents"—by default, thefiles in this folder are downloaded to the local machine when an XML applicationconfiguration file is opened in EMC | Documentum’s XML configuration editor—residesin the Docbase as a subfolder of the XML application folder. You specify the sampleXML files to place in this folder.

To create a sample XML documents folder:


2. Click the Sample Folder tab.

3. To create a new sample XML documents folder and copy files from the file system:

a. Check the Create a new sample file folder option.

b. To specify the files to copy from the local file system, click Add, finding andselect the files.

c. To prevent files from being copied, select the file in the textbox and click Remove.



4. To create a link to an existing Docbase folder, uncheck the Create a new samplefile folder option, click Browse to locate the folder in the Docbase, and then selectthe folder.

Validating XML applicationsYou validate XML applications in two ways:• To validate an existing XML application, choose Tools → XML Application →

Validate.• If you are creating a new XML application, check the Validate the DocApp before

checking in the XML application option and specify the validation options on theCreate XML Application dialog box’s Validation tab.

If errors occur during validation, then the XML Application Validation dialog boxis displayed, which displays the errors and allows you to fix some errors directly;otherwise, the XML application successfully passes validation.

Application Builder validates an XML application by:• Validating the XML application configuration file against the EMC | Documentum

configuration DTD (config.dtd) using the Xerces XML parser.• Checking whether these objects are correctly specified in the XML application

configuration file and exist in the Docbase:

— Object type names and their attribute names

— Document lifecycle names, paths, and initial states

— Alias set names for these sysobject attributes: acl_name, acl_domain,owner_name; and paths to folders and cabinets.

— User names

— System ACL names

You should include all of these objects (except for users and system ACLs) in yourDocApp to make your XML application portable to other Docbases. Because usersand ACLs cannot be included in DocApps, make sure that you use either a pre- orpost-installation procedure to create them or that they already exist in the targetDocbase.

Application Builder does not validate XML documents against a DTD or schema. Forinstructions on specifying the validation of XML documents against a DTD or schema, seeSpecifying validation options for XML documents using an XML application, page 180.



XML application validation resultsTo x the errors displayed in the XML Application Validation dialog box:

1. On theMissing DocApp Objects tab, if there are any objects that are specified in theXML application configuration file and exist in the Docbase, but are missing fromthe DocApp, click Insert Objects into DocApp to insert them from the Docbaseinto the DocApp.

2. On the Errors tab, correct these types of errors as described:

Note: Application Builder validates alias set names but not alias names; ApplicationBuilder does not validate variables in the XML configuration file, since they arevalidated at runtime only.

Error Description Solution

MismatchedXMLApplicationName

One of these conditions exist:• The XML application namespecified in the <name>element (which is a child ofthe <application element)in the XML applicationconfiguration file does notmatch the XML applicationname specified in the Namefield on the General tab.

• The XML application namespecified in the <name>element (which is a child ofthe <application element)in the XML applicationconfiguration file does notmatch the XML applicationconfiguration file name northe XML application foldername.

Make the XML application namespecified in the <name> element(which is a child of the <applicationelement) in the XML applicationconfiguration file the same as theXML application name, the XMLapplication folder name, and theXML application configuration filename.

MissingObjects inDocbase

Objects specified in the XMLapplication configuration filedo not exist in the Docbase.You might have incorrectlytyped a name.

You must either:• Create the objects.• Correct the object names in theXML application configurationfile.



Error Description Solution

MissingAttributes

One of these conditions exist:• Attributes specified inthe XML applicationconfiguration file are notdefined in the object type.

• You might have specifieda repeating value attributeas a single value attribute(or vice versa) in the XMLapplication configurationfile.

• You might have incorrectlytyped an attribute name.

You must either:• Define the attributes.• Correctly specify the attribute asrepeating or single value in theXML application configurationfile.

• Correct the attribute names in theXML application configurationfile.

MissingDocumentLifecycleStates

One of these conditions exist:• Document lifecycle statesspecified in the XMLapplication configurationfile are not defined in thecorresponding documentlifecycles.

• You might have incorrectlytyped the state name(in the <policy_state>element) or the documentlifecycle name (in the<policy_name> elements)in the XML applicationconfiguration file.

You must either:• Create the states.• Correct the state (in the<policy_state> element) ordocument lifecycle names (in the<policy_name> elements) in theXML application configurationfile.

DuplicateDocumentLifecycles

Document lifecycles specifiedin the XML applicationconfiguration file referencemultiple document lifecycleswith the same names andlocations in the Docbase.

Move or delete the duplicatedocument lifecycles such that onlyone remains in the same location.You can also specify the objectID of the appropriate documentlifecycle in the XML applicationconfiguration file, but when youinstall it to another Docbase, youwill need to change its object ID tothe new one.

The Information Only tab displays the variables specified in the XML applicationconfiguration file. These are not errors and you do not need to make any corrections.



Tasks to perform after creating XMLapplications

After creating, validating, and checking in your XML application, you can:

1. Test your XML application by creating an XML document using an editor with yourDTD, schema, or both and importing it into the Docbase.

2. Modify your XML application.

Modifying XML applicationsAfter creating an XML application, you can:• Modify the XML application’s properties: system ID, public ID, schema, and root

elements.• Modify the XML application configuration file. See Viewing and editing the XML

application configuration file, page 188.• Modify, add, replace, and delete the DTD, schema, DTD and schema members, and

supporting files.Although you can check out and version the files that compose XML applications, youcannot check out or version XML applications (that is, the XML application folder).Application Builder uses the current versions of the XML application configurationfile, DTD, and schema.

You cannot use Application Builder to change the names of XML applications or XMLapplication configuration files. Although you can use other EMC | Documentumapplications to change these names, you will need to re-insert the renamed XMLapplication into the DocApp and you must make sure that the XML applicationconfiguration file name and the value of the <name> element (which is a child of the<application> element) in the XML application configuration file matches the XMLapplication name. Modifying, adding, replacing, and deleting the DTD, schema, DTDand schema members, and supporting files from Application Builder actually callsDesktop (so, Desktop must be installed on your machine).

To add, replace, and delete the DTD, schema, DTD and schema members, and supportingles:

1. Double-click the XML application.The XML application folder is opened in Desktop.



2. Modify, add, replace, and delete the DTD, schema, members, and supporting filesand check in any new and changed files within Desktop.

3. Go back to Application Builder.

4. If you modified or replaced the DTD or schema, make any necessary changes to theXML application’s properties.

Viewing and editing the XML applicationconguration le

When you view or edit an XML application configuration file from within DAB, it opensin EMC | Documentum’s XML application configuration file editor (XML ConfigurationEditor).

Note:• If you open an XML application configuration file from another EMC | Documentum

client, it opens it in the editor that the operating system associates with XML fileextension.

• You can only open the EMC | Documentum XML Configuration Editor from withinDAB; if you want to use the EMC | Documentum XML Configuration Editor toedit an XML application configuration file that is not in a DocApp, perform oneof these tasks:

— Add it to a DocApp and then open it from within DAB.

— Check out the XML application configuration file, use DAB to open a differentXML application configuration file that exists in a DocApp, and then use theEMC | Documentum XML Configuration Editor to open the first checked-outXML application configuration file.

To view an XML application conguration le:

1. Double-click the XML application configuration file in the left tree pane.

2. Click View in the View/Edit dialog box.

To edit an XML application conguration le:

1. Double-click the XML application configuration file in the left tree pane.

2. Click Edit in the View/Edit dialog box.The current version is checked out--even if the file displayed in the left tree pane isnot the current version.

3. Edit the XML application configuration file and save your changes using the EMC |Documentum XML Configuration Editor.



4. If you added or deleted references to Docbase objects in the XML applicationconfiguration file, add and delete them to and from your DocApp as well--see Tasksto perform before creating an XML application, page 179 .

5. Validate your XML application.

6. Check in the file.




Chapter 21Understanding Document Lifecycles

This chapter explains the concepts underlying document lifecycles (DLCs). It also explains thecomplementary roles of DLCs and workflows.

These topics are included:• About document lifecycles, page 191

This section describes document lifecycles.• DLCs, workflows, and business processes, page 192

This section explains how EMC | Documentum models the business policies and processes thatpertain to an organization’s documents. It explains how DLCs and workflows complement oneanother to automate different kinds of business rules.

• States and transitions, page 193

This section describes the structure of a DLC as a succession of states and rules for transitionsbetween those states. It provides details of how to design and specify the elements that definestates and control transitions.

• Aliases, page 197

This section describes the role that aliases play in document lifecycles. It shows how the systemuses scopes to resolve aliases.

• Versions, page 199

This section describes the effects of versioning lifecycles or their associated documents.

About document lifecyclesA DLC encodes business rules for changes in the properties of an object as it movesthrough the stages of its life (for example, in draft, in review, operational, obsolete).

A DLC has a primary object type that it applies to. It can also apply to specified subtypesof its primary object type. An object type can have at most one DLC.


Understanding Document Lifecycles

A DLC must be in a Docbase. It can have any of the following statuses:• Draft – You’re still working on it.• Validated – The DLC editor certifies that it is complete and internally consistent.• Installed – It is available in the Docbase for objects of appropriate types to use.The main window of the DLC editor represents the formal structure of a DLC in adiagram called a lifecycle state diagram. Each state appears as a pentagon with a statename label. Arrows represent possible state transitions (that is, state changes) in thelives of documents controlled by the DLC.

The states of a DLC are of two kinds: normal and exception. Normal states have a linearorder, from an initial (or base) state to a final state. Exception states represent diversionsfrom the normal order. Anomalies cause documents to enter exception states. Correctingthe anomaly allows a document to go back to the normal path, either picking up where itleft off or starting over.

DLCs, workows, and business processesMany companies have policies that govern how specific types of documents work theirway through their useful lives, and beyond. Such policies typically specify the stagesthat a document passes through and the activities that occur at each stage. EMC |Documentum separates these aspects of document policy into two concepts: lifecycles,which define the stages of a document’s life, and workflows, which define sequences ofactions that users must perform on the document.

Document lifecycles and workflows complement one another. The DLC does not definewhat activities happen to a document while it resides in a state, who is responsiblefor those activities, or when the document should move to another state. A workflowdefines a connected set of activities, including who performs the activities and when.For more information about Workflow Manager, see its online help and the ContentServer Fundamentals.

You can simulate a document lifecycle in a workflow definition, but keeping the twoconcepts separate leads to simple, reusable designs. This is because the simulatedlifecycle applies only within that workflow, not in any other workflow. In addition, thelifecycle aspects of the workflow can become entangled with a potentially complexnetwork of activities.

You can use a workflow to drive the activities associated with a state in a documentlifecycle. For example, you can create a workflow to route a document to severalreviewers, then use a procedure associated with the appropriate state of the lifecycleto launch that workflow.



States and transitionsThis section describes both the structure of a DLC as a succession of states, which modelthe life stages of the document, and the rules for transitions between those states. Itprovides details of how to design and specify the elements that define states and controltransitions.

How document lifecycle states model document lifestages

Documents have natural life stages. A product specification, for example, might beginas an engineer’s draft, pass through review and approval, and finish as a controlledreference document. While all product specs might pass through approximately thesame stages, a vacation request or an expense report passes through different stages.

A DLC models a document’s life stages as a set of possible states and rules that governtransitions from one state to another. The states fall into two categories: normal andexception. Normal states follow a linear progression, from the first (base) state to thelast (terminal) state.

Exception states model the case when a document must go into limbo. An unanticipatedtemporary failure of a key piece of equipment may force you to suspend a releasedstandard operating procedure (SOP). The SOP may not need to change—when theequipment comes back on line, the SOP goes back into force.

Each normal state has either zero or one exception state into which documents can movefrom that normal state. An exception state can serve more than one normal state.

Document lifecycle state diagram

The main window of the DLC editor represents the formal structure of a DLC in adiagram called a lifecycle state diagram. Each state appears as a pentagon with a statename label. Arrows represent possible state transitions in the life of a document thatthe DLC controls.

Each normal state in the diagram has at most one arrow leading to it from a normal stateand at most one arrow leading from it to a normal state. Exactly one normal state, calledthe base state, has no arrow leading to it from a normal state. Exactly one normal state,called the final state, has no arrow leading from it to a normal state. That is, the normalstates form a non-branching linear path from the base state to the final state:

Base state –> . . . –> Final state



A normal state has at most one arrow leading from it to an exception state. An exceptionstate has one or more arrows leading to it. Different normal states can use the sameexception state.

Transitions

A transition is a state change. There are five kinds of transition: attachment, promotion,demotion, suspension, and resumption.

The system carries out transition in two parts. The first part is a transaction. If it fails,nothing changes. Failures in the second part, called the post-change procedure, do notprevent the state change. Transitions have the following form:Determine target stateIf transition is not allowedabort the transition

Transaction{Evaluate entry criteria and entry criteria procedureIf entry criteria are not met or procedure returns FALSEabort the transition and back out changes

Perform state actions and action procedureIf an action fails or action procedure returns FALSEabort the transition and back out changes

}Perform post-change procedure(failures do not abort the transition)

The DLC state editor allows you to view or modify the properties of a DLC state. Eachstate has properties in the following categories, corresponding to the tabs of the editor:• General – The state’s name and its transition restrictions.• Entry criteria – Attribute tests to qualify the object for entry into the state, and a

procedure to execute upon entry.• Actions – One or more operations from a predefined set (for example, request a PDF

rendition) to carry out upon entry, and a procedure to execute after the operations.• Post-change Procedure – A procedure to execute after the transition transaction is

complete.• Attribute property changes – Modify an attribute’s label, help text, comment, and

whether the attribute is read only, required, cannot be blank, hidden, or can bemodified on immutable objects in this state. The required and cannot be blankproperties are checked when the client application validates an object (whichtypically occurs on saving or checking in an object)--not when it enters the state.

• Functionality changes – Changes, only effective in this state, from the usualfunctionality for objects of this type.



Attachment

When you define a document lifecycle, you specify a primary object type to whichit applies. You can also specify which subtypes of the primary type it applies to. Adocument lifecycle resides in a Docbase as a dm_policy object.

Attachment is the process of associating a document with a lifecycle and settingdocument-specific values for all of the lifecycle’s aliases. When you develop a documentlifecycle, you specify which states allow attachment.

When you attach a document to a lifecycle you can specify a state for it to start in. Thisdoes not need to be the base state.

Promotion and demotion

Moving from a normal state to a later one is called promotion. Moving from a normalstate to an earlier one is called demotion.

A document in a normal state can be promoted only to the next state. It can be demotedonly to the previous state or to the base state.

Suspension and resumption

Moving from a normal state to an exception state is called suspension. Moving from anexception state to a normal state is called resumption. Suspension moves a documentinto its state’s designated exception state. Resumption moves a document either to thenormal state from which it was suspended or to the base state.

Returning versioned or saved objects to the base state

When an object is checked in or saved, you have the option of returning the object tothe base state or allowing it to remain in its current state. (For check in operations,the affected object is the new version.) To set this option, check the Demote documentto base state on checkin/save option in the DLC Editor (or set a state’s return_to_baseattribute to TRUE).

The object is tested against the base state’s entry criteria and if it fails, the checkin or savemethod fails. If it passes the entry criteria, the checkin or save succeeds and the state’sactions are executed. If the actions do not succeed, the object remains in the base stateand the checkin or save is not backed out.



Attribute constraints

The definition of an object type includes constraints on the possible values of theattributes of objects of that type. Subtypes of the type inherit those constraints andcan add others. The definition of a subtype cannot relax the constraints inherited fromthe supertype.

When you design a DLC state, you can specify that while a document is in that state,its attributes must satisfy define additional constraints, beside those defined for thegiven type or subtype. The additional constraints no longer apply when the documentleaves that state.

Functionality

Users manipulate documents through client programs. The client program matchesspecific capabilities—like checking in a document or moving it—with executablecomponents designed to implement those capabilities.

Desktop matches capabilities and components dynamically. It uses the functionalityof the component, the user’s client capability (consumer, contributor, coordinator, oradministrator), and the document’s type and DLC state to make the association.

The definition of an object type includes a set of functionality classes, which are symbolicnames for capabilities. The functionality of an object type is a set of associations betweenfunctionality classes and specific components that implement that functionality. Anobject type in a typical DocApp inherits most of its functionality classes from itssupertype and uses components of the default DocApp to implement most of thatfunctionality. For each functionality class the object type definition includes:• The permissions required to apply the functionality to a document.• The identity of a binary component to implement the functionality.When you design a DLC, you can provide different capabilities, permissions, and binarycomponents for each state. You can make the following changes to capabilities:• Remove functionality classes that appear in the object type definition• Reassign a functionality class to a different component• Add new functionality classes and implementationsFor each association of a functionality class and a component, you can specify thepermissions a user must have to invoke the functionality.



AliasesAliases are the parameters of a document lifecycle. They enable you to assign symbolicnames to aspects of the DLC that you expect to differ from one context to the next.

When you define a document lifecycle you can assign aliases to such instance-specificitems as user and group names, permission sets, and Docbase locations. For example,you might specify %SpecRepository rather than Engineering\Documentum 4iProject\Product Specs for the target location of a move action.

When the system attaches a document to a lifecycle, it must provide specific values forall aliases. Alias sets facilitate this process.

Alias sets

An alias set contains aliases. When you create a DLC, you can specify several alias sets(including a default alias set) for it. One of these alias sets can be assigned to resolvealiases when an object is attached to the DLC. If you did not specify an alias set for theDLC, the system uses its scope to resolve the aliases.

Using scopes to resolve aliases

The scope of an alias is the context in which the binding of a value to its name takes place.The system recognizes four scopes: DLC, session, user, and system.

At runtime the system’s ResolveAlias method examines the alias sets associated witheach scope, starting with DLC, then session, user, and system. If it finds one that containsthe given alias name, it uses the corresponding value.

Tip: If you know at design time the name of the alias set containing an alias youwant resolved at runtime, you can increase performance by specifying the name as anargument to the ResolveAlias method. The system needs only to search the specifiedscope.

Document lifecycle scope

Using Application Builder, you can associate one or more alias sets with a DLC. Whenyou attach the DLC to a document, the system looks first in these alias sets to resolveall aliases.



Note: Users with at least Write permission for the lifecycle object can associate alias setswith it. Only the owner or a system administrator can modify an alias set. No one canmodify an alias set that is referred to by an installed lifecycle.

Session scope

Use a session config object to specify values for a server session.

Table 21-1. Alias set attributes in session cong object

Attribute name Datatype Repeating Description

alias_set DM_STRING(32) Single Alias set for thesession

User scope

Use a dm_user object to specify values for an EMC | Documentum user.

Table 21-2. User scope attributes in dm_user


alias_set_id DM_ID Single User’s default aliasset.

_alias_set DM_STRING(32) Single Label for theuser’s default aliasset. The systemcomputes thisattribute.

System scope

Use a dm_server_config object to specify values for the system running the server.



Table 21-3. System scope attributes in dm_server_cong


alias_set_ID DM_ID Single Default alias set forthe system runningthe server.

_alias_set DM_STRING(32) Single The label for thesystem’s defaultalias set. Thesystem computesthis attribute.

VersionsBoth documents and DLCs can have versions. When you attach a document to a DLC,you attach a specific version of the document to a specific version of the DLC. You canattach different versions of a document to different DLCs. When you upgrade a DLCto a new version, existing documents remain attached to the old version of the DLC.Newly created documents of the DLC’s designated object type have the new version astheir default DLC.

When you design a DLC, you can specify that the document returns to the base statewhenever anyone checks it in. This is the default behavior if you design the DLC withApplication Builder, but you can override it.

When this option is in effect, the system attaches the newly checked in Document, whichis now a new version, to the latest version of the DLC.




Chapter 22Creating and Modifying DocumentLifecycles

These topics are included:• Creating or modifying a DLC, page 201• Editing a document lifecycle state, page 205• Specifying attachment, demotion, and schedule transition settings, page 206• Specifying a state type, page 207• Specifying entry criteria and procedure for a document lifecycle state, page 208• Specifying actions and a procedure for a DLC state, page 210• Specifying the Change Content Storage action to move content to storage areas, page 215• Specifying or modifying a post-change procedure for a document lifecycle state, page 216• Specifying changes to attribute properties in a document lifecycle state, page 217• Specifying functionality, page 217

Creating or modifying a DLCTo create a DLC:

1. In DAB, choose Insert → Document Lifecycle and then double-click the documentlifecycle in the left pane.

2. On the DLC editor’s General tab, specify a name and description in the appropriatetext boxes.

3. Click the Primary Type field’s ellipsis (. . .) button to open the DLC type selectionwindow, and choose a primary object type from the Primary Type drop-down list.

Tip: If clicking the drop-down list does not display the list, click two more times.


Creating and Modifying Document Lifecycles

A DLC applies to one primary object type. You can specify which of the primarytype’s subtypes can also use the DLC. Initially, the Available Subtypes windowcontains all of the primary type’s subtypes, and the Acceptable Subtypes windowis empty.

4. Use the arrow keys to choose acceptable subtypes from the available subtypes, andclick OK to return to the DLC editor.

5. Click the Default Alias Set field’s ellipsis (. . .) button to open the Select Alias Setswindow, and choose a default alias set for the DLC to use to resolve aliases.You can add more alias sets for the DLC to use to resolve aliases. You might wantto do this if an alias set has aliases that you want the DLC to use, but you do notwant to add them to the DLC’s default alias set. However, if the same alias name isdefined in the default alias set and one of the additional alias sets, the alias name inthe default alias is used.

6. In the Implementation field, select the programming language—Docbasic orJava—in which the document lifecycle’s procedures are to be written.All procedures in the document lifecycle must be written in the selectedlanguage—that is, you cannot use one Action procedure that is written in Docbasicand a validation procedure written in Java. In addition, the Java procedures are EMC| Documentum modules that implement the DFC interface that corresponds to thespecific kind of procedure as follows:• Action – com.documentum.fc.lifecycle.IDfLifecycleUserAction• EntryCriteria – com.documentum.fc.lifecycle.IDfLifecycleUserEntryCriteria• PostChange – com.documentum.fc.lifecycle.IDfLifecycleUserPostProcessing• Validation – com.documentum.fc.lifecycle.IDfLifecycleValidate

7. On the Advanced tab, specify a procedure that performs additional validation to runwhen you validate the document lifecycle.See Specifying a document lifecycle validation procedure, page 204.

8. Use the Add State, Add Exception, Delete, and Layout buttons to draw the DLCstate diagram.

9. For each state in the diagram, highlight its icon and click Edit State to open theDLC state editor.

10. Specify the state’s properties.See Editing a document lifecycle state, page 205.

11. Check in the document lifecycle.

12. To validate the document lifecycle, click Validate.Validating a document lifecycle makes sure that it does not have any errors thatmight prevent it from running. If you have specified a validation procedure, thenit is executed.



13. To install the document lifecycle, make sure the Status in Docbase is Validated andclick Install.If the Status in Docbase is Draft, then click Validate to validate it before clickingInstall.Installing a document lifecycle makes it available to users.

To modify a DLC:

1. Double-click the document lifecycle object in the left pane and click Edit.If you have not inserted the document lifecycle object into your DocApp, then chooseInsert→ Object from Docbase→ Document Lifecycle, select the desired documentlifecycle object, and then double-click the document lifecycle object.

2. In the document lifecycle editor, modify the desired fields and states.

3. Check in the document lifecycle.If you have not uninstalled the document lifecycle and want to check it in as thesame version, it is uninstalled and placed into the Draft state, and running instancesof the document lifecycle are suspended; otherwise, check it in as a new version,check it out, validate and install it.

4. To validate the document lifecycle, click Validate.Validating a document lifecycle makes sure that it does not have any errors thatmight prevent it from running.

5. To install the document lifecycle, make sure the Status in Docbase is Validated andclick Install.If the Status in Docbase is Draft, then click Validate to validate it before clickingInstall.Installing a document lifecycle makes it available to users and any running instancesof the document lifecycle are restarted.

Tip: In any DLC editor textbox, you can use the context menu to cut, copy, and pastetext, delete text, select all text in the textbox, or undo the last change. (There are nocorresponding keyboard shortcut keys.)

To cut or copy, and paste text:

1. Select the text.

2. Right-click in the textbox and select either Copy or Cut.

3. Position the cursor in the same or another textbox, right-click in the textbox, andselect Paste.

To delete text, select the text, right-click in the textbox and select Delete.

To select all text in a textbox, right-click in the textbox and select Select All.



To undo the last change, right-click in the textbox and select Undo.

Specifying a document lifecycle validation procedure

When you validate the document lifecycle, the specified validation procedure executesthe document lifecycle and is executed.

This feature is only available when connected to Content Server 5.2.5 (or greater).

To specic a validation procedure:

1. Select the Advanced tab in the DLC state editor.

2. Perform one of these actions:• If the General tab’s Implementation field value is Docbasic, click the ellipsis

button next to the Docbase Pathname field to open the Select ValidationProcedure dialog box, and navigate to the desired procedure.

Tip: If the version label field does not display the procedure version, selectthe procedure again.

• If the General tab’s Implementation field value is Java, click the ellipsis buttonnext to theModule Name field to open the Select Validation Module dialogbox, and navigate to the desired module.

3. If you specified a module, insert it into the DocApp; otherwise, it will not be includedin the DocApp archive.

See Designing the validation procedure, page 204.

Designing the validation procedure

Write the validation procedure as a Docbasic procedure or module that contains codeto perform validation tasks, such as verifying that states you require are specified inthe document lifecycle.

The module must implement the com.documentum.fc.lifecycle.IDfLifecycleValidateinterface.

The validation Docbasic procedure has the following signature:Public Function ValidationProc( _ByVal SessionId as String, _ByVal PolicyId as String, _ByVal UserName as String, _ByRef ErrorStack as String) As Booleanwhere:



SessionId Session ID (session established by the calling procedure)

PolicyId r_object_id of the dm_policy (document lifecycle) object.

UserName Name of the user who is executing the procedure.

ErrorStack Error message

Note: In Docbasic code, the function declaration must either appear on a single line or (asshown) have continuation characters (underscores) at the ends of all lines except the last.

Editing a document lifecycle stateTo edit a DLC state:

1. On the DLC state editor’s General tab, enter the state name and description in theappropriate text boxes.When running Application Builder on Japanese and Korean operating systemsagainst a Content Server version 4.1.x, 4.2.x, or 5.x, the first character of a documentlifecycle state name must be an ASCII letter (that is, lowercase or uppercase a – z).

Note: You cannot change the name of a state by clicking on its name in the DLCstate diagram; instead double-click the state to display the state editor and changeits name there.

2. Using the checkboxes, specify attachment, demotion, and scheduled transitionsettings.See Specifying attachment, demotion, and schedule transition settings, page 206.

3. Browse for and select a state type (dm_state_type object type) by which a clientapplication identifies the state or create a new state type.See Specifying a state type, page 207.

4. On the Entry Criteria tab, specify entry criteria and an entry procedure.See Specifying entry criteria and procedure for a document lifecycle state, page 208.

5. On the Actions tab, specify predefined operations and a procedure to execute afterentry into the state.See Specifying actions and a procedure for a DLC state, page 210.

6. On the PostChange tab, specify the procedure to execute after the change to thisstate is complete.See Specifying or modifying a post-change procedure for a document lifecycle state,page 216.

7. On the Attributes tab, specify changes, pertaining only while the object is in thisDLC state, to the properties of specified attributes of the object type.



See Specifying changes to attribute properties in a document lifecycle state, page 217.

8. On the Functionality tab, specify changes, pertaining only while the object is in thisDLC state, to the functionality of the object type.See Specifying functionality, page 217.

Specifying attachment, demotion, and scheduletransition settings

To specify attachment, demotion, and schedule transition settings, perform these tasks:• To allow objects that meet the state’s entry criteria to use this as their initial state,

check the DLC allow attachment directly to state property.• To allow transitions directly from this state to the previous state, check the Allow

demotion to previous state property.• To allow transitions from this state to the next state to occur as the result of a

time schedule, without explicit user action, check the Allow scheduled transitionsproperty.

To automatically demote objects to the base state under certain conditions, set theseoptions:• When connected to a version 4.2.x Docbase, you can check the option to force a

document to return to the base state of the DLC whenever it is checked in or saved.• When connected to a version 5.x Docbase, check these options to force a document to

return to the base state of the DLC on checkin, save, save as new, or branch. You canselect all of them, some of them, or none.

These options set the dm_policy type’s return_condition attribute to the these values:

Option Value Description

None 0 or undefined None of the options are selected andreturn_to_base is set to False.

Checkin 1 Return to base state on checkin andreturn_to_base is set to True.

Save 2 Return to base state on save andreturn_to_base is set to True.

Save as new 4 Return to base state on save as new andreturn_to_base is set to True.

Branch 8 Return to base state on branch andreturn_to_base is set to True.



When a 4.2.x Docbase is upgraded to 5.x, you do not need to make any changes to yourexisting DLCs; they retain the same functionality as they had in the 4.2.x Docbase. Whena 4.2.x Docbase is upgraded to 5.x, then return_condition for all existing DLC states isset to 0. The return_to_base attribute value does not change. If return_to_base is True,then Checkin, Save, and Save As are checked. If return_to_base is False, then none of theoptions are checked. If the state is subsequently checked in, the return_condition andreturn_to_base values will reflect the options checked in the dialog box.

Specifying a state typeSome client applications identify a state by state type instead of state name. Forexample, a state type, called “dcm_in_progress” is used by the client application, EMC |Documentum Compliance Manager (DCM).

This feature is only available when connected to server 5.2.5 (or greater).

To specify a state type (dm_state_type object type):

1. Select the General tab in the DLC state editor.

2. To specify an existing state type, click the ellipsis button, then browse for and selectthe desired state type.A state type (dm_state_type object type) identifies a state that a client applicationuses.

3. To create a new state type:

a. Click New.

b. Enter the state type name (state_type_name attribute) in the State Type field.A state type cannot have both the same name and the same application code asanother single state type in the Docbase. For example, if a state type has a nameof “dcm_in_progress” and an application code of “dm_dcm”, then there cannotbe another state that has a name of “dcm_in_progress” and an application codeof “dm_dcm”.Application code is a string that the client application recognizes, for example,“dm_dcm” for EMC | Documentum Compliance Manager (DCM). See theclient application’s documentation for information about its application codeand valid state types.

c. Enter the code (application_code attribute) for the application that uses the statetype in the application code field.

d. Click OK.

4. To delete the specified state type from the DocApp, click Clear.



Specifying entry criteria and procedure for adocument lifecycle state

A document can enter a state by attachment, promotion, demotion, suspension, orresumption. Before a document enters a state via attachment, promotion, suspension,or resumption, the system determines whether the document satisfies the state’s entrycriteria. The system does not check entry criteria on demotion.

For more information about how entry criteria are evaluated, see Evaluating entrycriteria, page 210.

To specify entry criteria:

1. Formulate each desired entry criterion as an attribute test.See Designing entry criteria, page 209.

2. On the Entry Criteria tab of the DLC state editor, use the Add Value Test and AddExpression Test buttons to help you enter and validate the attribute tests.

Tip: If clicking the drop-down list in the Expression Editor does not display thelist, click two more times.

3. Use the Up and Down buttons to specify the order of execution of the attribute tests.The DocApp evaluates the entry criteria in order, from the top of the list to thebottom. Because all criteria must be satisfied, and because attribute tests have noside effects, the order has no effect on the outcome. If an attribute test fails, however,the DocApp does not evaluate the remaining criteria, so an early failure can saveexecution time.


button next to theDocbase Pathname field to open the Select Criteria Proceduredialog box, and navigate to the desired procedure.


• If the General tab’s Implementation field value is Java, click the ellipsis buttonnext to theModule Name field to open the Select Criteria Procedure Moduledialog box, and navigate to the desired module.


See Writing the entry procedure, page 209.



State transitions occur within a transaction. Failure to satisfy entry criteria, failure ofany action, or an error or a FALSE return value from the entry procedure or the actionprocedure causes the system to abort the transition transaction and back out all changes.

Designing entry criteria

When designing a DLC, write each criterion as a Boolean Docbasic expression andspecify the attribute names of the document’s object type as variables in the expression.

An attribute test relates attribute values to one another or to constant values and mustevaluate to True or False. A value test is a criterion of the form:

Attribute [NOT] Relational_Operator Valuewhere the relational operators are

=, <, >, <=, =>, IncludesThe DLC editor provides special assistance for constructing value tests and generalDocbasic expressions.

Writing the entry procedure

Write the entry procedure as a Docbasic procedure or module and specify the attributenames of the document’s object type as variables in the procedure.

The module must implement the com.documentum.fc.lifecycle.IDfLifecycleUserEntryCriteria interface.

The entry Docbasic procedure has the following signature:Public Function EntryCriteria ( _ByVal SessionId as String, _ByVal ObjectId as String, _ByVal UserName as String, _ByVal TargetState as String, _ByRef ErrorString as String) As Boolean

where


ObjectId Document ID

UserName User ID



TargetState The state the document is trying to enter

ErrorString Error message

If the procedure returns TRUE, the system allows the transition. Otherwise, the transitionfails and the user sees the error message specified in ErrorString.

Note: In Docbasic code, you must specify the function declaration either on a singleline or have line continuation characters (underscores) at the ends of all lines exceptthe last (as shown).

Evaluating entry criteria

The system uses the following steps to evaluate a state’s entry criteria:

1. Evaluate individual criteria, each of which is a Boolean Docbasic expression in whichthe variables are names of attributes of the document’s object type.

2. Evaluate the specified logical combination of the values obtained in step 1.

If the value is FALSE, the system stops evaluating entry criteria, and the documentdoes not enter the state. Otherwise proceed.

3. Run the entry procedure if one is specified; if not, skip to the next step.

If the entry procedure returns FALSE, the system stops evaluating entry criteria, andthe document does not enter the state. Otherwise proceed.

4. Enter the specified state.

Specifying actions and a procedure for a DLCstate

After a document enters a state, the system performs the set of actions that you specifywhen you design the DLC.

The system uses the following steps to perform a state’s actions:

1. Perform all of the predefined actions (referred to as Standard Actions in ApplicationBuilder).

2. Perform the action procedure.



State transitions occur within a transaction. Failure to satisfy entry criteria, failure ofany action, or an error or a FALSE return value from the entry procedure or the actionprocedure causes the system to abort the transition transaction and back out all changes.

Tip: To make your DocApp portable and flexible at runtime, use aliases as much aspossible.

To specify new actions or modify an existing ones:

1. On the Action tab of the DLC state editor, click Add Action and select one of theseactions:• To add a value to one of the object’s repeating-value attributes, select Add to

Repeating Attribute or Set Attribute.• To add a version label to the object, select Add Version Label.• To create a link to the object in a new location, select Link to New Location.• To move the object and all its links to a new location, selectMove All links

to Location.• To delete a value from one of the object’s repeating-value attributes, select

Remove from Repeating attribute.• To delete a link to the object, select Remove Link from Existing Location.• To delete a version label from the object, select Remove Version Label.• To request renditions for the object, select Request Rendition.• To specify a value for one of the object’s single-value or repeating-value

attributes, select Set Attribute.• To specify an owner for the object, select Set Owner.• To specify a permission set for the object, select Set Permission Set.• To move content to a storage device, select Change Content Storage.These actions will be performed on the object after it enters this state.

2. Click Next.

3. If you selected, the Add Version Label or Remove Version Label options, enter theversion label that you want to add or remove as a string in the text field.

4. If you selected the Link to New Location,Move All links to Location, or RemoveLink from Existing Location action, choose one of these options:• To specify the location as a cabinet or folder, select Specify a Cabinet or Folder,

click the ellipses button, and select the cabinet or folder.• To specify the location using an alias, select Specify a Location Alias and select

an alias.

Only aliases in alias sets in the DocApp are available.



• To specify a location using a series of attribute values, select Specify a LocationExpression, enter a Docbase path in the text field that includes the current valueof one of the object’s attributes specified using the $value keyword:$value(attribute)where attribute is the name of the attribute from which the $value keywordretrieves a value. The $value keyword retrieves the current value of the object’sattribute.

The Specify a Location Expression option is only available on server 5.2.5 (orgreater).

Tip: To insert the correct $value syntax for a valid attribute, position yourcursor at the desired location in your Docbase path, select an attribute from thedrop-down list, and click Insert Attribute.

5. If you selected the Add to Repeating Attribute action, perform these tasks:

a. Select the attribute from the Repeating Attribute drop-down list.

b. To add the value to the last position in the repeating value attribute, select Addto end of list.

c. To add the value to a specific position in the repeating value attribute, select Addin position, and select a number that represents its position.

d. To specify the value to add, perform one of these tasks:• To manually enter a value, select Specify a Value and enter a value in the

text field• To specify an alias that will be resolved at runtime, select Specify an Alias,

and select an alias in the drop-down list.

Only aliases in alias sets in the DocApp are available.6. If you selected the Set Attribute action, perform these tasks:

a. Select the attribute from the Attribute to set drop-down list.

b. If the attribute is a repeating-value attribute, select a number that representsits position in the Item number field.

c. To specify the value to add, perform one of these tasks:• To manually enter a value, select Specify a Value and enter a value in the



Only aliases in alias sets in the DocApp are available.7. If you selected the Remove from Repeating Attribute action, perform these tasks:

a. Select the attribute from the Repeating Attribute drop-down list.



b. To delete all the values in the attribute, select Remove all values.

c. To delete a specific value, perform one of these tasks:• To manually enter a value, select Specify a Value and enter a value in the



Only user aliases in alias sets in the DocApp are displayed in the drop-downlist.

8. If you selected the Set Owner action, perform one of these tasks:• To specify a particular user, select Specify a Docbase User and select a user

from the drop-down list.• To specify an alias that will be resolved at runtime, select Specify a User Alias

and select an alias from the drop-down list or enter a group alias or group name.

Only aliases in alias sets in the DocApp are available.9. If you selected the Set Permission Set action, perform one of these tasks:

• To specify a particular permission set, select Specify a Permission Set and selecta user from the drop-down list.

Only system permission sets (including templates)—except for automaticallygenerated ones—are available.

• To specify an alias that will be resolved at runtime, select Specify a PermissionSet Alias and select an alias from the drop-down list.

Only aliases in alias sets in the DocApp are available.10. If you selected the Request Rendition option, select the option that corresponds to

the operating system on which you have EMC | Documentum AutoRender Proinstalled.You must have AutoRenderPro installed and correctly configured for this action tocomplete successfully.

11. If you selected the Change Content Storage action, follow the procedure inSpecifying the Change Content Storage action to move content to storage areas,page 215.

12. Click Finish.

13. To add additional actions, repeat Step 1 through Step 12.

14. To specify the order of execution of the actions, select an action, and click Up to moveit up, and click Down to move it down.Actions are executed in sequence from top to bottom.

15. To edit an action, select the action and click Edit.

16. To delete an action, select the action and click Delete.



To specify a procedure:


button next to the Docbase Pathname field to open the Select Action Proceduredialog box, and navigate to the desired procedure.


• If the General tab’s Implementation field value is Java, click the ellipsis buttonnext to theModule Name field to open the Select Action Procedure Moduledialog box, and navigate to the desired module.


3. If you do not want to specify any action procedure, click Clear.

Writing action procedures

Write the action procedure as a Docbasic procedure and specify the attribute names of thedocument’s object type as variables in the procedure.

The module must implement the com.documentum.fc.lifecycle.IDfLifecycleUserActioninterface.

The action Docbasic procedure has the following signature:Public Function Action( _ByVal SessionId as String, _ByVal ObjectId as String, _ByVal UserName as String, _ByVal TargetState as String, _ByRef ErrorString as String) As Boolean

where:



UserName User ID

TargetState The state the document is trying to enter


Note: In Docbasic code, you must specify the function declaration either on a singleline or have line continuation characters (underscores) at the ends of all lines exceptthe last (as shown).



Specifying the Change Content Storage actionto move content to storage areas

You use the Change Content Storage action to move an object’s content (that is, itsrenditions) to a specific storage area (which can be a file store or content-addressablestore).

This action is only available when logged into a Docbase 5.2.5 SP2 or greater. To use thisaction, Content Storage Services must be enabled in the Docbase.

Note: The Change Content Storage action will still be specified in a document lifecycle’sstate even when you install the document lifecycle from a Content Server 5.2.5 SP2 orgreater to a Content Server 5.2.5 SP1 or earlier. You should delete it because this actionwill not run in Content Server 5.2.5 SP1 or earlier.

To specify the Change Content Storage action that moves content to a storage area:

1. On the Action tab of the DLC state editor, click Add Action and select ChangeContent Storage.

2. In the Change Content Storage section:• To select an existing file store or content-addressable store, select Specify

Destination Filestore Name and select a file store or content-addressable storefrom the drop-down list;

• To specify an alias for a file store or content-addressable store, select Specify anAlias for Destination Filestore Name and type in an alias or select one fromthe drop-down list.

Note: At runtime, the alias is resolved from the DLC’s primary alias set or theDocbase default alias set.

3. In the Select Renditions to Move section:• To move all renditions (both primary and secondary) to the specified file store

or content-addressable store, select All Renditions;

An object’s primary rendition is the first content associated with the object; forexample, importing a Word document creates an object and the Word documentis specified as the object’s primary rendition. Thereafter, all other renditionsspecified as renditions of that object are secondary renditions.

• To move only the primary rendition to the specified file store orcontent-addressable store, select Primary rendition;

• To move only the secondary renditions to the specified file store orcontent-addressable store, select Secondary Renditions.

4. Click Finish.



Specifying or modifying a post-changeprocedure for a document lifecycle state

The post-change procedure is a procedure for the system to execute after the statetransition is complete.

When the part of a transition that occurs within the transaction is complete, the systemexecutes the post-change procedure. Failure of any part of the post-change proceduredoes not prevent the transition from succeeding.

To specify a post-change procedure:

1. Select the PostChange tab in the DLC state editor.


button next to the Docbase Pathname field to open the Select Post-ChangeProcedure dialog box, and navigate to the desired procedure.


• If the General tab’s Implementation field value is Java, click the ellipsis buttonnext to theModule Name field to open the Select Post-Change ProcedureModule dialog box, and navigate to the desired module.


See Designing the post-change procedure, page 216.

The failure of the post-change procedure does not prevent the state transition. Thesystem executes the post-change procedure after the transition transaction is complete.

Designing the post-change procedure

Write the post-change procedure as a Docbasic procedure in which the names ofattributes of the document’s object type can appear as variables.

The module must implement the com.documentum.fc.lifecycle.IDfLifecycleUserPostProcessing interface.

The post-change Docbasic procedure has the following signature:Public Function PostProc( _ByVal SessionId as String, _ByVal ObjectId as String, _ByVal UserName as String, _



ByVal TargetState as String, _ByRef ErrorString as String) As Booleanwhere:

SessionId Session ID (session established by thecalling procedure)


UserName User ID

TargetState The state the document is entering


Note: In Docbasic code the function declaration must either appear on a single line or (asshown) have continuation characters (underscores) at the ends of all lines except the last.

Specifying changes to attribute properties in adocument lifecycle state

To specify changes to the properties of an attribute, on the Attributes tab of the DLC stateeditor:

1. Select the attribute’s entry and click Change Properties.

2. In the Properties dialog box, enter a label, a help string, and a comment in theappropriate text boxes.

3. Using the check boxes, specify any combination of read-only, hidden, and not blank,and specify whether these changes should also apply to immutable objects.

4. To return an attribute’s properties to their standard values, highlight its entry andclick Revert to Type Definition.

Specifying functionalityThese topics are included:• Editing document lifecycle state functionality (overview), page 218• Modifying functionality in a document lifecycle state, page 218• Modifying inherited functionality in a document lifecycle state, page 219• Disabling inherited functionality in a document lifecycle state, page 219• Restoring Inherited Functionality in a Document Lifecycle State, page 219



• Adding functionality in a document lifecycle state, page 220• Removing added functionality in a document lifecycle state, page 220

Editing document lifecycle state functionality (overview)

Select the Functionality tab of the DLC state editor and perform these tasks:• To disable an inherited functionality class, see Disabling inherited functionality in

a document lifecycle state, page 219 .• To specify a different implementation for an inherited functionality class,

seeModifying inherited functionality in a document lifecycle state, page 219.• To restore the inherited implementation of a functionality class, see Restoring

Inherited Functionality in a Document Lifecycle State, page 219.• To add a functionality class and specify a component to implement it, see Adding

functionality in a document lifecycle state, page 220.• To remove an added functionality class, see Removing added functionality in a

document lifecycle state, page 220.• To modify the qualifications of the component that implements a functionality class,

see Modifying functionality in a document lifecycle state, page 218.

Modifying functionality in a document lifecycle state

To modify functionality in a DLC state:

1. Select the Functionality tab of the DLC state editor.

2. Select the row containing the functionality class.


4. Complete the Functionality Description dialog to modify the qualifications of theimplementing component.See Specifying component functionality in a document lifecycle state, page 220.



Modifying inherited functionality in a documentlifecycle state

To modify inherited functionality in a DLC state:



3. Select the row containing the functionality class to receive the new implementation.


5. Complete the Functionality Description dialog to attach the implementingcomponent to the functionality class.See Specifying component functionality in a document lifecycle state, page 220.

Disabling inherited functionality in a document lifecyclestate

To disable inherited functionality in a DLC state:


2. Select the row containing the functionality class to be disabled.

3. Click Remove.

Restoring Inherited Functionality in a DocumentLifecycle State

To restore inherited functionality in a DLC state:


2. Highlight the entry for the functionality class and click Restore.



Adding functionality in a document lifecycle state

To add functionality in a DLC state:



3. Click Add.

4. Complete the Functionality Description dialog to attach the implementingcomponent to the functionality class.See Specifying component functionality in a document lifecycle state, page 220.

Specifying component functionality in a document lifecycle state

You arrive at the Functionality Description dialog whenever you perform an operationthat requires attaching an implementing component to a functionality class.

To specify component functionality in a DLC state:

1. If the Name field does not have the desired value, enter it.

2. Enter a value in the Label field.

3. Specify permissions for as many groups as you wish.

a. Click the Add Group button, and select the group from the selection box.

b. Click the checkboxes in the User Capability section for the permissions you wishto assign to members of this group.

4. Use the Select Component button to choose one of the ActiveX component formsthat are part of the DocApp.

Removing added functionality in a document lifecyclestate

To remove added functionality in a DLC state:


2. Select the row containing the functionality class to be removed.



3. Click Remove.




Part 2

Installing Applications

These topics are included:• Chapter 23, Overview• Chapter 24, How to Use• Chapter 25, Installation Process• Chapter 26, Troubleshooting


Installing Applications


Chapter 23Overview

You use Application Installer to deploy DocApp archives to Docbases. A DocApp encapsulatesDocbase-related objects and processes that are specific to a business or department. You useApplication Builder to create a DocApp archive; a DocApp archive is the DocApp archive folder(with the same name as the DocApp) and the set of files that the Application Installer uses to installthe DocApp.

See these topics for more information about Application Installer:• Preparing the Target Docbase - Describes how to prepare the target Docbase so that you can

successfully install the DocApp archive. See Preparing the Target Docbase, page 229.• How to Use - Describes how to connect to a Docbase, select the DocApp archive and installer log,

and install the DocApp archive. See Chapter 24, How to Use.• Installation Process - Describes how included cabinets, folder hierarchies, and their objects are

installed to a Docbase, alias resolution, object upgrade options, and pre- and post-installationprocedures. See Chapter 25, Installation Process.

• Troubleshooting - Describes the installer log and error message syntax. See Chapter 26,Troubleshooting.

• Error Messages - Provides error message descriptions and solutions. See Chapter 29, ErrorMessages.


Overview


Chapter 24How to Use

These topics are included:• How to Use, page 227• Preparing the Target Docbase, page 229• How to use Application Installer From the Command Line, page 229

How to UseBefore installing a DocApp archive, EMC | Documentum recommends that you preparethe target Docbase first. For more information, see Preparing the Target Docbase, page229.

You can run Application Installer from the command line or the Start menu (as describedin the following instructions). For information about running Application Installerfrom the command line, see How to use Application Installer From the Command Line,page 229.

To use Application Installer (from the Start menu) to install a DocApp archive:

1. Select Start → Programs → Documentum → Application Installer.

2. Connect to the Docbase as a user with Superuser privileges by entering the Docbaseuser name, password, and domain when prompted and clicking OK.The domain is the operating system domain against which your user account isauthenticated. You might not be required to enter the domain.

Note: Your Docbase user account must have the Superuser privilege.

Superuser privilege is the highest level of user privilege in a Docbase. Users with theSuperuser privilege have a minimum access level of Read for all sysobjects. Theyalso have the ability to change the object-level permissions of any object.


How to Use

For more details about Superuser abilities and to learn how to grant superuserprivilege to a user, see the Content Server Administration Guide.

3. In the Select DocApp Archive dialog box, click Browse to find the DocApp archivefolder (which is the same name as the DocApp archive). EMC | Documentumrecommends that you do not change the name of the DocApp archive folder becauseApplication Installer uses it to install the DocApp archive and the DocApp archive foldermight be specified in paths (such as in the XML configuration file or location aliases).

4. Select the DocApp archive folder and click OK.By default, the installer log file is named archive_installerLog.html and is saved inc:\TEMP. archive is the name of the DocApp archive folder.

a. To select a different location for the installer log, click Browse (next to the Pathname field) and select a directory.

b. To specify a different filename, type a new one in the File name field.For more information about the installation log file, see Installation Log File, page246.

5. Click OK in the Select DocApp Archive dialog box.You are returned to the main window.

6. Click Start Installation.When a message box is displayed that states, "This will take a few minutes tocomplete," click Yes to continue.If a message box is displayed that states that there are connected users, click Yes tocontinue.If you specified aliases for objects in your DocApp, then the Resolve Alias dialogbox is displayed.

7. In the Resolve Alias dialog box, select the alias or folder in the Docbase under Value:

a. To find the appropriate folder, click Browse, select the folder—do notdouble-click the folder to open it—and then click Select.

b. Select the corresponding user or group from the drop-down list.

8. Click OK.Application Installer installs the DocApp archive. For information about the tasksthat Application Installer performs, see Chapter 25, Installation Process.If errors occur and the text, "Abort transaction," is displayed in the Installation Statuswindow, do not exit Application Installer. Refer to Chapter 26, Troubleshooting.

9. For new or modified object types to appear in a client application after installingthem:• For a WDK-based application, stop and restart the application server• For Desktop, choose File→Work Offline, and then choose File→Work Offline.


How to Use

Preparing the Target DocbaseMake sure the appropriate cabinets, folders, users, groups, permission sets, and localesare in the target Docbase. You must have the exact same users or users that have thesame permissions and privileges in the target Docbase as those that are in the sourceDocbase. You must have at least one locale published in the target Docbase.

See Changing the locale, page 32 for instructions on publishing locales.

The developer can use a pre-installation procedure or any combination of these tasksto create the appropriate cabinets, folders, users, groups, and permissions sets in thetarget Docbase:• Use Application Builder to include any source Docbase cabinets, folders, groups,

and permission set templates in the DocApp.

See Chapter 4, Working With Data Objects, Chapter 8, Working With Groups, andChapter 15, Working With Permission Set Templates.

• Use Application Builder to specify that at installation time the person installing theDocApp archive select target Docbase cabinets, folders, users, groups, or permissionset templates that correspond to any ones in the source Docbase.

See Setting installation options, page 36.In addition, you (as the target Docbase administrator) can use EMC | DocumentumAdministrator to create any source Docbase cabinets, folders, users, groups, andpermission sets in the target Docbase.

How to use Application Installer From theCommand Line

You use the launcher for Java applications, java, to run Application Installer from thecommand line. To run Application Installer from the command line, enter this command(all on the same line) at the command prompt:java [ -cp "dds_jar_path;dfc_jar_path;dart_jar_path;dfcbase_jar_path;dfc_config_path" ]com.documentum.ApplicationInstall.DfAppInstaller-d docbase_name -n user_name -p password-a docapp_archive [ -m domain ] [ -l install_log ] [-f property_file ]

Note:• java is part of the Sun JDK--and is not installed with Application Installer.• The paths to the dds.jar, dfc.jar, dart.jar, dfcbase.jar files are not set in the

classpath for the Sun JDK when Application Installer is installed. You must either


How to Use

manually specify the dds.jar, dfc.jar, dart.jar, and dfcbase.jar paths in theSun JDK classpath or use the standard java -cp option to specify them as shownin the aforementioned syntax.

• In the -cp option, the double quotes are required and there cannot be any spaces oneither side of the semicolons (;).

The command options enclosed within brackets ( [ ] ) are optional. The text in italicsare variables.

dds_jar_path The full path to and file name of the DDS.jar file. This file is locatedin the Shared directory of your EMC | Documentum commoninstallation directory.

dfc_jar_path The full path to and file name of the dfc.jar file. This file is locatedin the Shared directory of your EMC | Documentum commoninstallation directory.

dart_jar_path The full path to and file name of the dart.jar file. This file islocated in the Shared directory of your EMC | Documentumcommon installation directory.

dfcbase_jar_path The full path to and file name of the dfcbase.jar file. This fileis installed.

dfc_config_path The full path for the DFC Config directory. By default, this directoryis located in the EMC | Documentum user directory; for example,c:\Documentum\Config.

docbase_name The name of the Docbase to which you want to install the DocApparchive.

user_name The name of the user installing the DocApp archive. Your useraccount must have super user privileges.

password The password for the user.

docapp_archive The full path to and file name of the DocApp archive. Enclose pathsin double quotes if they contain spaces.

domain domain is the operating system domain of the user.

install_log The full path to and file name of the DocApp archive’s installationlog file. Enclose paths in double quotes if they contain spaces. Formore information about the installation log file, see Installation LogFile, page 246.

properties_file properties_file is the full path to and file name of the properties file.Enclose paths in double quotes if they contain spaces.

The EMC | Documentum installation directory is a directory of common EMC |Documentum files; it is usually the directory of the first EMC | Documentum clientproduct you install. The EMC | Documentum common installation directory is the


How to Use

value in the ProgramDirectory key in your machine’s registry. You can find your EMC| Documentum common installation directory by selecting Start → Run Program,entering regedt32.exe, and locating the value in the ProgramDirectory key forHKEY_LOCAL_MACHINE/Software/Documentum/Common.

Specifying Aliases in the Properties File

You can specify alias values in the properties file. When the developer uses ApplicationBuilder to create a DocApp archive, the properties file is automatically generated in thesame directory as the DocApp archive. The default file name is DocAppName.properties,whereDocAppName is the name of the DocApp. The text that the developer entered in thealias’s Description field (in Application Builder) is placed right before the correspondingalias value specified in the properties file; otherwise, a default description is used.

In the properties file, alias values are specified using this syntax:

AliasSet.Alias=value

AliasSet is the name of any alias set in the DocApp and Alias is analias name in the corresponding alias set. If, in Application Builder,you select an alias’ "Prompt for value at installation" option, this aliasline is automatically inserted into the properties file.

If the alias is a cabinet path or a "cabinet or folder path" alias, thenyou must specify value as a path; if the alias is a group alias, then youmust specify value as a group name; if the alias is a user alias, thenyou must specify value as a user name; if the alias is a "user or group"alias, then you must specify value as a user or group; if the alias is apermission set, then you must specify value as a permission set.


How to Use


Chapter 25Installation Process

These topics are included:• Installation Process, page 233• How Duplicate Objects Are Installed, page 236• Where Objects Are Installed, page 237• How Object Owners Are Assigned, page 239• How Permission Sets Are Assigned to Objects, page 240• How Cabinet, Folder, and XML Application Content Is Installed, page 241• How Pre- and Post-Installation Procedures Are Used, page 242

Installation ProcessTo install a DocApp archive to a target Docbase, Application Installer:

1. Runs a pre-installation procedure.

For example, it can create users and groups in the target Docbase. For moreinformation about how pre-installation procedures are used, see How Pre- andPost-Installation Procedures Are Used, page 242.

2. Installs object types.

If you specified locale-specific information for a type and that locale is not enabled(specified in the dm_docbase_config object’s dd_locales attribute for a version 4.2.xor 4.4.x Docbase and in the nls_key attribute’s values of the dm_domain object fora 5.x Docbase) on the target Docbase, then you are given a choice to continue orabort the DocApp installation. If you choose to continue, the type is installed butwithout the locale-specific information.

To install the type’s locale-specific information that was not installed, publish thelocales (identified in the DocApp archive installation log file) in the target Docbaseand reinstall the DocApp archive.


Installation Process

See the Application Builder online help for more information about publishinglocales.

Note: Object types are not installed in a transaction and are not rolled back if the restof the DocApp archive installation aborts.

3. If, in Application Builder, the developer checked the "Prompt for value atinstallation" option for aliases, then the Resolve Alias dialog box is displayed foreach alias. If the developer checked the "Create path if it does not exist" for a locationalias, then you are not prompted to resolve the alias and the specified cabinet orfolder path is created if it does not exist in the target Docbase.

Selecting a value that includes multi-byte characters is not supported. If you needto use multi-byte characters in an alias value, enter the alias value into the DAIproperties file and run DAI again.

Note: If values are specified for these aliases in the properties file, ApplicationInstaller uses these alias values and you will not be prompted to resolve them.

4. In the Resolve Alias dialog box, select one of these values in the Value field:

• Folder, cabinet, or permission set: Click Browse, select the folder, cabinet, orpermission set—do not double-click the folder or cabinet to open it—andthen click Select.

• User or group: Select the appropriate user or group from the drop-down list.

Note: The values that you want to assign to these aliases must alreadyexist in the target Docbase. Because a pre-installation procedure executesbefore aliases are resolved, a pre-installation procedure can create the values(cabinets, folders, users, groups, and permission sets) that you want toassign to aliases.

5. Click OK.

6. Applies the DocApp’s objects to the target Docbase in a transaction.

The objects are installed:

• To their default locations or their location aliases. For more information aboutwhere objects are installed, see Where Objects Are Installed, page 237.

• With the installing user as their owner (the default) or their owner aliases. Formore information about how object owners are assigned, see How ObjectOwners Are Assigned, page 239.

• With an associated permission set that depends on dm_server_config object’sdefault_acl attribute (the default) or their permission set aliases. For moreinformation about how object permission sets are assigned, see How PermissionSets Are Assigned to Objects, page 240.



If duplicate objects exist in the target Docbase, the duplicate objects are overwritten,not overwritten, or versioned according to their upgrade options; otherwise, objectsare installed as version 1.0 and made the current version. For more informationabout duplicate objects, see How Duplicate Objects Are Installed, page 236.

If the objects are cabinets or folders, their content and subfolders are installedaccording to their content transfer options.

Note:

• To preserve backward compatibility, even though objects are deleted from thesource DocApp, those objects are not deleted from the target DocApp.

• If you are installing a DocApp archive created with DAB 5.3, then the installationoptions of Java libraries included in any modules will be changed to overwrite inthe target Docbase when the module is newer.

In DAB 5.3 SP1, you can now install a Java library separately from modules byinserting the Java library explicitly (from the Insert menu) and specifying theJava library’s installation options, which will override those of any module inwhich the Java library is included.

7. Installs the DocApp’s objects by committing the transaction ("Commit transaction" isdisplayed in the Installation Status window).

If an error occurs, Application Installer aborts the installation and all of the changesin the transaction are rolled back—the next step is not executed.

8. Runs a post-installation procedure.

For example, this procedure can assign a newly installed permission set to anobject or a new user as an owner of an object. For more information about howpost-installation procedures are used, see How Pre- and Post-Installation ProceduresAre Used, page 242.

Application Installer records all its actions and all the objects that were installedin the installation log file, which is very useful in troubleshooting any errors. Forinformation about troubleshooting, see Chapter 26, Troubleshooting.

The application object (dm_application) is installed to the default location,Applications/DocApp_name folder in the System cabinet; DocApp_name is the name of theDocApp archive folder. If a DocApp with the same name as the DocApp archive exists inthe target Docbase, then the new version number is the version of the existing DocAppincremented by .1; otherwise, the DocApp archive is installed as version 1.0.

Note:• DocApp archives do not have a version number.• The developer uses Application Builder to set object upgrade options, location

aliases, owner aliases, permission set aliases, cabinet and folder content transferoptions, or pre- and post-installation procedures.



To learn how to use these features, see Setting installation options, page 36.• When you install a DocApp archive that was created from a 5.2 or greater Docbase

to a pre-5.2 Docbase, locale-specific object type functionality labels are not loadedinto the data dictionary. Locale-specific object type functionality labels are onlyavailable with version 5.2 or greater.

How Duplicate Objects Are InstalledTo learn how to set these options, see Setting installation options, page 36.

Upgrade Options

Select one of these options to determine the action that the Application Installer takeswhen a duplicate object already exists in the target Docbase.

If an object that can be versioned does not already exist in the target Docbase, the object isinstalled as version 1.0 and is made the current version (if the object cannot be versioned,it is installed without a version number). XML applications, cabinets, and folders are notoverwritten or versioned; instead, the content in the XML application folder, cabinets,and folders is overwritten or versioned.

Note: As of 5.3 SP1, Java libraries do not have their own upgrade options. Instead,they use these upgrade options.

• Overwrite in the target Docbase - (Default for non-sysobjects; that is, object types,permission set templates, alias sets, groups, and roles) The object in the Docbase isreplaced by the new object and all attribute values are overwritten with the newobject’s attribute values even when they are the same. The new object is made thecurrent version.

• Version in the target Docbase - (Default for sysobjects) The new object’s version isincremented by .1 and is made the current version.

Use of this option is limited to sysobjects; however, even though methods aresubtypes of sysobject, form templates (dm_xfm_form) are subtypes of dm_document,and Java libraries (dmc_java_library) are subtypes of sysobject, methods, forms,and Java libraries cannot use this option.

• Overwrite if newer - (Default for modules) If the module in the DocApp is newerthan the one in the target Docbase, then the module (including all the objects in itsfolder) in the Docbase is replaced by the new module—this option only applies tomodules. The new module is made the current version. The module’s objects thatwere originally in the target Docbase but are not in the new module will be deleted.



Module objects that were in the target Docbase and also in the new module areoverwritten.

• Do not overwrite; leave target object(s) alone - The object in the Docbase is notoverwritten or versioned, and remains the current version. The new object is notinstalled.


The following table shows the criteria that the Application Installer uses to determinewhen an object is a duplicate:

If object is Then criteria for duplicate is

object typealias setmethodgrouproleform templateformatJava librarymodulerelation type

Same name anywhere in Docbase

document lifecycleworkflow templatejobprocedurecomponentXML application

Same name and location in Docbase

data object Same name, location, language_code attribute, andobject type in Docbase

permission set template Same name and owner in Docbase

Where Objects Are InstalledTo learn how to set these aliases, see Setting installation options, page 36.



Location Alias

Select a location alias for a sysobject. Only the cabinet or folder aliases that have beeninserted into the default alias set are displayed in the drop-down listbox. You can alsoclick New to create a new cabinet or folder alias in the default alias set and specify it asthe owner alias for the sysobject.

Since object types, permission set templates, alias sets, and groups are not sysobjects,you cannot select location aliases for them. Also, you cannot select a location alias fora method or cabinet. Because a cabinet always appears at the top level of a Docbasehierarchy, there is no need to specify a location alias for it.



Default Installation Locations

This table describes the default installation location for each DocApp part in the targetDocbase.

Note: N/A (not applicable) means that the DocApp part is not installed into the cabinetor folder hierarchy.


application object(dm_application)


Object types(dm_type)

N/A

Document lifecycles(dm_policy)


Workflow templates(dm_workflow)

Workflow activities(dm_activity)


Permission set templates(dm_ACL)

N/A




Alias sets(dm_alias_set)

N/A

Jobs(dm_job)


Form templates(dm_xfm_form)

Forms folder in the System cabinet

Forms(dm_component)

Qualified component(dm_qual_comp)


Procedures(dm_procedure)


Methods(dm_method)

Methods folder in the System cabinet

Java libraries(dmc_java_library)

/System/Java Libraries

Modules(dmc_module)

/System/Modules/module_type. module_type is the type ofmodule (for example, TBO, SBO)

Groups (and Roles)(dm_group)

N/A

Formats(dm_format)

N/A

Relation types(dm_relation_type)

N/A

XML Applications Applications/DocApp_name folder in the System cabinet;DocApp_name is the name of the DocApp archive folder.

Data objects Applications/DocApp_name folder in the System cabinet;DocApp_name is the name of the DocApp archive folder.

How Object Owners Are AssignedTo learn how to set these aliases, see Setting installation options, page 36.



Owner Alias

Select an owner alias for the sysobject. Only the “dm_dbo” user, "user" and "user orgroup" aliases that have been inserted into the default alias set are displayed in thedrop-down listbox. You can also click New to create a new user alias in the default aliasset and specify it as the owner alias for the sysobject.

The default for sysobjects is the user who installs the DocApp.

Since object types, permission set templates, alias sets, and groups are not sysobjects,you cannot select owner aliases for them.



How Permission Sets Are Assigned to ObjectsTo learn how to set these aliases, see Setting installation options, page 36.

Permission Set Alias

Select a permission set alias for a sysobject. Only the permission set aliases that havebeen inserted into the default alias set are displayed in the drop-down listbox. You canalso click New to create a new permission set alias in the default alias set and specify itas the owner alias for the sysobject.

If the developer does not select a permission set alias for a sysobject, then the defaultpermission set is the permission set of:• The user who installs the DocApp if the dm_server_config object’s default_acl

attribute is set to 3. This setting is the default for any Content Server installation.• The folder to which the sysobject is installed if the dm_server_config object’s

default_acl attribute is set to 1.• The sysobject’s type if the dm_server_config object’s default_acl attribute is set to 2.No permission set is associated with the sysobject if the dm_server_config object’sdefault_acl is set to 4.

For more information about the default_acl attribute, see the Content Server AdministrationGuide.



Since object types, workflow templates, permission set templates, alias sets, and groupsare not sysobjects, the developer cannot select permission set aliases for them.



How Cabinet, Folder, and XML ApplicationContent Is Installed

In Application Builder, the developer sets content transfer options for cabinets andfolders.

To learn how to set these options, see Setting installation options, page 36.

Data Object Transfer

Select one of these options to determine the action that the Application Installer takeswhen it installs XML applications, cabinets, and folders:• All content - (Default) The specified XML application, cabinet, or folder, subfolders,

and objects in the cabinet and these folders are installed.• Object only - Only the specified XML application folder, cabinet, or folder is installed.• Hierarchical structure - The specified XML application folder and its subfolders, or

cabinet or folder and subfolders are installed; no objects are installed.• Top-level content - Only the specified XML application folder or folder and objects

in that folder are installed.The type of any object to be installed can only be dm_sysobject or any of itssubtypes—except for dm_process, dm_component, dm_qual_comp, dm_activity,dm_job, dm_method, and dm_policy. If you created a custom type (that is a subtypeof dm_sysobject), you must include it in the DocApp for any object of the custom typeto be included in the DocApp.

The XML application, cabinet, or folder hierarchy always appears in the target Docbasewith the same names it has when you insert it into the DocApp. If the target Docbasealready has a cabinet of the same name or the specified location already contains a folderof the same name as that of the top of the folder hierarchy, the Application Installercombines the contents of the two similarly named items, and does so recursivelythroughout the hierarchy.




Note: These are some important considerations for objects:• Renditions Included With DocApp, page 242• Cannot Insert Entire Virtual Document, page 242• Although Java libraries are subtypes of dm_folder, the Data Object Transfer option

for Java libraries is always All content.





How Pre- and Post-Installation Procedures AreUsed

To learn how to create these procedures, see Creating pre- and post-installationprocedures, page 162.

Procedures

Select a pre-installation procedure (and its version) that you want to execute before theApplication Installer begins installation and a post-installation procedure that you wantto execute after the installation completes. Only procedures that have been inserted intothe DocApp are displayed in the drop-down listboxes.



If you choose CURRENT in the version field, then the current Docbase version—notnecessarily the version of the procedure in the DocApp—of the procedure is archived.

If the pre-installation procedure fails, then Application Installer aborts the installation ofthe DocApp archive. If the DocApp archive installation fails, then the post-installationprocedure is not executed. If the post-installation procedure fails, then only thatprocedure fails (since the installation of the DocApp archive has already completed).

For more information about pre- and post-installation procedures, see Creating pre-and post-installation procedures, page 162.





Chapter 26Troubleshooting

These topics are included:• Solving errors that occur while running Application Installer, page 245• Installation Log File, page 246

Solving errors that occur while runningApplication Installer

To solve errors that occur while using Application Installer, look at the InstallationStatus window or the installation log file.

Note: If you did not create the DocApp, see the developer of the DocApp to resolvethese errors.

To troubleshoot errors:

1. If you remember the location of the installation log file (its default location isc:\temp), navigate to it and open it; otherwise, find the location and name of theinstallation log by scrolling to the top in the Installation Statuswindow. The line thatstarts with the text, "<P>Log filename," lists the installer log’s file name and location.

2. Find the installation log file and open it in your browser.For more information about the installation log file, see Installation Log File, page246.

3. Find the error message or chain of error messages that follows this text in red:"ERROR: Installation cannot proceed."

4. Fix the error in the DocApp described in the error message or the last error in thechain of error messages.

Usually, there is a chain of error messages and the last error message is the directresult of the root error—each of the other error messages results from the previous


Troubleshooting

error. For example, in this error message, the error message that is the direct result ofthe root error is "No value is found in alias set (ProductBase_Source421) for resolvingalias%reviewers_server."Installing dm_alias_set: ProductBase_Source421ERROR: Installation cannot proceed.DfException@36f:: THREAD: main; MSG: [DM_ACL_F_REFRESH_SELECT_INSTANCE]fatal: "Failure retrieving instances of template ACL. Select statement isselect object_name from dm_acl_s where owner_name = ’ProductBase’ and acl_class = 2and object_name like ’dm__________________80000d00’. DB error is -- No error."[DM_ACL_E_CANT_CREATE_INSTANCE]error: "Cannot create an instance of template ACLReviewer_serv_user based on alias set ProductBase_Source421."[DM_POLICY_E_AS_NO_ALIAS_SET]error: "No value is found in alias set(ProductBase_Source421) for resolving alias %reviewers_server.";ERRORCODE: 100; NEXT: null

Errors are generated by the Application Installer, DFC, and server API. For details aboutApplication Installer errors, see Chapter 29, Error Messages. DFC error messages arecaught in a DfException class, which is identified by the term, DfException, in theinstallation log file; server API errors thrown by the Content Server are also caughtby DFC and rethrown in a DfException class. The server API error message usuallydescribes the error. For DFC error messages, refer to the DFException class descriptionin the DFC javadocs.

Installation Log FileWhen Application Installer installs a DocApp archive, it writes a record of its actions tothe installation log file, including errors, which can be used to troubleshoot problems.The installation log file lists environment information, such as user name and targetDocbase, the objects to install, error messages, and whether the installation wassuccessful. The installation log file, an HTML file, contains the same information asthe Installation Status window.

By default, the installation log file is named archive_installerLog.html and is savedin c:\TEMP. archive is the name of the DocApp archive folder.


Part 3

Tutorials

These topics are included:• Chapter 27, Basic Tutorial: Creating DocApps• Chapter 28, Intermediate Tutorial: Creating DocApps


Tutorials


Chapter 27Basic Tutorial: Creating DocApps

This chapter is a tutorial that shows you, step-by-step, how to create and deploy a sample DocAppcalled ProductBase. It covers the basic tasks needed to create a DocApp that allows end users toapprove and route documents.

These topics are included:• Overview, page 249• Application Builder user interface, page 251• Design of the ProductBase DocApp, page 252• Module 1: Designing object types and displaying attributes to users, page 254• Module 2: Designing a user and security environment, page 261• Module 3: Designing document lifecycles, page 269• Module 4: Designing workflows, page 274• Module 5: Configuring Installation Options and Deploying DocApps to Other Docbases, page 279

OverviewThis chapter contains modules that enable you to create object types, alias sets,permission set templates, document lifecycle, workflows, and DocApp archives as wellas add existing groups, folders, and documents—and deploy your DocApp to otherDocbases:

• Module 1: Designing object types and displaying attributes to users, page 254• Module 2: Designing a user and security environment, page 261• Module 3: Designing document lifecycles, page 269• Module 4: Designing workflows, page 274• Module 5: Configuring Installation Options and Deploying DocApps to Other

Docbases, page 279


Basic Tutorial: Creating DocApps

Prerequisites

To complete the tutorial, you should understand:

• The EMC | Documentum system• The prior chapters of this manual.

Software requirements

EMC | Documentum recommends that you install this software on your computer tocomplete this tutorial. If you are using an earlier version of either Desktop (formerlyknown as Desktop Client), Application Builder (formerly known as Developer Studio),or Application Installer (formerly known as DocApp Installer), some features mightnot be available.• Desktop 5.2.5 or greater or Webtop 5.2.5 or greater• Application Builder 5.2.5 or greater• Application Installer 5.2.5 or greater

Note: If you are using an earlier version of Desktop, Webtop, Application Builder, orApplication Installer, see your release notes for information about the versions thatcan be installed on the same workstation.

You should also have access to EMC | Documentum Administrator 5.2.x and a ContentServer 5.2.5 or greater; otherwise, some features might not be available. You use EMC |Documentum Administrator to delete objects from your Docbase if you accidentally addthem using Application Builder.

Source les

Source files include a DocApp archive, DAB525Tutorial, which contains preconfiguredobjects that you will need to successfully complete the basic and intermediate as wellas final versions of the objects.

The source files are in a zip file that you can download from the EMC | Documentumdownload site.



Application Builder user interfaceApplication Builder uses a standard Windows interface as shown in Figure 27–1, page251. The left pane, called the tree pane, displays the objects; the right pane, called theresults pane, is a container for dialog boxes and windows.

Figure 27-1. EMC | Documentum Application Builder

Note: Figure 27–1, page 251 shows the DAB525Tutorial DocApp.

In addition to the standard Windows menu functions, these Application Builder-specificfunctions are available from the menus:• File – Connect and disconnect from Docbases; create new DocApps; open, close, and

save DocApps; view and edit objects.• Edit – Cut, copy, and paste objects; delete objects from the Docbase.• View – List All Attributes, which lists all attributes including inherited attributes;

Locale, which displays the DocApp’s current locale (as well as available locales)in which some attribute values will be saved; and Properties, which lists theapplication-specific properties of an object, such as location.

• Insert – Create objects in the DocApp (you can also insert existing objects into theDocApp from the Docbase).



• DocApp – Check in, check out, cancel checkouts of DocApps and objects; view andset target Docbase installation options for objects; remove objects from the DocAppand create DocApp archives.

• Tools – Setting preferences and validating XML applications.• Help – Application Builder online Help, which includes Application Builder task

help, Document Lifecycle Editor task help, Docbasic reference, and DFC reference..You use Business Process Manager, not Application Builder, to create business processesand Workflow Manager to create workflows. For a description of Workflow Manager,see the Workflow Manager online help and the Content Server Fundamentals. For adescription of Business Process Manager, see the Business Process Manager online helpand the Content Server Fundamentals.

Design of the ProductBase DocAppThe purpose of the sample application, ProductBase, is to automate the routing ofsales information.

The ProductBase DocApp includes:• Two new object types (hereafter, called types) that represent sales information, which

can be distributed as sales kits, brochures, Web site pages, or white papers. Salesinformation can apply to three product lines and each product line has its own setof products as follows.

Table 27-1. Products in each product line

Product line Products

StarFire StarBurst, StarPeak, StarMaster

Lightning Thunder, Rumble, Millennium

Comstar 1000, 1000i, 2000, 2000si

• An alias set that organizes aliases for groups (for example, authors and reviewers),cabinets, folders, and permission set templates.

• Eleven permission set templates (also called Access Control List (ACL) templates)that assign permissions to aliases and groups to help to make the ProductBaseDocApp portable between Docbases.

• Five groups for the different kinds of users.• A parent folder with six subfolders that correspond to the document lifecycle states.• One document that is an ASCII text template for a sales_info document.



• A document lifecycle (hereafter referred to as a lifecycle) that defines states for theauthoring, reviewing, approval, publishing, retirement, and suspension of salesdocuments.

• A workflow that defines the users and groups who will perform actions, such asreviewing and approving, on the sales documents and route them.

Using the ProductBase DocApp

Users log in to the Docbase through Desktop or Webtop and create or check out adocument of the sales_info type. When an author creates a new document, the authorapplies the lifecycle to it, promotes it to the InReview state, and inserts it into theReviewWkflow workflow to process it through the review process. The document isrouted to the appropriate people as identified by the workflow activities. The marketingmanager checks it in and it is automatically promoted to the Approved state. When themarketing manager thinks that it is ready for everyone to view it, the marketing managerpromotes it to the Published state.

If the document becomes inaccurate or product information suddenly changes, themarketing manager can suspend it to the Suspended state. The marketing managercan check out and check in the document to move it back to the base state, Authoring,to start the review and approval process.

If the product that the document describes becomes obsolete, the marketing managercan promote it to the Retired state. If the product is revived, the marketing managercan check out and check in the document to move it back to the base state, Authoring,to start the review and approval process.

Installing the DAB525Tutorial DocApp

• Estimated Time: 30 minutes• Goals: Install DAB525Tutorial DocApp Archive.• Tasks: Run Application Installer to install DAB525Tutorial DocApp Archive.Before starting the tutorials, install the DAB525Tutorial DocApp archive. TheDAB525Tutorial DocApp archive is located in a zip file (if you downloaded theApplication Builder tutorial zip file from the EMC | Documentum download site).

Follow the instructions in the To install the ProductBase archive into a target Docbase:,page 282 procedure to start Application Installer and navigate to the DAB525Tutorialfolder, choose the DAB525Tutorial archive, and install it in your Docbase.

Note:



• Because this tutorial includes new features that are only available on Content Server5.x, you can only install the DocApp archive on Content Server 5.x.

Module 1: Designing object types anddisplaying attributes to users

• Estimated Time: 45 minutes• Goals:

— Design attributes for the sales_info type.

— Display sales_info attributes in the Properties dialog box of Webtop or Desktop.• Tasks:

— Create a new DocApp named ProductBase.

— Add the sales_info type to the ProductBase DocApp and create a newproduct_name attribute.

— Create a new tab to display the product_line and product_name attributes.You design a new type to identify characteristics of specific documents as well as toallow specific lifecycles and workflows to manage them. In this module, you will createa new type, sales_info. You create attributes for the sales_info type; the attributes aredisplayed in a new Properties tab in Desktop and Webtop.

Tip: EMC | Documentum recommends that you create a subtype of an EMC |Documentum type, such as dm_document, for your company, and then create additionalsubtypes from your company’s subtype. You should select a supertype that best matchesthe attributes that you want to include in your company’s type, which inherits all theattributes from its supertype. Without affecting the EMC | Documentum type, you cancustomize your company’s subtype with any attributes (as well as override inheritedattributes) that are applicable to all types within your company.

Note: When the instructions do not ask you to specify a value for a field or whether toselect an option, accept the default.

Creating a new DocApp

You must create a DocApp that packages your type. When you create a DocApp, it iscreated in the Docbase. The user account you are using must have super user privilegesto create a DocApp. If your user account does not have super user specified for thePrivileges field, follow these steps to change it:



To change the user account’s privileges to super user:

1. Start EMC | Documentum Administrator use its URL to connect to it with yourWeb browser.

2. Select a Docbase from the Docbase listbox.If you do not see your Docbase, you might need to change the DocBroker host. Youcan change the DocBroker by clickingMore Options.

3. Enter your user name and password, and then click Connect.

Note: Your user account must have Administrator privileges for the Docbase.

4. Click User Management in the left pane and click Users in the right pane.

5. Type your user name in the User Name field, press the Enter key, and click theinformation icon (a blue disk with the letter i).

6. Click the drop-down listbox next to the Privileges field and select super user.

7. Click OK.

To create a new DocApp:

1. Start Application Builder by choosing Start→Documentum→Application Builder.You are prompted to connect to a Docbase.

2. Change the Docbase if desired, type a user name, password, and domain (ifrequired), and then click Connect.

Note: You must have super user privileges to create a new DocApp.

You are prompted to create a new DocApp, open an existing one from the Docbase,or open an existing local one on your workstation.

3. Click Create new DocApp.You are prompted to type a name for your DocApp.

4. In the Object Name field, type ProductBase and click Create.The ProductBase DocApp is created in a new folder called ProductBase in theDocbase under /System/Applications, and is automatically checked out.

Designing a new type

You design a new type, sales_info, for your ProductBase DocApp. The sales_info typedescribes the characteristics of sales_info documents. The sales_info type has twoattributes, product_line, which represents your fictional company’s product lines, anddistribution, which represents the different distribution media for sales information. Tomake the sales_info type functional, you will add a third attribute, product_name, that



represents all of the company’s products. The mycompany_document is the globaldm_document type for your entire company.

The mycompany_document and sales_info types were already installed with theDAB525Tutorial DocApp.

To design the sales_info type’s product_name attribute:

1. Choose Insert→Object fromDocbase→Object Type and select the sales_info type.The sales_info type is inserted under Object Types in the left pane.

2. Select sales_info and choose Insert → Attribute.The attribute1 attribute is inserted under sales_info.

3. Double-click attribute1.The Attribute editor is displayed.

4. In the Attribute editor’s General and Advanced tabs, type or select these values,and select these options:

Tip:• Attribute names must be unique among all attributes of a type—including

inherited attributes. To display inherited attributes, choose View → List AllAttributes.

• Attribute names cannot begin with dm_ , i_ , r_ , or a numeral• Attribute names must be all lowercase.

Table 27-2. Values for product_name attribute

Tab Field/Option Value Comment

General Attribute Name product_name

Label Product Name This text isdisplayed in theAttribute editordialog box for thedocument.

Data type String

Attribute can haveNULL value

Selected Check this option.

Tip: If you want to display attributes on a Properties dialog box tab for Desktop4.3.x (and previous versions) as well, enter the tab name in the Attribute Categoryfield on the Advanced tab.



5. To add the default for value assistance, click Add Default in the Attribute editor’sValue Assistance tab.To add conditional value assistance, you must create the default value assistance first.

Tip: You must check in the type before you reference any new attributes inconditional value assistance from another attribute. In the next series of steps, youreference the product_line attribute from the product_name attribute.

6. Select Fixed List and check List is complete.Selecting the Fixed List option allows you to enter a set of values in the text box(which follows the statement, Please enter individual values on a separate line);selecting Query allows you to enter a DQL query. For more information aboutentering DQL queries for value assistance, see Specifying a DQL query for defaultvalue assistance, page 302.Selecting the List is complete option prevents the end user from creating new valuesin the product_line attribute’s field in the Desktop Properties dialog box; otherwise,the end user can enter new values.

7. Enter:1000

1000i20002000Si(each value on a separate line), and click OK.The values you specify for default value assistance are displayed in the product_nameattribute’s field in the Desktop Properties dialog box when you first open the dialogbox or have not selected a value in the product_name attribute field.

8. To add conditional value assistance, in the Attribute editor’s Value Assistance tab,click Add Conditional.The Value Assistance Clause dialog box is displayed.In this dialog box you specify the conditional value assistance for the product_nameattribute. Conditional value assistance means that the values you specified for valueassistance are displayed when a specific condition is satisfied. For the product_nameattribute, you enter three conditions that specify when the end user selects a valuefor the product_line attribute, the corresponding product_name attribute values(listed in the value assistance text box) are displayed.

9. In the Value Assistance Clause dialog box, type these values or select these options:



Table 27-3. First value assistance clause for product_name attribute

Field/Option Value Comment

Condition for thefollowing ValueAssistance to be used

product_line ="StarFire"

This line is equivalent tothe If statement, whichis displayed in the ValueAssistance tab.

Value Assistance StarBurst StarPeakStarMaster

This line is equivalent tothe Then statement, whichis displayed in the ValueAssistance tab.

Fixed List Selected Select this option.

List is complete Selected Check this option.

10. Click Check Syntax.If an error is displayed stating that the constraint expression is invalid, check inthe object, close the DocApp, wait about five minutes for the type cache to refresh,reopen the DocApp, check out the type, and click Check Syntax again.

11. To add another statement for conditional value assistance, select the If-Then linesand click Add Conditional.

12. In the Value Assistance Clause dialog box, type these values or select these options:

Table 27-4. Second conditional value assistance clause for product_name attribute



product_line ="Lightning"

This line is equivalent tothe Else If statement, whichis displayed in the ValueAssistance tab.

Value Assistance Thunder RumbleMillennium

This line is equivalent tothe Then statement, whichis displayed in the ValueAssistance tab.



13. In the Value Assistance Clause dialog box, add the third statement for conditionalvalue assistance as previously, type these values, and select these options:



Table 27-5. Third conditional value assistance clause for product_name attribute



product_line ="ComStar"

This line is equivalent tothe Else If statement, whichis displayed in the ValueAssistance tab.

Value Assistance 1000 1000i 2000 2000Si This line is equivalent tothe Then statement, whichis displayed in the ValueAssistance tab.



The Value Assistance tab in the Properties dialog box should look as follows:

14. Check in the sales_info type by selecting it and choosing DocApp → Check InObject(s).

15. Check in the DocApp by choosing DocApp → Check In DocApp.Make sure to check it in as the same version (1.0). You only need to check a DocAppin as a different version if you think you might need to use the old version.



To create a new tab on which to display the product_line and product_name attributes:

1. Double-click the sales_info type and click Edit.

2. Click the Display Configuration tab.

3. Click Add and type Product Info in the Display Configuration Name field, checkthe Add to all applications checkbox, and click OK.Product Info will be the name of the tab. Checking the Add to all applicationscheckbox makes this tab (and any subsequent updates to it) available in allapplications.

4. Make sure that Product Info is selected and click Edit.

5. To make any updates to the Product Info tab available in all applications. click Yes.

6. To display only custom attributes, check the Show custom attributes only checkbox.

7. To add attributes to the tab, select product_line and product_name in the Availableattributes textbox and click Add.

8. Click OK.

Summary

You have created a new DocApp, ProductBase, added the sales_info type, and created anew product_name attribute for your sales information documents. You have enabledconditional value assistance to establish the product choices for each product line.You have created a new tab, Product Info, on which to display the product_line andproduct_name attributes.

Now you can create a new document (with Notepad, for example), import it into yourDocbase, create a new object of sales_info type for it, and assign properties to it basedon the attributes of sales_info.

Testing your DocApp

After creating your new type, test it to see if you have implemented it correctly. Log onto your Docbase from Desktop and create a new sales_info object.

Log on to your Docbase:

1. Open Windows Explorer and click on the plus sign next to the EMC | DocumentumDesktop icon.

2. Click the plus sign next to the Docbases icon.



3. Click your Docbase, type your user name and password when prompted, and thenclick Log On.

4. Open My Cabinet.

Create a new sales_info object and document:

1. In My Cabinet, right-click anywhere in the right pane and chooseNew→Document→ Other from the pop-up menu.

2. In the New dialog box, type a name for the document in the Name field.

3. Select sales_info for its type in the Type field.Keep the format as ASCII Text.

Note: If the sales_info type does not appear, you might need to restart the Desktopand Windows Explorer processes.

a. Use Task Manager to end the dcathmgr.exe, dcevtsrv.exe, and explorer.exeprocesses.

b. Choose File→ New Task (Run), type explorer in the Open field, and click OK.Alternatively, you can reboot your workstation.

4. To create a new document, click New and type some text into your new document.

5. Save your changes and quit the text editor.

6. Check in your document by choosing File→ Check In and clicking Check In.

7. To display the Properties dialog box, select your new document and choose File→ Properties.

8. Select a distribution media on the Distribution Media Info tab.

9. Select a product line and product name in the Product Info tab.

10. Test the conditional value assistance.For example, if you select StarFire as the product line, then StarBurst, StarPeak,StarMaster are the products available; if you select ComStar as the product line, then1000, 1000i, 2000, 2000Si are the products available.If you successfully performed these steps, you correctly created the sales_info type.

Module 2: Designing a user and securityenvironment




— Design a new Author user.

— Design permissions and aliases.• Tasks:

— Create a new Author user and add it to the authors group.

— Design an Authoring_folder permission set template for the Authoring folder.

— Add the Authoring_location alias set to the ProductBase alias set.You create alias sets to encapsulate aliases for groups and folders. You use these aliases tomake your DocApp portable to other Docbases. When the ProductBase DocApp archiveis installed into a Docbase, you are prompted to select existing groups and folders forthe aliases. You create permission set templates (also called ACLs) that assign permissionsto the users and folders.

You usually want to have different folders that correspond to each state of a lifecycle(which you will create in Module 3). Therefore, each folder has different permissions forthe users who access the documents. In this module, you will create a default permissionset template for the Authoring folder. By default, a user’s default permission set templateis assigned to any new documents that the user creates. A permission set template that isspecified for a folder regulates operations on objects within the folder, such as creating,moving, deleting, and copying objects. If you are reusing a DocApp and deploying itto another Docbase that services a different set of users in your company, permissionset templates are of great utility.

Since permission set templates contain aliases and alias sets, you must create alias setsbefore creating permission set templates.


Creating users

Create NT users using the User Manager for Domains tool. EMC | Documentumrecommends that create these new users even if you already have a set of Windows NTusers that you want to use for this tutorial.

Note: If you are using a Docbase that is installed on a UNIX computer, you might needto contact your system administrator to create new users.

To create Windows NT users:

1. Make sure that your user account (usually Administrator) has permissions to addusers and groups to your workstation’s domain.



2. Choose Start → Programs → Administrative Tools (Common) → User Managerfor Domains.

3. If you are not logged in to your workstation’s domain, select it by choosing User →Select Domain and entering your workstation as the domain.

4. Choose User → New User.

5. Create the Author, Marketing_Manager, Reviewer, and Viewer users with theirrespective user names as their passwords—except for the Marketing_Manager user,use “marketing” as its password.

6. For each user, uncheckUser Must Change Password at Next Logon, check PasswordNever Expires, and click Add or OK.

Creating users and modifying groups in the Docbase

You create a Docbase user andmodify a group using EMC |DocumentumAdministrator.Users in the Docbase correspond to the Windows NT users. You add the Docbase usersto the groups, which you add to the ACLs. By structuring your group membership inthis way, when your users change, you need only change membership in the groupsand not the ACLs.

Note: The other required users and all groups were created when the DAB525TutorialDocApp was installed.

To create the Author Docbase user:

1. Start EMC | Documentum Administrator use its URL to connect to it with yourWeb browser.

2. Select a Docbase from the Docbase listbox.If you do not see your Docbase, you might need to change the DocBroker host. Youcan change the DocBroker by clickingMore Options.

3. Enter your user name and password, and then click Connect.

Note: Your user account must have Administrator privileges for the Docbase.

4. In User Management in the right pane, click Create a new user.

5. Enter or select these values for the Author user:



Table 27-6. Attribute values for Author user

Field Value Comments

Name Author

User OS Name Author

Windows Domain Windows domain onwhichto authenticate users

You must enter a Windowsdomain against which toauthenticate users. This isthe same domain as the onewhere you created yourWindows NT users. It iseither a domain on yourcompany’s network or yourcomputer’s name.

E-mail Address Your email account When the workflowactivity is executed anemail with the task for youto perform will be sent toyour email account.

Privileges create group and cabinet

Default Group authors

Client Capability Contributor

Default ACL Author_user Specifies the defaultpermission set template toapply to objects that theuser creates.

Alias Set ProductBase An alias set must bespecified to resolve anyaliases in the default ACL.

6. Click OK.

To modify the authors Docbase group:

1. Click the plus sign next to User Management in the left pane.

2. Click Groups in the left pane.

3. Click authors, and choose File → Add Member(s).

4. To add the Author user to the group, check the Author user name, and click Add.

5. Click OK.



Adding aliases to alias sets

Add the Authoring_location alias to the ProductBase alias set that corresponds to theDocbase ProductBase\Authoring folder.

Note: The other required aliases were created when the DAB525Tutorial DocApp wasinstalled.

To add the Authoring_location alias to an alias set:

1. In Application Builder, open the properties dialog box for the alias set ProductBaseby double-clicking it and clicking Edit in the View/Edit dialog box.

2. In the properties dialog box, click Add.The Alias Object dialog box is displayed.

3. Select these values for the corresponding fields.• Name: Authoring_location• Type: Cabinet or Folder Path• Value: DAB525Tutorial/ProductBase/Authoring

Tip: Always use a single, contiguous string (without spaces) as an alias name;otherwise, you cannot specify it in Docbasic code.

The ProductBase alias set should look as follows:

4. Close the ProductBase alias set window by clicking on the close box and check inyour alias set by choosing DocApp → Check In Objects.



Creating permission set templates

Now that you have created aliases, you specify them in new permission set templates.Create a permission set template that corresponds to the Authoring folder. You createthe lifecycle in Module 3: Designing document lifecycles, page 269.

Note: The other required permission set templates were created when theDAB525Tutorial DocApp was installed.

To create the Authoring_folder permission set templates:

1. Choose Insert → Permission Set Template.

2. To display the properties of Set1, double-click it.The properties dialog box is displayed in the right pane.

3. Type Authoring_folder in the Permission Set Name field.

4. To display the aliases you created, select Show Alias-Sets in Application.The aliases are displayed in the left column.

5. Select the Authors alias in the left column, select Delete in the Permissions field,check all of the extended permissions (Run Procedure, Change Location, ChangeState, Change Permissions, and Take Ownership), and click Add to Set.The alias is added to the right column, which displays the user and grouppermissions in the permission set. The % sign in front of the alias name (for example,%Authors) indicates that the alias is defined at runtime from the values in the aliassets.

6. Select the Marketing_Managers alias in the left column, select Delete in thePermissions field, check all of the extended permissions, and click Add to Set.

7. To display dm_owner and dm_world, select Show Users and Groups.

8. Select dm_owner, select Delete in the Permissions field, check all of the extendedpermissions, and click Add to Set.

9. Select dm_world, selectNone in the Permissions field, check the Run Procedure andChange Location extended permissions only, and click Add to Set.The Authoring_folder permission set template should look as follows:



10. Choose Insert → Object from Docbase → Permission Set Template and selectthese other permission set templates (which were installed with the DAB525TutorialDocApp) to insert them into your DocApp:• Approved_folder• Author_user• DocApp_Developers• InReview_folder• Marketing_User• Published_folder• Retired_folder• Reviewer_user• Suspended_folder• Viewer_user

11. Check in the DocApp by choosing DocApp → Check In DocApp.Make sure to check it in as the same version (1.0). You only need to check a DocAppin as a different version if you think you might need to use the old version.Although Write permission and higher (Delete) folder security allows thespecified users to create, move, delete, and copy documents, users cannot performthese actions without the corresponding object-level security. For example,



in the Authoring folder with the Authoring_folder permission set template, aMarketing_Manager user has Write permission, but they would only have Readpermission on the object as specified in the Author_user permission set template.Therefore, although a Marketing_Manager user could create new objects and link toexisting objects, it could not delete, move, or modify an object that an Author usercreated in the Authoring folder.The DocApp_Developers permission set template enables you to create documentlifecycles and workflow templates with the appropriate permissions for marketingmanagers and authors. Users must have at least Relate permissions on a documentlifecycle to apply it to a document and at least Relate permissions on a workflowtemplate to start it.

Applying permission set templates to cabinets andfolders

To allow each user to perform the appropriate actions in the cabinet and each folder, youmust apply the corresponding permission set template.

To apply the permission set templates to folders:

1. In Desktop, log on to the Docbase as a super user.

2. Navigate to the Authoring folder.

3. Right-click on Authoring and select Properties.

4. In the Authoring Properties dialog box, click the Security tab.

5. Click Replace.

6. In the Replace Permissions Set dialog box, select the Authoring_folder permissionset template and click OK.

Note: Desktop does not differentiate between permission sets and permission settemplates.

7. In the Authoring Properties dialog box, click OK.

Summary

You have created aliases for groups and folders and organized the aliases into an alias set,ProductBase. You created a permission set template and added four others for users—forthe Author, Marketing_Manager, Reviewer, Viewer users and DocApp developers—andsix permission set templates for folders (Authoring, InReview, Approved, Published,



Suspended, Retired), each corresponding to a folder and state in the lifecycle that youwill create in the next module.

You test these permission set templates in the next module in which you use them torestrict access to sales_info documents in the various lifecycle states.

Module 3: Designing document lifecycles• Estimated Time: 45 minutes• Goals: Add entry criteria and actions to the Authoring state.• Tasks:

— Insert the SalesInfoCycle into the ProductBase DocApp.

— Add entry criteria and actions to the Authoring state.

— Check in, validate, and install the SalesInfoCycle.In this module, you create the SalesInfoCycle document lifecycle that encapsulates thestages (hereafter called states) through which documents of the sales_info type progress.In each state, you can control who has access to a document and how much access theyhave; you can also perform automated actions, such as promoting documents to thenext state. You use an Exception state to handle unexpected changes in documents. Inthis lifecycle, you use the Exception state to suspend a sales_info document from thePublished state to the Suspended state (the Exception state) when an unexpected changein sales information renders a document obsolete.

You use the SalesInfoCycle lifecycle in conjunction with the ReviewWkflow workflow tomanage the review of sales_info documents. The lifecycle defines the states of sales_infodocuments, but ReviewWkflow performs the actual routing of the document among thepeople who review and approve those documents. Once you develop the SalesInfoCyclelifecycle, you develop the ReviewWkflow workflow that routes the documents amongauthors, reviewers, and marketing managers.

Tip: WebPublisher requires five state types: WIP, Staging, Approved, Active, Expired.See theWeb Publisher Administration Guide for more information.

The SalesInfoCycle lifecycle has the structure shown in Figure 27–2, page 270:



Figure 27-2. SalesInfoCycle document lifecycle


Design the SalesInfoCycle lifecycle:

1. Choose Insert → Object from Docbase → Document Lifecycle, navigate to theDAB525Tutorial DocApp, and double-click SalesInfoCycle.

2. To check out and display SalesInfoCycle in the Document Lifecycle Editor,double-click it and click Edit.

3. The SalesInfoCycle document lifecycle has these values:

Table 27-7. Values for SalesInfoCycle documentlifecycle

Field Value Comments

Name SalesInfoCycle

Primary Type sales_info The primary type to whichthis lifecycle applies.

Default Alias Set ProductBase The default alias set that isused to resolve aliases ina permission set templatewhen a document entersone of the states.

Tip: WebPublisher requires that you specify a default alias set.

4. Double-click the Authoring state to modify its properties.

5. In the Entry Criteria tab, add an expression test that makes sure the author hasselected a product line and product name for the sales_info document.

a. Click Add Expression Test.The Expression Editor is displayed.



b. Click the selection arrow and select the product_line attribute.The product_line attribute is inserted into the editor field.

Note: If you do not see the product_line attribute in the drop-down list,manually enter the text in the following step in the editor field.

c. Add text after product_line so that it looks like this:product_line <> ""

Do not insert a space between the double quotes; otherwise you might not beable to apply this lifecycle to a document.This expression checks whether the product_line attribute is not equal tonothing; that is, if product_line contains a value.

d. To make sure that your expression uses the correct syntax, click Validate.If your syntax is correct, then OK is enabled.

e. Click OK.

f. In similar fashion, add the same expression test for the Product Name attribute.The text should look like this:

product_name <> ""

6. In the Actions tab, enter standard actions that the lifecycle applies to the sales_infodocument when it enters this state:

a. Click Add Action.The Define Action wizard is displayed.

b. To create a link in the Authoring folder, select Link to New Location and clickNext.

c. Select Specify a Location Alias, select the Authoring Location folder alias, andclick Finish.The Link to New Location action and Authoring Location folder alias are addedto the Standard Actions field.

7. In similar fashion, add these actions:

Table 27-8. Actions for SalesInfoCycle document lifecycle

Action Parameter Comments

Set Permission Set Author_user Specifies the permissionsfor the sales_info documentin the Authoring state.

Add Version Label Authoring Displays the text“Authoring” in the



Action Parameter Comments

document’s label fieldin Desktop.

8. Click the Close button in the upper right-hand corner of the dialog box.

Validate and install the SalesInfoCycle lifecycle:To use SalesInfoCycle, you must validate and install it into the Docbase.

1. Check in SalesInfoCycle.

2. View SalesInfoCycle by choosing File → View.To be installed in a Docbase, the lifecycle must remain checked in to the Docbase.

3. In the SalesInfoCycle dialog box, click Validate.

4. Click Install.

Summary

You inserted and modified the SalesInfoCycle lifecycle that defines entry criteria andactions to be applied to a sales_info document when it enters a new state. You specifiedthat any sales_info document must have a product line and product name specifiedbefore entering SalesInfoCycle’s first state, Authoring. You specified that each time thedocument moves from one state to another that the document is moved to the folderappropriate to the new state and that the corresponding permission set is applied. Forexample, when a document moves to the Published state, all permissions are changed toRead and only the marketing manager can move it, change its state, and so forth.

Testing your lifecycle

After creating your new lifecycle, test it to see if you have implemented it correctly. Logon to your Docbase from Desktop, create a new sales_info document, and promote thedocument through the lifecycle.


1. Open Windows Explorer and click on the plus sign next to the EMC | DocumentumDesktop icon.


3. Click your Docbase, type Author for the user name and author for the passwordwhen prompted, and then click Log On.



4. Open My Cabinet.To create a new document, see the procedure, Testing your DocApp, page 260.

Note: When you select the sales_info type in the New dialog box, make sure that thesales_info_template is displayed in the Template field

Move your sales_info document through the lifecycle:

1. Insert your document into the SalesInfoCycle by right-clicking it and choosingDocument Lifecycle → Apply.The Apply Document Lifecycle dialog box is displayed.

2. Make sure that SalesInfoCycle is displayed in the Document Lifecycle field andclick Apply.

3. Promote your document to the Review and Approval state by right-clicking it andchoosing Document Lifecycle → Promote.The Promote dialog box is displayed.

4. Click Promote.Your document is copied and pasted as a link into the InReview folder as specifiedby the Review and Approval state’s Action tab.

5. Promote your document to the Published state by right-clicking it and choosingDocument Lifecycle → Promote.The Promote dialog box is displayed.

6. Click Promote.Your document is moved into the Published folder and the text, “Published,” isappended to the version label as specified by the Published state’s Action tab.

7. Open your document’s properties by right-clicking on it and choosing Properties.Its Properties dialog box is displayed.

8. Click the Advanced tab.In the Document Lifecycle’s Name field, SalesInfoCycle is displayed; in the CurrentState field, Published is displayed.

9. Log on to the Docbase as Marketing_Manager.

10. Suspend your document by right-clicking on it and choosing Document Lifecycle→ Suspend.Your document is placed into the Suspend state and moved to the Suspended folder.If you can execute these steps, you have successfully created the SalesInfoCyclelifecycle.



Module 4: Designing workows• Estimated Time: 45 minutes• Goals: Design the ReviewWkflow workflow template.• Tasks:

— Insert the ReviewWkflow workflow template into the ProductBase DocApp.

— Add a reject flow.

— Set up an activity to automatically execute a method.

— Modify selection of performers for an activity.A workflow performs the actual routing of a document among the people whoreview and approve those documents. Here you develop a review workflow (named“ReviewWkflow”) that routes sales_info documents among authors, reviewers, andmarketing managers.

After an author creates a sales_info document, the author inserts it into theReviewWkflow. In ReviewWkflow, the author and reviewers collaborate to approvethe document. Once they agree on the content of the document, the document isautomatically promoted to the next state, Published, in the SalesInfoCycle lifecycle.From that point on, the marketing manager can decide to promote, demote, suspend, orresume the document in SalesInfoCycle.

You design the ReviewWkflow workflow shown in Figure 27–3, page 274.

Figure 27-3. ReviewWkow workow

The flows and activities perform these actions:



Table 27-9. Actions of ReviewWkow workow ows and activities

Flow/Activity Actions

Initiate-to-Review Starts the workflow and specifies Openas the operation to start in the Reviewactivity.

Review Routes sales_info documents to thereviewers and prompts them to reviewand edit the document as necessary. Ifthe document is rejected by the author,the reviewers are prompted to edit thedocument in response to the author’scomments.

Review-to-Approve Connects the Review activity to theApprove activity and specifies Open asthe operation to start in the Approveactivity.

Approve Routes sales_info documents to the authorand prompts him or her to annotate thedocument with comments to send back tothe reviewers or to approve it.

Approve-to-Review (Reject Flow) Connects the Approve activity to theReview activity and specifies Open as theoperation to start in the Review activity.This is a reject flow (denoted by the redcolor).

Note: Color is displayed only in thismanual’s PDF file or in ApplicationBuilder—it is not displayed in the printedmanual.

Approve-to-Promote Connects the Approve activity to thePromote activity and specifies Promoteas the operation to start in the Promoteactivity.

Promote Automatically promotes sales_infodocuments to the Published state.




To add the ReviewWkow workow to the ProductBase DocApp:

1. Choose Insert → Object from Docbase → Workflow Template.

2. Navigate to the ReviewWkflow workflow template in the ProductBase DocApp (inSystem/Appllications/ProductBase), and double-click it.

To create a reject ow from the Approve activity to the Edit activity:

1. To open ReviewWkflow in Workflow Manager, double-click it.

2. To enable modification of the workflow, choose File→ Uninstall (if it is installed).

3. In the toolbar, select the Create Reject Flow tool (the red “Z”).

4. Move the cross-hairs over the Approve icon—but do not click it.

5. When four compass points are displayed as small, black squares around theApproveicon (shown in the following figure), click and drag to the Edit activity icon.

6. When the four compass points are displayed around the Edit activity, release themouse button.

7. From the toolbar, select the Select Objects tool.

8. Double-click the reject flow.

9. In the Flow Inspector, click Add New Package.

10. Type or select these values for the package:

Table 27-10. Attribute values for Approve-to-Review reject ow

Field Value Comment

Name sales_info

Package type dm_sysobject Select the dm_sysobjecttype, which is thesupertype of manyother types (includingdm_document, whichis the supertype of thesales_info type). In thisway, you can use manyother objects with thisworkflow.



Field Value Comment

Version CURRENT

Operation at Destination Open This operation is displayedas a button in theperformer’s Task window.

11. Click OK.

To modify the Approve activity:

1. Double-click the Approve activity icon.

2. In the Properties dialog box, click the Performer tab, and click Select Performer.

3. Select Single user from group in the drop-down list and click Next.

4. Select the authors group and click Finish.Only the first user to accept the task in the authors group can complete it. The usermust click the Accept button before the Open button is enabled.

5. To allow the author approve or reject the changes, in the Transitions tab choose Letthe activity’s performer choose.If the changes are approved, the flow proceeds to the Promote activity. If thechanges are rejected, the flow proceeds to the Reject activity, which then returnsto the Review activity.

6. Click OK.

To specify an automatic method for the Promote activity:

1. Double-click the Promote activity icon.

2. Select the Automatically on behalf of a performer option.

3. In the Execute this method automatically drop-down list, select theWF_PromoteLifecycle method.

4. Click OK.

To save and install the workow:

1. Choose File→ Save As and select the /System/Desktop Client/Workflow Templatesfolder in which to save your workflow.Saving the workflow template in this folder makes it available to all Desktop usersand in the EMC | Documentum integration with Microsoft Outlook.

2. To validate your workflow, click Yes when prompted.

3. To install your workflow, click Yes when prompted.



Summary

You have designed a review workflow, “ReviewWkflow,” that you use during theReview and Approval state of the SalesInfoCycle lifecycle. ReviewWkflow enables afeedback loop between the reviewers and the author. It also automatically promotes thedocument to the next state, Published. Since dm_sysobject is specified as the type thatthe ReviewWkflow transfers from one activity to another, you can use ReviewWkflowfor other documents that are subtypes of dm_sysobject.

Testing your workow

After creating your new ReviewWkflow, test it to see if you have implemented itcorrectly. Log on to your Docbase from Desktop, create a new sales_info document,promote the document to the Review and Approval state, and insert your documentinto the ReviewWkflow.


1. Open Windows Explorer and click the plus sign next to the EMC | DocumentumDesktop icon.


3. Click your Docbase, type Author for the user name and its password whenprompted, and then click Log On.

4. Open My Cabinet.To create a new document, see the procedure, Testing your DocApp, page 260.

Apply SalesInfoCycle to your document:

1. Right-click your document and choose Document Lifecycle → Apply.The Apply dialog box is displayed.

2. Click Apply.

Promote your document to the Review and Approval state:

1. Right-click your document and choose Document Lifecycle → Promote.The Promote dialog box is displayed.

2. Click Promote.

Insert your document into ReviewWkow:

1. Re-log in as Marketing_Manager since you must have at least Coordinator clientcapability to open a workflow.



2. In your Docbase, double-click System/Desktop Client/WorkflowTemplates/ReviewWkflow/ReviewWkflow.

3. In the Start Workflow dialog box, click Insert.

4. Find your document and click Insert.

5. Click Start.

Complete ReviewWkow tasks:Once the workflow has started, all of the users in the reviewers group receive tasks intheir inboxes.

1. Relog on to the Docbase first as the Reviewer user and then as theMarketing_Manager user and open each one’s Inbox.

2. Double-click the Edit task to open it.

3. Click Open and then Edit to edit the document.

4. Check in your document when you complete your edits.

5. Click Finish and type your password when prompted to complete the task andstart the next activity.

Note: If a user does not check in the document, then the user who receives the nexttask will not be able to edit it. You must relogin as the previous user and checkin your document.

6. Complete all tasks to make sure that they all work as implemented.The document is finally promoted to the Published state at which time you relog onto the Docbase as Marketing_Manager and promote, demote, suspend, or resumethe document.

Module 5: Conguring Installation Options andDeploying DocApps to Other Docbases


— Configure target Docbase installation options for the ProductBase DocApp.

— Install the ProductBase DocApp on the target Docbase.• Tasks:

— Add a document template for the sales_info type, the ProductBase folderhierarchy, and pre- and post-installation procedures.



— Configure target Docbase installation options for all objects in the ProductBaseDocApp.

— Create a DocApp archive and install it to the target Docbase.You package a DocApp into an archive that you can deploy to other Docbases. If youare reusing the DocApp and deploying it to another Docbase that services a differentset of users in your company, aliases and permission set templates are of great value.When you install the DocApp archive into a Docbase, you can provide the desired values(user names, groups, cabinets, folders, or permission set templates) in the target Docbasefor the aliases in your DocApp.

Before archiving your DocApp, you configure target Docbase installation optionsfor the DocApp’s objects. Installation options control whether duplicate objects areversioned, overwritten, or ignored, whether data objects (cabinets, folders, documents)within cabinets and folders are installed, assigning a specific permission set, location,or owner alias to sysobjects (with one exception) or use the defaults, and running pre-and post-installation procedures.

You must perform some preinstallation tasks in the target Docbase. For example, youmust at least create the operating system users that correspond to the Docbase users (oruser aliases in your DocApp) that manipulate the documents in your DocApp; you canuse pre- and post-installation procedures to create Docbase users, groups, cabinets,and folders if required (or you can create them manually using EMC | DocumentumAdministrator).

You use Application Builder to configure installation options and package your DocAppinto an archive. You use Application Installer to install the DocApp archive into theDocbase.


You can automatically copy data objects (cabinets, folders, and documents), to the targetDocbase by adding (also called inserting) them into your DocApp. Smartlists anddocument templates are two useful documents to include in your DocApp.

To add a document:

1. Select Insert → Object from Docbase → Document.

2. Navigate to the sales_info_template file in the Templates cabinet, and select it.

3. Click Insert.

Tip: You must also include the type of the document in order for the documentto be included in the DocApp archive.



To add pre- and post-installation procedures:

1. Select Insert → Objects from Docbase → Procedures and select this procedure(which were installed with the DAB525Tutorial DocApp) to insert them into yourDocApp:• modFoldAlias – This procedure creates the required groups (authors,

reviewers, marketing_managers, viewers, docapp_developers) and users(Author, Reviewer, Marketing_Manager, and Viewer), temporarily specifiesthe ProductBase alias set as the default alias set for the installing user account,modifies the folder aliases, folders, and adds users to the appropriate groups.

Because the installing user account’s alias set is used to resolve the aliases inpermission set templates when they are assigned to objects (including folders),the alias set of the installing user account must be temporarily set to theProductBase alias set. See Chapter 3, Using Aliases to Make DocApps Portablefor information about how aliases are

To set installation options:

1. In Application Builder, choose DocApp → Set Installation Options.The Target Docbase Installation Options dialog box is displayed.

2. In the pre-installation procedure drop-down listbox, select the createGrp procedureand CURRENT for version.

3. In the post-installation procedure drop-down listbox, select the modFoldAliasprocedure and CURRENT for version.The current versions of the pre- and post-installation procedures in the Docbaseare archived—regardless of the versions of the procedures that are in the DocApp.When the DocApp archive is installed, the modFoldAlias post-installation procedureis executed after the DocApp is installed.

4. Select the sales_info_template in the tree pane and select Author_user for thepermission set template alias, Templates_location for the location alias andAuthor_user as the owner alias, and Overwrite in the Upgrade section to overwriteany existing templates in the target Docbase.Performing this step gives the Author and Marketing_Manager users permission tocreate a new document from the sales_info_template document template and installssales_info_template into the Templates cabinet.

5. Select the SalesInfoCycle document lifecycle in the tree pane, click New nextto the Permission set template alias field, and create a new alias for theDocApp_Developers permission set template:

a. In the Alias Object dialog box, enter these values for the corresponding fields.• Name: DocApp_Developer_PST• Type: Permissions Set• Value: DocApp_Developers



b. Click OK.

6. Select the ReviewWkflow workflow template in the tree pane and select theDocApp_Developer_PST permission set template for the permission set templatealias.Selecting the DocApp_Developer_PST permission set template alias gives the Authoruser Relate permission on SalesInfoCycle and ReviewWkflow which allows the userto apply a document lifecycle to a document and to a start a workflow instance.

7. Click OK.

To package ProductBase into an archive:

1. In Application Builder, choose DocApp → Create DocApp Archive.The Choose Directory dialog box is displayed.

2. Navigate to the directory in which you want to create the ProductBase archive.You do not need to create a ProductBase directory—Application Builder automaticallycreates a directory with the same name as your DocApp and places the archive files init. EMC | Documentum recommends that you do not change the name of the DocApparchive folder because Application Installer uses it to install the DocApp archive and theDocApp archive folder might be specified in paths (such as in the XML configurationfile or location aliases).

Note: The version number is not included in the DocApp archive. When a DocApparchive is installed in a Docbase that already contains a version of the DocApp, thenewly installed DocApp’s version is incremented by .1 from the existing version;otherwise, the DocApp is installed as version 1.0.

To create the corresponding operating system users in the target Docbase.

1. Create the operating system users as described in Creating users, page 287.

To install the ProductBase archive into a target Docbase:Before installing any DocApp, make sure that you have super user privileges in thetarget Docbase.

1. Choose Start → Programs → Documentum → Application Installer.Log on to the Docbase by typing your user name and password when promptedand clicking OK.The Select DocApp Archive dialog box is displayed.

2. Click Browse to find the ProductBase archive folder.Select the ProductBase archive folder and click OK.

3. Click OK in the Select DocApp Archive dialog box.You are returned to the main window.



4. Click Start Installation.If a message box is displayed that states that there are connected users, click Yes tocontinue.Application Installer performs these actions:• The types are installed.• The Resolve Alias dialog box is displayed. See .• The other objects in the DocApp archive are installed in a single transaction.• The modFoldAlias post-installation procedure is executed.

Summary

In completing this basic tutorial, you have created a portable DocApp that includes newtypes, aliases, alias sets, permission set templates, pre- and post-installation procedures,documents, a lifecycle, and a workflow. You have also configured installation optionsthat control whether duplicate objects are versioned, overwritten, or ignored, assigning aspecific permission set, location, or owner alias to sysobjects (with one exception) or usethe defaults, and running a post-installation procedure that create Docbase users andgroups, and modify folders, and data objects.

With the knowledge you have gained in these modules, you can now increase yourknowledge and skills in the following intermediate tutorial, which include creating jobsand methods, and developing complex document lifecycles and workflows that worktogether.




Chapter 28Intermediate Tutorial: CreatingDocApps

This chapter is an intermediate-level tutorial that continues the previous chapter’s sample DocAppcalled ProductBase. It covers the intermediate tasks needed to create a DocApp that allows endusers to approve and route documents.

Note: Since the previous release, enhancements have been made to the basic tutorial; you can eitherfollow the instructions in the Chapter 27, Basic Tutorial: Creating DocApps to learn about the newfeatures of this release described in that tutorial or start with this intermediate tutorial.

These topics are included:• Overview, page 285• Module 6: Adding Docbasic code using jobs and methods, page 288• Module 7: Retiring object types and specifying object type constraints, page 294• Module 8: More on attributes—search options, input masks, constraints, value mapping, and

conditional value assistance, page 298• Module 9: More on document lifecycles—post-changes, attribute properties, functionality,

page 305• Module 10: A more complex workflow—triggers, transitions, dynamic next performer and

spanning multiple states, page 308• Module 11: Using document lifecycles and workflows with multiple sets of users, page 313

OverviewThis chapter contains modules in which you create jobs, procedures, and methods. Thesemodules also put you on the road to mastering some of the intermediate features, suchas object type constraints, lifecycle post-changes and functionality, workflow templateperformers, methods, triggers, and transitions.• Module 6: Adding Docbasic code using jobs and methods, page 288


Intermediate Tutorial: Creating DocApps

• Module 7: Retiring object types and specifying object type constraints, page 294• Module 8: More on attributes—search options, input masks, constraints, value

mapping, and conditional value assistance, page 298• Module 9: More on document lifecycles—post-changes, attribute properties,

functionality, page 305• Module 10: A more complex workflow—triggers, transitions, dynamic next

performer and spanning multiple states, page 308• Module 11: Using document lifecycles and workflows with multiple sets of users,

page 313

Prerequisites

To complete this tutorial, you should have completed the previous chapter’s tutorial andbe familiar with Docbasic and the Server API methods.

Software requirements

EMC | Documentum recommends that you install this software on your computer tocomplete this tutorial. If you are using an earlier version of either Desktop (formerlyknown as Desktop Client), Application Builder (formerly known as Developer Studio),or Application Installer (formerly known as DocApp Installer), some features mightnot be available.• Desktop 5.2.5 or greater or Webtop 5.2.5 or greater• Application Builder 5.2.5 or greater• Application Installer 5.2.5 or greater

Note: If you are using an earlier version of Desktop, Webtop, Application Builder, orApplication Installer, see your release notes for information about the versions thatcan be installed on the same workstation.

You should also have access to EMC | Documentum Administrator 5.2.x and a ContentServer 5.2.5 or greater; otherwise, some features might not be available. You use EMC |Documentum Administrator to delete objects from your Docbase if you accidentally addthem using Application Builder.



Source les

Source files include a DocApp archive, DAB525Tutorial, which contains preconfiguredobjects that you will need to successfully complete the basic and intermediate as wellas final versions of the objects.

The source files are in a zip file that you can download from the EMC | Documentumdownload site.

Creating users

Create NT users using the User Manager for Domains tool. EMC | Documentumrecommends that create these new users even if you already have a set of WindowsNT users that you want to use for this tutorial; otherwise, you will need to modify thepre- and post-installation procedures in the DAB525Tutorial DocApp that you installin the next section.

Note: If you are using a Docbase that is installed on a UNIX computer, you might needto contact your system administrator to create new users.

To create Windows NT users:

1. Make sure that your user account (usually Administrator) has permissions to addusers and groups to your workstation’s domain.

2. Choose Start → Programs → Administrative Tools (Common) → User Managerfor Domains.

3. If you are not logged in to your workstation’s domain, select it by choosing User →Select Domain and entering your workstation as the domain.

4. Choose User → New User.

5. Create these users and corresponding passwords:

User name Password

engineer engineer

product_manager product

dept_head dept

Engineer_Server engineer

Prod_Manager_Server product

Dept_Head_Server dept



6. If you have not added the users in the basic tutorial, create the Author,Marketing_Manager, Reviewer, and Viewer users with their respective user namesas their passwords—except for the Marketing_Manager user, use “marketing” asits password.

7. For each user, uncheckUser Must Change Password at Next Logon, check PasswordNever Expires, and click Add or OK.

Module 6: Adding Docbasic code using jobsand methods

• Estimated Time: 30 minutes• Goals: Create a job and method that the job executes.• Tasks:

— Create the notifyArchiveSalesInfo method.

— Create the notifyArchiveSalesInfo job.In this module, you create a job that executes a method at the end of each week andprompts the marketing manager to archive all Sales Information documents that are inthe Retired state. To create a job, you must first create a method and then referencethat method in the job.


Creating a method

You create methods to automate tasks. This method calls the dmAPIGet(“archive...”)API server method.

To create the notifyArchiveSalesInfo method:

1. In Application Builder, open the ProductBase DocApp that you completed inModule 4: Designing workflows, page 274.

2. Select Insert → Method.

3. Double-click the method in the left pane.

4. In theMethod dialog box, specify these values:



Table 28-1. Attribute balues for notifyArchiveSalesInfo method


Name notifyArchiveSalesInfo

Command .\dmbasic -enotif-yArchiveSalesInfo

.\dmbasic instructs theserver to look for thedmbasic program in thedirectory where the serverexecutable is located(the default location is%DM_HOME%\bin onNT or $DM_HOME/bin onUNIX).

-e indicates the entrypoint,the name of the routinethat you want to runfirst; in this case,notifyArchiveSalesInfois the entrypoint.

Run Synchronously Selected Keep the defaults for theMinimum, Default andMaximum timeout values.

5. Open the text file, notifyArchiveSalesInfo.txt (which was installed with theDAB525Tutorial DocApp and is located in the DAB525Tutorial folder), that containsthe following Docbasic code and copy the text:

’ notifyArchiveSalesInfo’ -- This method sends an email to the marketing manager’ to archive all sales_info documents that are in a Retired (4)’ state.’ Executed as a job.

Sub notifyArchiveSalesInfo( ByVal docbase As String, _ByVal user As String, _ByVal password As String)

On Error GoTo notifyArchive_ErrorDim errorMsg as StringDim sessionId As StringDim event_id As Object ’ item_id of dmi_queue_item

’ Get a session.errorMsg = "Connecting to docbase"sessionId = dmAPIGet("connect," & docbase & "," & user & "," & password)

’ Execute the archive method to get all sales_info_dates docs’ that are in a Retired (4) state.



event_id = dmAPIGet("archive,sessionId,sales_info WHEREr_current_state=4,Marketing_Manager,1,T")

Exit Sub

notifyArchive_Error:Print errorMsgdmExit (100)

End SubThese docbase, user, and password arguments correspond to the arguments thatthe job passes to the method.The dmAPIGet(“archive...”) method returns an object ID (or item_id) ofthe dmi_queue_item. All the text for this method must be on one line. TheMarketing_Manager is the user that the archive request is sent to. The numeral, 1, isthe priority of the archive request, and the letter, T, indicates that an email should besent to the Marketing_Manager.

Tip: Do not use spaces between the delimiting commas and parameters of the serverAPI methods (for example, dmAPIGet). If you use spaces, the method does notexecute correctly and an error does not occur.

6. Add the file as content for the notifyArchiveSalesInfo method.

a. Click Add, select all the existing text, and paste the notifyArchiveSalesInfo textthat you just copied.

b. Choose Run→ Check Syntax to check that the syntax does not have any errors.

c. Choose File → Save to save the file.

d. Choose File → Exit and Return to exit from the Docbasic Editor.

7. Check in the method.

Creating a job

This job executes the method that you created in the previous section. Jobs automaticallyexecute methods at regular intervals.

To create the notifyArchiveSalesInfo job:

1. Select Insert → Job.

2. Double-click the job in the left pane.

3. In theMethod dialog box, specify these values:



Table 28-2. Attribute values for notifyArchiveSalesInfo job


Name notifyArchiveSalesInfo

Subject Notification to archiveretired sales_infodocuments.

Designated Server yourDocbase The name of the Docbaseon which you want toexecute this job.

Method notifyArchiveSalesInfo The name of the methodthat you created.

Arguments yourDocbase yourUserNameyourPassword

Select the Argumentsradio button and enterthe text in the Valuecolumn. yourDocbase isthe DocApp’s Docbase;yourUserName is your username; yourPassword is youruser password.

Deactivate on failure Selected

Run once upon saving,then run as scheduled

Selected Once you check in this job,the job will run and youcan see if it works.

Execute on 6, week Select the sixth day (Friday)of every week.

4. Check in the notifyArchiveSalesInfo job and the DocApp.

Job failed to execute

If you receive the following email message, you must use EMC | DocumentumAdministrator to add a date and time for the a_next_invocation attribute:Job "notifyArchiveSalesInfo" failed to execute successfully. The message was:"[FATAL ERROR] [AGENTEXEC 380] Detected while schedulingjob notifyArchiveSalesInfo: Job a_next_invocation must be supplied."

To add a date and time for the a_next_invocation attribute:

1. Start EMC | Documentum Administrator and click Jobs in the left pane.



2. In the EXISTING JOBS field, select All.

3. Scroll down to the bottom of the window and click Attributes for thenotifyArchiveSalesInfo job.

4. Select Active.

5. In the Next Run Date/Time field, select a time that is a few minutes greater than thecurrent time shown on your computer.

6. Select Run After Update and click Update.When your computer clock reaches the time you specified, the notifyArchiveSalesInfojob executes. You can set a shorter date and time interval initially, so that you canmake sure that the job executes.

Summary

You have created a job that executes a method, notifyArchiveSalesInfo, every Friday.The notifyArchiveSalesInfo method checks for sales_info documents in the Retired state.If any sales_info documents are in a Retired state (represented by the number 4), anemail is sent to the Marketing_Manager and the DM_ARCHIVE event is created inthe Marketing_Manager’s inbox.

Testing your job

After creating your job, test it to see if you have implemented the modifications correctly.

Use the following procedures to create a sales_info document and promote it to theRetired state.




3. Click your Docbase, type your user name and password when prompted, and thenclick Log On.

4. Open the folder with your user name as its title.

To create a new document:

1. In your folder, right-click anywhere in the right pane and choose New→ Document→ Other from the pop-up menu.




3. Select sales_info for its type in the Type field.Keep the format as ASCII Text.

Note: If the sales_info type does not appear, you might need to use Task Manager torestart the Desktop and Windows Explorer processes.



4. To create a new document, click New and type some text into your new document.


6. Check in your document by choosing File→ Check In and clicking Check In.

Promote your sales_info document to the Retired state:

1. Log on to your Docbase as Marketing_Manager.

2. Insert your document into the SalesInfoCycle by right-clicking it and choosingDocument Lifecycle → Apply.The Apply Document Lifecycle dialog box is displayed.

3. Make sure that SalesInfoCycle is displayed in the Document Lifecycle field andclick Apply.

4. Promote your document to the Review and Approval state by right-clicking it andchoosing Document Lifecycle → Promote.The Promote dialog box is displayed.

5. Click Promote.

6. Repeat Step 4 and Step 5 until you have promoted the document to the Retired state.

Change the run interval for the job to every minute.

1. In Application Builder, double-click the notifyArchive job in the left pane.

2. Click the Schedule tab, select the Execute every option, and then select 1 andMinutes in this option’s fields.

3. Check the option, Run once upon saving, then run as scheduled.

4. Check in notifyArchive by selecting DocApp → Check In Object(s)If you receive an email (which should arrive in a few minutes) stating that you havedocuments to archive, you have successfully created the notifyArchive job and thenotifyArchiveSalesInfo method.



Other troubleshooting tips

If your job does not execute, make sure that your Docbase is running correctly. Forexample, the Docbase’s agent exec process, which controls job execution, might not berunning. See the Content Server Administration Guide for more information.

Module 7: Retiring object types and specifyingobject type constraints

• Estimated Time: 30 minutes• Goals: Retire an object type and specify constraints between two attributes.• Tasks:

— Retire the sales_info object type.

— Specify constraints between the sales_info_dates object type’s review_due_dateand publishing_due_date attributes.

In this module, you retire the sales_info type and modify the sales_info_dates typethat you installed with the DAB525Tutorial DocApp. You modify the sales_info_datestype, which contains the same attributes as the sales_info type, by adding two newattributes. You specify constraints between two new attributes, review_due_date andpublishing_due_date, that restricts the due date to within fourteen days of the reviewdate.

When you retire a type, the type is no longer displayed in the Desktop New Documentor Import dialog boxes, which makes the type unavailable to end users. You do not wantexisting sales_info documents to display the new attributes and cause confusion for yourend users. Occasionally, you might need to retire types when you create new typesthat provide new features and you want your end users to use the new types for newdocuments; however, you still want to maintain the existing documents of the old typeswithout having to use the new features.

Adding the sales_info_dates type

Insert the sales_info_dates type, which was installed with the DAB525Tutorial DocApp;the sales_info_dates type contains the same attributes (distribution, product_line,product_name) as those in the sales_info type.



To insert the sales_info_dates type:

1. Choose Insert → Object from Docbase → Object Type and select thesales_info_dates type.

Specifying constraints

Create the review_due_date and publishing_due_date attributes, then create theconstraint in the sales_info_dates type. The sales_info_dates type can manage constraintsbetween its attributes; whereas attributes can only manage constraints within themselves.

To create the constraint:

1. Double-click the sale_info_dates type and click Edit in the message box that isdisplayed.

2. Click the Constraints tab and enter this constraint expression (all on one line):DateDiff("d", publishing_due_date, review_due_date) >= 0

DateDiff, a Docbasic function, subtracts the review_due_date attribute value fromthe publishing_due_date attribute value; consequently, the date of review_due_datecannot be greater than the date of publishing_due_date. Think of a constraint as the Ifportion of an If... Then statement.This constraint stipulates that publishing_due_datemust occur within 14 days of the review_due_date.

Tip: If you make a mistake, you can click Reset Expression to set the currentconstraint expression back to the checked in version. To delete a constraintexpression, click Delete Constraint.

3. In the field, Error message string to use when above constraint is violated, enterthis text:The publishing due date must occur after the review due date.

Note: In Application Builder 4.1, the text in this field is replaced with the constraintexpression when you cancel the check out of a type or you close and reopen theDocApp. This is fixed in Application Builder 4.2 and above.

4. Click Next and enter this constraint expression (all on one line):DateDiff("d", publishing_due_date, review_due_date) <= 14

5. In the field, Error message string to use when above constraint is violated, enterthis text:The publishing due date must occur at most 14 days after the reviewdue date.

6. Make sure that the Enforce Constraint option is checked.



7. Click Check Syntax to verify that the constraint expression is correct.If an error is displayed stating that the constraint expression is invalid, check inthe object, close the DocApp, wait about five minutes for the type cache to refresh,reopen the DocApp, check out the type, and click Check Syntax again.

8. Make sure that the sales_info_dates type (or one of its attributes) is selected andchoose DocApp→ Check In Object(s) to check in the sales_info_dates type.

Retiring the sales_info type

Retire the sales_info type by specifying Obsolete for its life cycle.

To retire a type:

1. Edit the sales_info type.

2. Select Obsolete from the Type Lifecycle field on the General tab.You must also change any objects that use the sales_info type to use thesales_info_dates type.

Note: Selecting Future, which has the same affect in Desktop as selecting Obsolete,means that the type is not yet ready for use.

To change the objects that use sales_info:

1. Change the primary type for the SalesInfoCycle to sales_info_dates.

2. Use DAB to change sales_info to sales_info_dates in the notifyArchiveSalesInfomethod.

3. Use EMC | Documentum Administrator to add sales_info_dates_template document(that was installed with the DAB525Tutorial DocApp) as a new template and addit to the ProductBase DocApp.

Summary

You have created the review_due_date attribute that specifies the date on which thereview of a sales_info_dates document starts and the publishing_due_date attributethat specifies the date on which the review should end. Finally, you have created atype-level constraint between these two attributes that restricts the due date to withinfourteen days of the review date.

You have retired the sales_info type such that it no longer appears in the Desktop NewDocument and Import dialog boxes. You have changed the SalesInfoCycle document



lifecycle and notifyArchiveSalesInfo method to use the new sales_info_dates type andadded a new template for it to the ProductBase DocApp.

Testing the sales_info_dates type

After modifying your sales_info_dates type, test it to see if you have implemented themodifications correctly. Using the following procedures to log on to your Docbase fromDesktop, create a new sales_info_dates document, and enter dates for the review dateand due date.




3. Click your Docbase, type the Author user name and password when prompted,and then click Log On.

4. Open the folder with your user name as its title.

To create a new document:

1. In your folder, right-click anywhere in the right pane and choose New→ Document→ Other from the pop-up menu.


3. Select sales_info_dates for its type in the Type field, make sure that thesales_info type is not displayed—since it is retired—and make sure that thesales_info_dates_template template is displayed in the Template field.Keep the format as ASCII Text.

Note: If the sales_info_dates type does not appear, you might need to restart theDesktop and Windows Explorer processes.



4. To create a new document, click New.

5. If an error message is displayed, stating that you need to satisfy some propertyconstraints, go to Step 7.

6. In the text editor, enter some text, save the file, exit the text editor.



7. Click OK to display the Properties dialog box.

To enter dates for the review date and due date:

1. Click the Product Info tab.

2. Enter values for the Product Line, Distribution, and Product Name fields.

3. Click in the Review Date field and enter a date (for example, 12/31/05) for thereview to start.

4. Enter a new date (for example, 01/31/016) in the Due Date field that is more thanfourteen days after the review date and click Apply.An error message should be displayed; the new dates are not saved.

5. Click in the Due Date field, enter a date for the review to end that is within fourteendays of the review date, and click Apply.The new dates should be saved.

6. Click OK.

7. In the text editor, type some text into your new document.


9. Check in your document by choosing File→ Check In and clicking Check In.If you successfully performed these steps, you correctly customized thesales_info_dates type and review_due_date and publishing_due_date attributes.

Module 8: More on attributes—search options,input masks, constraints, value mapping, andconditional value assistance

• Estimated Time: 45 minutes• Goals: Modify attribute search options, input masks, constraints, value mapping,

and use a DQL query for value assistance.• Tasks:

— Modify attribute search options.

— Add an input masks to constrain the characters entered for the part_numattribute.

— Add a constraints for the values of the pgs attribute.

— Add value mapping to the product_line attribute’s value assistance values.

— Modify the distribution attribute to use a DQL query for value assistance.



In this module, you specify an input mask for a new part_num attribute. You constrain anew pgs attribute to less than 100 pages of a sales_info_dates document. You use a DQLquery to set the default value assistance for the distribution attribute. Finally, you usevalue mapping to map internal code names for product names to the real product names.

Using a DQL query to set the default value assistance (or conditional value assistance aswell) is very convenient, because it enables you to retrieve the attribute values from adocument of a different type—the object could be in the Docbase by itself or includedanother DocApp. Another user can modify the attribute values independently of thetype that loads the values.

Specifying search options

You specify search options for an attribute to set the search operators and defaults forclient applications.

To specify a default search value and search operators for the distribution attribute:

1. Double-click the distribution attribute in the left pane.

2. Click the Advanced tab and enter Web Site in the Default search value field.

3. Use the Add and Remove buttons to include the following search operators in theAllowable search operators field:• is• is not• is defined• is not defined

4. Specify the is operator as the default search operator.Since the distribution attribute is a single-value attribute and is using valueassistance, it does not make sense to include either the is in and is not in operators,which apply only to repeating value attributes, nor any of the other operators thatsearch for substrings or compare strings.

Note: The correct search operators might not be immediately displayed in the Finddialog box; it takes a few minutes for the Content server to refresh the cache.

Specifying input masks

You specify an input mask for an attribute to set the format (including special characters,numerals, and alphabetic characters) for the values that the user can enter for the



attribute. Specify an input mask for a new part number attribute, part_num, thatuniquely identifies a sales_info_dates document.

To specify an input mask for the part_num attribute:

1. To expand the attributes of sales_info_dates, click the plus sign next to it in theleft pane.

2. Double-click the part_num attribute in the left pane.The Properties dialog box is displayed.

3. Click the Advanced tab and enter the following text, which is an input mask for thepart number, in the Input Mask field:####-UU####

This input mask for the part number requires that the first four digits of the partnumber be numerals, which are followed by a hyphen, two uppercase letters (whichcan correspond to a month), and four numerals (which can correspond to the year).

4. Make sure that the sales_info_dates type (or one of its attributes) is selected andchoose DocApp → Check In Object(s) to check in the part_num attribute and thesales_info_dates type.

Specifying constraints

You specify constraints to restrict the values that users can enter for an attribute or type.You will restrict the number of pages for a sales_info_dates document to less than orequal to 100. In an attribute constraint, you can use only the attribute name itself—youcannot use other attribute names.

Adding a constraint

To add a constraint to the pgs attribute:

1. To expand the attributes of sales_info_dates, click the plus sign next to it in theleft pane.

2. Double-click the pgs attribute in the left pane.The Properties dialog box is displayed.

3. Click the Constraint tab and enter the following text in the Constraint expressionfield:pgs <= 100

This constraint restricts the number of pages to 100 or less.



4. Click Check Syntax to validate the syntax of the expression.

5. In the field, Error message string to use when above constraint is violated, enterthis text:You must enter 100 pages or less.

Note: In Application Builder 4.1, the text in this field is replaced with the constraintexpression when you cancel the check out of a type or you close and reopen theDocApp. This is fixed in Application Builder 4.2 and above.

6. Make sure that the sales_info_dates type (or one of its attributes) is selected andchoose DocApp → Check In Object(s) to check in the pgs attribute and thesales_info_dates type.

Specifying value mapping

You specify value mapping to match the displayed values to the saved values.

To specify value mapping for the product_line attribute:

1. Double-click the product_line attribute in the left pane.

2. In the Properties dialog box’s Value Mapping tab, type these values:

Table 28-3. Values for product_line attribute

Data Display string Description

ComStar CommunicationsSatellite StarVersion 1

CommunicationsSatellite

StarFire Military SatelliteFirewall Version 2

Anti-jammingSatellite

Lightning Military SatelliteLightning Version 3

Jamming Satellite

3. Make sure that the sales_info_dates type (or one of its attributes) is selected andchoose DocApp → Check In Object(s) to check in the pgs attribute and thesales_info_dates type.



Specifying a DQL query for default value assistance

A new type, publication, has been created with a distribution attribute in theDAB525Tutorial DocApp. The distribution attribute is displayed in a field on a new tab,Bill of Materials, in the Properties dialog box. The person who builds the bill of materialscan modify the distribution attribute’s values, which are displayed in the Product Infotab’s Distribution field in the Properties dialog box.

The publication object type’s distribution attribute that has these values:

Table 28-4. Values for distribution attribute

Tab Field/Option Value Comment

General Attribute Name distribution

Label Distribution

Data type String

Repeating Selected Enables selectionof more than onevalue to display inthe sales_info_datestype’s distributionfield.

Default Value(s) Sales KitWeb SiteBrochureWhite Paper

Click Edit anduse the Add andRemove buttons toadd these defaultvalues. They willbe displayed inthe Distributionfield when a newpublication typedocument is firstcreated.

Attribute can haveNULL value

Selected Check this option.

Advanced Attribute Category Bill ofMaterials

A new tab withthis name is addedinto the document’sProperties dialogbox.

Note: Instead default value assistance, default values have been specified.



To specify a DQL query for the sales_info_dates type’s distribution attribute’s default valueassistance:

1. Edit the distribution attribute and select the Value Assistance tab.

2. Click Edit and select Query instead of Fixed List.

3. Enter the following query text in the Please enter query used to generate the list ofvalue assistance field:select distribution from publication

Do not enter an attribute in the Query attribute providing data to display option,since you have already specified the attribute in the above statement. You only needto specify an attribute in this field when you need to differentiate between two ormore attributes that you have specified in the select statement.

4. Make sure that the List is complete option is checked.

Summary

You have customized the sales_info_dates type further by adding two new attributeswith a constraint, input mask, and value mapping. You have restricted the number ofpages for a sales_info_dates document to 100. You have specified an input mask thatrestricts users to entering a part number in a specific format. You have created a DQLquery to retrieve the distribution attribute’s default value assistance from another type’sattribute. Finally, you have mapped internal product lines to real product lines that aredisplayed to users.

Testing your customized type

After customizing your sales_info_dates type, test it to see if you have implementedit correctly. Log on to your Docbase from Desktop, create a new sales_info_datesdocument, enter and select values for the Product Info tab fields, and save the properties.

To test the pgs and part_num attributes:

1. To log on to a Docbase and create a new sales_info_dates document, see Testing thesales_info_dates type, page 297.

2. Test the constraint for the pgs attribute.

3. Enter 120 in the Number of Pages field and click Apply.The error message, “The number of pages must be equal to or less than 100,” shouldbe displayed.



4. Enter 75 and click Apply.An error message should not be displayed.

5. Test the input mask for the part_num attribute.

6. Enter A.You should not be able to enter a letter.

7. Enter four numerals, two letters (for the month), and four numerals (for the year).The two letters that represent the month should appear in uppercase.

To test the product_line attribute:

1. Click the Product Line drop-down listYou should see these choices:• Communications Satellite Star Version 1• Military Satellite Firewall Version 2• Military Satellite Lightning Version 3

2. SelectMilitary Satellite Firewall Version 2 for the Product Line field, StarPeak forthe Product Name field, and click OK.The properties should be saved.

3. Right-click the sales_info_dates document, and then choose Check in to check it in.

4. Select Same Version and click Check In.

5. In EMC | Documentum Administrator, click DQL/API in the left pane.

6. In the DQL statement field, enter this query:SELECT product_line FROM sales_info_dates

For the query results, the text, StarFire, should be displayed. StarFire, whichis the value in the Data column of the product_line attribute’s Value Mappingtab, corresponds to the Display String column value,Military Satellite FirewallVersion 2.If you successfully performed these steps, you correctly customized the pgs,part_num, and product_line attributes.

To test the distribution attribute:

1. Select a value in the Distribution field and click OK.

2. Use Desktop to create a document called publication_values of the publication type.

3. Open the Properties dialog box for the publication_values document and addanother value, Release Notes, to the list.

4. Open the Properties dialog box for your sales_info_dates document and make surethat the Release Notes value is displayed in the Distribution field.



5. Choose Tools→ Find→ Documentum Items to display the Find dialog box.

6. Select the sales_info_dates type in the Look for field and the Distribution attributein the Properties to look for field.

7. Make sure that by default, the is operator is selected, only the is, is not, is defined,and is not defined operators are available, and that all of the correct values aredisplayed in the drop-down list of values for which to search.

Module 9: More on document lifecycles—post-changes, attribute properties, functionality

• Estimated Time: 45 minutes• Goals: For a state, specify a post-change procedure, hide object attributes, and

remove available functionality.• Tasks:

— Specify the queueOnSuspension procedure for the Suspended state.

— For the Published state, hide the publishing_due_date and review_due_dateattributes and disable the Promote functionality.

In this module, you specify a post-change procedure that queues a notification and sendsan email to all viewers when a sales_info_dates document is suspended. You disable thedue_date and review_date attribute fields when sales_info_dates documents enter thePublished state. You prevent end users from choosing File → Document Lifecycle →Promote to promote sales_info_dates documents that are in the InReview state.

Implementing post-change procedures

To implement a post-change procedure for a document lifecycle state, you add theprocedure to the DocApp, and specify it as a post-change procedure for a state. Theprocedure is executed after a document successfully enters the state.

Tip:• Enter all Server API methods (for example, dmAPIGet) on one line. In the above

code sample for the method, the dmAPIGet methods are not all on one line.• Do not use spaces between the delimiting commas and parameters of the server API

methods (for example, dmAPIGet). If you use spaces, the method does not executecorrectly and an error does not occur.



To specify the PostChange procedure in the Suspended state:

1. Choose Insert→Object fromDocbase→ Procedure, navigate to the DAB525TutorialDocApp, and double-click the queueOnSuspension procedure.The signature for any post-change procedure must be:

Public Function PostProc(_ByVal SessionID As String,_ByVal ObjectID As String, _ByVal UserName As String,_ByVal TargetState As String,_ByVal ErrorString As String) As Boolean

You use the Main Sub procedure to test your PostProc function. To run a Docbasicfunction in the Procedure debugger, a Main entry point must be specified. Youcall the PostProc function from the Main Sub procedure. The Main Sub procedurecontains values for the input parameters to the PostProc function. You can hard-codethe values in the Main Sub procedure or use the InputBox$ method to prompt theuser for them.

2. In Application Builder, double-click the SalesInfoCycle_Basic_Final lifecycle in theleft pane.

3. Double-click the Suspended state and click the PostChange tab.

4. Click the ... (Browse) button for the Docbase Path Name and navigate to and selectthe queueOnSuspension procedure.

5. Check in SalesInfoCycle_Basic_Final.

To debug the queueOnSuspension procedure (optional):

1. Check out the queueOnSuspension procedure.

2. Double-click on the queueOnSuspension procedure.

3. In the Docbasic Editor, set a breakpoint on line 19 (the line that starts with the text,ViewersID = DMAPIGet) by:

a. Placing the cursor on the line, and

b. Pressing F9.

4. Run the procedure by pressing F5.The Docbasic Editor checks the syntax and displays any errors detected. If no errorsare detected, the procedure runs until it gets to the breakpoint.

5. Set the following watched variables by selecting each variable and choosing Debug→ Add Watch:• ViewersID• NumOfUsers• UserNameInGroup



• EventIDThe watched variables are displayed in a separate window below the toolbar.

6. Press F8 to step through the procedure a single line at a time.

7. As you step through the procedure, observe the values of the watched variables:• The value of ViewersID should be an ID (for example, 120f421580000503).• The value of NumOfUsers should be 5 (Author, First_Reviewer,

Second_Reviewer, Marketing_Manager, Second_Reviewer, Viewer).• The successive values of UserNameInGroup should be Viewers,

Second_Reviewer, Marketing_Manager, First_Reviewer, Author. The exact ordermight vary, since the order of the user names in the group depends on the orderin which you added them to the group.

• The value of EventID should be an ID (for example, 1b0f421580004105).8. If any of the values are unexpected, check the code in your procedure against the

code in .

Modifying attribute properties and functionality

You can modify some basic properties of the primary types attributes and functionalitythat is available in the state. Since the review of a sales_info_dates document has beencompleted when it enters the Published state, disable the due_date and review_dateattributes in the Published state by enabling each one’s hidden property. In the DesktopProperties dialog box, you cannot enter values into the due_date and review_dateattribute fields and values are not displayed. Since you only want to promote asales_info_dates document in ReviewWkflow, you want to disable (or prohibit) thePromote functionality in the InReview state. In Desktop, choosing File → DocumentLifecycle → Promote results in an error—but you can still use ReviewWkflow topromote documents.

To hide the publishing_due_date and review_due_date attributes and disable the Promotefunctionality:

1. Edit SalesInfoCycle_Basic_Final and open the Published state.

2. On the Attributes tab, select publishing_due_date and click Change Properties.

3. Select the Attribute is hidden option and click OK.

4. Perform steps 2 and 3 for the review_due_date attribute.

5. On the Functionality tab for the InReview state, select DcDocumentLifecyclePromoteand click Remove.

6. Check in and install SalesInfoCycle_Basic_Final.



Summary

You have created a procedure, queueOnSuspension, and added it as a post-changeprocedure to run when a sales_info_dates document enters the Suspended state. ThequeueOnSuspension procedure queues the sales_info_msg document to each Viewersgroup user’s inbox as well as sends an email to each one.

You have disabled the due_date and review_date attributes in the Published state. Youhave disabled the Promote menu item in the InReview state.

Testing

To test that the Promote menu in the InReview state has been disabled:

1. Promote one of your sales_info_dates documents to the InReview state and makesure that an error message is displayed when you try to promote it.

2. Apply ReviewWkflow to your document and make sure that the document isautomatically promoted to the Approved state.

To test that the due_date and review_date attributes have been disabled in the Publishedstate and the queueOnSuspension procedure executes correctly:

1. Promote your document to the Published state enter values into the Review Dateand Due Date fields on the Properties tab.

2. Suspend it to the Suspended state.

3. Check that a queue item is in each Viewers group user’s inbox and that an email hasbeen sent to each one.

Module 10: A more complexworkow—triggers, transitions, dynamicnext performer and spanning multiple states

• Estimated Time: 45 minutes• Goals: Specify activity triggers, allowing one activity’s performer to choose the

next activity’s performer; observe how a workflow can promote an object throughmultiple states.

• Tasks:



— Specify the review activities be started when only one of the previous activitiesis completed.

— Specify the performer of the Product Management Review activity specifies theperformers of the Second Promote activity.

In this module, you modify the Approval workflow template that was installed withthe DAB525Tutorial DocApp. The required users and groups have also been installedwith the DAB525Tutorial DocApp.

In the Approval workflow, you allow only one of several triggers (also called ports),which correspond to a flow’s endpoints, to start an activity. This technique is usefulbecause you might want to reuse the activity by starting (or triggering) it from severaldifferent activities at different times. You also specify a transition that lets the currentperformer choose the next activity from several activities. This technique is usefulbecause if you cannot specify conditions to automatically choose the next activity outof several choices, then you can use the human intelligence of the current performerto decide.

You can specify that the performer of one activity can specify the performer of afollowing activity (this is also referred to as the dynamic next performer feature). Thistechnique is useful because you might need the performers of one activity to be chosenby the performers of a previous activty.

The Approval workflow also spans multiple states (InReview, Approval, and Published)of the SalesInfoCycle_Basic_Final document lifecycle, which makes the workflow moretightly integrated with its corresponding document lifecycle. When a workflow spansmultiple states, you will be able to use it only with document lifecycles that have statessimilar to the ones that the workflow uses. The workflow does not span the Retired andSuspended states, since Authoring, Retired and Suspended are tasks separate fromreviewing and approving a document; that is, a workflow is meant to complete a singletask and that task is not required to encompass all of a document lifecycle’s states.

The Approval workflow is shown in the following figure:

Figure 28-1. Approval workow

The Author user attaches the sales_info_dates document to the SalesInfoCycle_Basic_Final, promotes it to the InReview state, and inserts it into the Approval Workflow. Thesales_info_dates document first goes through a product management review in which the



Product_Manager user (who has been created by the DAB525Tutorial DocApp) reviewsthe document. If the sales_info_dates document is approved and no modifications arerequired, then it is sent to the engineering review in which the Engineer user (whohas been created by the DAB525Tutorial DocApp) reviews the document. However,if modifications are required, then the Product_Manager rejects the sales_info_datesdocument and it is sent back to the Author user to be edited. Once the Author usercompletes editing the sales_info_dates document, it is sent back to the Product_Managerto review and approve. This process can be repeated until the Product_Managerapproves the sales_info_dates document and it is sent to the Engineering Review.

The product_manager user also determines the performer for the Third Promote activity.

If the Engineer user approves the sales_info_dates document, then it is sent to thedepartment head review in which the Dept_Head user (who has been created by theDAB525Tutorial DocApp) reviews the document. If modifications are required, thenthe Engineer user rejects the sales_info_dates document and it is sent back to theAuthor user to be edited. As with the previous scenario, the Engineer user can rejectthe modifications and the process is repeated until the Engineer user approves thesales_info_dates document and it is sent to the department head review.

Again, the Dept_Head user can approve it or reject it and the editing and review processis repeated. Once the Dept_Head user approves the sales_info_dates document, then itis automatically promoted to the Approved state. Then the Marketing_Manager user,which was chosen by the Product Management Review activity’s performer, promotesthe sales_info_dates document to the Published state.

Note:• The product_managers, dept_heads, and engineering groups were added to the

reviewers and viewers groups by the DAB525Tutorial DocApp, so that theirmembers (Engineer, Product_Manager, and Dept_Head users) would have the samepermissions as the reviewers in the InReview and Published states.

• The Forward activity is required, since you can create only one input flow to thefirst activity after the Initiate activity.

Specifying that one input ow can trigger an activity

By default, an activity is triggered when all input flows that are connected to it have beencompleted. Two input flows are connected to each of the review activities (ProductManagement Review, Engineering Review, Dept. Head Approval), yet only one ofthose input flows can be completed at one time. Therefore, a review activity should betriggered when only one of the input flows is completed.



To specify that a single input ow that triggers an activity:

1. Choose Insert → Object from Docbase → Workflow Template, navigate to theDAB525Tutorial DocApp, and double-click the Approval workflow template.

2. To edit the Approval workflow template, double-click it.

3. Double-click each review activity (Product Management Review, EngineeringReview, Dept. Head Approval), click the Trigger tab, and select This number ofinput flows selected.The number 1 is automatically entered in the field below the option. Since twoinput flows are connected to this activity, the number 2 is displayed as the numberof possible input flows.

4. Click OK.

Specifying that a performer of one activity species theperformers of a following activity

In the Approval workflow, you specify that the performer of the Product ManagementReview activity specifies the performers of the Second Promote activity.

To specify that a previous performer species the performers of an activity:

1. Double-click the Second Promote activity and click Select Performer.

2. In the Select Performer dialog box, select Single user from group in the SelectPerformer field.

3. In the Define Performer(s) section, click the Have performer(s) of activity<Workflow Initiator> determine performer(s) of this activity “Second Promote”option and select the Product Management Review activity to replace the <WorkflowInitiator> field.

4. Click Finish and then OK.The performer of the Product Management Review activity will be prompted tochoose a performer for the Third Promote activity.

Summary

You have specified that the performer of the Product Management Review activityspecifies the performers of the Second Promote activity. You have specified that eachreview activity is activated when only one input flow is selected since each review activityhas more than one input flow, but only one input flow is active at any one moment.



Testing

After modifying the Approval workflow, test it to see if you have implemented itcorrectly. Log on to your Docbase from Desktop, create a new sales_info_datesdocument, promote the document to the InReview state, and insert your document intothe Approval workflow.





4. Open My Cabinet.To create a new document, see Testing your DocApp, page 260.

Apply SalesInfoCycle_Basic_Final to your document:


2. Click Apply.

Promote your document to the InReview state:


2. Click Promote.

Insert your document into the Approval workow:

1. In your Docbase, double-click System/Applications/DAB525Tutorial/Approval.



4. Click Start.

Complete the Approval workow tasks:Once the workflow has started, all of the users in the product_managers group receivetasks in their inboxes.

1. Relog on to the Docbase as Product_Manager and open your Inbox.





4. Click Finish and then Reject to reject the document and send it to the Edit activity,where the Author implements or rejects your editing suggestions.

5. Check in your document.

6. Complete all tasks to make sure that they all work as implemented.The Product Management Review performer should choose the marketing_managersgroup as the performer of the Second Promote activity, since the Marketing_Manageruser is the only one that can promote a document to the Publish state. When thedocument is promoted to the Approved state, the Marketing_Manager (who is theonly member of the marketing_managers group) receives a task in the inbox and isasked to promote the document to the Published state.

Module 11: Using document lifecycles andworkows with multiple sets of users

• Estimated Time: 45 minutes• Goals: Modify the SalesInfoCycle_Basic_Final document lifecycle, Approval

workflow template, and the ProductBase alias set, so that you can use both the Serverand ProductBase users with them.

• Tasks:

— Modify the SalesInfoCycle_Basic_Final document lifecycle’s list of default aliassets.

— Modify the Approval workflow template’s performers.

— Modify the ProductBase alias set.In this module, you use alias sets to generalize the SalesInfoCycle_Basic_Final documentlifecycle to work with different sets of users differentiated by alias sets. You enablethe workflow initiator to choose different groups for the Approval workflow templateinstance.

Alias sets contain the aliases that the system uses to resolve to specific users, groups,cabinets, folders, and permission set templates. You specify an alias set, Server, inaddition to the ProductBase alias set for SalesInfoCycle_Basic_Final such that when youapply SalesInfoCycle_Basic_Final to a document, you can select the Server alias set.The Server alias set contains folder, group, and permission set template aliases for theserver engineers, product managers, and department heads. You create a new set ofserver-specific users, groups, and permission set templates as well as folders to organizethe server-specific sales_info_dates documents.



Whenever you create a new set of users and associated groups, and folders, you shouldalso create new permission set templates for them—even if the permissions are similarbetween the sets of users. In this way, changing the user, group, and folder permissionsfor one set of users does not affect the other set of users.

The required users, groups, folders, permission set templates, and alias set were installedwith the DAB525Tutorial DocApp.

Modifying the document lifecycle and workowtemplate

You must modify the SalesInfoCycle_Basic_Final and Approval workflow template forthem to use the correct users, groups, folders, and permission sets.

To modify SalesInfoCycle_Basic_Final to use the server aliases:

1. Insert and check in the Server alias set that was installed with the DAB525TutorialDocApp.The Server alias set is located in the DAB525Tutorial DocApp folder.

2. Add the same Reviewer_user and Viewer_user permission set template aliases thatare in the Server alias set to the ProductBase alias set.These aliases allow SalesInfoCycle_Basic_Final to resolve these aliases for either theProductBase or Server alias set.

3. Uninstall SalesInfoCycle_Basic_Final if required.

4. Open SalesInfoCycle for editing and click ... (Browse) next to the Default AliasSet field.

5. Click Add, select the Server alias set, and click OK.

6. Click OK again.

7. Double-click on the InReview state and click on the Actions tab.

8. Select the Set Permission Set action and click Edit.

9. Select the Specify a Permission Set Alias option, select Reviewer_user, and clickOK.Selecting this option forces the action to resolve the Reviewer_user aliasagainst the appropriate alias set (the one that the user chooses when applyingSalesInfoCycle_Basic_Final to a document).

Note: Only the aliases in the document lifecycle’s default alias set are displayedfor selection.



10. Execute steps 4 to 6 for the Published state, except select Viewer_user as thepermission set alias.

11. Check in SalesInfoCycle_Basic_Final.

To modify the Approval workow to use the server groups:

1. Uninstall the Approval workflow if required.

2. Open Approval workflow for editing.

3. Double-click on the Product Management Review activity and click on thePerformer tab.

4. Click Select Performer.

5. Make sure that All Users in Group is displayed in the Select Performer(s) field.

6. Select the Define performers alias option and click Next.

7. Select the Alias set of document in package option.

8. Select the sales_info package for the package name and click Next.

9. In the Performer title field, enter:Product_Managers

The performer title exactly matches the Product_Managers alias in theProductBase and Server alias sets. When the sales_info package enters the ProductManagement review activity, the performer is determined by the resolution of theProduct_Managers alias. The Product_Managers alias value is determined by thealias set (either ProductBase or Server) that was chosen for the sales_info documentwhen it was attached to the SalesInfoCycle_Basic_Final.

10. Click Finish and then OK.

11. Execute steps 3 through 10 for the Engineering Review activity, except use this text:

Table 28-5. Performer title for Engineering Review activity

Field Text

Performer Title Engineering

12. Execute steps 3 through 10 for the Dept. Head Approval activity, except use this text:

Table 28-6. Performer title for Dept. Head Approval activity

Field Text

Performer Title Dept_Heads

13. Save, validate, and install the Approval workflow.



Summary

You have modified the Approval workflow template to enable the person who attachesthe sales_info document to SalesInfoCycle_Basic_Final to determine (through the selectedalias set) the groups to execute the Product Management Review, Engineering Review,and Dept. Head Approval activities. You have also modified SalesInfoCycle_Basic_Finalto resolve folder and permission set template aliases against either the default alias set(ProductBase) or the Server alias set—whichever one users choose when they applySalesInfoCycle_Basic_Final.

In completing the basic tutorial and this intermediate tutorial, you have created aportable DocApp that includes new types, aliases, alias sets, permission set templates, ajob and associated method, pre- and post-installation procedures, folders, documents, alifecycle, and workflows. Armed with the knowledge you have gained in these modules,you can now sharpen your skills to create fully functional DocApps that improve theefficiency and effectiveness of content management processes for your company usingthe EMC | Documentum Content system.

In the following advanced tutorial, you learn how to customize and dynamically deployDesktop components.

Testing

After modifying SalesInfoCycle_Basic_Final and the Approval workflow, test them to seeif you have implemented them correctly. Log on to your Docbase from Desktop, create anew sales_info_dates document, promote the document to the InReview state, and insertyour document into the Approval workflow.





4. Open My Cabinet.To create a new document, see Testing your DocApp, page 260.

Apply SalesInfoCycle_Basic_Final to your document:




2. Choose the appropriate alias set (ProductBase or Server) and click Apply.

Promote your document to the InReview state:


2. Click Promote.

Insert your document into the Approval workow:

1. In your Docbase, double-click System/Applications/DAB525Tutorial/Approval.



4. Click Start.

Complete the Approval workow tasks:Once the workflow has started, all of the users in the group that corresponds to theProduct_Managers performer title receive tasks in their inboxes.

1. Relog on to the Docbase as the user that is a member of either product_managers orprod_managers_server and open your Inbox.



4. Click Finish and then Reject to reject the document and send it to the Edit activity,where the Author implements or rejects your editing suggestions.

5. Check in your document.

6. Complete all tasks to make sure that they all work as implemented.The document is finally promoted to the Published state at which time you canrelog on to the Docbase as Marketing_Manager and promote, demote, suspend, orresume the document.




Part 4

Quick Reference

These topics are included:• Chapter 29, Error Messages


Quick Reference


Chapter 29Error Messages

This section lists the error message descriptions and solutions alphabetically (articles andvariables are ignored) by error message. Variables are shown in italics.

Bad argument index: index_number.

The DocApp archive ’archive’ cannot be found. Installation cannot continue.

The DocApp ’docapp’ is locked by another user.

Error: Execution of installation procedure ’procedure’ failed.

Error: Installation cannot proceed: The acl ’acl’ for alias ’alias’ is incorrect. The acl doesnot exist.

Error: Installation cannot proceed: The group ’group’ for alias ’alias’ is incorrect. Thegroup does not exist.

Error: Installation cannot proceed: The location ’cabinet_or_folder’ for alias ’alias’ isincorrect. The path does not exist.

Error: Installation cannot proceed: The user ’user’ for alias ’alias’ is incorrect. The userdoes not exists.

Error: Installation cannot proceed: The user or group ’user_group’ for alias ’alias’ isincorrect. The user or group does not exist.

Error: The procedure ’procedure’ did not complete successfully.

Error: The program could not read a required file. Reason: An error occurred outside ofthe program. Details: Error reading file: file_name

Error: The properties file at location ’path’ was not found

ERROR: Unable to archive the DocApp since the following alias: ’alias’ does not exist inthe default alias set.

ERROR: Unable to attach ’object’ to document lifecycle ’document_lifecycle’. The documentlifecycle is not in the ’Installed’ state.


Error Messages

ERROR: Unable to attach ’object’ to document lifecycle ’document_lifecycle’. The followingserver error occurred: server_error

Filestore ’filestore_name’ does not exist. Content for object ’object_name’ will be placed inthe default file store ’default_filestore_name’

Installation cannot proceed: CANNOT FIND Object Type in target Docbase or DocApparchive:

Installation cannot proceed: CANNOT FIND SuperType of:

Installation cannot proceed: The location ’path’ for object ’object_name’ is incorrect. Thepath does not exist.

Installation cannot proceed: No value found for location alias ’alias’. You may haveforgotten to turn on the ’prompt for value’ option.

Installation cannot proceed: No value found for permission set alias ’alias’.

Installation cannot proceed: No value found for owner alias ’alias’. You may haveforgotten to turn on the ’prompt for value’ option.

Installation cannot proceed: Permission Set ’permission_set’ is not owned by user ’user’.Cannot be used.

Installation cannot proceed: Permission Set ’permission_set’ does not exist.

Installation cannot proceed: User ’user’ does not exist in the current docbase.

Installation cannot proceed: The Workflow template: ’workflow_template’ is in the’installed’ state. Workflows can be altered only if they are in the ’draft’ state

Installation Status: This object is locked by someone else or has been installed by someother user. Installation terminated.

Locale information for this Docbase is not available.

The locale locale is not present in the Docbase.

Login failed.

User chose not to continue

User ’user’ does not have the privilege to configure audit.

WARNING: The Workflow template: ’workflow_template’ could not be validated.

WARNING: The Workflow template: ’workflow_template’ could not be installed.

WARNING: The Workflow template: ’workflow_template’ was not validated or installedwhen it was archived. It will NOT be installed.

Warning: ’object’ will be attached to the base state of document lifecycle document_lifecycle.The current state ’state’ is not attachable.


Error Messages

Warning: ’object’ will be attached to the base state of document lifecycle document_lifecycle.The current state ’state’ is an exception state.

Warning: ’object’ will be attached to the base state of document lifecycle document_lifecycle.The document lifecycle does not contain current state ’state’.

Warning: The XML Application xml_application already exists at location current_location.

Workflow template will not be audited.


ACL does not exist

ACL does not exist

Purpose Indicates that ACL does not exist in the target Docbase.

Error MessageError: Installation cannot proceed: The acl ’acl’ for alias’alias’ is incorrect.The acl does not exist.

where:

acl is the name of the permission set specified as the value of the alias. alias is the name ofthe alias.

DescriptionThis error occurs when the permission set (or access control list (ACL)) specified for thepermission set alias does not exist in the target Docbase. The installation is aborted.

SolutionUsing Application Builder, the developer checks the Prompt for value at installationoption for the permission set alias or uses a pre-installation procedure to create thepermission set and rearchives the DocApp; then you reinstall the DocApp archive.

You can also use EMC | Documentum Administrator to create the permission set inthe target Docbase and reinstall the DocApp archive—although this does not resolvethe problem in the DocApp archive itself.


Alias does not exist in default alias set

Alias does not exist in default alias set

Purpose Indicates that the alias does not exist in default alias set.

Error MessageERROR: Unable to archive the DocApp since the followingalias: ’alias’ does not exist

in the default alias set.

where:

alias is the name of the alias.

DescriptionThis error occurs when an alias referenced by a document lifecycle or workflow templatein the DocApp does not exist in the default alias set.

SolutionUsing Application Builder, the developer adds the alias to the default alias set or changesthe default alias set to the alias set in which this alias exists.


Bad argument index

Bad argument index

Purpose Indicates a bad argument index.

Error MessageBad argument index: index_number.

where:

index_number is the index number.

DescriptionThis is an internal error.

SolutionRearchive the DocApp and reinstall the DocApp archive. If these steps do not resolve theproblem, contact EMC | Documentum Technical Support.


Cannot attach object to document lifecycle

Cannot attach object to document lifecycle

Purpose Indicates that an object cannot be attached to document lifecycle.

Error MessageERROR: Unable to attach ’object’ to document lifecycle’document_lifecycle’.The following server error occurred: server_error

where:

object is the name of the object to attach. document_lifecycle is the name of the documentlifecycle. server_error is the server error message.

DescriptionThis error is caused when a EMC | Documentum Content Server error occurs and theobject is not attached to the document lifecycle.

SolutionCorrect the problem identified by the Content Server error message.


Cannot nd properties le

Cannot nd properties le

Purpose Indicates that the properties file cannot be found

Error MessageError: The properties file at location ’path’ was not found

where:

path is the directory path.

DescriptionThis error occurs when the properties file was not found on the directory path that youspecified on the command line.

SolutionLocate the properties file, make sure you entered the correct path, and rerun theApplication Installer from the command line.


Cannot nd supertype

Cannot nd supertype

Purpose Indicates that the supertype of a user-defined object type could not be found.

Error MessageInstallation cannot proceed: CANNOT FIND SuperType of:

DescriptionThe supertype (which is usually a user-defined type) of a user-defined object type(identified in the error message) was not included in the DocApp archive nor does itexist in the target Docbase.

SolutionUsing Application Builder, the developer inserts the supertype of the user-defined objecttype in the DocApp and rearchives the DocApp; then you can reinstall the DocApparchive.


Cannot read a required le

Cannot read a required le

Purpose Indicates that a required file could not be read.

Error MessageError: The program could not read a required file.Reason: An error occurred outside of the program.Details: Error reading file: file_name

where:

file_name is the name of the file.

DescriptionThis error occurs when the objects file (in the DocApp archive folder) could not bedeserialized. The occurs when:• The DocApp archive was created using Application Builder 4.0.• The objects file is corrupt.

SolutionIf the DocApp archive was created using Application Builder 4.0, the developer mustupgrade the version 4.0 Docbase that contains the corresponding DocApp to version4.2.x and rearchive the DocApp; then you can reinstall the DocApp archive.

If you suspect that the objects file is corrupt, have the developer can rearchive theDocApp; then you can reinstall the DocApp archive.


DocApp archive cannot be found

DocApp archive cannot be found

Purpose Indicates that the DocApp archive could not be found.

Error MessageThe DocApp archive ’archive’ cannot be found.Installation cannot continue.

where:

archive is the name of the DocApp archive.

DescriptionThis error occurs when the DocApp archive’s objects file is not in the DocApp archivefolder. The installation is aborted.

SolutionMake sure that the objects file is in the DocApp archive folder.


DocApp is locked

DocApp is locked

Purpose Indicates that the DocApp is locked by another user in the target Docbase.

Error MessageThe DocApp ’docapp’ is locked by another user.

where:

docapp is the name of the DocApp.

DescriptionThis error occurs when the dm_application object of the DocApp is locked by anotheruser in the target Docbase. Application Installer cannot install the DocApp when theDocApp’s dm_application object is checked out.

SolutionHave the person who has the DocApp checked out check it in, which checks in thedm_application object of docapp; then you reinstall the DocApp archive.


Document lifecycle is not in the installed state

Document lifecycle is not in the installed state

Purpose Indicates that the document lifecycle is not in the installed state.

Error MessageERROR: Unable to attach ’object’ to document lifecycle’document_lifecycle’.The document lifecycle is not in the ’Installed’ state.

where:

object is the name of the object to attach. document_lifecycle is the name of the documentlifecycle.

DescriptionThis error occurs when an object in the DocApp, which is attached to the documentlifecycle, could not be attached to the document lifecycle in the target Docbase becausethe document lifecycle was not in the installed state.

SolutionUsing Application Builder, you change the state of the target Docbase’s documentlifecycle to the Installed state and reinstall the DocApp archive.


Filestore does not exist

Filestore does not exist

Purpose Indicates that the filestore does not exist in the target Docbase.

Error MessageFilestore filestore_name does not exist. Content for object object_namewill be placed in the default file store default_filestore_name

DescriptionDAI was not able to set the content of the sysobject because the filestore does not exist inthe target Docbase. The content for the object is placed into the default filestore location.The installation continues.

SolutionNo action is necessary; however, you can manually move the content to another filestore.


Folder or cabinet does not exist

Folder or cabinet does not exist

Purpose Indicates that the folder or cabinet does not exist.

Error MessageError: Installation cannot proceed: The location ’cabinet_or_folder’for alias ’alias’ is incorrect. The path does not exist.

where:

cabinet_or_folder is the name of the cabinet or folder path specified as the value of thealias. alias is the name of the "cabinet or folder path" alias.

DescriptionThis error occurs when a "cabinet or folder path" alias specifies a folder path or cabinetthat does not exist in the target Docbase. The installation is aborted.

SolutionMake sure that the path for the alias in the properties file (or you can leave the alias valueblank to be prompted for a valid path) is correct and reinstall the DocApp archive.

The developer can perform one of these actions and rearchive the DocApp (then you canreinstall the DocApp archive):• Using Application Builder, create a pre-installation procedure to create the path.• Using Application Builder, check the Prompt for value at installation option for

the cabinet or folder path alias.


Group does not exist

Group does not exist

Purpose Indicates that the group does not exist.

Error MessageError: Installation cannot proceed: The group ’group’ foralias ’alias’is incorrect. The group does not exist.

where:

group is the name of the group. alias is the name of the group alias.

DescriptionThis error occurs when a group alias specifies a group that does not exist in the targetDocbase. The installation is aborted.

SolutionMake sure that the group for the alias in the properties file is correct (or you can leave thealias value blank to be prompted for a valid group) and reinstall the DocApp archive.

The developer can perform one of these actions and rearchive the DocApp (then you canreinstall the DocApp archive):• Using Application Builder, create a pre-installation procedure to create the group.• Using Application Builder, check the Prompt for value at installation option for

the group alias.


Execution of installation procedure failed

Execution of installation procedure failed

Purpose Indicates that the execution of the pre- or post-installation procedure failed.

Error MessageError: Execution of installation procedure ’procedure’ failed.

where:

procedure is the name of the pre- or post-installation procedure.

DescriptionThis error occurs when a pre-installation or post-installation procedure couldn’t beexecuted. The procedure was not found in the target Docbase or dmbasic.exe couldnot be executed.

SolutionMake sure that the procedure is in the DocApp archive by looking at the archive log fileand at the files in the DocApp archive folder; if the procedure is not in the DocApparchive, then insert the procedure, specify it as a pre- or post-installation procedure,rearchive the DocApp, and reinstall the DocApp archive.

Make sure that the dmbasic.exe program is in the path of the computer onwhich Application Installer is installed and in the EMC | Documentumclients’ Shared directory (a subdirectory of the directory identified by theHKEY_LOCAL_MACHINE\SOFTWARE\Documentum\Common\ProgramDirectoryregistry key).


Locale information for this Docbase is not available

Locale information for this Docbase is not available

Purpose Indicates that no locale is published in the target Docbase.

Error MessageLocale information for this Docbase is not available.Please check the docbase config object to make surethere is at least one locale specified.

DescriptionThis error occurs when no locale is published in the target Docbase. At least one localemust be published on the target Docbase. The published locales are specified in thedm_docbase_config object’s dd_locales attribute for a version 4.2.x or 4.4.x Docbase andin the nls_key attribute’s values of the dm_domain object for a 5.x Docbase.

SolutionPublish at least one locale in the target Docbase and reinstall the DocApp archive.

See the Application Builder online help or the Content Server Fundamentals for moreinformation about publishing locales.


Locale is not present in the Docbase

Locale is not present in the Docbase

Purpose Indicates that the locale is not present in the Docbase

Error MessageThe locale locale is not present in the Docbase.Locale-sensitive information for the type type will not be installed.

where:

locale is the name of the locale that does not exist in the target Docbase.

type is the name of the type for which locale-specific information exists.

DescriptionThis error occurs when a type contains locale-specific information, but the locale is notpublished in the target Docbase. The type is installed but the information specific to anylocales that are not published in the target Docbase are not installed with the type.

SolutionTo install the type’s locale-specific information that was not installed, publish the locale(identified in the error message) in the target Docbase and reinstall the DocApp archive.

See the Application Builder online help for more information about publishing locales.


Login failed

Login failed

Purpose Indicates that the user failed to enter the correct user name, password, or both.

Error MessageLogin failed.

DescriptionThe user failed to enter the correct user name, password, or both.

SolutionEnter the correct user name and password.


No value for location alias

No value for location alias

Purpose Indicates that no value for a location alias was provided.

Error MessageInstallation cannot proceed: No value found for locationalias ’alias’.You may have forgotten to turn on the ’prompt for value’ option.

where:

alias is the name of a cabinet path or "cabinet or folder path" alias.

DescriptionThis error occurs when no path was entered for the alias and the Prompt for value atinstallation option was not checked in Application Builder. The installation is aborted.

SolutionThe developer can perform one of these actions and rearchive the DocApp (then you canreinstall the DocApp archive):• In Application Builder, check the Prompt for value at installation option for the

cabinet path or "cabinet or folder path" alias (and, optionally, specify a value inthe properties file).

• In Application Builder, enter a path for the cabinet path or "cabinet or folder path"alias and select the Create path if it does not exist option.


No value for owner alias

No value for owner alias

Purpose Indicates that no value for owner alias was provided.

Error MessageInstallation cannot proceed: No value found for owner alias ’alias’.You may have forgotten to turn on the ’prompt for value’ option.

where:

alias is the name of a user alias.

DescriptionThis error occurs when no user was specified for a user or "user or group" alias, whichwas selected as an owner alias, and the Prompt for value at installation option wasnot checked. The installation is aborted.

SolutionUsing Application Builder, the developer checks Prompt for value at installation optionor specifies a user that exists in the target Docbase for the user or "user or group" alias,and rearchives the DocApp; then you can reinstall the DocApp archive.


No value for permission set alias

No value for permission set alias

Purpose Indicates that no value for permission set alias was provided.

Error MessageInstallation cannot proceed: No value found for permissionset alias ’alias’.

where:

alias is the name of the permission set alias.

DescriptionThis error occurs when a name of a permission set was not entered for a permission setalias in the properties file.

SolutionMake sure that the permission set for the alias in the properties file is correct and reinstallthe DocApp archive.


Object is locked or has been installed by someone else

Object is locked or has been installed by someoneelse

Purpose Indicates that the object in the target Docbase is currently checked out by a userother than the user who is installing the DocApp archive.

Error MessageInstallation Status: This object is locked by someone elseor has been installed by some other user. Installation terminated.

DescriptionThe object in the target Docbase is currently checked out by a user other than the userwho is installing the DocApp archive. The installation is aborted.

SolutionHave the user check in the object.


Object path does not exist

Object path does not exist

Purpose Indicates that a directory path for an object to be installed does not exist in thetarget Docbase.

Error MessageInstallation cannot proceed: The location ’path’ forobject ’object_name’is incorrect. The path does not exist.

where:

path is the directory path for the object. object_name is the name of the object.

DescriptionThis error occurs when a directory path for an object to be installed does not exist in thetarget Docbase. The installation is aborted.

SolutionCreate the path in the target Docbase and then reinstall the DocApp archive.

Using Application Builder, the developer creates a cabinet path or "cabinet or folder path"alias, checks the Prompt for value at installation option, assigns it as a location alias tothe object, and recreates the DocApp archive; then you can reinstall the DocApp archive.


Permission set does not exist

Permission set does not exist

Purpose Indicates that a document lifecycle or workflow template references a permissionset that was not included with the DocApp and the permission set does not existin the target Docbase.

Error MessageInstallation cannot proceed: Permission Set ’permission_set’ does not exist.

where:

permission_set is the name of the permission set.

DescriptionThis error occurs when a document lifecycle or workflow template references apermission set that was not included with the DocApp and the permission set does notexist in the target Docbase. The installation is aborted.

SolutionMake sure that the permission set for the alias in the properties file is correct and reinstallthe DocApp archive.

The developer can perform one of these actions and rearchive the DocApp (then you canreinstall the DocApp archive):• Using Application Builder, include the permission set in the DocApp.• Using Application Builder, create a pre-installation procedure to create the

permission set.• Using Application Builder, create a permission set alias for the permission set, check

the Prompt for value at installation option for the alias, and, if the permission setwas referenced in a document lifecycle or workflow template, specify that aliasin one or both of them.


Permission set not owned by user

Permission set not owned by user

Purpose Indicates that the permission set is not a system permission set (ACL) and theowner is not the user installing the DocApp archive.

Error MessageInstallation cannot proceed: Permission Set ’permission_set’is not owned by user ’user’. Cannot be used.

where:

permission_set is the name of the permission set. user is the name of the user.

DescriptionThis error occurs when the permission set is not a system permission set (ACL) and theowner is not the user installing the DocApp archive.

SolutionUsing EMC | Documentum Administrator, the developer changes the permission setowner to the user installing the DocApp archive, or changes the permission set to asystem ACL and rearchives the DocApp; then you can reinstall the DocApp archive.


Procedure did not complete successfully

Procedure did not complete successfully

Purpose Indicates that the pre- or post-installation procedure was executed, but encounteredan error and was aborted.

Error MessageError: The procedure ’procedure’ did not complete successfully.

where:

procedure is the name of the procedure that failed.

DescriptionThe pre- or post-installation procedure was executed, but encountered an error andwas aborted.

SolutionDebug the procedure by using Print statements to send output to the installation log file.


State does not exist in document lifecycle

State does not exist in document lifecycle

Purpose Indicates a warning that a state does not exist in the document lifecycle.

Error MessageWarning: ’object’ will be attached to the base state ofdocument lifecycle document_lifecycle. The document lifecycledoes not contain current state ’state’.

where:

object is the name of the object to attach. document_lifecycle is the name of the documentlifecycle. state is a state.

DescriptionThis is only a warning message. This warning occurs when there are target Docbaseobjects that are attached to the existing document lifecycle’s state, but the state does notexist in the document lifecycle that is being installed. Consequently, the objects areattached to the newly installed document lifecycle’s base state.

SolutionIf removing this state was unintentional, use Application Builder to insert the state intothe document lifecycle in the target Docbase and manually move the objects to the state.For future installations, a developer uses Application Builder to recreate this state andrecreate the DocApp archive; then you can reinstall the DocApp archive.


State is exception state and not attachable

State is exception state and not attachable

Purpose Indicates a warning that the state is an exception state and therefore the objectcannot be attached to it.

Error MessageWarning: ’object’ will be attached to the base state ofdocument lifecycle document_lifecycle. The current state ’state’ isan exception state.

where:

object is the name of the object to attach. document_lifecycle is the name of the documentlifecycle. state is the exception state.

DescriptionThis is only a warning message. This warning occurs when there are target Docbaseobjects that are attached to the existing document lifecycle’s state, but objects cannot bedirectly attached to exception states. Consequently, the objects are attached to the newlyinstalled document lifecycle’s base state.

SolutionIf you want the appropriate objects to be attached to the exception state, you mustmanually move the objects to the exception state.


State is not attachable

State is not attachable

Purpose Indicates a warning that the state does not allow objects to be attached to it.

Error MessageWarning: ’object’ will be attached to the base stateof document lifecycle document_lifecycle.The current state ’state’ is not attachable.

where:

object is the name of the object to attach. document_lifecycle is the name of the documentlifecycle.

DescriptionThis is only a warning message. This warning occurs when there are target Docbaseobjects that are attached to the existing document lifecycle’s state, but the state to whichthe objects are attached does not allow objects to be directly attached to it.

SolutionIf you want the appropriate objects to be attached to the state, you must manually movethe objects to the state. For future installations, a developer uses Application Builder tomake sure that the document lifecycle state is attachable.


Type does not exist in target Docbase or DocApp archive

Type does not exist in target Docbase or DocApparchive

Purpose Indicates that the object type does not exist in target Docbase or DocApp archive.

Error MessageInstallation cannot proceed: CANNOT FIND Object Type in target Docbaseor DocApp archive:

DescriptionThis error occurs when an object type of an object in the DocApp does not exist in thetarget Docbase or DocApp archive. The installation is aborted.

SolutionUsing Application Builder, a developer finds the missing type, inserts it into the DocApp,and rearchives the DocApp; then you can reinstall the DocApp archive.




Purpose Indicates that the user chose not to continue.

Error MessageUser chose not to continue

DescriptionYou clicked Abort Installation. The installation is aborted.

SolutionReinstall the DocApp archive.


User does not exist

User does not exist

Purpose Indicates that the user does not exist.

Error MessageInstallation cannot proceed: User ’user’ does not existin the current docbase.

where:

user is the name of the user.

DescriptionThis error occurs when a user is referenced in a document lifecycle or workflow templatebut does not exist in the target Docbase. The installation is aborted.

SolutionUse EMC | Documentum Administrator to add the user to the target Docbase andreinstall the DocApp archive.

The developer can perform one of these actions and rearchive the DocApp (then you canreinstall the DocApp archive):• Using Application Builder, create a pre-installation procedure to create the user.• Using Application Builder, create a user alias for the user, check the Prompt for

value at installation option for the alias, and specify that alias in the documentlifecycle or workflow template.


User does not exist for alias

User does not exist for alias

Purpose Indicates that the user does not exist for the alias.

Error MessageError: Installation cannot proceed: The user ’user’ foralias ’alias’ is incorrect.The user does not exists.

where:

user is the name of the user specified as the value of the alias. alias is the name of theuser alias.

DescriptionThis error occurs when the user alias in the DocApp specifies a user that does not existin the target Docbase and the Prompt for value at installation option was not checkedor the user alias in the properties file specifies a user that does not exist in the targetDocbase. The installation is aborted.

Solution

To resolve this problem, perform these steps:

1. Make sure that the specified user is correct in the DocApp or the properties file.

2. If the specified user is correct, use EMC | Documentum Administrator to add theuser to the target Docbase and reinstall the DocApp archive. The developer can alsocreate a pre-installation procedure to add the user to the target Docbase.

3. If the specified user is incorrect, either:• Correct it in the properties file (or you can leave the alias value blank to be

prompted for a valid user), or• In Application Builder, the developer checks the Prompt for value at installation

option for the user alias and rearchives the DocApp; then you reinstall it.


User does not have privilege to congure audit

User does not have privilege to congure audit

Purpose The specified user does not have the privileges to configure a workflow templatefor auditing.

Error MessageUser ’user’ does not have the privilege to configure audit.hi

DescriptionThe specified user does not have Config_audit privileges, which is required for auditing.Installation continues.

SolutionUse EMC | Documentum Administrator to give the user Config_audit privileges.


User or group does not exist

User or group does not exist

Purpose Indicates that the user or group specified for the alias does not exist.

Error MessageError: Installation cannot proceed: The user or group ’user_group’for alias ’alias’ is incorrect. The user or group does not exist.

where:

user_group is the name of the user or group specified as the value of the alias. alias is thename of the "user or group" alias.

DescriptionThis error occurs when the "user or group" alias in the DocApp specifies a user or groupthat does not exist in the target Docbase and the Prompt for value at installation optionwas not checked or the user or group alias in the properties file specifies a user or groupthat does not exist in the target Docbase. The installation is aborted.

Solution

To resolve this problem, perform these steps:

1. Make sure that the specified user or group is correct in the DocApp or the propertiesfile.

2. If the specified user or group is correct, use EMC | Documentum Administrator toadd the user or group to the target Docbase and reinstall the DocApp archive. Thedeveloper can also create a pre-installation procedure to add the user or group tothe target Docbase.

3. If the specified user or group is incorrect, either:• Correct it in the properties file (or you can leave the alias value blank to be

prompted for a valid user or group), or• In Application Builder, the developer checks the Prompt for value at installation

option for the user or group alias and rearchives the DocApp; then you reinstallit.


Workow template cannot be in the installed state

Workow template cannot be in the installed state

Purpose Indicates that the workflow template cannot be installed because it is in theinstalled state in the target Docbase.

Error MessageInstallation cannot proceed: The Workflow template:’workflow_template’ is inthe ’installed’ state. Workflows can be altered only if they arein the ’draft’ state

where:

workflow_template is the name of the workflow template.

DescriptionThis error should not occur in Application Installer version 4.3 or later. In version 4.2.x orearlier, this error occurs when a workflow template is not installed because the workflowtemplate in the target Docbase is in the installed state.

SolutionUsing Workflow Manager, uninstall the workflow template in the target Docbase.


Workow template could not be validated

Workow template could not be validated

Purpose Indicates a warning that a workflow template could not be validated.

Error MessageWARNING: The Workflow template: ’workflow_template’ couldnot be validated.

where:


DescriptionThis is only a warning message. This warning occurs when a workflow template couldnot be validated. The workflow template remains in the draft state.

Solution

To resolve this problem, follow these steps:

1. Using Workflow Manager, open the workflow template in the target Docbase.

2. Attempt to validate the workflow template.If the workflow template is not valid, an error message displaying the validationerrors is displayed; otherwise, the workflow template is validated.

3. Correct any validation errors displayed in the error message; if a message statingthat the workflow template is validated instead of an error message, then theworkflow template is validated.


Workow template could not be placed in installed state

Workow template could not be placed in installedstate

Purpose Indicates a warning that the workflow template could not be placed in the installedstate.

Error MessageWARNING: The Workflow template: ’workflow_template’ couldnot be installed.

where:


DescriptionThis is only a warning message. This warning is caused when a workflow templatecould not be installed.

Solution

To resolve this problem, follow these steps:

1. Using Workflow Manager, open the workflow template in the target Docbase.

2. Attempt to install the workflow template.If the workflow template cannot be installed, an error message displaying theinstallation errors is displayed; otherwise, the workflow template is installed.

3. Correct any installation errors displayed in the error message; if a message statingthat the workflow template is installed instead of an error message, then theworkflow template is installed.


Workow template not validated or installed when archived

Workow template not validated or installed whenarchived

Purpose Indicates a warning that the workflow template was not validated or installedwhen archived.

Error MessageWARNING: The Workflow template: ’workflow_template’ was not validatedor installed when it was archived. It will NOT be installed.

where:


DescriptionThis is only a warning message. This warning occurs when the workflow templatewas not validated or installed when the DocApp was archived. Although the DocApparchive is installed, the workflow template is not.

SolutionUsing Workflow Manager, the developer validates and installs the workflow templatein the source Docbase, then rearchives the DocApp; then you can reinstall the DocApparchive.


Workow template will not be audited

Workow template will not be audited

Purpose Indicates that the specified workflow template will not be audited.

Error MessageWorkflow Template ’workflow_template’ will not be audited

DescriptionThe specified workflow template cannot be audited because a user did not have theConfig_audit privileges. Installation continues. See the User does not have privilege toconfigure audit error message.

SolutionUse EMC | Documentum Administrator to give the user Config_audit privileges.


XML application already exists at the same location


Purpose Indicates a warning that the XML application already exists at the same location.

Error MessageWarning: The XML Application xml_application already exists atlocation current_location. The current application will be installedin location new_location.

where:

xml_application is the name of the XML application.

current_location is the existing XML application’s folder path in the target Docbase.

new_location is the folder path in the target Docbase where the XML application will beinstalled.

DescriptionThis is only a warning message. This warning occurs when the XML application alreadyexists in the same location.

SolutionNo other action is required.




Index

AabortTransaction method, 93Action function, 214actions, 210

change content storage, 215activity templates

inserting, 44installation, 44

adding, 139new functionality, 139

alias sets, 51, 195, 197copying, 46creating and modifying, 52cutting, 46default for DocApp, 54installation options, 36pasting, 46

alias valuesmulti-byte characters, 52

aliases, 227, 229folders or cabinets do not exist, 335groups do not exist, 336, 357location, 237not in default alias set, 325owner, 239permission sets, 240resolving, 227, 229, 231scopes, 197users do not exist, 357

ALL keyword, 154ANY keyword, 154API calls to server, 79Application Builder

user interface, 251application code, 207application events, see events, applicationApplication Installer, 227

using, 227Application Support Documents

folder, 175

creating, 183application_code

dm_state_type, 207applications, 19Applications, 40, 238archives, 43, 227

cannot be found, 331creating, 43installation options, 36

aspects, 83attachment, 195attributes, 125, 143, 145, 217

Advanced tab, 145attribute category, 145attribute lifecycle, 145deleting, 156displaying in Documentum

clients, 129example of creating, 256input masks, 145 to 146locale-sensitive fields, 35object type, in data dictionary, 136search characteristics, 147search options, 145specifying constraints, 150value assistance, 151, 154$value keyword, 152value mapping tables, 155

auditable events, see eventsauditing

no privileges, 356

Bbad argument index, 326base state (business policy)

returning to, 195beginTransaction method, 93best practices

caching repository objects, 94extending DFC interfaces, 101


Index

extending TBOs, 101remapping Documentum types, 101reusing SBOs, 94SBO state information, 94UPDATE queries, 102

business policy statesbase state

returning to, 195Business Process Manager (BPM)

best practices, 44workflow templates, adding, 49

Ccabinets, 241

do not exist, 335inserting, 56installation options, 36

caches, 94See also persistent caching

cancelling checkout, 45Cannot read a required file, 330casting, 103Ccabinets, 56change content storage action, 215check-in validation option, 49check-in validation option prompt, 49checking in/out, 26, 44 to 45

cancelling, 45chunking, 174class loaders, 72ClassCastException class, 72COM (Microsoft component object

model), 100commitTransaction method, 93components, 65, 220

ActiveX, 65, 220adding as new functionality, 139deleting as new functionality, 140functionality, specifying, 140installation options, 36qualified, 65, 218, 220replacing inherited functionality, 138

connecting, 25connecting to Docbases, 227constraints, 34, 125, 134

attributes, 150object types, 134

content, 241moving to file stores, 215

content transfer options, 241content-addressable stores

moving content to, 215copying objects, 46creating, 26

alias sets, 52archives, 43attributes, 143, 145DocApps, 26DocApps, example of, 254document lifecycles, 48formats, 59formatswith digital assetmanagement

attributes, 61jobs, 75modules, 79, 113object types, 254permission set templates, 158procedures, 161relation types, 167

cutting objects, 46

Ddata dictionary, 34

locale-sensitive attributes, 35publishing, 33

data model, 57DBOR (Documentum business object

registry), 83DcDesktopClient

installing, 20Ddata dictionary, 35deleting

attributes, 156new functionality, 140objects from DocApp, 47objects from Docbase, 47

demotion. See transitions, 194designing

attributes, example of, 256DFC

obtaining object type information, 137DfCollectionEx class, 91DfDborNotFoundException class, 94DfDocument class, 95 to 96, 101DfNoTransactionAvailableException

class, 92DfPersistentObject class, 99DfService class, 83, 87 to 88, 90


Index

DfServiceCriticalException class, 94DfServiceException class, 94DfServiceInstantiationException class, 94DfServiceNotFoundException class, 94DfSysObject class, 99digital asset management, 61disabling

inherited functionality, 139dm_format, 59, 61dm_relation_type, 167dm_state_type, 207

application_code, 207state_type_name, 207

dmc_jar type, 71dmc_module type, 71, 82DocApp

locked, 332DocApp application, 40, 238DocApp archives, 20, 227

installing, 282selecting, 227

DocApps, 125alias sets, 20changing national languages, 32changing permission sets, 47creating and removing links, 48creating archive for, 43creating or modifying, 26default alias set, 54deploying, 280example of creating, 254installation options, 36, 280making copies of, 28opening from file system, 26packaging for deployment, 20planning, 19properties, 28redeploying, 51saving changes to file system, 27tutorial, 252versions, 26, 32

Docbases, 227connecting to, 227target; preparing, 229

Docbasic, 204, 209 to 210, 214, 216Docbasic programs, 161document lifecycles, 48, 174, 193, 201, 205

alias sets, 197and alias sets, 51cannot attach object, 327

creating, 48exception state (not attachable), 350installation options, 36modifying, 48not in installed state, 333overview, 191relation to workflows, 192state does not exist, 349state not attachable, 351versions, 199

documents, 55inserting, 55installation options, 36renditions, 39, 55, 242virtual documents, 39, 56, 242

Documentum Application Builder, 174drop-down lists

See value assistance., 249, 285DTD member files, 178duplicate objects

how installed, 236

Eelements

<app_pattern>, 178<application>, 178<import>, 178<name>, 178<pub_id>, 178<schema>, 178<sys_id>, 178

email templatesinserting, 44installation, 44

entitiesparameter, 178 to 179

EntryCriteria function, 209error messages, 321events

application, 141events, application

creating, 135deleting, 135modifying, 135

External Interfaces folder, 71

Ffactory methods, 87, 96 to 97


Index

file storesmoving content to, 215

files, 27opening DocApps from, 26saving DocApp changes to, 27

FIRST keyword, 154folders, 56, 229, 241

do not exist, 335inserting, 56installation options, 36

form templates, 57adding, 58

format, 59, 61advanced tab, 61digital asset management, 61full-text indexing, 61

formatsinstallation options, 36

forms, 65, 220creating and modifying, 66installation options, 36

forms, Documentum Forms Builderarchiving, 44

FOSI, 175, 179functionality, 138, 218

adding new, 139deleting new, 140disabling inherited, 139modifying inherited, 138restoring inherited, 139

functionality classes, 196

GgetClient method, 96getDocbaseNameFromId method, 90getLocalClient method, 102getResourceAsStream method, 113getSession method, 89, 92 to 93, 103getSessionManager method, 90, 97, 103getStatistics method, 91getTransactionRollbackOnly method, 91getVendorString method, 88, 98getVersion method, 88, 98global components list

modifying, 49groups, 69, 220, 229

adding, 69do not exist, 336, 357installation options, 36

IIAPI

obtaining object type attributeinformation, 137

obtaining object type information, 136IDfBusinessObject interface, 83, 96 to 98IDfDynamicInheritance interface, 96, 98IDfLoginInfo interface, 102IDfModule interface, 83IDfService interface, 83, 87 to 88IDfSessionManagerStatistics interface, 91IDispatch interface, 101IDL files, 101init method, 99input masks, 146

specifying for attributes, 145installation directories

Documentum, 230installation options

overview, 280installation process, 233Installation Status window, 245installer log file, 245installing, 36

activity templates, 44DocApps

options for, 36email templates, 44

isCompatible method, 88, 98isTransactionActive method, 91 to 92

JJAR files, see Java archive filesJava archive (JAR) files, 71, 113jobs, 75

creating and modifying, 75installation options, 36viewing, 77

LLAST keyword, 154lifecycles, 145

See also attributes; document lifecycleslinks, 48locale, 32 to 33, 35locales

information not available forDocbase, 338


Index

not in Docbase, 339localization, 35location

aliases, 237aliases, no value for, 341

logging in to Docbasedomain, 227

loginfailed, 340

Mmasks, see input masksmetadata

extracting, 174methods, 79

installation options, 36modifying, 26

alias sets, 52attribute search characteristics, 147attributes, 143, 145DocApps, 26document lifecycles, 48formats, 59, 61formatswith digital assetmanagement

attributes, 61global components list, 49inherited functionality, 138jobs, 75modules, 79, 113permission set templates, 158procedures, 161properties, 28relation types, 167workflow templates, 49

modules, 82 to 83creating and modifying, 79, 113overview, 81

Modules folder, 83multi-byte characters

in alias values, 52

Nnaming conventions, 87national language, 33.NET platform, 82New Application prompt, 49newService method, 87, 102 to 103newSessionManager method, 102

Oobject types, 125, 217

attributes, 125, 217constraints, 125, 134creating or modifying, 127definition of, 125deleting from DocApp, 136example of creating, 254functionality, 125, 218locale-senstive fields, 35modifying functionality, 140security, 125, 134viewing in data dictionary, 136

objectsdeleting from Docbase, 47duplicate, 37, 237duplicate, how installed, 236installation location, 237installed by different user, 344installed with cabinets/folders, 241installed with XML applications, 241locked, 344not overwriting, 236overwriting, 236owner aliases, 239owners, 239path does not exist, 345permission sets, 240removing from DocApp, 47versioning, 236

opening, 26DocApps from file system, 26

overriding DfSysObject methods, 99overview, 225owner aliases, 239

no value, 342owners

of objects, 239

Pparameter entities, 179

external, 178pasting objects, 46permission set aliases

no value, 343permission set templates, 157permission sets, 31, 229

aliases, 240


Index

changing for sysobjects andDocApps, 47

copying, 46cutting, 46default for object type, 134do not exist, 346installation options, 36not owned by user, 347pasting, 46templates, 158

post-installationprocedures, 42, 243

PostProc function, 216pre-installation

procedures, 42, 243privileges, 227procedure

validation, 204procedures, 161, 205, 208, 210

creating and modifying, 161failed, 348installation options, 36, 162post-installation, 36, 42, 162 to 163,

243, 337pre- and post-installation, 281pre-installation, 36, 42, 162 to 163,

243, 337promotion. See transitions, 194Prompt for Value at Installation

option, 229properties, 28

modifying, 28Properties file, 231

cannot find, 328public identifier, 178publish_dd method, 33publishing locales, 33

Qqualified components, 65, 218, 220

Rrelation type, 167relation types

installation options, 36releaseSession method, 89, 103removing

objects from DocApp, 47

renditions, 39, 55, 242repeating value attributes, 154

constraint and value assistancekeywords, 154

repositories, 82repository metadata

extracting, 174resumption. See transitions, 195return_to_base attribute, 195roles, 171

adding, 171installation options, 36

root elements, 178

Ssandboxing, 72saving, 27

copy of DocApp, 28DocApp changes to file system, 27

SBOs, see service based objectsschema members, 178schemas, 178scope definitions

creating, 133deleting, 133modifying, 133

scopescreating, 132deleting, 132modifying, 132

search characteristics, 147attributes, 147search operators, 147

search optionsspecifying for attributes, 145

security, 69, 171selecting DocApp archives, 227service based objects (SBOs), 86

architecture, 87implementing, 88instantiating, 94, 102returning TBOs, 103session manager, 103specifying a repository, 90threads, 102transactions, 91

session managers, 87internal statistics, 91transactions, 92


Index

setDomain method, 102setIdentity method, 102setPassword method, 102setSessionManager method, 103 to 104setTransactionRollbackOnly method, 91

to 92setUser method, 102simple modules, see modulesSmartlists, 55starting Application Installer, 227, 229state information, 87 to 88, 90, 101state types

specifying, 207state_type_name

dm_state_type, 207states

actions, 210attachment, 195attribute constraints, 196entry criteria, 208entry procedure, 210functionality, 196normal and exception, 193post-change procedure, 216

status bar, 32locale, 32

supertypes, 127superuser privilege, 227supporting files, 175, 179supporting files, XML

adding, 183supportsFeature method, 98suspension. See transitions, 195Sysobjects

changing permission sets, 47copying, 46creating and removing links, 48cutting, 46installation options, 36pasting, 46

system identifier, 178

TTBOs, see type based objectsTEOs, see aspectsthreads, 92TLB files, 101transactions

nested, 92

transitions, 194 to 195troubleshooting, 245tutorial

creating types, 254design of DocApp, 252overview, 249, 285prerequisites, 250, 286software requirements, 250, 286

type based objects (TBOs), 94 to 95extending, 101implementing, 97interfaces, 97, 100 to 101returning from SBO, 103

type extension objects (TEOs), see aspectstypes, 236

cannot find, 329, 352

UUPDATE queries, 102upgrade options, 37, 236upgrading objects, 37, 236user chose not to continue, 353user interface (UI), 57users, 229

do not exist, 354 to 355, 357no privileges to configure audit, 356

using Application Installer, 227

Vvalidation

of XML application configurationfile, 174

validation procedure, 204ValidationProc function, 204value assistance, 151, 154

conditional, example of creating, 257example of creating, 257

$value keyword, 152value lists, 151value mapping tables, 155version differences, 96 to 97versions, 26, 32, 44View/Edit prompt, 49virtual document, 39, 56, 242

WWeb content management, 174workflow template


Index

not audited, 362workflow templates

adding, 49See also Business Process Manager

(BPM)cannot be in installed state, 358creating, 274installation options, 36not in installed state, 360not validated, 359not validated or installed when

archived, 361reject flows, 276tutorial, 274

workflowsrelation to document lifecycles, 192

wrappersfor non-XML documents, 174

XXDQL, 174

XMLapplication detection, 181DTD patching, 181XML configuration file, 188

XML application configuration file, 174,178

XML applications, 241already exists at the same location, 363benefits of using, 173checklist, 177components, 174configuring, 174creating, 175, 179installation options, 36modifying, 187

XML Configuration File Editor, 174 to 175XML content management in

Documentum, 173XML Sample Documents folder, 175XSLT, 174XSLT stylesheets, 175, 179
