In order to create and configure a versioned repository for one of your application’s repositories, perform these tasks:

  1. Verify the Versioned Repository Definition.

  2. Modify the Repository Configuration.

  3. Modify the Repository Definition if necessary, to indicate which item types should be versioned.

  4. Optionally, Set the Behavior of Versioning Caches, which control the behavior of each versioned item’s HeadOfLine and CurrentVersionItem caches.

  5. Modify the Secured Repository Definition if applicable, to give Business Control Center users access to the items.

Verify the Versioned Repository Definition

Before creating a versioned repository, verify the original repository definition file. In general, make sure it conforms to the original (unversioned) database schema.

Specifically, verify the following in the repository definition file:



readable/writable attributes

Set to true in all <property> tags within a <table>, for all properties whose values you want to maintain from one asset version to the next.

If a property is not readable and writable, its value for a given item is not checked in and maintained in the versioning system, nor is it deployed to a staging or production target. By default, all properties are readable and writable.

Note 1: If necessary, indicate not to deploy a readable and writable property by setting its deployable attribute to false, as in the following example:

<property name="myProperty">
  <attribute name="deployable" value="false" data-type="boolean"/>

You can also set the deployable attribute for item-descriptors:

<item-descriptor name="myItemDescriptor">
  <attribute name="deployable" value="false"/>

Note 2: If two properties have a many-to-many relationship, designate one as read-only by setting its writable attribute to false. This ensures that only one side of the relationship is updated, which prevents duplicate copies of the same asset versions and potential data corruption. Read-only properties can be displayed but not edited via the Business Control Center.

required attribute

Set to true in <property> tags in a <table> tag for properties whose corresponding database columns are defined as NOT NULL.

Note: If a property references an item that is defined in the database as NOT NULL but you cannot mark the property as required, indicate this by adding the references attribute tag and set its value to true.

references attribute

Set to true in <table>-nested <property> tags, for all properties that reference another item that is defined in the database as NOT NULL. In the case of one-to-many relationships between item descriptors, the underlying join tables are defined in the database as NOT NULL. Thus, the multi-table definition must set the references attribute to true, as in the following example:

<table name="dcs_cat_chldprd" type="multi"
 multi-column-name="sequence_num" shared-table-sequence="1">

 <property category-resource="categoryProducts"
   name="fixedChildProducts" data-type="list"
   component-item-type="product" column-name="child_prd_id"
   queryable="true" display-name-resource="fixedChildProducts">

    <attribute name="propertySortPriority" value="-4"/>
    <attribute name="references" value="true"/>


Repository ID

