Synchronize CMVC data with Rational Team Concert data

How to configure periodic synchronization of the data

IBM Configuration Management Version Control (CMVC) is older software still in use in some mainframe systems, but it has been superseded by newer Rational software, including Rational Team Concert. The tutorial explains the Item Connector Framework for integrating the two repositories and provides sample code. Learn how CMVC artifacts can be mapped to Rational Team Concert artifacts by using synchronization rules and how periodic synchronization will help you get the benefit of both applications.


Megha Mittal (, Staff Software Engineer, IBM

author photoMegha Mittal works with the Software Development Workbench team of the IBM India Software Lab. She has seven years of experience in application development, primarily in Java technology.

Ankur Sharma (, Staff Software Engineer, IBM

author photoAnkur Sharma is a staff software engineer for IBM Rational software. He has six years of experience in application development, including web application development, web services, and Eclipse Standard Widget Toolkit (SWT) development.

31 January 2012

Also available in Chinese Portuguese


IBM® Rational Team Concert™ is the collaborative planning, development, integration platform. Organizations are moving to this new platform because of great level of flexibility. IBM Configuration Management Version Control (CMVC) is used for different teams and has a lot data (millions of defects, features, tracks, and so on).

This tutorial explains how to extend the defect management features of CMVC to the Rational Team Concert environment. It describes IBM® Rational® Jazz™ Item Connector Framework, which is used for migrating CMVC data to Rational Team Concert to keep both systems synchronized, based on periodic synchronization.

Problem scenario

CMVC is two-tier application that has rich UI and backend. The UI retrieves the data from a database, based on actions in the UI.

The IBM Rational Team Concert Item Connector Framework is the framework provided by IBM® Rational® Jazz™ technology to make connections between an item in a Jazz repository and objects in any external repository.

CMVC is not event-based, so updates cannot be sent to Rational Team Concert based on updated events in CMVC. In contrast, in Rational Team Concert, any update is put in the queue as and when it occurs. So the problem is when data needs to be synchronized on both the sides.


We took approach of periodic synchronization in which updates from the CMVC are fetched at the end of some specified time interval and pushed to Rational Team Concert, and updates from Rational Team Concert are queued up to be pushed into CMVC. The only condition we have is that data should not be modified at both ends simultaneously, because that would result a conflict.

CMVC overview

The CMVC (system is a now-outdated two-tier application for configuration management and defect tracking. CMVC provides the coordination of development activities across all of these phases of the product development lifecycle:

  • Configuration management
  • Version control
  • Change control
  • Problem tracking

CMVC encompasses defects, features, tracks, level, releases, files, and user information.

The CMVC Java client API provides a Java interface for client applications to access CMVC server functionality. All CMVC graphical user interface (GUI) clients are now based on this API.

Rational Team Concert overview

IBM Rational Team Concert integrates work item tracking, source control management, continuous builds, iteration planning, and highly configurable process support to adapt to the way you want to work, enabling software developers and architects, project managers, and project owners to work together effectively. Rational Team Concert puts more focus on team cooperation and collaboration. Therefore, it makes development and project management more efficient.

Rational Team Concert provides the flexibility to create your own process template to manage work item types and workflows. You can take advantage of this flexibility to create your own process templates that follow CMVC workflows.

Design overview

According to the Item Connector Framework provided by Jazz technology, there are two major components to be developed to enable synchronization between a Jazz item and an object from any other repository.

Item Connector Client
This component lies outside of the Jazz server and is used to fetch data from an external repository and push it to Rational Team Concert.

Figure 1. Rational Jazz Team Server components and the Item Connector
Diagram of component architecture

External Repository Manager

This component is developed as a Jazz server extension and is used to transfer data from Rational Team Concert to external repository.

See the links in the Resources section for details on the Item Connector framework and creating a new item connection.


This article provides information about how to build a connector, how to import data from CMVC to Rational Team Concert, and how to periodically synchronize data.

Source code compressed files are attached with the installers.

To start with Rational Team Concert CMVC synchronizer, you need to have a Rational Team Concert client and server installed and running. Configure a development environment on the Rational Team Concert client, and set the server compatible Rational Team Concert-SDK library as the target platform in the client. (This demo is compatible with Rational Team Concert 3.0.1 SDK and CMVC 5.0.)

Incoming connector client

This has to be a plain Java application that can be run from any machine. The application will fetch the data from CMVC based on the query provided and will import the result into Rational Team Concert.

Code overview

The incoming connector client comprises these four classes:


This is the main class to start the application. It reads the argument from the property file and starts the synchronizer.

Listing 1. Some of the methods of the class
public ISyncRule getSyncRule(String type) throws
                TeamRepositoryException { 
    IInteropManager interopManager = 
    ISyncRuleHandle[] syncRuleHandles = null;
    ISyncRule syncRule = null; 
        syncRuleHandles = interopManager 
            projectArea, null); 
        if (syncRuleHandles.length == 0) { 
            throw new TeamRepositoryException("No sync rule is found in 
                this Project Area."); 
        } else if (syncRuleHandles.length > 1) { 
            throw new TeamRepositoryException("More than one sync rule 
        syncRule = (ISyncRule)teamRepository.itemManager(). 
                    fetchCompleteItem(syncRuleHandles[0], IItemManager.REFRESH, null);
    } catch(final TeamRepositoryException e) { 
        System.out.println("Exception while loading sync rule. 
    return syncRule; 
Listing 2. Set and Get methods for previous sync time
private void updatePrevSyncTime() {
    Date currentTime = new java.util.Date(); 
    Calendar cal = Calendar.getInstance(); 
    String currentSyncTime = cal.getTime().toString(); 
    DateFormat df1 = new SimpleDateFormat("yyyy/MM/dd HH:mm:ss"); 
    currentSyncTime = df1.format(currentTime); 

public String getPrevSyncTime() { 
    return prevSyncTime; 
public void setPrevSyncTime(String prevSyncTime) { 
    this.prevSyncTime = prevSyncTime; 

This is a utility class to log into the CMVC family, execute the query, and parse the result in the form of CmvWorkitemObject.

Listing 3. Method to get CMVC artifacts to be synchronized
private static final String SELECT_CLAUSE = 

public static List<CmvcWorkitemObject> 
    retrieveCMVCWorkitemListToSynch(final List<String> 
        cmvcPropNames, final String viewName, final String 
        prevSyncTime,String whereClause) throws Exception 
    Command command 
    command.addParameterValue("-general", viewName); 
    command.addParameterValue("-select", SELECT_CLAUSE); 
    if((whereClause!=null) && 
whereClause= whereClause + "AND lastUpdate >= '"+ 
    if ((whereClause!=null)&&(whereClause.length()>0)) 
        command.addParameterValue("-where", whereClause); 
            CommandResults commandResult = null; 
                commandResult = command.exec(); 
            }catch(Exception e){ 
            return parseCmvcWorkitemResult(commandResult.getMessagesString(),

This is a simple class to hold the data of a CMVC object, such as a defect or feature.

Listing 4. Parsing of the result retrieved from CMVC
public static List<CmvcWorkitemObject> parseCmvcWorkitemResult( 
        String resultMsg,String selectClause){ 
    if (resultMsg != null && resultMsg.length() > 0) { 
        final String[] attributes = selectClause.split(COMMA); 
        String[] values = null; 
        HashMap<String, String> properties = null; 
        final String[] workItemInfoList = resultMsg.split(LINE_SEPARATOR); 
        final ArrayList<CmvcWorkitemObject> workItemList = 
            new ArrayList<CmvcWorkitemObject>(workItemInfoList.length); 
        for (final String workItemInfo : workItemInfoList) { 
            values = workItemInfo.split(FIELD_TOKEN); 
            int index = 0; 
            properties = new HashMap<String, String>(attributes.length); 
            for (final String attribute : attributes) { 
                properties.put(attribute, values[index++]); 
            workItemList.add(new CmvcWorkitemObject(properties)); 
        return workItemList; 
        return Collections.emptyList();

This class is the core of the incoming connector client, which imports and synchronizes the defect or feature from CMVC to Rational Team Concert.

Listing 5. Method to push CMVC artifacts using item connector framework
 Map<String,String> attrMap = cmvcObject.getAttributesMap(); 
IInteropManager interopMgr = TestSynchronization.interopManager; 
URI u; 
IExternalState externalState = null; 
Map<String, Object> state = null; 
try { 
    u = new URI(cmvcObject.getId()); 
    attrMap.put("unique_identifier", cmvcObject.getId()); 
    attrMap.put("addDate", attrMap.get("addDate").replace('/', '-')); 
    attrMap.put("id", cmvcObject.getId()); 
    IExternalProxy proxy = interopMgr.findProxybyUri(u, null); 
    if (proxy == null) { 
        externalState = 
        proxy = InteropFactory.INSTANCE.createExternalProxy(); 
        proxy = interopMgr.saveProxyWithStateAndUri(proxy, 
                externalState, u, null); 
            externalState = (IExternalState)
            proxy = (IExternalProxy)proxy.getWorkingCopy(); 
            externalState = 
            state = externalState.getState();
            externalState = 
                    interopMgr.saveExternalState(externalState,null ); 
            }catch(StaleDataException e){ 
                externalState = (IExternalState) 
                externalState = 
                state = externalState.getState(); 
                externalState = 
                        interopMgr.saveExternalState(externalState,null ); 
        } catch (URISyntaxException e) { 
        } catch (TeamRepositoryException e) { 

External repository manager

This plug-in reside on the Rational® Jazz™ Team Server and enables synchronization from Rational Team Concert to CMVC. To enable the periodic synchronization, see Enabling outgoing synchronization in the IBM® Rational® ClearQuest® information center.

Code overview

It includes following classes:

  • CMVCCommands
  • CMVCLoginHelper
  • CMVCRepository
  • RepositoryManager


This class sends all of the Rational Team Concert updates to CMVC in the form of a CMVC query, using the CMVC Java API.

Listing 6. Method to create defect in CMVC
public String createDefect(Map<String, Object> state, 
        CMVCLoginHelper loginInfo) { 

Command cmd; 
String defectName = null; 
try { 
    cmd = CommandFactory.getInstance().getCommand("DefectOpen"); 
    for (Iterator<String> it = state.keySet().iterator(); 
    it.hasNext();) { 
        Object key =; 
        Object value = state.get(key); 
        if (value!=null){ 
            if (key.equals("compName")) 
            cmd.addParameterValue((String) key, (String) value); 
// execute command 
CommandResults commandResult = cmd.exec(); 
int rc = commandResult.getReturnCode(); 
if (rc == CommandResults.SUCCESS) { 
    defectName = commandResult.getValue(cmd.getName(), "name"); 

} catch (Exception e) { 
return defectName; 
Listing 7. Method to update defect in CMVC
 public boolean modifyDefect(Map<String,String> 
        modifiedAttr,CMVCLoginHelper loginInfo) { 
    Command cmd; 
    try { 
        String id=modifiedAttr.get("id"); 
        String name=getDefectNameFromId(id,loginInfo); 
        cmd = CommandFactory.getInstance().getCommand("DefectModify"); 
        cmd.addParameterValue("modify", "\"" + name + "\""); 
        for (Iterator<String> it = modifiedAttr.keySet().iterator(); 
        it.hasNext();) { 
            Object key =; 
            String value = (String)modifiedAttr.get(key); 
            if ((value!=null)&&(value.trim().length()>0)&& 
            cmd.addParameterValue((String) key, (String) value); 
        // execute command 
        CommandResults commandResult = cmd.exec(); 
        int rc = commandResult.getReturnCode(); 
        if (rc != CommandResults.SUCCESS){ 
            throw new Exception("Command to modify defect was not successfull"
                    + commandResult.getFailureMessages()); 
        }else { 
            return true; 
    } catch (Exception e) { 
    return false; 


This is a utility class to connect to CMVC.

Listing 8. Method to login to CMVC
public boolean loginCMVCFamily() { 
    try { 
        CommandResults cmdRes = passwordAuthenticationObject.login( 
                getFamilyInfo(), sessionDataObject, false, 0,mServerVersion); 
        int rc1 = cmdRes.getReturnCode(); 
        if (rc1 != CommandResults.SUCCESS) 
                throw new Exception("Command to login CMVC was not successfull"
                        + cmdRes.getFailureMessages()); 
            return true; 
        catch (Exception e) { 
        return false; 


This class does all necessary transformation required before sending a command to CMVC. For example Remarks is a mandatory field in CMVC, and is not mapped to the any field in this article. So before sending a command to CMVC, Summary content is also added to the CMVC’s Remarks field to avoid CMVC command failure during defect creation in CMVC.

Listing 9. Method to create final map to send to CMVC
public String Create(Map<String, Object> state){ 
    String defectID = null; 
    Map<String, Object> tempMap= new HashMap<String, Object>(); 
    try { 
        Iterator<String> it = state.keySet().iterator(); 
        while(it.hasNext()) { 
            String key =; 
            Object value = state.get(key); 
            if (key.equals("abstract")) { 
                key = "remarks"; 
        String defectName = cmd.createDefect(tempMap, loginInfo); 
        if (defectName!=null) 
    } catch (Exception e) { 
        return null; 
    return defectID; 
Listing 10. Method to create final map to be updated in CMVC
public boolean update(URI uri, Map<String, ?> newState,List<String> 
    Map<String,String> modifiedAttr = new HashMap<String,String>(); 
    boolean updateState = false; 
    modifiedAttr.put(idPropName, uri.toASCIIString()); 
    try { 
        for (Iterator<String> it = newState.keySet().iterator(); 
        it.hasNext();) { 
            String key =; 
            String value = (String) newState.get(key); 
            modifiedAttr.put(key, value); 
        if (!modifiedAttr.isEmpty()){ 
            updateState = cmd.modifyDefect(modifiedAttr,loginInfo); 
    } catch (Exception e) { 
    return updateState; 


This class is the first point of contact for the Jazz server to trigger outgoing synchronization. It implements the IInteropExternalManager interface and the AbstractInteropExternalManager class. It implements findObject, createObject, and updateState methods and returns the result of any update or creation done in CMVC back to Rational Team Concert.

Listing 11. Method to return creation info
public CreationInfo createObject(String typeName, Map<String, ?> 
        state,Map<String, Object> returnedState, List<String> 
        propertyNames,IExternalRepositoryConnection externalConnection, 
        IProcessArea processArea) { 
    URI uri = null; 
    String defectId = null; 
    try { 
        boolean login=doCMVCLogin(externalConnection); 
        if (!login){ 
            throw new RuntimeException( 
                    "Command to login CMVC was not successfull");
        defectId = gateway.Create( (Map<String, Object>) state); 
        if (defectId == null) return null; 
        uri = URI.create(defectId); 
        Map<String,Object> externalState = 
                gateway.find(uri.toASCIIString(), propertyNames); 
        if (externalState == null) { 
            return null; 
    } catch (Exception e) { 
        throw new RuntimeException(e); 
    return new CreationInfo(uri, null); 
Listing 12. Method to retun the result of update called on CMVC
public boolean updateState(String typeName, URI uri, Map<String, ?> 
        newState, Map<String, ?> lastState, Map<String, Object> 
        returnedState, List<String> propertyNames, 
        IExternalRepositoryConnection externalConnection, 
        IProcessArea processArea) { 
    boolean isDone=false; 
    Map<String,Object> newMap = null; 
    try { 
        isDone=gateway.update(uri, newState, propertyNames ); 
        newMap = gateway.find(uri.toASCIIString(),propertyNames); 
    }catch (Exception ex) { 
        if (newMap != null) { 
            return false; 
        } else 
                throw new RuntimeException(ex); 
    return isDone; 

Run the demo

There are two compressed files provided with this tutorial (see Downloads):


Download them, and follow these steps to run the demo (details in the subsections that follow):

  1. Deploy a work item server extension.
  2. Create an external repository connection.
  3. Create a custom attribute.
  4. Create synchronization rules.
  5. Run the connector client.

Deploy a work item server extension

Following are the steps for outgoing synchronization process deployment:

  1. In the Jazz server installation directory (default is /opt/IBM/JazzTeamServer for UNIX systems and C:\Program Files\IBM\JazzTeamServer\server\conf for Microsoft Windows systems), create a new folder, for example: OutgoingPlugin. Extract all files of into the OutgoingPlugin directory.

The Jazz server directory structure will now look like Figure 2.

Figure 2. OutgoingPlugin inside the Jazz Server directory
Jazz team server directory for provisioning
  1. Configure the provision_profiles directory inside the server directory:
  2. Create a new file, cmvcjazzsync-profile.ini, in the provision_profiles directory.
  3. Enter the absolute path of the Outgoing plug-in directory in that cmvcjazzsync-profile.ini file, as follows:

    If you have configured the Outgoing work item import on a Windows system, put the absolute path as OutgoingPlugin and the featureid as follows:
    url=file: ccm/sites/OutgoingPlugin
  4. Reset the server by entering the following link in the Jazz web client https://SERVER-HOST:PORT-NUMBER/jazz/admin/cmd/requestReset
  5. (Replace server host with your Jazz server name and port number with your port number.)
  6. Stop the Rational Team Concert server if it is running.
  7. Start the Rational Team Concert server.
  8. Go to the admin status page in the web client, and select the Component Status link.

You should see service on this page, as Figure 3 shows.

Figure 3. Jazz server Component Status page is the third item

In case of any problems, check the server logs and refer to the Jazz standard plug-in deployment described in detail at "Instructions on how to provision a new Jazz Server Component" (see Resources for a link).

Create an external repository connection

  1. To provide CMVC connection information, create an External Repository Connection for this project area using the Synchronization Rules View (Window > Show View > Other > Team > Synchronization Rules).
  2. Select External Repository Connection > Right Click > New > External Repository Connection.
Figure 4. Dialog window to create an external repository connection
External Repository Properties dialog window

Fill in these properties:

  • Name: Can be any name to identify this repository connection
  • Connection info: Format is familyname@hostname@port
  • User ID:cmvc.userid.
  • Password: Password of cmvc.userid (CMVC password)
  • Project Area: Select the created project area

Create a custom attribute

  1. Open the Project Area, select the Process Configuration tab and expand Project Configuration > Configuration Data > Work Items > Types and Attributes. Choose Defect as the type category.
  2. Select Defect, and click Add to add three custom attributes:
    • Field Name: cmvc_id (case-sensitive)
    • ID: cmvc_id
    • Type: Small String
  3. Click Save to save the configuration.

Create a synchronization rules

Create the synchronization rules in the project area.

  1. In the Synchronization Rules View tab, select the project area.
  2. Right-click on it and select New > Synchronization Rule.
Figure 5. Synchronization Rules view in Rational Team Concert
Selections in directory and drop-down menus
  1. When the Synchronization Rule creation window opens, type the name of sync rule: CMVCDefect (for this example).
  2. In the Type Mapping section, use these values:
    • Item type:
    • Item Type Qualifier: Defect
    • Item Manager: workitem manager
    • External Repository: Created in a previous step. CMVC repository in this case.
    • External Manager: Repositorymanager
    • External Type: Defect
  3. In the Property Mapping section:
    1. Write cmvc_id as item property (case -sensitive), set direction to IN, and set ID as external property. Also, select the External identifier check box and click Add.
    2. Write Filed Against as item property, direction as IN/OUT , and set compName as external property. Click Add.
    3. Write Summary as item property, direction as IN/OUT, and set abstract as external property. Click Add.
    4. Write Type as item property, and set direction to IN. Click OK.
    5. Select Type property, uncheck the No Transformation check box, and go to the value mapping section.
    6. Click Add.
    7. Write defect as the item value, and check the default item value check box.
    8. Click OK.
  4. In the Property Mapping view, select the Filed Against field, and uncheck the No Transformation check box.
  5. Go to the Value Transformer combination box, and select Workitem Category transformer from list.
  6. Save the synchronization rule.
Figure 6. Synchronization rule editor
Synchronization Rule editor in Eclipse client

Larger view of Figure 6.

Run the connector client

  1. Extract the file anywhere on your desktop. It will list the following files:
    • IncomingConnectorClient (Eclipse project, including source code)
    • lib
    • SynchCommand.bat
  2. Open and configure these parameters required to run the incoming connector:
    RTC_USER_NAME: Jazz server authenticated user
    RTC_USER_PWD: Jazz server authenticated user password
    RTC_REPOSITORY: Jazz server repository url
    RTC_PROJECT_AREA: RTC project area name
    CMVC_PORT_NO: CMVC family port number.
    CMVC_HOST: CMVC family host name
    CMVC_USER: CMVC family user name
    CMVC_PWD: CMVC family user password
    CMVC_QUERY: CMVC query for import and continuous synchronization
    CMVC_TYPE_TO_SYNCHRONIZE: Type of CMVC item to be synchronized.
    SYNCHRONIZE_SLEEP_TIME: Sleep time for continuous synchronization (in minutes)
  3. Save the file.
  4. These are the plug-in names that need to be put in the lib folder of demo project, IncomingConnectorClient. These plug-ins are part of Rational Team Concert SDK 3.0.1, which you can download from
    • org.apache.commons.logging_1.0.4.v200904062259.jar
    • org.eclipse.core.jobs_3.4.100.v20090429-1800.jar
    • org.eclipse.core.runtime_3.5.0.v20090525.jar
    • org.eclipse.emf.common_2.5.0.v200906151043.jar
    • org.eclipse.emf.ecore_2.5.0.v200906151043.jar
    • org.eclipse.emf.ecore.xmi_2.5.0.v200906151043.jar
    • org.eclipse.equinox.common_3.5.1.R35x_v20090807-1100.jar
    • org.eclipse.equinox.registry_3.4.100.v20090520-1800.jar
    • org.eclipse.jface_3.5.2.M20100120-0800.jar
    • org.eclipse.osgi_3.5.2.R35x_v20100126.jar
    These are the plug-in names from
    • commons-codec-1.3.jar
    • commons-httpclient-3.0.jar
    • httpclient-4.0-beta2.jar
    • log4j-1.2.16.jar
  5. Open the SynchCommand.bat file in Notepad, and configure RTC_JRE and RTC_JAVA.
  6. Save the file, and then run the SynchCommand.bat script. This will start the synchronizer, and defect data will start importing into Rational Team Concert.

Make sure that the Java path is set before running.


Code sampleExternalRepositoryManager.zip1MB
Code sampleIncomingConnectorClient.zip506KB



Get products and technologies

  • Download Rational Team Concert from (requires registration).
  • Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

Zone=Rational, DevOps
ArticleTitle=Synchronize CMVC data with Rational Team Concert data