Lifecycle Policies
A document lifecycle policy is an object that defines the "life" of a document in terms of phases or states through which the document cycles. The states are user-defined, and, when one state moves to another, a lifecycle-related system event fires. The event is handled by a lifecycle action, which is a user-implemented, server-side component. For example, you might have a lifecycle policy that defines five states for loan application documents: Application, Approval, Funding, Servicing, and Closed. The policy would also define a lifecycle action. Each time a user changed the state of a loan application, the lifecycle action would be started and do something based on the application's new state.
To be useful, a document lifecycle policy must be assigned to documents,
either to individual Document
objects, or to the Document
class
or any of its subclasses. A document or class can have at most one
lifecycle policy that is associated with it. A Document
object
includes a changeState
method for moving the object
from one state to another, and a CurrentState property for getting
the current state of the object.
When you create a Document
object of a class type
that is associated with a lifecycle policy, the policy is automatically
assigned to the new document. To override the class-assigned lifecycle
policy, you must specify a different lifecycle policy when you create
the document.
Document
object, you can
assign a document lifecycle policy to it only when you create the Document
object;
you cannot update an existing Document
object with
a document lifecycle policy.You can create document lifecycle policies and retrieve them. For document lifecycle policy code examples, see Working with Lifecycle-related Objects.
Lifecycle Policy Setup Requirements
A document lifecycle policy is
represented by a DocumentLifecyclePolicy class. You instantiate
an object with the Factory.DocumentLifecylePolicycreateInstance
method,
then set the following key properties:
- The display name of the lifecycle policy to identify it (DisplayName property).
- The list of user-defined states through which a document can move (DocumentStates property). See Document States.
- The lifecycle action object that represents the actions that are taken when a document's state changes (DocumentLifecycleAction property). See Lifecycle Actions.
You can also set lifecycle policy properties that specify:
- Whether direct-access control entries (ACEs) are preserved on
a document when a lifecycle policy is applied to the object (PreserveDirectPermissions
property). You can define extra state-dependent security for a document
by setting the TemplatePermissions property of one or more
DocumentState
objects. When the document moves to a state on which permissions are applied, the state-defined permissions are then applied to the document. Therefore, if the PreserveDirectPermissions property is set to FALSE, a document's direct permissions are effectively ignored.For a code sample that includes setting the PreserveDirectPermissions property, see Creating a DocumentLifecyclePolicy Object. For general information on setting permissions, see Working with Security.
- Whether to reset the lifecycle state of a document to the initial state upon a new version check-in, or to maintain the lifecycle state of the document from one version to the next (ResetLifecycleOnCheckin property).
For more information, see DocumentLifecyclePolicy Properties.
Document States
A document state is the status of a document at a given point in time. Typically, documents with states are used collaboratively, with different users responsible for putting a document into a particular state, until the document moves through all of its states, therefor completing its lifecycle. For example, a loan application document might move through the following states to complete its lifecycle: Application, Approval, Funding, Servicing, and Closed. Document states are user-defined and move linearly. A document can be moved either forward (promoted) to its next state or moved backward (demoted) to its previous state.
A document state is represented by
a DocumentState object. It includes properties for
naming the document state and for indicating whether the state can
be demoted. It also includes the TemplatePermissions property for
setting permissions on a document; that is, when a document moves
to a state where permissions are defined, the permissions are applied
to the document. DocumentState
objects are added
to a DocumentStateList object, which is set on the DocumentLifecyclePolicy
's
DocumentStates property.
To move through the states of
a document, you call the changeState
method on a Document object. The method takes a LifecycleChangeFlags constant that specifies the
state to apply to the document. In addition to promoting to the next
state, demoting to a previous state, or resetting to its initial state,
you can put the document into an exception state to indicate an error condition
or to block state changes. When you clear the exception state, the
document remains in the same state as when you set the exception.
Note that the state change is transactional.
If a change action fails, the document remains in the state prior to
the changeState
call.
Lifecycle Actions
Lifecycle actions handle state changes in documents to which lifecycle policies are assigned. Represented by a DocumentLifecycleAction object, a lifecycle action contains properties that point to a user-implemented lifecycle action handler that runs in response to document state changes. A lifecycle action handler runs synchronously on the Content Engine.
You create a lifecycle action handler by implementing the Content Engine Java™ API DocumentLifecycleActionHandler interface. It can be implemented as a JavaScript or Java component. You can package a Java class in a JAR file, and you can check in your class or JAR file as a CodeModule object in a Content Engine object store. Alternatively, you can specify a Java-implemented handler in the class path of the application server where the Content Engine is running.
You set the DocumentLifecycleAction
object's ProgId
property to identify the inplemented JavaScript or Java lifecycle action handler. If you checked
in a Java-implemented handler to an object store, you must also set
the DocumentLifecycleAction
object's CodeModule property.
For code examples on implementing a lifecycle action handler and on
creating a lifecycle action object, see Working with Lifecycle-related Objects.
For more implementation and deployment information, see Action Handlers.
To
associate a DocumentLifecycleAction
object with a
lifecycle policy, you set the policy's DocumentLifecycleAction property.
A policy can contain only one DocumentLifecycleAction
object.
However, a DocumentLifecycleAction
object can be
contained by multiple DocumentLifecyclePolicy
objects,
which is the case if you code a single lifecycle action handler to
service multiple document lifecycle policies.
Note that
the DocumentLifecycleAction property is not required to be set; that
is, you can create a lifecycle policy without a document lifecycle
action. As an alternative to handling state changes with a document
lifecycle action, you can handle them with an event action that is
triggered by a ChangeStateEvent object. In general, there is
no advantage in using an event action, except for the case where you
need the Document
object in the previous state to
the state that is being changed. With an event action handler, which
is passed an event object, you can use the ChangeStateEvent
object's
OriginalObject property to retrieve the Document
object before
the event transition. You cannot do this retrieval with a lifecycle
action handler.
You also have the option of using both
a lifecycle action and an event action for a document or Document
class
or subclass. If you choose to include an event action, you must create
a subscription that references the event action, the ChangeStateEvent
object,
and the document to which the lifecycle policy is assigned.