Repository IDs in versioned repositories cannot contain special characters such as pound/hash (#), slash (/), and colon (:).

id-column-names attribute

In all <table> tags, specify the correct column name(s) in the database.

All reference properties

Define correctly. For example, all reference properties should specify an item-type attribute, not a data-type attribute.

display-name-resource attribute

Specify in all <item-descriptor> tags.

For detailed information on the attributes and tags specified above, see the ATG Repository Guide.

Modify the Repository Configuration

You must modify the repository component in order to configure a VersionRepository instance. To do so, layer on a configuration file for the component by placing it in the versioned module’s main config directory.

The configuration file might look like this:



The versionManager property should be set to the default VersionManager:


The versionItemsByDefault property sets the default for versioning all item types:

The next section, Modify the Repository Definition, shows how the repository definition file specifies versioning for individual item types.

You can also set the String properties that are listed in the following table. Typically, you only need to set one of these properties if a default table or column name used to store version metadata matches a name in your existing, unversioned schema.

Property Name



The column name of the asset-version item property.

Default: asset_version


The name of the column used to persist the branch of a version.

Note: ATG Content Administration only uses the versioning system’s main branch.

Default: branch_id


The name of the column used to persist the date that a checked-in version of an asset was created.

Default: checkin_date


The name of the historyId item property. This property is dynamically created and represents the unversioned, original ID property.

Default: historyIdProperty


The name of the column used to persist the flag that determines if a version is the head of a branch.

Default: is_head


The column name of the predecessor item property.

Default: pred_version


The column name of the version-deleted item property.

Default: version_deleted


The column name of the version-editable item property.

Default: version_editable


The column name of the workspace item property.

Default: workspace_id

You can also use the Component Editor of the ATG Control Center (ACC) to modify a repository component’s properties. If using the Component Editor, be sure to save changes to the correct module.

Modify the Repository Definition

When you use ATG Content Administration with your versioned module, the definition files for all versioned repositories are automatically extended to support asset version metadata. Thus, you should not modify the definition files to do so.

Depending on your requirements, you might need to modify the versioned repository’s definition file in two ways:

The setting for the versionable attribute depends on the setting of the versioned repository’s versionItemsByDefault property:

If versionItemsByDefault is set to:

Override for an item type by setting versionable to:

true: version all repository items

false: do not version items of this type

false: do not version any item types

true: version items of this type.

You modify the definition file for a versioned repository by layering on a definition file. Place the new definition file in the config directory of your versioned module—for example, /MyCatalogVer/config/myApp.

In some cases, a repository is defined using multiple definition files that are located across several application modules. If this is true for your versioned repository and you need to change each definition file, store the modified definition files in separate config directories in the versioned module—one for each config directory across all source modules. For example:

Location of source repository file:

Location of versioned repository file:





Note: If you create additional config directories in your application’s versioned module, add them to the ATG-Config-Path variable specified in the versioned module’s manifest file. For more information on application modules, see the ATG Platform Programming Guide.

It’s also important to note that, while the definition files for versioned repositories are extended automatically at startup, in a subsequent setup step you must manually create and install the corresponding database schema (see Create and Install the Versioned Database Schema).

Set the Behavior of Versioning Caches

Versioned repositories have two caches for each item type, which maintain information about an item’s latest version:

Together, these caches help optimize performance of versioned repositories, by avoiding overhead otherwise incurred through repeated queries for an item’s head version, and creation of redundant CurrentVersionItem objects.

By default, the size of versioning cache sizes and when they time out are set by the item descriptor’s item-cache-size and item-cache-timeout attributes, respectively. In general, you can rely on these settings for versioning caches if they are set appropriately for the item type itself. If desired, you can explicitly set the behavior of versioning caches independently of the item cache through the following item descriptor attributes:

The timeout attributes are set in milliseconds. If no timeout is set for versioning caches or the item cache, the HeadOfLineCache and CurrentVersionItemCache use the VersionRepository properties maxHeadOfLineCacheTimeout and maxCurrentVersionItemCacheTimeout, respectively.

Modify the Secured Repository Definition

If you copy definition files for the secured repositories that sit on top of your repositories, you must modify those files in order to provide access to their data via the Business Control Center.

Specifically, you must modify the <descriptor-acl> and <creation-base-acl> attributes of the item descriptors to include the four ATG Content Administration roles that are provided with the product:

To give users access to secured assets within the Business Control Center, modify the access control lists (ACLs) for the item descriptors to include ATG Content Administration roles. If you also configure item-level security, you must also modify the ACLs for the individual items to include ATG Content Administration roles.

The following XML for the catalog item descriptor shows how access rights might be defined. The ACLs below are similar to those defined for the item descriptors and items in the PublishingRepository.

<item-descriptor name="catalog">

  <!-- The ACL that applies to the item view/descriptor -->
  <descriptor-acl value="Profile$role$epubSuperAdmin:read,write,create,

  <!-- The property that the ACL will be stored in -->
  <acl-property name="acl"/>

  <!-- An ACL fragment that is assigned to all new items -->
  <creation-base-acl value="Profile$role$epubSuperAdmin:read,write,


These changes get you started with repository data. As you customize the Business Control Center to meet your needs, you are likely to further modify access rights for various item descriptors and items to subsets of ATG Content Administration users. For more information on ATG Content Administration security, see the chapter Managing User Access and Security. For more information on secured repositories, see the Secured Repositories chapter in the ATG Repository Guide.