Moving an Engineering Workflow Management (EWM) SCM component to a new EWM SCM server

This article relates to Engineering Workflow Management (EWM) Source Control Management (SCM) components. EWM was formerly known as Rational Team Concert. The products were renamed during the ELM 6.0.6.1/7.0 timeframe. For more information, see Renaming the IBM Continuous Engineering Portfolio

Newly introduced in the ELM 6.0.6.1 release, there are now two repotool commands to refactor your components across different server repositories.

Note:

1. This method of moving Components, is meant for 1-time import of components only. Once a component is imported into the destination repository, the next import of the same import with newer baselines will not be accepted during the import.

2. In case distributed SCM is enabled in the source repository (during the export of the component), this needs to be enabled in the destination repository too.

Introduction

New capabilities were introduced in the 6.0.6.1 release of EWM. This document explains about the uses of these new capabilities and their importance.

Component Export\Import

The repotools-ccm command for the CCM server now supports

• Exporting a component and the contained SCM information into an export file.
• Importing a component and the contained SCM information from an export file.

These new capabilities can be used to migrate a component from one server to another with history references without the need to use distributed SCM.

The scmExportComponent command exports the contents of source-control management (SCM) components to a .tar file. The scmImportComponent command imports the contents of an exported .tar file. The EWM SCM CLI functions that are described here must be run by a user with administrative privileges.

This section outlines the process of migrating an ELM SCM component to a new server. It provides step-by-step instructions.

Supported Use Cases

The new capabilities supports the following use cases:

• Populating a new server with an EWM SCM component’s content and history
• Migrating SCM data to another server.
• Database reduction: migrate SCM content to a new server and remove it from the original server to rebalance database sizes
• Refactoring: Separate the SCM data to a different server due to product closure or geographical repositioning
• Creating a pre-production Jazz environment with real data
• Setting up a second CCM server only for SCM/Build

Important considerations

• The initial replication can be very long-running. You can run in non business hours (resource-intensive activity).
• Issues running export\import commands with derby database, It will support derby in a network mode.
• This document was tested by using DB2 11 enterprise database.
• This document is applicable to all supported databases see link CLM 6061 System Requirements to system requirements and works when you export from one database vendor to another.

Part 1 - Export the component (Server-A)

The scmExportComponent command exports the contents of a database, scoped to a set of SCM components, to a .tar file.

The exported .tar file only contains data that is only a part of the specified SCM components and is not a full database export. You can import the .tar file onto a different server.

Use the scmExportComponent command to export the contents of SCM components to a .tar file.
Before you import components, ensure that they do not exist on the server already. All components in the archive are imported together. The following data is included in an exported component archive:

• Component
• Contained baselines
• History
• Change sets
• Files and folders that are modified by change-sets in the component, and the content that is associated with these files.
• Version identifiers, item permissions, and custom attributes for any files and folders that are part of the export.
• Contributor information for all users who create or modify any exported item.

The following data is not included in an exported component archive:

• The current state of the component in the workspace or stream, and the history of operations done in a stream or workspace. Before you export, create baselines to record the current state of any notable streams or workspaces.
• Snapshots are not included, but the individual baselines under the component are included.
• Baseline hierarchies are not included, but the individual baselines that make up the hierarchy under the component are included.

UseCase

Repository tools command to export SCM components

Use the scmExportComponent command

The export command requires a component UUID. To determine the UUID of the component use the EWM web browser or use the EWM SCM Command Line command.

Use "command prompt" for Windows operating systems. For multiple operating systems or for operating systems other than Windows, use "command line."

Example

Open a command prompt and enter the following command:

cd C:\Program Files\IBM\JazzTeamServer\server\

repotools-ccm.bat -scmExportComponent components=_iIfDAEKSEd2A5aJWEO8dbA,_pN8RYPi-Ed2J16MAqQXG5g toFile=exportComponents.tar

Open a command prompt and enter the following command: cd /opt/IBM/JazzTeamServer/server/

./repotools-ccm.sh -scmExportComponent components=_iIfDAEKSEd2A5aJWEO8dbA,_pN8RYPi-Ed2J16MAqQXG5g toFile=./exportComponents.tar

The command can also be used for multiple components. Example:

Export Command Output:

Additional fix in 7.0 & prechecklist for Import command

• Component import with new contributors does not work with OIDC SSO, fixed in EWM 7.0 version.

If scm component import contains new contributors  and the server is configured to use OIDC single sign on, then the import will fail while attempting to create the contributors in the JTS

https://jazz.net/jazz/web/projects/Rational%20Team%20Concert#action=com.ibm.team.workitem.viewWorkItem&id=489373

• Component import with new contributors does not work if the JTS is offline ( Ensure that JTS is online) , fixed in EWM 7.0 version.

When performing an offline component import, if we have new contributors then we will fail to make calls to the JTS to create the users and import will fail.

https://jazz.net/jazz/web/projects/Rational%20Team%20Concert#action=com.ibm.team.workitem.viewWorkItem&id=489374

Note: Check latest ifix for the 6061 version, if it's back-ported.

Part 2 - Import the component (Server-B)

*Use the scmImportComponent command to import the contents of an exported source-control management (SCM) component .tar file into a database.

Repository tools command to import SCM components

