8 Oracle Content Services Versioning

Oracle Content Services provides a way to version items. Versioning tracks changes made to the content and metadata of an item throughout its life cycle, and allows users to see and revert to older versions of the item.

Versioning in Oracle Content Services

Oracle Content Services allows an administrator to choose the right balance between user requirements, system resources, and performance. Tracking every version of every document in the system can stress the system's resources, so it is important for administrators to be able to control the specifics of the versioning configuration. To allow better control, Oracle Content Services allows customizing of the versioning policy at the site, Library, Container, or Folder level.

Versioning Policies

Oracle Content Services can create a new version of a document whenever a modifying operation is performed on an existing document such as an FileManager.updateDocument call, upon creation of a new document (with a FileManager.createDocument call), or as part of a copy or move operation (with a FileManager.copy or move call).

Versioning policy can be set for the entire site, or it can be set at a lower level, such as on a Library, Container, or folder. There are three versioning strategies: automatic, manual, and none.

With automatic versioning enabled, performing an operation that would cause an existing document to be modified (such as a copy, move, update, or create operation) will create a new version of that document. If the existing document was not versioned, two versions of the document will exist. Otherwise, the version count on the document will increment by 1. Any createDocument call requires write access on the destination, and the destination cannot be locked (for example, the document could be locked if explicitly checked out by another user, or it could be locked as part of a workflow process). With automatic versioning enabled, explicit checking-out of a document is optional.

With manual versioning enabled, changing a document in the system will fail unless the document has been explicitly checked out by the calling user. If a different user has checked out the document, you will have to wait until the document becomes available. The VersionManager.checkoutDocuments method allows you to check out one or more documents, providing you have permissions on the folder to do so.

Versioning can also be disabled entirely. In this case, any operation that would cause an existing document to be modified (such as a copy, move, update, or create operation) will overwrite the existing document's content and metadata.

Versioning Configuration

The default versioning policy for an Oracle Content Services instance is "no versioning". The versioning policy can be set at the site, Library, Container, or folder level, and all its descendants will inherit the policy by default. A descendant can override the inherited versioning policy only if the CONFIGURATION_FINAL attribute was set to false on the original policy. To prevent descendants from overriding the versioning policy, set that policy's CONFIGURATION_FINAL attribute to true.

Setting the versioning policy at the site level must be done in administrator mode, whereas setting the policy on a Library, Container, or folder only requires the appropriate permissions on the object.

The versioning policy also dictates the maximum number of versions to store, by setting the VERSIONING_CONFIGURATION_MAX_VERSIONS attribute. Any updates to the version count will be checked against this number, and when exceeded, the oldest stored version will be deleted. However, if a version is set with the DO_NOT_PURGE flag set to true, it will not count against the maximum version count. In other words, VERSIONING_CONFIGURATION_MAX_VERSIONS refers to the number of versions to keep which have DO_NOT_PURGE set to false. These criteria typically refer to versions created by an automatic versioning policy. The DO_NOT_PURGE flag of a version can be changed at any time with the updateVersion method of the VersionManager.

Versions are assigned comments and labels. Comments describe the version, and the label indicates the version number. The VERSIONING_CONFIGURATION_LABEL_TYPE attribute determines what kind of label a version gets (numbers, letters, or Roman numerals). By default, Oracle Content Services will assign the labels automatically according to the label type. To change how labels are assigned, set the VERSIONING_CONFIGURATION_AUTO_LABEL attribute to false.

Rolling back to an older version of a document involves copying the older version onto the latest version using the VersionManager.copyToLatestVersion method. Similarly, to download a working copy of any version in the item's version history, use the copyToWorkingCopy method, and supply the ID of the version.

Conflict Resolution

When uploading new of versions files which have previously been versioned, the possibility for a naming or versioning conflict arises. Oracle Content Services offers two ways of handling a conflict.

The first way is to set options on the file describing the resolution policy at the time of its creation. These options are passed inside the createDocument method of the FileManager. The options are:

Options.NEWVERSION - this option ensures that when uploading to a folder with manual or automatic versioning configuration, a new version will always be created on upload. There is no need to explicitly check out the document before uploading.
Options.UNIQUENAME - this option ensures that each upload will produce a unique name, so that no file will ever be overwritten. Thus, attempting to upload an existing filename will result in a slightly modified new filename.
Options.OVERWRITE - this option ensures that when uploading to a folder with no versioning policy, any existing item with the same name will automatically be overwritten.

The other way of handling a conflict is by allowing the createDocument call to throw an exception, and processing the conflict based on the returned error. This strategy allows more user interaction as the application can then defer to the user to provide the correct action.

A sample exception is listed below, with the relevant error messages highlighted:

FdkException:
    Error Code: ORACLE.FDK.AggregateError
    Detailed Error Code: ORACLE.FDK.AggregateError
    Trace Id: 33-1138800897129
    info (NamedValue[]):
    FdkExceptionEntry:
    Id: 86842
    Error Code: ORACLE.FDK.OperationError
    Detailed Error Code: ORACLE.FDK.ItemAlreadyExists
    Trace Id: 32-1138800897126
    info (NamedValue[]):
    ECM.EXCEPTIONINFO.ConflictResolutionOptions (String[])=
        OPT.NEWVERSION
        OPT.UNIQUENAME
    ECM.EXCEPTIONINFO.ConflictingObjectId=86836 (Long)

The ConflictResolutionOptions array of the exception returns the names of the possible conflict resolution options. Retrying the operation with one of these options set on the transaction will increase the chance of (but not necessarily guarantee) the success of the transaction.

Tip:

Since the conflict resolution takes place at the end of the file transaction, a user uploading a large file to the server may be forced to upload the file again if there is a versioning conflict. To avoid this, use a DocumentDefinition item (created by the FileManager.createDocumentDefinition method) when uploading so that the content of the file remains on the server even if there is a conflict. After the content is uploaded, call createDocument to create the file object and resolve the conflict.