Using Rational Team Concert for a software engineering class project, Part 1: Introduction to working with the team and work item features

Part 1 of this tutorial series guides you through the process of setting up and running IBM Rational Team Concert for the first time. We provide a general introduction to Rational Team Concert, the Rational Team Concert Eclipse client, and some of the fundamental concepts, mainly teams and work items.

This tutorial series describes some of the major concepts of IBM Rational Team Concert, such as work items, teams, source control, and iteration plans, and how these concepts can be used in developing a small software project using an agile process in a class setting.


Thomas Fritz (, Postdoctoral Researcher, University of British Columbia

author photoThomas Fritz received the Diploma degree in computer science from the Ludwig-Maximilians-University Munich, Germany, in 2005. He received the PhD degree in computer science from the University of British Columbia (UBC) in 2011. He has experience working as an intern with several companies, including the IBM OTI labs in Zurich and Ottawa where he worked with the Jazz work item and source control teams. He has taught the undergraduate introductory course to software engineering in the department of computer science at UBC and is currently a postdoctoral researcher at UBC. His research focuses on how to help software developers better manage the information and systems on which they work.

Meghan Allen (, Lecturer, University of British Columbia

author photoMeghan Allen received her BSC and MSc degrees in computer science from the University of British Columbia (UBC) in 2001 and 2006. She has experience working as a software developer where she used team coordination tools "in the wild." Since 2007, she has been a lecturer for the department of computer science at UBC, where she has taught a variety of undergraduate courses including the introductory course in software engineering that uses Rational Team Concert.

27 September 2011

Also available in Vietnamese Spanish

Software development teams must undertake activities such as breaking down a development project into manageable tasks, creating and changing source code, communicating with fellow developers, and managing teams. IBM Rational Team Concert collaborative project management software supports many such engineering activities and thus can form the cornerstone of software development projects.

IBM Rational Team Concert software and the IBM Rational Jazz technology that it uses can form the cornerstone of your project development. This software embodies a modern approach to software engineering and, as such, is a very good way to learn the important concepts of software engineering hands-on.

Although you might be familiar with many of the Rational Team Concert concepts, learning to use a new software tool is never easy. For example, the specific nomenclature of Rational Team Concert will sometimes differ from the one you are used to.

The goal of this tutorial is to introduce Jazz and Rational Team Concert by focusing on the skills that you need to complete a small class project. It is in no way a complete documentation of the tool and, at some point, you will probably need to dig deeper to find answers to your questions.

Install, setup, and run Rational Team Concert and the Eclipse client

Eclipse, which you may have used before, is a very good development platform for your Java™ projects. However, Eclipse is more than a code editor; it's an entirely open platform that can be extended by third-party developers. Rational Team Concert is partly an Eclipse expansion provided by IBM Rational in order to facilitate and coordinate team work.

Compared to typical Eclipse plug-ins, however, Rational Team Concert includes so many additions and customizations that it cannot be installed on top of your current version of Eclipse. Instead, you will need to download and install it from the Jazz technology website (, What you will get is a complete bundle that includes Eclipse, the typical Java development plug-ins, and all of the plug-ins required for Rational Team Concert to run.

Extending and upgrading your new Eclipse client

When you get your new Eclipse client, you might be tempted to extend it with all your favorite plug-ins or to upgrade it to the latest version. Although this can be done, it is not as simple as with a standard Eclipse installation because IBM uses customized versions of various standard packages. These customized packages live in a different directory and cannot be overridden. In other words, extending or upgrading the Rational Team Concert version of Eclipse is not as easy as extending or upgrading Eclipse. In all cases, the bundled version of Eclipse has all the tools you will need to use for this tutorial.

Install Rational Team Concert on your own machine

This section shows you how to download and install Rational Team Concert on your home PC or your laptop. We strongly recommend that you do this, because it will enable you to work on the project from home. It will also let you enjoy one great aspects of source control and of Rational Team Concert in particular, namely the fact that it can automatically replicate your entire development environment across the various computers you use. You will need to create an account on if you want to be able to browse the online documentation and download the Rational Team Concert Eclipse client.

Create a Jazz account

If you want to download Rational Team Concert, or even if you only want to browse the associated documentation, you will need to register on the Jazz Community site:

  1. Go to
  2. Click the Register now! button, and follow the entire procedure.

Download and install the Jazz client

  1. After you have registered and logged in, download the most recent fix pack (see Resources for a link).

    Make sure that you are on the page for the version of Rational Team Concert that is compatible with your server (for this example, iFix5). Do not download any other version of Rational Team Concert¸ because it might not be compatible with the Jazz server.

  2. Download the version for your operating system:
    1. Select the Microsoft Windows or Linux version from the list under Features on the left side of the page, and then select Download for Express-C.
    2. If you use a Mac, select Client for Eclipse IDE that is listed on the All Downloads page under Incubator. Again, make sure you're still on the Rational Team Concert site of the version that your server is compatible with, because newer versions won't necessarily be compatible with your server.
  3. Accept the license agreement, and your download will start.
  4. Install the Jazz client:
    • On a Windows platform simply unzip the file you just downloaded.
    • We (the authors) have never installed the client on a Mac, so you will have to figure this part out by yourself.

Run Rational Team Concert for the first time

To run Rational Team Concert:

  1. Go to the folder on your windows machine that you just unzipped.
  2. Open jazz\client\eclipse, and double-click the eclipse.exe file.

Select a workspace

The first thing that Rational Team Concert will ask you upon startup is to provide a workspace. The workspace concept is part of Eclipse; it indicates the directory where all of your source files, binary files, external Java Archive files (JARs) and other development resources (such as icons) will be stored. This is intended to be the unique entry point for development, so it might eventually get filled with various unrelated projects and libraries. This is not really a problem, however, because Eclipse offers various techniques to efficiently filter your workspace content.

If you already have an Eclipse workspace, do not use it with Rational Team Concert. This is because Rational Team Concert uses a customized version of Eclipse that seems to create various incompatibilities. Therefore, make sure that you are creating a new workspace specifically for Rational Team Concert.

After configuring your workspace, click Workbench at the top of the Welcome screen shown in Figure 1.

Figure 1. Welcome screen for the Rational Team Concert client
Screen capture, Overview on left, First Steps on right

Tip: If you don't get this welcome screen, or if you want to return to it later, simply select Help > Welcome from the Rational Team Concert menu.

Get familiar with Eclipse views and perspectives

The workbench refers to the main Eclipse window. For now, it should look similar to Figure 2.

Figure 2. Workbench with Team Artifacts tab open
Screen capture of Rational Team Concert workbench view

Click to see larger image

Figure 2. Workbench with Team Artifacts tab open

Screen capture of Rational Team Concert workbench view

The workbench contains a menu, a toolbar, a status bar, and an arrangement of subwindows. Each of these subwindows contains several tabs. For example, the currently selected tab on the left is called Team Artifacts. In Eclipse, the content of these tabs is called a view, and views are used to gather together related information.

In Figure 2, the large gray subwindow will contain special types of views called editors. You probably already know the standard editor that you use for entering Java code. Among the other kinds of editors are the work item editor and the iteration plan editor.

On the upper right, notice the Work Items button. This indicates the current Eclipse perspective. A perspective is simply a specific configuration of views and editors that facilitates a particular task.


When working with Rational Team Concert, you usually want the Work Items perspective. When editing code, you will want to be in the Java perspective. When debugging, you will use the Debug perspective. You can change perspectives through the menu by selecting Window > Open Perspective.

Remember that a perspective is simply a useful arrangement of views. You can access all of the views in all of the perspectives by using Window > Show View. You can also move views around, reorganize, or close them by clicking the X button in the tab. If you mess too much with your workbench, you can always reset it using Window > Reset Perspective.

Connect to a repository

In this tutorial, we will not go over the steps of setting up a repository, but we assume that one has been set up already. You will need to manually connect to the repository:

  1. Make sure you are in the Work Items perspective and that the Team Artifacts view is selected.
  2. Then click the Connect to project area link to open a dialog window.
  3. Select Create a new repository connection, and click Next.
  4. Fill out the form shown in the screen capture in Figure 3, but enter your server URI and your own user ID and password.
    Figure 3. Wizard for connecting to a project area
    Jazz Repository Connection dialog window
  5. Click Next to connect to the Jazz server.

    Tip: If the connection fails:

    • Make sure that you typed the correct URI.
    • Check the user ID and password.
    • Make sure that you are using the right version of the client.
  6. You will then see a list of project areas.
    Figure 4. Example of a list of project areas
    Project area selection list with check boxes
  7. Select the main project area that you will be using. In this case, select CPSC 310 – Spring 11, the project area for the class project that you are working with. You can select additional project areas if you want to connect to multiple project areas.
  8. Click Finish.

In the Team Artifacts view, you will see the repository connection that you created, along with the selected project areas.

Note: There is a difference between Java projects and the Rational Team Concert project areas. A project area is expected to group together all the development effort related to a specific product, but a product often contains numerous Java projects.


You need to be already be added to a team by the server administrator before you continue. You can check My Team Areas in the Team Artifacts view to verify that have been correctly added to your team.

Guidelines for working in accounts and projects

Always work from your own account

Do not edit or update anything using somebody else's account. It's important that everything you do and everything you work on be correctly attributed to your user name.

Do not fool around in the main project

You have a lot of permissions in the main project. For example, you could add yourself to more than one team or try customizing the process for your team. Please do not do that, because it could seriously affect the project configuration. If you are interested in exploring other features of Rational Team Concert, feel free to create a sandbox project area and do so there.

Work items

A large development project is an accumulation of small tasks, from the classes to need to code to the bugs you must squash, even including writing the documentation that your client requires. These tasks are distributed among the team's members, and it is often very useful to know what the other members are (or should be) working on. Given that Rational Team Concert is all about organizing teamwork, it provides very efficient tools to do just that.

The cornerstone of teamwork management in Rational Team Concert is the work item. Work items are tasks (usually short) that need to be performed in order to achieve a specific goal. The many attributes present in a work item let you add various details, including how long it should take to resolve, who should be working on it, and when it is due.

Create a work item

As part of this tutorial, you are required to create your first work item. Because this is one of your tasks, you should create a work item for it!

  1. Click the New work item icon (Figure 5).
  2. Select the project area that you will be working with (for this example: CPSC 310 – Spring 11), and then click Task for your work item type.
    Figure 5. New Work Item icon in top toolbar
    New Work Item icon: document with down arrow
  3. You will now see the Work Item editor:
    Figure 6. Work Item editor screen
    Summary, Status, Details, Description

    Click to see larger image

    Figure 6. Work Item editor screen

    Summary, Status, Details, Description
  4. You need to fill in the values for this work item. These items are mandatory:
    1. Every work item must have a Summary, so enter one (For example: My first Work Item).
    2. Another field that you need to fill out for every work item is Filed Against. In this example, there is a Jazz Tutorial category (for this tutorial), so select it.
    3. Another field to complete in every work item is the Planned For attribute. This describes which iteration the work item is planned for and makes it appear in the Iteration Plan, which we'll describe shortly. Choose the Jazz Tutorial Iteration, the iteration that was created for this tutorial.
    4. Finally, in the Owned By field, you can assign the work item to any member of your team. For now, assign the work item to yourself.

    Tip: If you don't see the category that you are looking for, there can be various reasons. Most likely, you did not add the work item to the right project area. Click the little arrow on the right of the work item's title, and then select Move/Copy to Project Area (Figure 7).

    Figure 7. Task drop-down menu for the work item
    Drop-down menu with list of actions
  5. (Optional) You can fill the other fields if you like. However, a lot of work items do not need such precision.
    1. If you want to estimate the required time to complete this task enter something like 5 mins in the Estimate field.
    2. If you think the work item is complex enough, add some details in the Description field. You get the idea.
  6. If a warning message appears: Hovering your cursor over this sign will probably display "Owner does not belong to Team Area" (see Figure 8). This usually means that you selected the wrong category. Make sure that you select a category (in Filed Against) that corresponds to the team that the desired owner is in.
    Figure 8. Warning about owner of the task
    Screen capture of the warning message
  7. When you are finished entering the details of your work item, click the Save button in the upper-right corner of the Work Item editor.

Notice how the work item status changes from Uninitialized to New. This indicates that the work item has been successfully created. Most of the time, you will leave it in the New state for now.

During the project, you will constantly be creating new work items, so adding a work item must be quick and easy. Make sure to master this process. They can always be clarified later, so don't hesitate to add simple work items with this minimal set of attributes:

  • Summary
  • Type
  • Category
  • Planned For

Tip: As you noticed, saving the work item does not close the editor. You could manually close it by clicking the X button, but sometimes it is good to leave it available so you can easily come back after you have completed the task.

Change the status of a work item

When you start working on a work item, however, you might want to change its status to indicate this. Do this now for your current work item:

  1. Click the drop-down arrow and select Start Working.
  2. Then click Save again.

The status will change to "In Progress."

Tip: Don't worry if you forget to change the status of a task before you start working on it. This status is usually most useful for larger tasks. Often, a small task goes directly from New to Resolved.

Discuss a work item

Work items often concern an entire team, and various team members might have opinions on how to perform the task. The best way to make sure that your thoughts are not lost is to record them in the discussion related to the task:

  1. Click the Add Comment link at the bottom-right of the work item editor, and enter a comment in the newly created edit box.
  2. When you're finished, click Save.

Note: For this tutorial, you must add at least one comment to the discussion.

Check the evolution of a work item

Complex tasks often stay open for a while. When this happens, it is sometimes interesting to check what has happened with the item in the past by clicking the History tab at the bottom of the work item editor. Click it now, and you should see something like the screen in Figure 9.

Figure 9.Task history
Task 3684 history today with options for months

Click to see larger image

Figure 9.Task history

Task 3684 history today with options for months

This window shows a timeline indicating when activity has been recorded on the work item, together with a list of the changes that have occurred. In practice, this kind of view is often used by managers to check the progress of a project and to make sure that the workload is well distributed among the team members and that everybody contributes.

Close your work item

Now that you have successfully created this work item, you have accomplished your task.

  1. Change its status from In Progress to Resolved.
  2. Click Save.

Advanced features

Work items can become quite complex. They can be organized hierarchically, they can refer to one another, they can require approval by other team members, and so on. You can find these features on the other two tabs of the work item, the Links and Approval tabs. You probably won't need these advanced features, but it's good to know what exists. Feel free to experiment with them in a sandbox project area.

Searching for work items

Creating work items wouldn't be very useful if you were not able to look for them.

  1. To search for work items, go to the Team Artifacts view, expand the project area (in this case, CPSC 310 - Fall 10).
  2. Then select Work Items, > Shared Queries > Predefined (see Figure 10).
    Figure 10. Predefined queries in the Team Artifacts view
    Tree view (directory) of queries available
  3. You should now see a long list of queries. All of these refer to work items and can be useful at various stages of the project development.
  4. Double-click Closed created by me query.

This will populate the Work Items view at the bottom of the screen. There, you should see that "My first Work Item" is now resolved.

Other queries

Take a look at the other queries. They have descriptive names that let you guess what they are doing. In reality, they are just filters over the various attributes of a work item. Try to imagine scenarios in which you would need to know all of the work items for "Open created by me" or the "New unassigned" work items.

Tip: To know exactly what a query is doing, try right-clicking it and selecting Edit.

When to create work items

Create work items as soon as you think of something to do, even if you start doing it immediately.

The reason is that work items are not only your to-do list, they are also an integral part of the project and make it possible to trace its evolution through the accumulation of tasks. So if you start working on some piece of code or writing a design document, make sure that you have a corresponding work item.

Tip: You don't have to go to the Work Items perspective to add a work item. The New Work Item icon appears on the toolbar even when you are coding or debugging.

What makes a good work item

Which of these is the best work item?

  • Implement vector addition
  • Write the vector class
  • Create the mathematics module

The answer is very subjective. A work item should be small enough to be tackled by a single individual in a short amount of time, and it should describe the work to be performed. However, it shouldn't divide the work to the point that work item maintenance becomes tedious. In all cases, don't worry if you don't get the work item right on the first try, because you can always divide it later.


Teams are made up of users: you and your teammates. This section describes how you can find and set up your user page to give a bit more information about you.

Open a user page

To get more information about a user (or add to that about yourself), you must open the user page.

  1. Open the Team Artifacts view and expand My Team Areas. This will display the list of teams that you're a part of, so look for your team for this project.
  2. Expand this team to see the names of all your teammates.
  3. Double-click on your name to open the User editor.

Tip: If you want to open the user page of somebody who is not in your team, open the Process perspective. From the Team Organization view, look for a team that includes that person.

Edit your user page

Using this editor, you can change various things in your profile, such as your name or your photo.

Change your profile photo

Change your picture now by clicking Browse and selecting a local image file. If you don't have a photograph of yourself, download a small image off the internet and use it as a placeholder. Don't forget to click Save!

Tip: Use a picture of yourself rather than an avatar. This will help your teammates identify you, especially in bigger project teams.

Edit your working hours

  1. From your User editor page, click the Work Environment tab at the bottom.
  2. Make sure that your Time Zone is set to your local time zone (for this example: America/Vancouver).


What you have learned

After completing this tutorial, you should have a basic understanding of the following important concepts of Eclipse and Rational Team Concert:

  • What the Eclipse Perspectives and Eclipse Views are and how to manipulate them
  • That Rational Team Concert helps organize the work of teams working on the same software project
  • What a project area is and how it differs from a standard Java project
  • Why it is important to work from your own account when using Rational Team Concert
  • What is a work item and what are its important attributes
  • How to quickly create a new work item and change its status
  • How to discuss a work item and check its evolution
  • How to search for work items based on various criteria
  • When you should create work items and what you should put in them
  • How to edit your user profile

What you have accomplished

If you followed this tutorial correctly, you should have accomplished at least the following:

  • Created an account on the Jazz Community Site
  • Launched Rational Team Concert and created your own workspace
  • Connected to a repository and a project area
  • Created a first work item and changed it status to Start Working and then Resolved
  • Posted your user picture (or a placeholder)

What's next

In this part of the tutorial, we provided a general introduction to Rational Team Concert, the Rational Team Concert Eclipse client, and some of the fundamental concepts, mainly teams and work items. To successfully collaborate on a project and share code with your team, there are additional concepts that are important. In Part 2 of this tutorial, we will introduce you to the source control mechanism and iteration planning tools that you will need for the evolution of your project.

Also see the Resources section for where to find more information. Get familiar with Rational Team Concert as soon as possible so that you can concentrate on your development work in the future.



  • Download the Eclipse client from the Rational Team Concert section of the site. Like all web pages, the Jazz download pages sometimes get moved, so if the link does not work, start from, log in, click the Downloads link, and select Rational Team Concert.
  • For more helpful information, check the Learn More section on or look under Help > Help Contents. There are several good tutorials and lessons on the use of basic features of Rational Team Concert, for example: Tutorials > Do and Learn > Get started with Rational Team Concert.
  • Find Rational Team Concert articles and links to many other resources on the IBM developerWorks page.
  • Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  • Watch developerWorks demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
  • Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the "Getting Started" ones are free.

Get products and technologies



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=Using Rational Team Concert for a software engineering class project, Part 1: Introduction to working with the team and work item features