All data in the previously exported SCM component .tar file is imported together. Components being imported must not previously exist on the server.

• Imported components are initially owned by the default Admin user and are in an archived state. An administrator must unarchive the component and set the owner to an appropriate process area or contributor before users can access it.
• Imported files and folders with permissions set to a context that does not exist on the server are reassigned to the Admin user. When you import components onto a new server, the permission context (that is, project area) might not exist.
• Custom attributes are controlled by the project area that owns the component.
• Custom attributes of the component that is imported to a new server are retained. But users cannot set new attributes unless they are configured in the project area that owns the component.

Command Example: EWM 6061

Open a command prompt and enter the following command:

cd C:\Program Files\IBM\JazzTeamServer\server\

repotools-ccm.bat -scmImportComponent fromFile=exportComponents.tar

Open a command prompt and enter the following command:

cd /opt/IBM/JazzTeamServer/server/

./repotools-ccm.sh -scmImportComponent fromFile=./exportComponents.tar

Import Command Output:

Command Examples for: EWM 70, 701, 702 and 703

The scmImportComponent behaviour has changed from 7.0 (see defect 489374) where the 'importContributors' option has been introduced.

This option needs to be used when the archive file has new contributor records. Contributor information has to be imported first before other information like components, baselines, changesets, etc. Because while importing component or change-set information, owner info needs to be set, and running the import command with the 'importContributors' option first makes new owner info available in the server later on.

In short, when the archive file has new contributors information then the import command should be run twice, once with the 'importContributors' option first and again without the 'importContributors' option.

New usage: : EWM 70, 701, 702 and 703

./repotools-ccm.sh -scmImportComponent fromFile="exportComponents.tar" importContributors repositoryURL=https:/// adminUserId= adminPassword=

./repotools-ccm.sh -scmImportComponent fromFile="/root/exportComponents.tar" repositoryURL=https:/// adminUserId= adminPassword=

Note: The output of the scmImportComponent command with the 'importContributors' option which shows that the component/baselines/changesets are imported (but shows the time taken is 0ms which basically means they are skipped from getting imported) and a work item should be raised to fix the output message.

https://jazz.net/jazz/web/projects/Rational%20Team%20Concert#action=com.ibm.team.workitem.viewWorkItem&id=544008

Part 3 - Set the migrated component into the project Scope in Server-B

Imported components are initially owned by the default Admin user and are in an archived state. An administrator must unarchive the component and set the owner to an appropriate process area or contributor before users can access it.

1) Explicitly list archived components by using the SCM list components command.

Lists the components that are associated with a workspace, stream, or repository.

list components

Example: “code” is a component that is migrated from Server-A to Server-B

C:\IBM\RTCEE42\scmtools\eclipse>

scm.exe list components -r https://RTC6061:9443/ccm -u Admin -j --visibility archived

Note: In some cases it is seen that this command does not return any results. You can retrieve the required value under the ITEM_ID of the component - using the repodebug utility and query the SCM.COMPONENT table, and look for the component name in the NAME_COL column.

2) Change the visibility scope of the component

For example, : Private or Public, depending on what you want to set as visibility.

Note: If the alias is not working, use the components UUID in the command executions.

Set the attributes of items.

set attributes

C:\IBM\RTCEE42\scmtools\eclipses

scm.exe set attribute --component _4_gg0ON8EemgH41uLVD-BQ --visibility public -r https://db2:9443/ccm -u Admin

Password (Admin @ https://db2:9443/ccm): The component property was set.

3) Change the owner scope for the component

For Example,..: Project Area or Team Area, depending on what you want to set as owner).

Note: If the alias is not working, use the components UUID in the command executions..

Set the attributes of items

set attributes

C:\IBM\RTCEE42\scmtools\eclipse>

scm.exe set attribute --component _4_gg0ON8EemgH41uLVD-BQ --ownedby Demo -r https://db2:9443/ccm -u Admin

Password (Admin @ https://db2:9443/ccm/): The component property was set.

Post Checklist:

1) Check that the imported component is under project scope.

*Note: Imported component can be listed using the following command. *

C:\IBM\RTCEE42\scmtools\eclipse>

scm.exe list components -r https://db2:9443/ccm -u Admin -j

Password (Admin @ https://db2:9443/ccm):

2) Add the component into the stream and verify the following details.

• Component
• Contained baselines
• History
• Change sets
• Files and folders that are modified by change-sets in the component, and the content that is associated with these files.
• Version identifiers, item permissions, and custom attributes for any files and folders that are part of the export.
• Contributor information for all users who create or modify any exported item.

Cleaning up and reclaiming space

Database Growth - Strategies for minimizing the growth of repository databases, RosaNaranjo describes how to perform the final step.

In Engineering Workflow Management (EWM), the following items contribute greatly to database growth if not kept in check:

• Build results
• Work item attachments
• Binary content in SCM as versioned content

You can refer the following articles and presentations that are written on this topic:

• Help! My EWM Database is getting big!
• Follow-up to Help! My EWM Database is getting big!
• Deleting data in Engineering Workflow Management
• Reducing the size of the Engineering Workflow Management repository database
• Deleting content in EWM

Related topics: Database Growth, Deleting data in Engineering Workflow Management

External links:

• IBM

Additional contributors: PaulEllis, RosaNaranjo