33 Managing Revision Tracking
Topics:
33.1 Revision Tracking Overview
WebCenter Sites provides revision tracking functionality through its revision tracking API. This API is used to provide additional revision tracking functionality for asset type tables.
When you enable revision tracking for an asset type, WebCenter Sites creates a new table, called a tracker table, for assets of that type. You specify how many versions you want to keep and you also specify a storage directory that the tracker table uses to store supporting files for the assets that it is tracking.
WebCenter Sites' implementation of revision tracking provides the following features:
Check out and check in:
Check out locks an asset so that only one user can edit it at a time.
Check in releases the lock on the asset, increments the version number, and determines whether the number of versions falls within the configured limit. If the new version exceeds the limit, the oldest version is deleted to make room for the next version.
Storage of multiple versions of an asset:
When you enable revision tracking for an asset type, WebCenter Sites stores versions in a tracker table; upload data is stored in a storage directory that you specify, as shown in RTInfo Table. Because past versions are stored (that is, a history exists), a user can roll back an asset to a previous version or examine the differences between two versions of the asset.
Administrative or maintenance features:
An administrator can delete past versions of an asset or clear the checkout for an asset by overriding the check out on it and checking it back in.
When an asset type is tracked, WebCenter Sites provides check in, check out, and other revision tracking features on the New and Edit forms for assets of those types.
This section covers the following topics:
33.1.1 Tracker Tables and Storage Directories
When you enable revision tracking for an asset type, creates a tracker table that stores revision information for the records in the source table. A tracker table has the same name as the main storage table for the asset type with _t appended to it. For example, the tracker table for the article asset type would be named Article_t. The tracker table for the attribute type asset type would be named AttrTypes_t.
For each record in a tracked asset type table, there are several rows in the corresponding tracker table that stores its version information. Tracker tables have two kinds of columns:
-
Columns that store the system information that the revision tracking system requires to keep track of all the versions
-
Columns that hold the IDs of text files that are stored in a storage directory
When a new version of an asset is checked in, creates a text file to hold the data in each of the asset type's upload (URL) fields and in any text fields that are configured to hold more than 64 characters. These files are stored in shared/rtStorage/AssetType. There is a set of these text files stored in the storage directory for each version of the asset.
Note:
Because tracker tables hold system information only, they are hidden in Explorer. Do not attempt to modify the information in any of the tracker tables with a database tool.
33.1.2 RTInfo Table
While the tracker tables are kept hidden, the RTInfo table is visible through Oracle WebCenter Sites Explorer. This table holds information about which tables are being revision tracked. It has the following columns.
Table 33-1 RTInfo Table
| Column | Description |
|---|---|
|
|
The name of a table that is being revision tracked. For asset types, this is the name of the main asset type table. |
|
|
The number of versions to store for each asset of this type. |
|
|
The path to the storage directory that holds the text files for each version of assets of this type. The path is in the shared folder, located in |
|
|
A timestamp of the last time a version was stored in the tracker table. |
|
|
The time at which revision tracking was enabled for the source table. |
33.1.3 Revision Tracking and the Two Asset Models
Because the data model for basic assets is different from the data model for flex assets, the revision tracking system works differently for the two asset models:
-
For basic assets, only the row in the main asset storage table is tracked.
-
For flex assets and the other multi-table asset types (template and CSElement), the information from the appropriate rows from all of their tables are serialized into an object and stored in the tracker table for that asset type.
For example, if you enable revision tracking for template assets, the appropriate rows from the Template, SiteCatalog, and ElementCatalog tables are serialized into an object and stored in the Template_t table.
33.1.4 Implicit vs. Explicit Checkin and Explicit Checkout
When revision tracking is on for an asset type, provides both implicit (or automatic) and explicit (or manual) checkout, and explicit check in functionality. When users create or edit assets of a type that is being revision tracked, they do not have to manually check out the asset: it is automatically assigned to them. However, implicit check in is not allowed; when they click Save, the asset is not checked back in. Users must manually check assets in.
This may or may not be the behavior that you want. For example, if an author is making extensive revisions to an asset that was checked out implicitly, the changes will not be available until the user also explicitly checks in the asset. This will help prevent the user from overwriting an older version that they wanted to keep. An additional example is when an author implicitly checks out an asset to make edits, then navigates to a different area, then returns to the asset. Once an implicitly checked out asset is navigated away from, it must be explicitly checked in when complete.
Implicit checkouts are used for quick edits where the editing and saving would be done in one operation. These types of updates that are expected to be done with minimal clicks. Explicit checkouts are for changes to an asset over time.
When a content provider implicitly or explicitly checks out an asset, a version is not stored, no matter how many times he or she saves it, until it is manually checked in.
33.1.5 Revision Tracking and Non-Asset Tables
In addition to using revision tracking for your asset types, you can implement revision tracking on your non-asset tables.
To do so, you use the User Access Management feature in the Admin tab to enable tracking for the table. WebCenter Sites then creates a corresponding tracker table to support the tracked table. It is named the same way as a tracker table for an asset type: nameOfTable_t.
When revision tracking is enabled for a non-asset table, you can use either the revision tracking features accessible from the menus in Oracle WebCenter Sites Explorer or the User Access Management node on the Admin tab to lock (check out) a row and then unlock the row (check it back in) when you are finished with it.
If you have to provide additional support outside of the Oracle WebCenter Sites Explorer tool for revision tracking of a non-asset table, your developers can code additional forms using the WebCenter Sites revision tracking API and revision tracking XML or JSP tags. For more information, see the Tag Reference for Oracle WebCenter Sites and the Java API Reference for Oracle WebCenter Sites.
Note:
If you have to delete a non-asset table from the WebCenter Sites database and that table is being revision tracked, untrack the table before deleting it.
33.1.6 How Many Versions?
Each revision of an asset or a database row occupies disk space. Therefore, your decision about how many revisions to keep must be based on the following factors:
-
The amount of disk space that you have available
-
The typical data size of the asset (or row)
-
The likelihood that there could be a requirement for a rollback of several versions
For example, an asset that consists of a small amount of ASCII data occupies so little space that a large number of revisions would take little disk space. However, each version of an asset that holds a large amount of binary data could occupy a significant amount of disk space. In the second case, you must strike the appropriate balance, storing the fewest number of versions necessary for rollback purposes.
33.2 Enabling Revision Tracking
You can enable revision tracking for assets and for non-asset tables, as the following topics describe:
Note:
If Revision Tracking is turned on at the publishing target destination for either ElementCatalog or SiteCatalog, then the publishing of template will fail and the template may be corrupt.
It is not recommended to enable Revision Tracking on the target destination.
33.2.2 Enabling Revision Tracking for Non-Asset Tables
To enable revision tracking for database tables that do not hold assets, use the User Access Management node.
To enable revision tracking for non-asset tables:
- In the General Admin tree, expand the Admin node, expand User Access Management, and then double-click Revision Tracking.
- In the form that opens, select Track Tables and click OK.
- In the Enter root storage directory field, enter the full path to the directory in which revisions of table rows will be stored. Do not add a slash (or backslash) character after the directory name.
- In the Enter number of revisions to keep field, enter the number of revisions should store for rollback purposes.
- Select the Track? check box next to each table for which you are enabling revision tracking.
- Click Track Tables.
33.2.3 Editing Revision Tracking Settings
You must have the SiteGod, xceladmin, Visitor Admin or Remote Client ACL to either inspect or edit revision tracking settings. If you attempt to examine the current revision tracking settings for a tracked asset type or non-asset table and you do not have one of those ACLs, the system does not display the name of the root storage directory or the number of revisions. Because revision tracking settings directory affect the database, you must be careful when changing these settings.
This section covers the following topics:
33.2.3.1 Changing the Root Storage Directory
Caution:
If you change the root storage directory for an asset type or non-asset table, you will lose all the versions currently stored in it.
If you must change the root storage directory, follow these steps:
- Disable revision tracking for the asset type or table. When you do this, all the version data for the asset type is orphaned.
- Enable revision tracking for the asset type or table, entering the new root storage directory.
33.2.3.2 Changing the Number of Revisions
The following sections provide information about increasing and decreasing the number of revisions to be stored for an asset type or table.
- To increase the number of revisions to be stored for an asset type, simply increase the value in the Revisions to Keep field.
- To increase the value, in the Admin tab, expand Asset Types, expand the asset type you want to modify, Revision Tracking, and double-click Set Revisions. Use the form that opens to increase the value.
Although you could have to decrease the number of versions while you are testing configuration settings on a development system or while you are fine-tuning the management system, it is best if you do not decrease the number of versions stored by Revision Tracking on a management system.
If you decrease the value in the Revisions to Keep field to a number that is less than the number of revisions currently stored, the following occurs:
-
The text files in the storage directory for the extra versions are orphaned
-
The rows in the tracker table for the extra versions are orphaned
You can avoid creating orphan rows in the tracker table by deleting the extra versions (the oldest ones) before you decrease the number of revisions. However, you cannot avoid creating orphan text files in the storage directory and you should not attempt to delete them because it is very difficult to determine which ones to delete.
If you must decrease the number of revisions, use the form associated with the asset type. In the Admin tab, expand Asset Types, the asset type to modify, Revision Tracking, and double-click Set Revisions. Use the form to decrease the value.
33.3 Disabling Revision Tracking
When you disable revision tracking for an asset type or a non-asset table, the following occurs:
-
The tracker table is inactivated, not deleted. The versions stored in it are orphaned, not deleted. After revision tracking is disabled for a table, you can no longer delete versions by using the WebCenter Sites revision tracking forms.
-
All links to the text files in the storage directory are broken, but the files themselves are orphaned, not deleted.
If you decide to re-enable revision tracking for that asset type, the old versions and text files are ignored and remain orphaned.
Because these old versions could take up unwanted space, it may be necessary to delete them manually. Manually delete all the text files from the revision tracking directory located inside the storage directory for that asset type. For example, if the storage directory for the asset type is /Storage/AssetType, then delete all the files from the /Storage/AssetType/AssetType revision tracking directory.
Note:
Do not delete any files from the asset type storage directory.
To disable revision tracking for asset types:
33.4 Unlocking Revisions
Occasionally, user operations can leave an asset in an inappropriate locked state. Resolving these states is an administrative responsibility.
For asset types, use the Clear Checkouts function in the Admin tab.
Before you begin, find out the name of the user who has the asset locked. This information is listed on the Inspect form for the asset.
To clear checkouts for assets: