Extending Rational Team Concert 3.x
Jim Ruehlin, Jazz Jumpstart Team
Last updated: December 12, 2011
Build basis: Rational Team Concert 22.214.171.124
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:
- Modifying a predefined template
- Project and Process Concepts: Behavior
up work items
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
- 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
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 ExtensionsClient 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 AdvisorsUse 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.
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
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.
- Work Items
- Team Process Developer's Guide
- Create a Process Aspect Editor
API for Process
- Operation Advisors (Process Advisors)
and Follow-up Actions: Creating, Specifying, and
- Pre-condition Examples
- Follow-up Action Examples
- Pre-conditions and Follow-up Actions: Creating, Specifying, and Integrating
- RTC Client
- Other Topics
- 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
Copyright © 2012 IBM Corporation