Lifecycles

A document object in Cinnamon may have a lifecycle attached to it which defines the current state of the object as seen from the business logic.

A typical editing lifecycle would have the following states which are applied to the individual document objects:

• edit (object is assigned to an editor who create or updated the content)
  
• review (object is under review by a reviewer who checks the content but is not allowed to change it)
• published (reviewer has consented to publish the content)

A lifecycle is different from a workflow, because it is generally limited to the passive state of one single object. A workflow is concerned with acting on and changing the state of one or more documents and actively furthering the evolution of one state to another. In a factory setting, a lifecycle would be the place where a fabricated object is resting in any given moment, be it on a workbench or inside a holding area or a machine, while the workflow would be the process which moves an item from one machine to another, depending on what the current production requirements are.

It should be noted that since both lifecycles and workflows use Java classes to accomplish their goals, you are basically free to mix lifecycle and workflows actions in numerous ways. I would recommend a clear design of workflows which may trigger lifecycle changes. For example, you should not have a lifecycle class which manages which user receives a document for review. But still, it is possible to have a lifecycle state that triggers a workflow on change.

A simple demo lifecycle

Cinnamon has a simple demo publishing lifecycle built in. It consists of three lifecycle states.

• Authoring [default]
  
• Review
• Published

A document should be attached to the publishing lifecycle upon creation. When the document is ready for review by an editor, the author (or rather, the client) will change the lifecycle state by using changeState with the target being the "review" state.

Each lifecycle state is associated with a custom Java class, which checks objects entering and leaving this state and, if necessary, stops the server from moving a document into an invalid state. This way, a document may leave the authoring state for the review state, but it may not be published from the authoring state without being checked by an editor. From the review state, a document may be put back into the authoring state, or into the final state: published.

If this were a real lifecycle, the state changes would cause changes to the object's ACL to enable writing of content (in authoring state) or metadata (in review state, for editor's notes) or prevent both (in published state).

The ChangeAclState class

This built-in class allows you to create basic lifecycles where each state corresponds to a configured ACL.

The state class is server.lifecycle.state.ChangeAclState, and the Acl is set by the parameter field:

<param>
  <aclName>_default_acl</aclName>
</param>

You can of course set the ACL directly, without using the lifecycle class. But we recommend the use of lifecycles over direct manipulation of ACLs, as you may one day wish to add further checks to such state changes. An ACL does not have entry / exit criteria, so nothing prevents a user (if he is allowed to change the system metadata of an object)  from setting the ACL from an unfinished document to the "archived"-ACL.