Integrate Perforce configuration management with Rational Team Concert 3.0

This article explores patterns of integrating Perforce software with IBM® Rational Team Concert™. It includes a sample program for integration.

Share:

Ken Kumagai (theken@jp.ibm.com), Software Engineer, IBM

author photoKen Kumagai is a software engineer at the Yamato Software Development Laboratory at IBM Japan. He works as a developer in the IBM Rational ClearCase MultiSite team. One of his current interests is how existing systems can work seamlessly with the Rational Team Concert and Jazz technology platform, based on Open Services for Lifecycle Collaboration (OSLC). In his spare time, he enjoys reading books at the nearest Starbucks coffee shop.



14 June 2011

Also available in Chinese

Overview

You can use an alternative software configuration management (SCM) system with IBM® Rational Team Concert™ rather than the default version control system (see Resources for the link to "Integrating other SCM Systems with Rational Team Concert 2.0"). This article explains how to integrate Perforce software with Rational Team Concert by following two different integration patterns based on different use cases:

  • launch-from-rtc
  • launch-from-p4

Integration patterns

The launch-from-rtc pattern works by creating Perforce jobs, and then creating bidirectional links between the jobs and work items in Rational Team Concert when the technical lead assigns work items. Perforce changelists can also be created and linked to the work items. Developers can use Perforce to check in and check out files by using these prepared jobs and changelists, without being aware of the work items. Later in this article, there are procedures for implementing this pattern.

Figure 1. launch-from-rtc pattern
diagram of launch-from-rtc pattern

The launch-from-p4 pattern works by creating bidirectional links between Perforce changelists and the work items in Rational Team Concert when the changelists are submitted. Perforce jobs that are attached to changelists and work items can be linked to each other. Developers with Perforce can dynamically link additional changelists to work items by selecting their IDs as necessary while development progresses. This pattern and a procedure for implementation are described in the article titled "Integrate Perforce software with Rational Team Concert" (see Resources).

Figure 2. launch-from-p4 pattern
a image of launch from p4 pattern

Both of these patterns complement each other and do not conflict. You can use either of them to address various use cases. Alternatively, after the launch-from-rtc pattern is used, developers can add changelists later by using the launch-from-p4 pattern.

Setup

Prerequisite software

The examples that are used in this article run on Microsoft Windows. cURL and Perl are not necessarily restricted to the Cygwin runtime system.

  1. Prerequisites for Perforce
    • Command-line client (P4)
      • P4 must be installed on the same machine with Rational Team Concert.
      • A user called p4tester with the password p4tester uses P4.
    • Visual client (P4V)
      • Developers must check in or check out files with P4V.
    • Server (P4D)
      • P4D must run on port 1666.
    • Web client (P4Web)
      • P4Web can be installed on the same machine as P4D.
        • P4Web must be running with the -B option in viewer mode to allow access from remote machines.
        • Links written in the work items will be http://(the same machine as P4D):8080/xxx
      • P4Web can be installed on each developer's machine but not on the machine with P4D.
        • P4Web is running as default mode to allow each developer to access it locally.
        • Links written in the work items will be http://localhost:8080/xxx
      • P4Web must run on port 8080.
  2. Prerequisites for Rational Team Concert v3.0
    • Client for Eclipse IDE
      • A user named tester with the password tester uses the client for the Eclipse IDE.
      • A project area named TestProject must be created by the user.
    • Server
      • The server must run on port 9443.
  3. Prerequisites for Cygwin cURL, Perl
    • cURL and Perl must be installed on the same machine as the Rational Team Concert server.
Figure 3. System configuration
image of a system configuration

Install the Perl script

  1. Copy launch-from-rtc.pl and P4RTC.pm to C:\cygwin\usr\local\p4rtc-pl on the machine where Rational Team Concert (RTC) server is installed.
  2. Modify the following environment parameters to match your environment in P4RTC.pm:
    • Perforce: $P4RTC::p4web, $P4RTC::p4d_port, $P4RTC::p4user, $P4RTC::p4pass,$P4RTC::p4user_client
    • Rational Team Concert: $P4RTC::rtc_user, $P4RTC::rtc_pass, $P4RTC::rtc_serv, $P4RTC::rtc_path

Install the plug-in for Rational Team Concert

  1. Ensure that the Rational® Jazz™ server is shut down.
  2. Copy p4bridge.site to C:\ProgramFiles\IBM\JazzTeamServer\server\conf\ccm\sites
  3. Copy p4bridge.ini to C:\ProgramFiles\IBM\JazzTeamServer\server\conf\ccm\provision_profiles
  4. Add properties to server.startup.bat under C:\ProgramFiles\IBM\JazzTeamServer\server (see Listing 1). The required properties are p4rtc.runtime and p4rtc.program, which are used, respectively, for a runtime path to run a linking program and a path for a linking program. The property p4rtc.skipword is optional and is used for a word to skip while running a linking program if the word exists in the summary fields of the work items. The p4rtc.checkbox property is also optional and is used for the label of a check box to decide whether or not to run a linking program.
Listing 1. An example of setting properties
set JAVA_OPTS=%JAVA_OPTS% -Dp4rtc.runtime="C:\\cygwin\\bin\\perl.exe"
set JAVA_OPTS=%JAVA_OPTS% -Dp4rtc.program="C:\\cygwin\\usr\\local\\
	p4rtc-pl\\launch-from-rtc.pl"
set JAVA_OPTS=%JAVA_OPTS% -Dp4rtc.skipword=p4skip
set JAVA_OPTS=%JAVA_OPTS% -Dp4rtc.checkbox=p4link
  1. Start the Jazz server.
  2. Modify the operation behavior of save workitem:
    1. Open the project area.
    2. Select a role by clicking Process Configuration > Team Configuration > Operation Behavior > Workitem > Save workitem.
    3. Click Add.
    4. Select Create and link P4 objects in Save (P4 Bridge) (see Figure 4).
    5. Click OK and then click Save.
Figure 4. Select the P4 bridge
screen cappture of selecting p4bridge
  1. (Optional) Use Request Server Reset if you update the plug-in and must copy it again:
    1. https://hostname:port/ccm/admin?internal#action=com.ibm.team.repository.admin.serverReset
    2. Shut down the Jazz server, perform Step 2, and then start the Jazz server.

Customize the work item editor in Rational Team Concert (optional)

In some situations, users want to decide whether Perforce objects are created and linked when work items are created in Rational Team Concert. One option is to add a check box by customizing the work item editor. Users select the check box if they want to create and link Perforce objects when they create work items; otherwise, they can deselect it (Figure 5).

Figure 5. Add a check box
image of p4link checkbox

To add a check box to the work item editor, you must add attributes and decide on specific layouts.

  1. Open a project area with the Project Area editor.
  2. Modify types and attributes to add attributes to work items:
    1. Expand Process Configuration > Project Configuration > Configuration Data > Work Items > Types and Attributes.
    2. Select a work item type (Figure 6). For example, click Defect to extend the work item editor for the defect type.
Figure 6. Select a work item type
image of a work item type
  1. Click Add in Attributes to fill in the following fields, and then click OK (Figure 7):
    • Name: p4link
    • ID: p4link
    • Type: Boolean
Figure 7. Add an attribute to a work item type
Screen capture of adding an attribute
  1. Repeat steps 2 and 3 to further customize the work items.
  2. Modify editor presentations to decide on the layouts where the added attributes will appear:
    1. Expand Process Configuration > Project Configuration > Configuration Data > Work Items > Editor Presentations.
    2. Select a work item type (Figure 8). For example, select com.ibm.team.workitem.editor.default to extend the work item editor for the defect type.
    3. Click Details under Overview, and click Add Presentation.
      • Attribute-based Presentation: Selected
      • Attribute: p4link
      • Kind: Boolean
      • Label (optional): p4link
      • Description (optional): Link work item to p4 objects
      • ID (optional): p4link
      • Hide in Workflow States: Select In Progress, New, Reopened, Resolved, Verified under Defect Workflow
    4. Figure 9 shows that the attribute p4link is at the last position in the Details pane.
    5. Repeat Steps b through d to customize the types of work items as needed.
