Extending Rational Team Concert 3.x

Jim Ruehlin, Jazz Jumpstart Team
Last updated: December 12, 2011
Build basis: Rational Team Concert 3.0.1.1

When you extend RTC, you programmatically add or change features in the RTC Eclipse Client or the RTC server. Either way, this is accomplished by writing Eclipse plug-ins using the RTC API.

There’s a steep learning curve required to start writing RTC extensions, particularly if you are unfamiliar with Eclipse Plug-ins. Building RTC extensions is the last alternative you should use to customize your process or RTC installation. There are many ways to customize RTC for your environment without getting into the complexity of extensions. Investigate the following areas for potential customizations before building extensions:

• Process Templates
  
• Modifying a predefined template
• Project and Process Concepts: Behavior
• Setting up work items
  

Getting Started

This section provides tutorials and setup information that will help you started extending RTC.

Learn the basics of Eclipse Plugin development
All extension development is done as Eclipse Plugin development, including server extensions. Jazz leverages the Eclipse Platform’s extensibility mechanism. The benefit of this architecture is that development of client and server side extensions are implemented in a consistent way.

If you’re new to plug-in development, here are some resources to get you started:

• Eclipse Resources: Plugins
• Some basics of the Plugin Development Environment (PDE)
• Introduction to Eclipse Plugin Development
• There are also a number of books you can purchase or download on Eclipse plugin development

Review the introductory videos on RTC extensibility

• Part I – Extending RTC with Process Advisors
• Part II – Extending RTC with Process Advisors
• Part III – RTC Process Advisor Example in Jetty

Set up Your RTC Extensions Development Environment

• View this video that describes how to set up your development environment. Note that some information describes how to set up for internal IBM development and will not be relevant to your environment.
  
• Review Server Side Development with Process Preconditions for a quick look at setting up your development environment and to see some advantages and disadvantages of different server environment setups.
• Set up your RTC extensions environment as described in Lab 1 of the Extensibility Workshop.
• Install additional development tools as necessary.
• Perform these additional setup steps if you’re developing on a Mac.

Do the Extensibility Workshop to step through setting up different development and testing environments, and to see how client and server-side extensions are written and debugged.

If you’re writing process extensions, start by understanding process pre-conditions and follow-up actions. Then see the example on Server Side Development with Process Preconditions.

Create a Hello World custom operation advisor (process extension).

Leverage the Community
Join the Extending Team Concert forum on Jazz.net.

Writing RTC Extensions

The information in this section will help prepare you to write your actual extensions.

Integrating and Extending Rational Team Concert is a comprehensive guide for day-to-day extensions development. Review this information before building production quality extensions, and use it as an ongoing reference.

Learn the details of how to build extensions as you need them by leveraging existing code samples.

There are several different types of extensions you can write:

• Client extensions add or modify functionality in the RTC Eclipse client. For example, you might decorate files in the Eclipse Package Explorer with the RTC SCM unique identifier (UUID) for the displayed file version.
• Process Advisors allow you to add pre-conditions or follow-up actions for tasks such as change set delivery. You can prevent actions from occurring  if certain conditions are not met, or kick off extra behavior after successfully completing an action. Process Advisors can run on the RTC Eclipse client or the RTC server depending on the services needed.

RTC Eclipse Client Extensions

Client extensions are standard Eclipse plug-ins that also leverage the RTC API. They run on the RTC Eclipse client and are often used to enhance the RTC Client UI or automate developer tasks. Client extensions are deployed using the standard Eclipse plug-in deployment methods.

Process Advisors

Use this information to understand how to extend processes:

• Start by reading Creating Custom Operation Advisors
• Understand process pre-conditions and follow-up actions
• Review Team Process Component of the Jazz Architecture
• Review Process Configuration for Projects and Teams. This is an overview of how processes work in RTC. Pay particular attention to Operation Behavior.
• The Process Extensions Landing Page is an introduction to the two types of process extensions (preconditions and follow-up actions) that also provides the detailed information you need to create process advisors.
  

References for developing process extensions:

• Process Aware RTC Operations: A table that provides a brief description and operation ID for process areas that can be extended. You need this information to bind your extension to the process operation you want to extend.
  
