Workflow and Lifecycle essentials

Soumya Mitra

Abstract: This document explores the Lifecycle and Workflow of Content Server.

Date 10/24/2007
Copyright © 2006-2007 EMC Corporation. All rights reserved.
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without
notice.
THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO
REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION,
AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE.
Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
EMC2, EMC, and EMC Documentum product names are trademarks of EMC Corporation. All other trademarks used herein are the
property of their respective owners. All other brand names are trademarks or registered trademarks of their respective owners.

Workflow and Lifecycle essentials 2

Workflow and Lifecycle
Content Server provides powerful features for implementing business process with the stored digital assets.
These features are Lifecycle and Workflow. Apparently they may appear similar from their ability to
invoke predefined server process while the document passes through different lifecycle stages or workflow
activities. However, they are fundamentally different from each other in the following ways-

Lifecycle
It is not possible to route document to any user’s in-
box.
There is no task related to any document lifecycle,
so it is not possible to implement complex business
logic.
Lifecycle state progresses sequentially from start to
end.
Can not handle multiple documents deriving from
different parents. It can only handle dm_sysobjects
and its sub types.
Lifecycle is a flag to indicate the state of a single
document like draft – reviewed – final – approved.
Workflow
Routes documents to single or multiple users in-
box.
Users need to perform a predefined task on the
routed document.
Workflow can have complex network of task flow
to implement a business rule.
Can route any document types.
Workflow is not concerned with any state of the
packaged documents. It just controls the flow of the
package through the business rule network.

Lifecycle State
A lifecycle is a set of linearly connected states of an object’s life. An object attached to a lifecycle
progresses through the states like “Draft”, “Review”, “Approved” as it moves through its lifetime. A
change from one state to another is governed by business rules. These rules are implemented using Server
methods and get triggered when the document enters, dwells or leaves the state.

Lifecycle State of the state

At any point, the state of a document associated to a lifecycle can have two states- “normal” or
“exception”. Normal state is the typical state of an object’s life. Exception state represent situation outside
of the normal states of an object’s life. All lifecycles must have normal states. Exception states are optional.
Each normal state in a lifecycle definition can have one exception state.

If an exception state is defined for a normal state, when an object is in that normal state, you can suspend
the object’s progress through the lifecycle by moving the object to the exception state. Later, you can
resume the lifecycle for the object by moving the object out of the exception state back to the normal state
or returning it to the base state.

Lifecycle stage criterion

Each stage in a lifecycle may have three criterions-
1. Entry criteria
2. Actions on entry
3. Post-entry actions.

Workflow and Lifecycle essentials 3

Entry criteria are typically conditions that an object must fulfill to be a candidate to enter the state.
Actions on entry are typically operations to be performed if the object meets the entry criteria. For example,
changing the ACL might be an action on entry. Both entry criteria and actions on entry, if present, must
successfully complete before the object is moved to the next state.

Post-entry actions are operations on the object that occur after the object is successfully moved to the state.
For example, placing the object in a workflow might be a post-entry action.

Can we set a lifecycle permanently to an object type?

This feature is not present OOTB. However, you may achieve this by writing a SBO, that would extend the
checkin/import functionality and apply a lifecycle to the document on checkin or import. The component
exchange on the developer site has an example on this topic under Apply Lifecycle on Checkin. You can
use this as a starting point.

Objects used in LifeCycle

Lifecycle is defined by using the tool DAB. It provides a graphical user interface to visually design the
states and define the state criterion. The lifecycle definition is stored in dm_policy object. The attributes of
the object define the states in the lifecycle, the object types to which the lifecycle may be attached, whether
state extensions are used, and whether a custom validation program is used.

How state transition takes place

Lifecycle state transition can take place in two ways-
1. Manual transition is performed by a user, who can use a client tool like Webtop to trigger the state
transition.
2. Scheduled transition is preprogrammed in the Lifecycle definition. In this case the transition from
one state to another is triggered by a timer. For example, we can define, once a document enters in
the “final” state, it will remain at that state for three years. There after it will auto transition in to
archived state.
Both manual and scheduled transitions move the object between states in a lifecycle through
promotions, demotions, suspensions, and resumptions. Promotions and demotions move objects
through the normal states. Suspensions and resumptions are used to move objects into and out of the
exception states.

