Versioning Concepts

An instance of a Document class or any of its subclasses is a Versionable object; that is, the object can have multiple versions associated with it. You create an initial version when you create and check in a new document, and you create a new, additional version when you check out and check in the existing document. Among the actions that you can take with a Versionable object is to freeze the custom properties of a version, promote a minor version to a major version, and demote a major version to a minor version. You can also retrieve a VersionSeries object, which represents the complete set of versions of a document. The VersionSeries object allows you to perform an action on all document versions collectively by issuing one call, like simultaneously moving the content for all document versions to a different location. And, as a convenience, the VersionSeries class contains some methods and properties also contained by the Versionable class, allowing you to work with either object to perform certain actions.

This topic provides an overview of the following Content Engine versioning concepts:

For additional information on Content Engine versioning, see the versioning-related topics in the Content Engine Administration Help. For versioning code examples, see Working with Versioning-related Objects.

Version Levels

The Content Engine provides support for three levels of versioning: no versioning enabled, single-level versioning, and two-level versioning. A document's class specifies whether documents assigned to the class are versioning-enabled. A Content Engine system administrator can change the "supports versioning" setting for a class (in either direction). However, changing a class' setting does not affect existing documents. In other words, the versionability of a document is bound at the time the initial version is created and never changes. Also, changing a document's class (either by the system administrator or via the Content Engine Java API's changeClass method) does not change the versionability of the document.

If versioning is disabled for a class (and therefore for a document of this class), it means that you cannot perform versioning-related operations on the document (such as checking the document into and out of an object store). There will be a VersionSeries object associated with the document, but there will be just one document version in the version series. To check whether a document is versioning-enabled, retrieve the object's IsVersioningEnabled property from its Document or VersionSeries interface. For additional information on versioning-disabled documents, see About enabling versioning in the Content Engine Administration Help.

With single-level versioning, all documents are released (major) documents. Two-level versioning supports both minor and major document versions. (A minor version is typically a draft document that is not yet complete and, therefore, not ready for a wider distribution.) Note that, if versioning is enabled for a class, then both one- and two-level versioning are also enabled (that is, there is nothing to configure to enable one- or two-level versioning). Your application exposes the minor version feature of two-level versioning by calling the checkin method with the CheckinType parameter set to MINOR_VERSION. For additional information on one- and two-level versioning, see One-level versioning and Two-level versioning in the Content Engine Administration Help.

Version Numbering

Each version series has a major and a minor version number associated with it that reflect the current version numbers for the version series — regardless of whether your application exposes single-level versioning or two-level versioning. For example, if you check in the initial version of a document as a major version, its major version number will be 1 and its minor will be 0 (thus, when combined and separated with a decimal point, you could display them as 1.0). These numbers are specified in the MajorVersionNumber and MinorVersionNumber properties for a Versionable object. In the Content Engine Administration Help, see the Version numbering topic on how the Content Engine assigns initial values and when it increments and decrements those values.

Version Status

Each document version has a version status associated with it that reflects whether the document is a reservation object, a superseded document, or the current released document. If your application exposes two-level versioning, then a document version could also have a status of in-process. This status is specified in a Versionable object's VersionStatus property. For detailed definitions, see Version Status in the Content Engine Administration Help. For the effect on version status from document-related actions, see Versioning Actions.

Security

As mentioned above, a document version has a status associated with it. Based on version status, security can automatically be applied to the various versions of a document. For example, you may want different access rights for the in-process version than for the superseded versions of a document. You control version security with the VersioningSecurityTemplate class. For more information on how the Content Engine APIs expose this functionality, see Security Policies.

There are also security considerations when performing operations on a reservation object, such as checking in a document and canceling a checkout.

Reservation Object

When you create a new document or check out an existing document, the Content Engine server creates a reservation object. This object essentially records the intention to check in the document. A reservation object is not a separate class of object, but rather is the new, unchecked-in version of the document. If a document is a reservation object, the value of its VersionStatus property is VersionableStatus.RESERVATION.

A reservation object can be collaborative (anyone with appropriate permissions can check in, modify, or delete the reservation), or exclusive (only the creator of the reservation can check in, modify, or — with one exception, explained below — delete the reservation). The default reservation behavior is defined at the object store level via the ObjectStore object's DefaultReservationType property. (Note that when a new object store is created, this property is initialized to exclusive.) An initial reservation object — the reservation object created when you create a new document — uses the default reservation type. For an existing document, you can specify whether a reservation should be collaborative, exclusive, or use the default type when you call the checkout method on a Versionable object.

For an exclusive reservation object, the Content Engine performs the check for the reservation owner before the normal security access checks; the reservation owner is not granted any additional rights by virtue of having created the reservation. No one but the reservation owner can change the reservation object's class, check in the reservation, or perform property modifications that require WRITE permission. The owner must also have the appropriate access rights to check in a document (RIGHT_MINOR_VERSION to check in a minor version, RIGHT_MAJOR_VERSION to check in a major version), Modifications to security properties, which require either WRITE_ACL or WRITE_OWNER permission, are allowed subject to the normal access checks. In addition, deleting the reservation object (by canceling a checkout) is disallowed except to the reservation owner and to anyone with WRITE_OWNER and DELETE permissions.

After you create a new document or check out an existing document, the returned reservation object initially has no content associated with it. If you want to associate one or more content elements with the document, you must set the content before you check in the document. Also, if you want to explicitly set the value of the Document object's MimeType property (as opposed to having the Content Engine automatically set its value), you must set the value before you check in the document. Note that you can file an initial reservation object into a folder.