Figure 8. Select a work item type for the layout
Screen capture of the action
Figure 9. Add an attribute to a layout.
Image of adding an attribute into a layout.

Use case

The following use case happens between two roles: a technical lead and a developer.

  1. The technical lead creates a work item in Rational Team Concert.
    • A switch controls whether a Perforce job and changelist are created. Here, this switch is implemented both as a check box and by a keyword in the work items. If the customized check box exists, then the decisions conform to the value of the check box. If the check box does not exist, then the decisions depend on the existence or absence of the keyword in the summary fields of the work items.
    • If the switch is selected, both the Perforce job and changelist are created automatically, and then they are linked to the work item during the saving process (Figure 10).
    • If not selected, neither the Perforce job nor the changelist are created.
  2. The developer receives an email notification of the new work item from Rational Team Concert.
  3. The developer checks out, edits, and checks in the files in the Perforce changelist.
  4. The technical lead modifies the status of the work items and receives an email notification of the status changes from Rational Team Concert.

    Note:
    Changing the status of work items does not create a Perforce changelist or job. They are only created when the work item is created.
  5. The developer submits the files by using the Perforce job and then closes the Perforce job.
  6. The technical lead confirms that the Perforce job is closed and then closes the work item.
Figure 10. Links to a Perforce job and changelist
Links to job and changelist

Implementation

To automatically create a Perforce job and changelist while creating a work item in Rational Team Concert, the saving process for the work item must be hooked to execute the Perforce commands for the creations of the Perforce job and changelist. Do this by implementing a run method for com.ibm.team.process.common.advice.runtime.IOperationAdvisor. These steps might be necessary in the run method.

  1. Create a Perforce job and changelist.
  2. Enter the URL of the work item in the description fields of the Perforce job and changelist.
  3. Enter the URLs of the Perforce job and changelist into the related artifact field of the work item in Rational Team Concert.

Note:
There is a problem in the third step. Updating the fields of work items is forbidden in a run method because the update invokes an additional saving process, which causes an infinite loop. We suggest that you only create and start a new thread in the run method. An external script processes these three steps inside the newly created thread after the run method has finished.

Implement the plug-in for Rational Team Concert