Java Lifecycle
DCTM lifecycle has entry, action and postchange event where we can specify a procedure to execute. This
procedure can be a docbasic procedure or can be a Java procedure. These Java procedures have to be
implemented as BOF and stored as modules in the Docbase. They are located at docbase folder
/System/Modules/Lifecycle. Each module contains a dmc_jar docbase object whose content is a jar file
implementing one or more of the following interfaces.
• IDfLifecycleUserEntryCriteria
• IDfLifecycleUserAction
• IDfLifecycleAction
• IDfLifecycleUserPostProcessing
• IDfLifecycleUserValidate

You can not mix and match Docbasic and Java methods in a single lifecycle. Programs written
for the entry criteria, actions on entry, and post-entry actions for a Lifecycle must be either all
Java or all Docbasic.

Workflow and Lifecycle essentials 4

What happens during a request to attach an object to a Lifecycle?
In response to an operation like attach or promote, the Server will invoke the dm_method object named
dm_bp_transition_java. The dm_bp_transition_java method runs in the Java Method Server. In cases of
failure, check the log files in $DM_HOME/tomcat/logs for error messages. This method invokes the BOF
modules as specified in the lifecycle definition.

The launch of dm_bp_transition_java can be traced by setting the attribute trace_launch to T.

The Server log file will contain the trace output

Tracing of lifecycle
There are two ways to trace the Java Lifecycle methods.
1) Pass the argument –debug true in the repository method dm_bp_transition_java.
2) Enable log4j tracing in the dfc.properties file.

Location of trace output files

1) When using –debug true with the repository method, the trace output goes to bp_transition_<session
ID>.out in $DOCUMENTUM/dba/log/<repository ID>/bp
2) When set in log4j.properties, the trace file location is controlled by the properties file.

Workflow
Workflow is actually a business process involving documents passing through various activities and
moving from one business state to another. The workflow can be defined visually through two tools:-
Workflow manager and Business Process Manager (BPM). The workflow definition is stored in the
Docbase. It consists of one process definition and several activity definitions. The process definition is
stored as dm_process object and each activity definition are stored in individual dm_activity objects. We
can think the dm_process and dm_activity objects as the template of the workflow.

When a workflow is initiated by a client application, Content server creates an instance of the workflow by
creating several workflow object types:-

• dm_workflow --- workflow instance

• dmi_workitem --- activity instance
• dmi_package --- package instance
• dmi_queue_item --- inbox notification instances
• dmi_wf_timer --- instance of activity timer

Workflow objects are subtypes of the persistent object type, and consequently, have no owner. However,
every workflow has a designated supervisor (recorded in the supervisor_name attribute).

Workflow and Lifecycle essentials 5

How to design a workflow?
Workflows can be designed by using two
tools- Documentum Application Builder
or Business Process Manager. Both of
them are stand alone Java Swing
applications and provide a graphic user
interface to visually design the workflow
activity network. The arrow line shows the
flow of packages (Documents) from one
activity to another.
A Documentum server method can be
triggered by any activity. This is how the
business logic is implemented in a
workflow.

Work Flow Designer Screen

Sometime a server method fails to show up in Workflow Designer screen while

configuring the activity. This is because all method objects have an attribute
a_special_app, and this attribute must have a value of "Workflow" in order for it to show
up in the workflow manager. The following DQL can be used to update the attribute
UPDATE dm_method OBJECT SET a_special_app='Workflow' WHERE
r_object_id='<object id of method object>'
or

UPDATE dm_method OBJECT SET a_special_app = 'Workflow' WHERE

object_name = '<whatever>'

How to get the running workflow instance ID?

To obtain the workflow template object id:
select r_object_id from dm_process where object_name = '<workflow template name>'

To obtain the running instances of that specific workflow template.

