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, set up, and run the software
Chapter 1 of this tutorial will guide you through the process of setting up and running Rational Team Concert for the first time.
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 (jazz.net), 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.
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 jazz.net 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:
- Go to http://jazz.net.
- Click the Register now! button, and follow the entire procedure.
Download and install the Jazz client
- 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, 22.214.171.124 iFix5). Do not download any other version of Rational Team Concert¸ because it might not be compatible with the Jazz server.
- Download the version for your operating system:
- 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.
- If you use a Mac, you want the 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.
- Accept the license agreement, and your download will start.
- 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:
- Go to the folder on your windows machine that you just unzipped.
- 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
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
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.
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:
- Make sure you are in the Work Items perspective and that the Team Artifacts view is selected.
- Then click the Connect to project area link to open a dialog window.
- Select Create a new repository connection, and click Next.
- 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
- Click Next to connect to the Jazz server.
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.
You will then see a list of project areas.
Figure 4. Example of a list of project areas
- 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.
- Click Finish.
In the Team Artifacts view, you will see the repository connection that you created, along with the selected project areas.
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.
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!
- Click the New work item icon (Figure 5).
- 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
You will now see the Work Item editor (Figure 6).
Figure 6. Work Item editor screen
- You need to fill in the values for this work item. These items are mandatory:
- Every work item must have a Summary, so enter one (For example: My first Work Item).
- 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.
- 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.
- 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.
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
- (Optional) You can fill the other fields if you like. However, a lot of work items do not need such precision.
- If you want to estimate the required time to complete this task enter something like
5 minsin the Estimate field.
- If you think the work item is complex enough, add some details in the Description field. You get the idea.
- If you want to estimate the required time to complete this task enter something like
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
- 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:
- Planned For
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:
- Click the drop-down arrow and select Start Working.
- Then click Save again.
The status will change to "In Progress."
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:
- Click the Add Comment link at the bottom-right of the work item editor, and enter a comment in the newly created edit box.
- When you're finished, click Save.
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
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.
- Change its status from In Progress to Resolved.
- Click Save.
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.
- To search for work items, go to the Team Artifacts view, expand the project area (in this case, CPSC 310 - Fall 10).
- Then select Work Items, > Shared Queries > Predefined (see Figure 10).
Figure 10. Predefined queries in the Team Artifacts view
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.
- Double-click the 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.
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.
To know exactly what a query is doing, try right-clicking it and selecting Edit.
How to use work items
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.
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.
- 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.
- Expand this team to see the names of all your teammates.
- Double-click on your name to open the User editor.
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!
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
- From your User editor page, click the Work Environment tab at the bottom.
- 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)
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 Jazz.net site. Like all web pages, the Jazz download pages sometimes get moved, so if the link does not work, start from http://jazz.net, log in, click the Downloads link, and select Rational Team Concert.
- For more helpful information, check the Learn More section on Jazz.net 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. You can also watch the Using Rational Team Concert in a globally distributed team webcast or a demonstration of the Dashboards and reports, or listen to the podcast about IBM Rational Team Concert and Jazz.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools, as well as IT industry trends.
- Watch developerWorks on-demand 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
- Rational Team Concert trial downloads (free):
- 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.
- Join the Rational Team Concert discussions or ask questions in the Jazz.net forums.
- Rate or review Rational software. It's quick and easy. Really.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. You'll get worldwide exposure, RSS syndication, a byline and a bio, and the benefit of professional editing and production on the developerWorks Rational website. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook and Twitter (@ibmrational), and add your comments and requests.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.
- Connect with others who share your interests by joining the developerWorks community and responding to the developer-driven blogs.
Dig deeper into Rational software on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.