Oracle ATG Web Commerce - Create and Configure Versioned Repositories

Create and Configure Versioned Repositories

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

Verify the Versioned Repository Definition.
Modify the Repository Configuration.
Modify the Repository Definition if necessary, to indicate which item types should be versioned.
Optionally, Set the Behavior of Versioning Caches, which control the behavior of each versioned item’s HeadOfLine and CurrentVersionItem caches.
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:

Verify...	Requirements
`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"/> </property>` You can also set the `deployable` attribute for item-descriptors: `<item-descriptor name="myItemDescriptor"> <attribute name="deployable" value="false"/> </item-descriptor>` 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" id-column-name="category_id" 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"/> </property> </table>
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:

$class=atg.adapter.version.VersionRepository

versionManager=/atg/epub/version/VersionManagerService
versionItemsByDefault=true

The versionManager property should be set to the default VersionManager:

/atg/epub/version/VersionManagerService

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

False (default): Versioning is disabled for all item types except those whose repository definitions explicitly specify versioning.
True: All item types are versioned except those whose repository definition explicitly excludes them from versioning.

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	Description
`assetVersionColumnName`	The column name of the `asset-version` item property. Default: `asset_version`
`branchColumnName`	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`
`checkinDateColumnName`	The name of the column used to persist the date that a checked-in version of an asset was created. Default: `checkin_date`
`historyIdPropertyName`	The name of the `historyId` item property. This property is dynamically created and represents the unversioned, original ID property. Default: `historyIdProperty`
`isBranchHeadColumnName`	The name of the column used to persist the flag that determines if a version is the head of a branch. Default: `is_head`
`predecessorColumnName`	The column name of the `predecessor` item property. Default: `pred_version`
`versionDeletedColumnName`	The column name of the `version-deleted` item property. Default: `version_deleted`
`versionEditableColumnName`	The column name of the `version-editable` item property. Default: `version_editable`
`workspaceColumnName`	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:

Specify whether items referenced by an item property are automatically checked out with the parent item.
By default, all required single-item references are checked out with the parent item. This ensures that a referenced item cannot be deleted in one project while its parent item is checked out by another project. You can turn off this safeguard by setting the property’s auto-checkout attribute to false as follows:
<attribute name="auto-checkout" value="false"/>
Set an item descriptor’s versionable attribute to indicate whether to enable or disable versioning for individual item types.

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:
`/Catalog/config/myApp/catalog.xml`	`/CatalogVer/config/myApp/catalog.xml`
`/MyCatalog/config/myApp/catalog.xml`	`/MyCatalogVer/config/myApp/catalog.xml`

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:

HeadOfLineCache caches information that identifies the item’s head version on a given branch.
CurrentVersionItemCache caches CurrentVersionItem objects, which encapsulate the most recent versions of repository items on a given branch.

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:

headOfLineCacheSize
currentItemCacheSize
headOfLineCacheTimeOut
currentItemCacheTimeOut

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:

EPub-Super-Admin
EPub-Admin
EPub-Manager
EPub-User

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,
delete;Profile$role$epubAdmin:read,write,create,delete;
Profile$role$epubManager:read,write,create,delete;
Profile$role$epubUser:read;Admin$role$administrators-
group:read,write,create,delete"/>

  <!-- 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,
list,destroy,read_acl,write_acl;Profile$role$epubAdmin:read,write,
list,destroy,read_acl,write_acl;Profile$role$epubManager:read,write,
list,destroy;Profile$role$epubUser:read,list;
Admin$role$administrators-group:read,write,list,destroy,read_acl,
write_acl"/>

</item-descriptor>

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.

Legal Notices