Author name

Thu, 16 Nov 2017

5 min read

Rational Team Concert: External content repositories

Dean Roberts, DJ Houghton, Andrew Niefer – Persistent Systems
Last updated: 18 October 2017
Build basis: Rational Team Concert 6.0.5 and later

Introduction

Starting in version 6.0.5, Rational Team Concert supports external content repositories. This feature enables Rational Team Concert to store large source control management (SCM) files in an external content repository instead of the server database. An external content repository can be a directory on the Rational Team Concert server file system, or a WebDAV-compliant artifact repository server such as Artifactory.

The external content repository is configured by an administrator, is completely transparent to users, and is fully compatible with older clients.

Configuring an external content repository

To configure an external content repository, a Jazz administrator uses the Advanced Properties page in the web client for the Change and Configuration Management (CCM) server. The relevant properties are in the SCM section, with the other Versioned Content configuration properties.

External content repository configuration properties

Property name	Default value
Versioned Content External Repository – Type	“NONE”
Versioned Content External Repository – Write Enabled	false
Versioned Content External Content – Artifact Minimum Size	1,000,000 bytes
Versioned Content External Repository – URI	N/A
Versioned Content External Repository – User ID	N/A
Versioned Content External Repository – Password	N/A

Configuration steps:

Set the Versioned Content External Content – Artifact Minimum Size property to the size, in bytes, of the smallest file you want stored in the external content repository. When this property is enabled, no files larger than the specified size will be stored in the CCM server database.
Set the Versioned Content External Repository – Type property to FILE to use the CCM server file system, or WEBDAV to use a WebDAV-compliant artifact repository such as Artifactory.
Set the Versioned Content External Repository – URI property to the root path of the external content repository.
For the FILE repository type, the URI will be a directory on the CCM server file system (for example, file:///mount/farm/repoRoot).
For the WEBDAV repository type, the property will be the URL to the repository root on the WebDAV artifact repository server (for example, https://server.example.com/artifactory/repoRoot).
If you are configuring a WebDAV repository type, set the following properties to the user name and password of an account that has read, write, and delete access on the WebDAV server for the configured URI:
- Versioned Content External Repository – User ID
- Versioned Content External Repository – Password
To begin storing large content to the external content repository, set the Versioned Content External Repository – Write Enabled property to true.

Changing the configured external content repository

You can change the configuration values for the external content repository. Any changes will affect where new content is stored; it does not affect how existing content is stored or retrieved.

Versioned Content External Repository – Write Enabled

If this property is set to false, all new content is stored in the CCM server database regardless of its size. Content that was previously stored in an external content repository will continue to be retrieved from that external content repository.

Versioned Content External Repository – URI

Changing the URI to reference a new server causes new large content to be saved to the new server. Previously saved content will remain on and be retrieved from the old server.

There is no limit to the number of external content repository servers that can host previously stored content. However, only one external content repository can be configured to store new content at any given time.

Changing WebDAV access credentials

Rational Team Concert stores the access credentials for each Versioned Content External Repository – URI value that you enter. If you change the Versioned Content External Repository – URI value and its associated credentials, the old URI and credentials are stored so that Rational Team Concert can continue to retrieve content on that server while using the new credentials to access the currently configured external content repository.

To change the credentials for the currently configured external content repository, modify the Versioned Content External Repository – User ID and Versioned Content External Repository – Password properties on the Advanced Properties page.

To change the credentials for previously configured WebDAV servers, you must edit the external content repository credentials file directly.

The credentials file is a JSON file named externalContentRepositories.conf, which is located in the CCM server configuration directory. By default, this file is in ./server/conf/ccm, where server is the CCM server installation directory.

The following externalContentRepositories.conf file contains two external content repositories with their credential data. Notice that the passwords are encrypted.

[
    {
        "PASSWORD": "[qoSGR4gvSUY=]",
        "URI": "https:\/\/example.com\/artifactory\/content\/",
        "USER": "repoUser1"
    },
    {
        "PASSWORD": "[DZCEyaFThdWaWOsOL2l2Cg==]",
        "URI": "https:\/\/example.com\/artifactory\/content2\/",
        "USER": "repoUser2"
    }
]

Use a text editor to change the USER and PASSWORD fields for the appropriate external content repositories. Be careful to only edit the characters between the quotation marks for the USER and PASSWORD values. New passwords are entered in plain text. Save the file and Rational Team Concert will automatically detect the changes, update the password fields with their encrypted values, and begin using the new credentials.

The following example shows the same file with updates to both passwords and the second user name.

[
    {
        "PASSWORD": "newPassword1",
        "URI": "https:\/\/example.com\/artifactory\/content\/",
        "USER": "repoUser1"
    },
    {
        "PASSWORD": "newPassword2",
        "URI": "https:\/\/example.com\/artifactory\/content2\/",
        "USER": "newRepoUser2"
    }
]

Note: The externalContentRepositories.conf file includes entries for FILE-based external content repositories; however, credentials are currently only used for WebDAV repositories, and are not supported for file-system-based content repositories.

Moving content

You can use the repository tools moveContent command to move previously stored content in these ways:

From the CCM server database to an external content repository
From an external content repository to the CCM server database
From an old external content repository to the currently configured one

You run the command while the server is up, and access to content is not disrupted during the move.

The moveContent command has arguments to specify source and destination content repositories, as well as the minimum or maximum size of content to move. For details about how to run the command with various arguments, see the repository tools command-line reference documentation.

Deleting content

When content stored in an external content repository is deleted from Rational Team Concert, the server also attempts to delete the content from the external content repository. However, deleting content from the external repository is a “best effort” and the Rational Team Concert server cannot guarantee that the content will be removed from the external content repository.

If a problem occurs with deleting content from the external repository, the problem is logged on the server but does not cause the delete operation to fail.

Reporting using JMX MBeans

In Rational Team Concert, you can monitor content stored in SCM by using Java Management Extensions (JMX) managed beans (MBeans). An administrator can enable reporting of MBeans for SCM-versioned content by using the Advanced Properties page in the web client for the CCM server. The properties are located under the com.ibm.team.scm.service.internal.content.metrics.VersionedContentMetricsTask section of the Serviceability Component.

Property name	Default value	Description
Delay between invocations	604800	The time in seconds between invocations of the Versioned Content Metrics background task, which collects data to publish as MBeans.
Enable Versioned Content Repository Metrics MBean	false	When set to `true`, publishes information for all content repositories in which content has been stored.
Enable Versioned Content Component Metrics MBean	false	When set to `true`, for each component, publishes an MBean that contains information about the number of files, and the size and storage location of content claimed by files in each component.
Enable Top File Sizes MBean	false	When set to `true`, publishes information about the largest files stored in SCM.
File Sizes MBean – Number of Files to report	20	The number of files to report on for the Top File Sizes MBean.
File Sizes MBean – size threshold	1000000	The minimum size in bytes for files to be considered by the Top File Sizes MBean.

Content Repository Metrics MBean

When the Content Repository Metrics MBean is enabled, an MBean is published that contains a list of the content repositories in which content has been stored. The CCM database is represented as a repository with “DATABASE” as its URI.

The MBean name has the form com.ibm.team.scm.content:name="<app-context>",type=repositoryMetrics. The bean contains a list of repositories. For each content repository, the following information is published:

Property name	Description
externalURI	The external content repository URI for the content repository, or “DATABASE” for the default database repository.
totalNoOfContent	The number of unique content objects stored in the content repository.
compressedDBSize	The total number of bytes stored in the database for this content repository. For the default “DATABASE” repository, this is the compressed size of the content. External content repositories store metadata in the database.
totalSize	The total uncompressed size of the content stored in the content repository.

Component Metrics MBean

When the Component Metrics MBean is enabled, an MBean is published for each SCM component. The MBean names have the form com.ibm.team.scm.content:name="<app-context>",type=componentContent,componentNameAndId="<componentName>_<componentUUID>". For each content repository, the following information is published:

Property name

Description

componentName

The name of the component.

componentId

The UUID of the component.

ownerName

The name of the component owner. This is the name of the containing project area if the component is owned by a project or team area, or the name of the owning contributor.

ownerId

The UUID of the component owner. This is the UUID of the containing project area if the component is owned by a project or team area, or the UUID of the owning contributor.

totalNoOfContent

The number of unique content objects claimed by files in this component.

dbSize

The total number of bytes stored in the database for content claimed by files in this component.

totalSize

The total uncompressed size of content claimed by files in this component.

externalStores

A list of external content repositories in which content is stored for this component. This value will be empty if all content is stored in the CCM database. For each external content repository, the following information is provided:

externalURI	The URI of the external content repository.
totalSize	The total number of bytes stored in the external content repository.
totalNoOfContent	The number of unique content objects claimed by files in this component stored in this external content repository.

Rational Team Concert uses a hash-based storage mechanism to eliminate storing multiple copies of identical content. If identical content is checked in multiple times, only a single copy of that content is physically stored and each project, component, or file associated with that content points at the single persisted copy. The transparency to users applies to both content stored in the CCM server database and content stored in external content repositories.

The combined total of the all component metrics beans might be larger than the actual number of bytes physically stored in the database or external content repositories.

Top File Sizes MBean

The number of files reported by the Top File Sizes MBean is controlled by the CCM server advanced property File Sizes MBean – Number of Files to report under VersionedContentMetricsTask. When the Top File Sizes MBean is enabled, a bean is published for each of the largest files whose size is greater than that specified by the File Sizes MBean – size threshold (in bytes) property.

The MBean names have the form com.ibm.team.scm.content:name="<app-context>",type=topContent,rank="<N>". For each of the largest files, the following information is published:

Property name

Description

contentSize

The compressed size of this content if stored in the database; otherwise, the full content size when stored externally.

externalURI

The URI for the external content repository where this content is stored, or “DATABASE” if stored in the CCM server database.

contentClaimer

The list of files that claim this content. For each claimer, the following information is provided:

componentName	The name of the containing component.
itemId	The item UUID for the claiming file.
stateId	The state UUID for the claiming file.
approximatePath	The approximate “most popular” path for the file. The path for a file is determined by the particular directory structure of each repository workspace or stream in which it appears and, in general, can’t by computed without specifying a workspace or stream. The file might not actually exist at the approximatePath in any particular workspace, particularly if each workspace or stream that contains the file has it at a different path.

Rational Team Concert clustering considerations

If you are using Rational Team Concert in a clustered environment, consider the following items:

Your external content repository must be accessible to all nodes in the cluster. This is true for both FILE-based and WebDAV-based content repositories.
If you have content in multiple WebDAV repositories, and need to edit the credential files manually, you must update the credentials file on each node in the cluster.

Backup

When you back up a Rational Team Concert configuration that uses external content repositories, it’s important to back up the CCM database first, and then back up the external repositories. When data is restored, the server reflects the state immediately after the database backup, regardless of when the external content repositories are backed up.

If you roll back the server, you only have to roll back the CCM database. You don’t have to roll back the external content repositories. In this type of scenario, the external content repositories retain any orphaned content that was added before the database roll back, and the data integrity is not affected. The orphaned content is automatically reclaimed if the content is checked in to the server again.

The backup procedure for an external content repository depends on the type of repository. For a WebDAV content store, consult that product’s documentation for specific instructions. For a file system content store, any industry-standard file system backup procedure is appropriate.

During the time between the completion of the database backup and the completion of the external repository backups, do not use the delete content feature or the repository tools moveContent command. The delete content feature is a rare action performed by an administrator that removes content bytes from Jazz Team Server. It does not refer to the common action of checking in file deletions. Most users never use the delete content feature.

If any content deletions are performed between the two backups, after data is restored, the content delete must be reapplied to return the database to a consistent state for those items. Content deletes, if originally performed, must also be reapplied if the CCM database is rolled back and the external content store is not.

Best practices

Note the following best practices for configuring external content repositories:

WebDAV

Configure your WebDAV server to use HTTPS. Rational Team Concert uses Basic authentication to send WebDAV login credentials. Configuring your WebDAV server to use HTTPS ensures that these credentials are encrypted and not passed in plain text.
Do not use very small values for the Versioned Content External Content – Artifact Minimum Size property. The added overhead of making HTTP requests to a WebDAV server negatively affects performance if very large numbers of small files need to be accessed. The external content repository feature was designed to move large files out of the CCM server database and into external content repositories. It is not intended to move all SCM files out of the CCM server database.

Artifactory

Turn off anonymous access in Artifactory to prevent non-authenticated users from retrieving content from the Artifactory server.
If you use the content delete feature in Rational Team Concert to delete sensitive SCM content, keep in mind that you must empty your Artifactory trash folder, or configure Artifactory not to use a trash folder.

File

UNC paths are not supported. If you want to use network storage for a FILE external content repository, it must be mounted on the local file system on Linux, or mapped as a network drive in Windows.
Use canonical paths when you configure the content repository URI. Paths that contain spaces should be appropriately escaped (for example, file:////C:/Content%20Repository).

About the authors

Dean, DJ, and Andrew work on the Source Control Management (SCM) team for Rational Team Concert, and are based in the Persistent Systems lab in Ottawa, Ontario, Canada.

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Feedback

Was this information helpful?

1 person rated this as helpful.