• For an in-depth discussion of how process advisors are handled by RTC, see Process Behavior Lookup in RTC 1.0 and Process Permissions Lookup in RTC.
• This topic describes how to create, specify, and integrate custom pre-conditions and follow-up actions.
• Use this list of process operation pre-conditions and follow-up actions to give you insight on what you can customize.
  
• Allow users to customize aspects of your extension by creating an Aspect Editor.

How do I…

Get the RTC API documentation?
The RTC API is documented using published JavaDoc. The documentation in the RTC SDK download, which is available at the bottom of the All Downloads page in the RTC Downloads area for the current release.

Know which API is officially supported?
The official API is documented in the published JavaDoc (part of the SDK download). If it’s in the JavaDoc, it’s official. But only part of the RTC API is included in the published JavaDoc. The part that isn’t official can be used but it may change in future releases without warning. The part that’s not official yet is not published in the API documentation. Note that at present, only part of the client-side API is in the API documentation, and none of the server-side API is published there. You can use the server-side part of the API, and any other undocumented part of the API, but be aware that it could change in future releases.

Discover which API I need?
The Yari Eclipse plug-in has the capability to report the API that is called when you click on a UI element in Eclipse. You can sometimes find the API you need directly or indirectly by using Yari to find the API that’s activated from the Eclipse UI. We’ll be providing more tips later on how to determine the APIs you’ll need for your extension.

Other Helpful Links

This section provides references on detailed and day-to-day information you’ll need when developing extensions.

• Learn more about extending the RTC API at Integrating and Extending Rational Team Concert.
• The main Development Setup page provides many tips and answers for setting up your development environment.
• See the Jazz Foundation Application SDK for information on extending the Jazz Foundation.
  

Examples and Developer Information

• Work Items
  • Programmatic Creation of Work Items
  • Work Item Web Item Proxy Designhel
  • Programmatic Link Creation
  • Bridge Between Change Sets and Work Items
    
  • Resource Oriented Work Item API
  • OSLC Change Management Interface
  • Contributing Attribute Presentations

• Process
  • Team Process Developer’s Guide
  • Create a Process Aspect Editor
  • REST API for Process
    
  • Operation Advisors (Process Advisors)
    • Pre-conditions and Follow-up Actions: Creating, Specifying, and Integrating
      
    • Pre-condition Examples
      • Server-side Development with Process Preconditions
        
      • Cancel work item save when the word “fail” appears in the work item
      • Ensure selected work items have been approved
        
    • Follow-up Action Examples
      • Link work item to promotion build
      • Trigger promotion from work item status change

• SCM
  • Using RTC Source Control APIs
  • Cancel work item save when the word “fail” appears in the work item
  • Using the SCM Command Line Interface in Builds
  • Source Control Importer
    

• Build
  • Sample code for build use case (connect to repo, request build, set label, query builds)
  • Using the SCM Command Line Interface in Builds
  • Link work item to promotion build
  • Trigger promotion from work item status change
  • Bridge Between Change Sets and Work Items

• RTC Client
  • Integrating and Extending RTC, Part III – Eclipse Client Extensions
    
  • Contributing to Team Central

• RTC Server
  • Server-side Development with Process Preconditions
  • Adding Event Handlers
    

• OSLC
  • OSLC and RTC (introduction to how RTC leverages OSLC)
    
  • OSLC Change Management Interface

• REST
  • REST: Get users from a team area and post them to a new group
  • REST API for Process
  • REST API for Security
    

• Other Topics
  • Using and Extending the Notifier for Events
  • Using and Extending the Foundation Fulltext Service (queries)
  • REST: Get users from a team area and post them to a new group
    

Best Practices

• Look for simpler solutions than creating an RTC Extension, such as customizing a process template or work item.
  
• Research the API before making promises. It’s not always possible to perform some action (or the API for that action is hidden) due to performance or other internal constraint.
• … more to come
  

How to Provide Feedback

• Post on the Extending Team Concert forum.
• Create an RTC work item if you want a new or enhanced API.
• If you have recommendations about this page, you can submit a work item or email Jim Ruehlin.
  

---

Copyright © 2012 IBM Corporation