For a full explanation of how to create plug-ins for Rational Team Concert, see "Rational Team Concert - Creating Custom Operation Advisors" in Resources. The following procedure shows you how to create the plug-in, feature, and update site projects that are used in this article.

  1. Set up the SDK for Rational Team Concert v3.0 (see "Set up the Target Platform" in RTCSDK20_DevelopmentEnvironmentSetup).
    • Download and extract the Rational Team Concert SDK from Rational Team Concert 3.0.
    • Select Window > Preferences > Plug-in Development > Target Platform > Add, and click Nothing: Start with an empty target definition.
    • Then click Next.
    • In the Name field, enter RTC-SDK-30, and click Add on the Locations tab.
    • Click Installation, and then click Next.
    • Browse the root directory of the extracted Rational Team Concert SDK, click Finish, and then click Finish again.
    • Click RTC-SDK-30 on Target Definitions.
    • Click OK.
  2. Create the Plug-in project:
    • Project name: p4bridge
      • ID: p4bridge
      • Version: 1.0.0.qualifier
      • Name: p4bridge
      • Deselect Generate an activator, a Java class that controls the plug-in's life cycle.
    • Select This plug-in is a singleton on the Overview tab in the plugin.xml file.
    • Add the following required plug-ins in the Dependencies tab in the plugin.xml file:
      • org.eclipse.core.runtime
      • com.ibm.team.process.common
      • com.ibm.team.process.service
      • com.ibm.team.workitem.common
      • com.ibm.team.repository.common
      • com.ibm.team.repository.service
      • com.ibm.team.workitem.service
    • Fill in the Extensions tab of the plugin.xml file (Figure 11, Figure 12):
      • Extension points: com.ibm.team.process.service.operationAdvisors
      • ID: p4bridge.operationAdvisor
      • Class: p4bridge.P4BridgeCreateAndLinkInSave
      • Name: Create and link P4 objects in Save (P4 Bridge)
      • operationID: com.ibm.team.workitem.operation.workItemSave
      • Select New > extensionService by right-click on the operationAdvisor, and input componentId, implementationClass.
        • componentId: p4bridge.extensionService
        • implementationClass: p4bridge.P4BridgeCreateAndLinkInSave
      • Select New > prerequisites by right-click on the extensionService, switch to plugin.xml tab, and add com.ibm.team.workitem.service.IWorkItemServer as requiredService (Listing 2).
      • In the New Java Class dialog window, click the class link to create the class that implements com.ibm.team.process.common.advice.runtime.IOperationAdvisor, and implement the P4BridgeCreateAndLinkInSave class (see Listing 3).
      • Save.
  3. Create the Feature project:
    • Project name: p4bridge.feature
    • Feature ID: p4bridge.feature
    • Feature Name: p4bridge feature
    • Feature Version: 1.0.0.qualifier
    • In the Referenced Plug-ins and Fragment section of the New Feature dialog window, select p4bridge.
  4. Create the Update Site project:
    • Project name: p4bridge.site
    • Click Add Feature on the site map tab in the site.xml file, and select p4bridge.feature.
  5. Build, export, and set up:
    • Select PDE Tools > Build Site by right-clicking on the site.xml file in the p4bridge.site project.
    • Select Export > File System by right-clicking on the p4bridge.site project.
    • Enter the file path in to directory. Click Finish.
    • Install the plug-in (see Install the plug-in for Rational Team Concert subsection in the Setup section).
  6. Troubleshoot if the newly created plug-in does not display in the process configuration:
    • Confirm that plugin.xml is selected at binary build on the Build tab in plugin.xml file in the p4bridge project.
    • Use Request Server Reset, and restart the Jazz server to clear the caches.
    • Restart the Eclipse client to clear the caches.
Listing 2. Add required service under prerequisites
...
<extensionService
componentId="p4bridge.extensionService"
implementationClass="p4bridge.P4BridgeCreateAndLinkInSave">
<prerequisites>
  <requiredService 
  interface="com.ibm.team.workitem.service.IWorkItemServer" />
</prerequisites>
</extensionService>
...
Figure 11. Define operationAdvisor
a image of operationAdvisor definition
Figure 12. Detailed information of operationAdvisor
a image of operationAdvisor in details

Listing 3 is the implementation of the run method of the com.ibm.team.process.common.advice.runtime.IOperationAdvisor interface. There are three points to notice:

  • First, the method should be run only when a new work item is created, so the method is executed only when the getOldState method returns null.
  • Second, skipping is decided by whether there is a customized check box on work item editor or a keyword in the summary field of the work items.
  • Third, a new thread, thRun, calls an external script to handle the creation and linking of the Perforce jobs and changelists after the run method is finished.