select * from dm_workflow where process_id = <'workflow template object id'>

Activity instance state

When a workflow instance is executing, it passes through several states. It is important to understand the
phase transition. The figure below shows the phase transition diagram.

Workflow and Lifecycle essentials 6

As we can see from the diagram, a workflow instance moves to a failed state whenever it encounters any
error condition. It remains in that state unless it is restarted again.

Workflow Agent
For performance enhancement, all automatic activities of a workflow are handled by a separate thread-
called Workflow Agent. The Workflow Agent spawns a number of worker threads and assigns each
automatic activity to a separate worker thread. The way it works is:-

1. As soon as an automatic activity is launched, it is added to the task queue.

2. Content Server notifies the workflow agent. Otherwise workflow agent periodically polls the task
queue every after a preset sleep interval.
3. Workflow agent scans the task queue and assigns the task ID to a free worker thread.
4. Worker thread sets the session status to running, checks task state & locks it down, executes the
acquired task and then sets session status to idle to indicate that it is free to perform another
activity.

The Workflow Agents runs a query to locate automatic workflow task that are queued for execution. The
query used is:

select all r_object_id, r_workflow_id, r_runtime_state, r_creation_date

from dmi_workitem
where r_runtime_state in (0,1) and
r_auto_method_id != '0000000000000000'
and r_exec_launch = 0
order by r_priority desc, r_creation_date desc

This will return the newest (most recent) workflow tasks if all automatic tasks have the same priority. That
means the most recent automatic task will run first.

Workflow and Lifecycle essentials 7

The diagram below shows the interaction between the various components of CS during execution of
automatic activity of a workflow.

We can tweak the workflow agent’s performance by:

• Changing the number of worker sessions

• Changing the sleep interval
• Disabling the workflow agent

For trouble shooting the workflow agent, we can turn on the workflow agent trace (See Appendix Server
Traces). Trace output goes to server log file. Use following IAPI call to turn it on:-

Apply,c,null,SET_OPTIONS,OPTION,S,trace_workflow_agent,VALUE,B,T

Why all automatic activities are not running anymore?

There was a server upgrade bug from pre 5.2.5 version to 5.2.5 or higher. The upgrade process
incorrectly sets the value of the wf_worker_agent_threads to 0. If you are seeing this problem and
have done a server upgrade recently, then check the value of the wf_worker_agent_threads on the
server config object. If it is set to 0, then set this attribute to a value of 3 or higher and then restart
the server. That should fix it.

It is possible to setup multiple workflow agent worker thread. See consult support note 16501 to
get steps for it.

If run into any problem because of parallel execution of automatic tasks, set
wf_agent_worker_threads to 1 should correct the problem. Please remember to recycle the CS to
after making the change.

Workflow and Lifecycle essentials 8

What permission is required to use workflow?
Following are the permission requirement to author and use a workflow

Activity Permission / Role

Create a workflow Superuser, Sysadmin, coordinator
User of a workflow Contributor
View available workflows Read permission on the workflow object
(dm_process)

Workflow Server Trace

Workflow Agent trace is logged in the server log, with one line per worker session as show below:-

Thu Nov 20 16:35:44 2003 687000 [DM_WORKFLOW_I_AGENT_START]info: "Workflow agent

worker (tid : 3100, session 012007898000000a) is started sucessfully."
Thu Nov 20 16:35:45 2003 687000 [DM_WORKFLOW_I_AGENT_START]info: "Workflow agent
worker (tid : 3112, session 012007898000000b) is started sucessfully."
Thu Nov 20 16:35:46 2003 687000 [DM_WORKFLOW_I_AGENT_START]info: "Workflow agent
worker (tid : 3124, session 012007898000000c) is started sucessfully.“

– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
4a20078980016101
– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
– WORKFLOW AGENT TRACE :
4a20078980016104
Agent master found new tasks without waiting.
Agent master assigning work item 4a20078980016101
Worker session 012007898000000b processing work-item
There are 1 active threads.
There are 1 active threads.
Workflow Agent is waiting for new tasks.
Notifying Workflow Agent of new tasks.
Workflow Agent is notified of new tasks.
Workflow Agent is waiting for new tasks.
Notifying Workflow Agent of new tasks.
Workflow Agent is notified of new tasks.
Agent master assigning work item 4a20078980016104
Worker session 012007898000000c processing work-item

