Introduction

A lifecycle in Documentum defines a chain of states that a document can pass through during its lifetime. Each state has a name, like “Draft”, and can be configured to perform certain actions as documents enter or leave it. Lifecycles can be built, maintained, and packaged for deployment using Documentum Developer Studio. Lifecycles should not be confused with Workflows which route tasks among users and are built using Documentum Workflow Manager.

Lifecycles are stored as dm_policy objects in the docbase. A document can be attached to only one lifecycle at a time. A document’s lifecycle and current state are stored in its r_policy_id and r_current_state attributes. R_policy_id contains the r_object_id of the currently attached lifecycle while r_current_state contains the index of the state that the document is in.

The following exercise shows the steps for creating and installing a simple lifecycle…

Step1: Open Developer Studio, Create a New DocApp

1. Open Documentum Developer Studio and log in to your Docbase using a superuser account.
2. From the initial “New Application” dialog, select “Create New DocApp” and then enter a name like “lifecycle_test” for the new DocApp. Do not use spaces in the DocApp name or Developer Studio won’t be able to reopen it.
3. A new DocApp should open in Developer Studio showing a tree view on the left. The tree-view displays all of the objects that are a part of this DocApp. The key icon next to the root node means that this Docapp is currently checked-out to you.

Step 2: Add a New Lifecycle to the DocApp

1. From the Developer Studio file menu, select “Insert->Document Lifecycle”. A new lifecycle object named “Lifecycle1” should appear in the left-hand tree view under the “Document Lifecycles” folder.
2. Right-click the new “Lifecycle1” object and select “Edit”. The lifecycle editor dialog should open in the right pane of Developer studio.
3. Change the name of the lifecycle by typing something like “my_lifecycle” in the “Name” text box.
4. Change the primary type of the lifecycle to “dm_document” by pressing the “…” button next to the “Primary Type” text box. In the pop-up dialog that appears, select “dm_document” from the top pick-list and click “Ok”. Don’t add any sub-types. This setting determines what object types can be attached to the lifecycle.

Step 3: Add States to the Lifecycle

1. From the lifecycle editor dialog, press the “Add State” button four times. You should see four blue polygons appear representing four new lifecycle states (see below).

   
   Figure 1

2. Right-click the first blue polygon labeled “S1”, and choose “Edit State”. A new dialog, the state editor, should appear over the lifecycle editor.
3. On the “General” tab of the state editor, rename the state “Start State” by typing over “S1” in the “State Name” text box. Close the state editor.
4. Now edit the second state, “S2”, and change its name to “State Two” on the “General” tab. Don’t close the state editor yet.
5. On the “Entry Criteria” tab, press the “Add Value Test” button. This is where we will add an attribute test. Attribute tests test the values of specified attributes for required values. If a document fails an attribute test it cannot enter the lifecycle state.
6. Select the “title” attribute from the left pick-list. Then select the “<>” operator from the next pick-list. Leave the right-hand text box blank. This creates an entry-criteria requiring that the title not be blank upon entry of “State Two”. Now close the state editor for “State Two”.

   
   Figure 2

7. Select the third state, “S3”, and change its name to “State Three” by typing over “S3” in the “State Name” box.
8. On the “Actions” tab of “State Three” press the “Add Action” button. A “Define Action” dialog should pop up. On the “Define Action” dialog, select “Add Version Label”. In the “Label to Add” text box type “Draft” and click “Finish”. This will cause a “Draft” version label to be added to the document as it enters this state.
9. Rename the last state, “S4” , to “State Four” on the state’s “General” tab.
10. Now close the lifecycle editor. In the left-hand tree view, right-click “my_lifecycle” and choose “Check in Object(s)”. Check in the lifecycle as the same version (1.0).

Step 4: Install and Test the New Lifecycle

Now that we have defined a lifecycle, we have to Validate and Install it before it can be used.

1. Right-click “my_lifecycle” in the left-hand tree view and select “View”.
2. Press the “Validate” button on the lifecycle dialog. The label on the “Validate” button should change to “Install”.
3. Press the “Install” button. The lifecycle is now installed and can be used by dm_documents.
4. To test the lifecycle, open Desktop Client and log in to the Docbase.
5. Create a new dm_document. Don’t set the title attribute yet because we want to see the document fail the entry-criteria for State Two. Check in the new dm_document.
6. Right-click your new dm_document and choose “Document Lifecycle->Apply”. Pick “my_lifecycle” from the pick-list of available lifecycles and click “Apply”.
7. Now right-click the dm_document again and view its properties. On the “Advanced” tab you should see that the document is attached to “my_lifecycle” and is in “State One”. Close the properties dialog.
8. Right click the dm_document again and select “Document Lifecycle->Promote”. Click “Ok” in the next dialog telling you that the document is about to be promoted from “State One” to “State Two”. This should generate an error because we specified that the title attribute cannot be blank on entering “State Two”.
9. Go to the Properties dialog of your dm_document and set the title to something other than blank.
10. Try to promote the dm_document again. It should work this time because the entry criteria has been satisfied.
11. Now promote the dm_document to “Step Three”. This promotion should set the version to “Draft”. You can verify this by viewing the document’s “Version” tab on the properties dialog.

That’s the end of this example. You can promote your document on to “State Four” or you can unattach the lifecycle by right-clicking your document and selecting “Document Lifecycle->Remove”.

Calling Procedures from Lifecycles

In addition to using the predefined actions like “Add Version Label”, you can add calls to your own custom procedures at various points during a lifecycle state transition. Creating procedures is beyond the scope of this article, but if you want to learn more about it, look in the Documentum Docbasic Reference. There are three opportunities to make a custom procedure call during a single state transition: 1.) Immediately after the attribute tests, 2.) Immediately after the standard actions are performed, and 3.) Immediately after the actual state change. Defined below are the function signatures used for each of the three procedure call types. Don’t forget to provide a boolean return value in your functions.

Public Function EntryCriteria (ByVal String SessionId, ByVal String ObjectId, ByVal String UserName, ByVal String TargetState, ByRef String ErrorString) As Boolean

EntryCriteria = True ‘If you return False, the state transition is canceled and the user sees the ErrorString.

End Function

Public Function Action (ByVal String SessionId, ByVal String ObjectId, ByVal String UserName, ByVal String TargetState, ByRef String ErrorString) As Boolean

Action = True

End Function

Public Function PostProc (ByVal String SessionId, ByVal String ObjectId, ByVal String UserName, ByVal String TargetState, ByRef String ErrorString) As Boolean

PostProc = True

End Function