IBM FileNet P8, Version 5.2.1            

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.



Last updated: October 2015
version_concepts.htm

© Copyright IBM Corporation 2015.