if the attribute "save execution" results is set to True, on the specific automatic activity in
the Workflow, then if the method fails, a log is created at documentum\dba\log

BPM and Workflow

BPM and BPS adds more automation capability to workflow. They offer a rich set of SBOs which enables
us to perform activities like sending and email or waiting for an email notification in a workflow. BPM
offers a GUI to visually design a Workflow like the Workflow Designer tool. It is a superset of Workflow
designer, so if you use BPM, there is no need to use the Workflow Designer.

The following example illustrates how we can easily implement wait for an email capability in a
Workflow:-

1) Create a workflow using BPM, which sends out an email.

2) Add a manual activity immediately after sending the email. This will be so called ‘blocking
activity’. It will keep on waiting till a specific event happens.

Workflow and Lifecycle essentials 9

 3) In the manual activity, define its trigger as a particular custom event say myEvent
4) Write the code for myEvent. The easiest way to do so will be customizing the out-off-the-
box BPS example handler CompleteActivityService. It has all necessary code, just put the
new event name as myEvent.
5) Compile the handler and register it as CompleteActivityHandler SBO.
6) In BPS, create a new mail account following the BPS email convention id-handlername-
connection@server for this CompleteActivityHandler
7) Install and run the workflow. It will wait for an incoming email reply, after sending out an
email.
8) As soon as an email arrives at the account, the CompleteActivityHandler will be invoked. This
will trigger the myEvent event and unblock the manual activity of the workflow.

Summary- Workflow and Lifecycle in nutshell

Workflow and Lifecycle are two powerful features of Documentum Repository. They allow us to
implement business process for the digital assets stored in the repository.

Lifecycle allows us to define and flag various states of a digital asset like “draft” – “review” – “approved”
etc. It also allows us to define sequential transition rule from one state to another.

Workflow does not flag or care about the state. It allows us to define a business rule by graphically drawing
a network, depicting how the digital asset would be routed from one user to another from start to end. It
also offers conditional branching.

Both Workflow and Lifecycle are executed at content server side. All errors for Workflow and Lifecycle
are captured in the Content Server Log.

In real life scenario, both Lifecycle and Workflows are used in Tandem to implement business logic for a
type of digital asset in an enterprise.

Test Questions
1. What are two key differences between Workflow and Lifecycle?
2. Which thread executes the automatic Workflow activities?
3. Which tool is used to design a Lifecycle?
4. Which are the tools you can use to design a Workflow?
5. How many documents can be attached to a Lifecycle?

Workflow and Lifecycle essentials 10

About EMC
EMC Corporation (NYSE: EMC) is the world leader in information storage systems, software, networks,
and services, providing automated networked storage solutions to help organizations get the maximum
value from their information, at the lowest total cost, across every point in the information lifecycle.
Information about EMC’s products and services can be found at www.EMC.com

About Documentum Software from EMC

Documentum software from EMC Corporation includes enterprise content management solutions that
enable organizations to unite teams, content, and associated business processes. With a single platform,
EMC Documentum software enables people to collaboratively create, manage, deliver, and archive the
content that drives business operations, from documents and discussions to e-mail, Web pages, records, and
rich media. The Documentum enterprise content management platform makes it possible for companies to
distribute all of this content in multiple languages, across internal and external systems, applications, and
user communities. As a result of deploying Documentum, thousands of the world’s most successful
organizations are harnessing corporate knowledge, accelerating time to market, increasing customer
satisfaction, enhancing supply chain efficiencies, reducing operating costs, and improving their overall
competitive advantage.
For more information about Documentum enterprise content management, visit
www.emc.com/documentum or call 800.607.9546 (outside the U.S.: +1.925.600.5802).

Workflow and Lifecycle essentials 11