Lifecycle Policy Concepts

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.

Lifecycle Policy Setup Requirements

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:

See DocumentLifecyclePolicy Properties for more information.

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 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

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.