Versioning
An instance of a Document class or any of its subclasses is a Versionable object; that is, the object can have multiple versions that are 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 that are also contained by the Versionable class,
allowing you to work with either object to perform certain actions.
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 supports 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 enabled for versioning. A Content Engine system administrator can
change the versioning support setting for a class (in either direction).
However, changing the setting of a class 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
by using 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 out the
document from an object store). In this case, the document has an associated VersionSeries object, but there is only a single document version in the version series.
To check whether a document is enabled for versioning, retrieve the object's IsVersioningEnabled
property from its Document or VersionSeries interface. For more
information about versioning-disabled documents, see About enabling versioning.
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-level and two-level versioning
are also enabled (that is, there is nothing to configure to enable
one-level 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 more information about one-level and two-level versioning, see One-level versioning and Two-level versioning.
Version Numbering
Each version series has a major and a minor version number that is associated with it that
reflect the current version numbers for the version series, regardless of whether your application
exposes one-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 is 1 and its minor is 0 (thus,
when combined and separated with a decimal point, you can display them as 1.0). These numbers are
specified in the MajorVersionNumber and MinorVersionNumber properties for a Versionable object. For more information about how the Content Engine assigns initial values and when it increments and decrements those
values, see Version numbering.
Version Status
Each document version has a version status that is 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 might also have a status of "in process". This status is
specified in the VersionStatus property of a Versionable object. For detailed definitions, see Version Status. For information about the effect on version status from document-related
actions, see Versioning Actions.
Security
A document version has a status that is associated with it. Based on version status, security
can automatically be applied to the various versions of a document. For example, you might 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 about how the
Content Engine APIs expose this functionality, see Security Policies.
There are also security considerations operations are performed on a reservation object, such as checking in a document and canceling a check-out.
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, delete
the reservation). The default reservation behavior is defined at the
object store level through the DefaultReservationType property of
the ObjectStore object. (Note that when a new object
store is created, this property is initialized to a value of EXCLUSIVE.)
An initial reservation object (the reservation object that is created
when you create a new document) uses the default reservation type.
For an existing document, you can specify whether a reservation is
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 on the user who checked out the document before the normal
security access checks; the user is not granted any additional rights
by virtue of having created the reservation. No one but the user who
created the reservation object can change the object's class, check
in the reservation, or perform property modifications that require
WRITE permission. The user 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 (by canceling a check-out) is disallowed except for
the user who created the reservation 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 that is 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.