Listing 3. The run method in the P4BridgeCreateAndLinkInSave class implementing the IOperationAdvisor interface.
private int workitem_id;
...
public void run(AdvisableOperation operation, 
    IProcessConfigurationElement advisorConfiguration, 
    IAdvisorInfoCollector collector, IProgressMonitor monitor)
    throws TeamRepositoryException {
  ...
  Object op_data = operation.getOperationData();
  if (op_data instanceof ISaveParameter) {
    IAuditable new_state = ((ISaveParameter) op_data).getNewState();
    IAuditable old_state = ((ISaveParameter) op_data).getOldState();
    /*
     * The 1st point.
     * a linking program can be executed only during the creation of work items.
     */
    if (old_state == null && new_state instanceof IWorkItem) {      
      /*
       * do these.
       * - check the existence of the customized check box.
       * - get a boolean value of the check box if it exists.
       */
      boolean doP4Link = false;
      IWorkItem workItem = (IWorkItem) new_state;
      IWorkItemServer wiService = getService(IWorkItemServer.class);
      List<IAttributeHandle> attrs = workItem.getCustomAttributes();
      boolean doesP4RtcCheckboxExist = false;
      if(attrs != null){
        for (IAttributeHandle attrHandle : attrs) {
          IAttribute attribute = 
            wiService.getAuditableCommon().resolveAuditable(attrHandle, 
            IAttribute.FULL_PROFILE, monitor);
          if (attribute.getDisplayName().equals(p4rtc_checkbox)) {
            // the customized checkbox exists.
            doesP4RtcCheckboxExist = true;
            Object value = workItem.getValue(attribute);
            if( value instanceof Boolean){
              // get the value of the checkbox.
              doP4Link = (Boolean)value;
            }
          }
        }
      }
      
      // get summary text for skipping decision by key word
      String summary = workItem.getHTMLSummary().getPlainText();
      
      /* 
       * The 2nd point.
       * a linking program is decided to be executed in either of these two conditions.
       * - checkbox exists and the value is true
       * - the checkbox does not exist and a key word does not exist in summary text
       */
      if((doesP4RtcCheckboxExist && doP4Link)
      || (doesP4RtcCheckboxExist == false && summary.contains(p4rtc_skipword) == false)){
        try{
          workitem_id = workItem.getId();
          Runnable th = new Runnable(){
            public void run(){
              try{
                ProcessBuilder pb = new ProcessBuilder(p4rtc_runtime_path, 
                  p4rtc_program_path, "" + workitem_id);
                pb.redirectErrorStream(true);
                // The 3rd point. a linking program is executed outside of the plug-in.
                Process ps = pb.start();
                getStdout(ps);
              }catch(Exception e){
                e.printStackTrace();
              }
            }
          };
          Thread thRun = new Thread(th);
          thRun.start();
        }catch(Exception e){
          e.printStackTrace();
        }
      }else{
        //skip p4 link
      }
    }
  }
}
...

Implement the Perl script

For this article, we implemented the external script in Perl by following these steps:

  1. Log in to the Perforce server.
  2. Create a Perforce job:
    1. Name prefix job_rtc plus the ID of the work item.
    2. Enter the URL of the work item into the Description field.
  3. (Optional) Create a Perforce changelist.
    • Enter the name of the Perforce job into the Jobs field.
    • Enter the URL of the work item into the Description field.
  4. Log in to the Rational Team Concert server.
  5. Ensure that the work item has been saved in Rational Team Concert.
  6. Update the work item:
    • Enter the URL of the Perforce job into the related link field.
    • (Optional) Enter the URL of the Perforce changelist into the related link field.
    • (Optional) Enter any additional information into the discussion field.

Summary

This article described integrating Perforce software with Rational Team Concert by following the launch-from-rtc pattern. It showed the sample source code and a script. As the next step, the status of the jobs in Perforce and the state of the work items in Rational Team Concert can be synchronized so that when the jobs are closed, the state of the work items close automatically, and vice versa.


Acknowledgements

The author thanks Masaki Wakao and Kotaro Shima for technical advice.


Downloads

DescriptionNameSize
Plug-in projects for Rational Team Concertp4bridge-all.zip19KB
Perl scripts for integration p4rtc-pl.zip7KB

Resources

Learn

Get products and technologies

Discuss

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=678888
ArticleTitle=Integrate Perforce configuration management with Rational Team Concert 3.0
publish-date=06142011