In order to create and configure a versioned repository for one of your application’s repositories, perform these tasks:
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
andCurrentVersionItem
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 |
---|---|
Set to If a property is not Note 1: If necessary, indicate not to deploy a readable and writable property by setting its
You can also set the
Note 2: If two properties have a many-to-many relationship, designate one as read-only by setting its | |
| Set to Note: If a property references an item that is defined in the database as |
| Set to true in
|
Repository ID | Repository IDs in versioned repositories cannot contain special characters such as pound/hash ( |
| In all |
All reference properties | Define correctly. For example, all reference properties should specify an |
| Specify in all |
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 |
---|---|
| The column name of the Default: |
| 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: |
| The name of the column used to persist the date that a checked-in version of an asset was created. Default: |
| The name of the Default: |
| The name of the column used to persist the flag that determines if a version is the head of a branch. Default: |
| The column name of the Default: |
| The column name of the Default: |
| The column name of the Default: |
| The column name of the Default: |
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 tofalse
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: |
---|---|
|
|
|
|
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:
HeadOfLineCache
caches information that identifies the item’s head version on a given branch.CurrentVersionItemCache
cachesCurrentVersionItem
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:
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.