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.

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 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.DocumentLifecylePolicycreateInstancemethod, 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.