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 transitions to another, a lifecycle-related system event fires. The event is handled by a lifecycle action — a user-implemented, server-side component. For example, you could 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 invoked 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 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's 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.
NOTE For a 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 as well as retrieve them. This topic focuses on the requirements and steps to create a document lifecycle policy. For document lifecycle policy code examples, see Working with Lifecycle-related Objects. For information on lifecycle-related objects as implemented in the Enterprise Manager, see Lifecycles.
A document lifecycle policy is represented by a
DocumentLifecyclePolicy class. You instantiate an object with the
Factory.DocumentLifecylePolicy createInstance
method, then set the following key properties:
You can also set lifecycle policy properties that specify:
DocumentState
objects. When the document transitions to a state on which permissions have been 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.
See DocumentLifecyclePolicy Properties for more information.
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 transitions through all of its states, thereby completing its lifecycle. For example, a loan application document may transition through the following states to complete its lifecycle: Application, Approval, Funding, Servicing, and Closed. Document states are user-defined and transition 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 transitions 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 transition 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 transitioning. When you clear the exception state, the document remains in the same state as when you set the exception.
Note that the state transition is transactional. If a transition action fails, the document will remain in the state prior to the changeState
call.
Lifecycle actions handle state transitions 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 executes in response to document state transitions. A lifecycle action handler runs synchronously on the Content Engine.
You create a lifecycle action handler by implementing the Content Engine Java™ API's DocumentLifecycleActionHandler interface. You can package the 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 the lifecycle action handler in the classpath of the application server where the Content Engine is running.
To associate a lifecycle action handler with a DocumentLifecycleAction
object, you set the DocumentLifecycleAction
's ProgId property to the fully qualified name of the Java class. If you checked in the lifecycle action handler to an object store, you must also set the
DocumentLifecycleAction
's CodeModule property.
For best practices for implementing a DocumentLifecycleActionHandler
interface, see Implementation Concepts. For code examples on implementing a lifecycle action handler and on creating a lifecycle action object, see Working with Lifecycle-related Objects. For deployment options, see Deploying 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. This would be the case if you were to 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 transitions with a document lifecycle action, you can handle them with an event action that's triggered by a ChangeStateEvent object. In general, there's no advantage is using an event action, with the exception of the case where you need the Document
object prior to its state being changed. With an event action handler, which is passed an event object, you can use the ChangeStateEvent
's OriginalObject property to retrieve the Document
object prior to the event. You cannot do this 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 will have to subscribe it to a subscription, along with the ChangeStateEvent
object, and the document to which the lifecycle policy is assigned.