About this article
This article describes, in detail, various concepts of the Jazz platform in detail. It explains how to set up your development environment with all of the required plug-ins, describes views, and defines terminology. After you have the environment set up, you will create a Project Area for project management and define a team that will be able to use the Project Area. You will also learn about the various views and perspectives in Rational Team Concert. The article covers these topics:
- Downloading the software and setting up the environment
- Downloading plug-ins for Rational Team Concert (Jazz Team Server, Jazz client, and more)
- Downloading plug-ins and add-ons for Mozilla Firefox
- Setting up the Project Area
- Understanding various views
- Team Artifact view
- Work Item view
- Pending Changes view
- Adding users to the Project Area
- Modifying user preferences
- Creating a Team Area and adding users
- Creating components in stream
- Defining an integration stream
- Managing the Project Area
- Creating work items and assigning them to users
- Creating a repository workspace
- Creating blank projects and delivering them
- Linking work items
In this article, you learn how to:
- Download and install the Jazz server and client on a machine that is running Microsoft® Windows®
- Download and install any additional plug-ins needed for JUnit, codegen, and Aptana and Mozilla Firefox plug-ins
- Understand Jazz terminology and the views in Rational Team Concert.
- Create a Project Area and basic structure of the project
This article assumes that you are familiar with the concepts of the Eclipse™ IDE, including views, editors, panels, and so on. We also assume that you understand the various concepts of enterprise-level development, such as source file management, project management, and defect management.
- Access to Jazz.net or any other location where you can download Rational Team Concert
- Microsoft Windows operating system with a minimum of 1Gb of RAM
- Mozilla Firefox Version 2.0.0 to use with the Web-based interface to the application
Set up the environment
For this article, we used Rational Team Concert Beta 3 RC5 source and binary files. These are available for download from Jazz.net (see Resources).
At the time of publication of this article, Rational Team Concert Version 1.0 is available from the link below. The versions of additional components will vary, based on the versions of required components.
To set up a development environment, you need to download the package shown in Table 1.
Table 1. Required components
|Jazz binary and source files||Client and server binary and source files (login required)||Get the files|
Extract these files to a location on your machine, such as
C:\Jazz. We will refer to this location as the <install loc> later in this article. If you have any problems extracting the files, you can find the detailed instructions for extracting these plug-ins and setting up Rational Team Concert can be found on the Component development page on the wiki.
Additional components useful in building applications on the platform
By default, only the required plug-ins are packaged. If you will be building on the Jazz platform, you will need to add the plug-ins shown in Table 2.
Table 2. Additional components
|JUnit plug-in||JUnit plug-in binary files||JUnit plug-in files|
|EMF full plug-in||Complete EMF plug-ins (v 2.3.2) for modeling||EMF plug-in files|
|codegen plug-in||Wrapper on EMF code generator||Get the codegen plug-in|
Extract these plug-ins in the
<install loc> where you already have the client and server binary files for Jazz and Rational Team Concert.
To debug your application on the web user interface add Mozilla Firefox plug-ins for debugging.
Table 3. Mozilla Firefox add-ons
- Under improper shutdown of Mozilla Firefox, or a script error, these add-ons malfunction. Under extreme conditions, it is possible that you may not be able to activate these plug-ins for an instance of Firefox.
- To overcome this problem, close all instances of Mozilla Firefox by selecting File > Exit. If your modifications are not reflected in the Web pages, try clearing the Firefox cache. Remember to clear the Authenticated Sessions and open the Web page in debug mode.
Set up the Project Area
Now that you have all of the plug-ins downloaded and extracted, you are ready to start the server. You will then connect to it to create a Project Area and modify it further.
- Open the installation location (for example, C:\Jazz) and navigate to <install loc>/jazz/server.
- Double-click the server.startup.bat file that you find there to start the server. This will bring up the server console window where you will be able to see the messages.
Whenever you want to shut down the server, always use theserver.shutdown.bat file that is in the same location. Improper shutdowns of the server might lead to inconsistent states.
Create the Project Area
A Project Area is where you will manage all of the work related to the project. This will consist of the Team Area, various streams (such as code, integration, and so forth), components, work items, and more. A server can host multiple Project Areas, and the data for each is managed separately.
First, you will create a connection to the server and then create a Project Area in the server
- Navigate to <install loc>/jazz/client/eclipse and select the TeamConcert.exe file to open the application.
- Select a workspace location, such as C:\TestWorkspace, and click OK.
After Rational Team Concert launches, you will see a screen similar to the one shown in Figure 1.
Figure 1. Rational Team Concert view
- The view on the left is the Team Artifact view, which provides easy navigation in your Project Area.
- Click the Create Repository Connection link in the Team Artifact view.
Figure 2. Create Repository Connection
- Enter the URL as
https://localhost:9443/jazzand the user name and password as
- Change the connection timeout to
localhost because we have the server running on the same machine as the client. If the server were running on a remote machine, we would have used the IP address and network name of that machine. Because we have a fresh server running, we used
ADMIN as the user name and password. After we set up the Project Area, we can add users. Thereafter, users can access the Project Area by using custom user names and passwords.
- The server needs to be running to be able to connect to the server by using the Rational Team Concert client. If you are getting a "Login failed" message, it is possible that the server is not started yet. Check for an "INFO: Server startup in xxxx ms" message on the server console. If you are not able to see this message, wait for a while and then try to log in again.
- With Beta 3, Jazz has added restrictions based on authentication. We will explicitly apply specific extra privileges to allow the ADMIN user to create a Project Area.
- Right-click on the repository connection and select Administer > Open users.
- In the dialog, enter
ADMIN, click Select to select that user, and then click Finish.
- In the ADMIN user page, in the Client Access License section, allow ADMIN access to all areas by selecting all three check boxes.
- Save the user preferences and close the editor.
Figure 3. Enabled ADMIN license
The Team Artifact view shows the connection and other information (see Figure 4). Now you will create a Project Area.
- Right-click on the repository connection and select New > Project Area (see Figure 3).
Figure 4. New Project Area
PetStoreas the name, and click Next.
- Select Deploy Template. (This deploys the default process definitions provided with Rational Team Concert.)
- Select The Eclipse Way for Process (Figure 5), leave the defaults for the rest of fields, and click Finish.
Figure 5. The Eclipse Way
This will create a Project Area named PetStore and initialize it with the process that you selected.
Explore Rational Team Concert views
After creating the Project Area, there are various views in Rational Team Concert that are similar to the one shown in Figure 6. If you do not see this screen, select Windows > Show View to get the Views menu.
Figure 6. Views
Team Artifacts view
There is a PetStore Project Area visible now that has various subnodes:
- Builds: After you define a build script for your project, you will be able to start a build, as well as see the in-progress build status and the build reports from this section. You can also configure your build to run automatically.
- Plans: Because we used The Eclipse Way as the process, you will be following the agile process for development. In this section, you can define your iteration plans and milestones.
- Reports: There are various reports that are pre-created for your Project Area. You can also create custom reports for analysis purposes.
- Streams: The development process can be defined to use multiple streams for various reasons. For example, there might be a development stream for Milestone 6, a stability stream for Milestone 5, and yet another stream as a maintenance line for Milestone 4.
- Work items: Similar to reports, you can define a query or use a shared query to fetch work items. Work items can be of various types, such as defects, tasks, or enhancement requests. The Jazz work item component is built so that you can define your own work item type, as well.
- Favorites: You can select a work item and add it to your Favorites list. By doing this, the change sets or the files that you have changed and are about to deliver will get automatically associated with the work item in your Favorites.
- Feeds: A general feed mechanism is built ito Jazz. Updates will be reflected through feeds.
- Workspaces: Under My Repository Workspace, there is a PetStore Team Stream Workspace, which is automatically created. This is the work area where all of your files will be stored ( (for IBM® Rational® ClearCase® users, this is similar to a view). Unless explicitly delivered, the files are not delivered in the stream.
- Team Areas: This section displays the various Team Areas that you are part of. There can be multiple Team Areas in the same project, and a single contributor can be a part of multiple Team Areas.
- Work Item History: This shows the latest work items that you have visited or modified.
Work Item view
A work item is something that is to be completed in the domain of this project area. It could be a task, a defect, or an enhancement, for example. The Work Item view (Figure 7) shows a list of work items. You can customize this view at run time by choosing the columns that you want to see for the work items. You can also modify the column widths by dragging the borders. Double-clicking on the view opens the work item in the editor. The multi-page work item editor is very useful. You will see how to use it shortly.
Figure 7. Work Item view
Add users to the Project Area
You will create two users, Joe and Larry, for the PetStore project. (You can use the same process for creating more users.)
- Right-click on the Project Area in the Team Artifact view (Figure 8), and open the project area.
- Expand the Members section and select Create.
- Select Create new user and click Next
Figure 8. Create User
- Enter these details for Joe:
- Name: Joe
- User ID: joe
- E-mail address: firstname.lastname@example.org
- Click Next.
- On the next screen, provide the Repository Group permission for this user. For Joe, use the JazzUser permission level, and then click Next.
- To provide the Client Access License, select Contributor and Developer access by clicking the check boxes for each.
- Click Finish to close the dialog.
Because we used a trial version of the software for this article, only 10 users are allowed for Contributor and Developer roles. A full version of Rational Team Concert and Jazz allows more users.
- Using a similar method, create another user named
Larrywith these details:
- Name: Larry
- User ID: larry
- E-mail address: email@example.com
- Click Next.
- Assign the Repository Group as JazzUser.
- Assign the user's Client Access License as Contributor and Developer.
- You want both users to be able to contribute to the project, so assign them Contributor roles.
- Select the newly created user Joe from the Member section in the Project Area, and click Process Roles.
- Select Contributor from the available roles, and click Add (see Figure 9).
Figure 9. Assign roles to users
- Repeat the process for Larry.
- Save the process by using CTRL+S.
- You might be asked if you want to send e-mail notifications to the newly added users. Clicking OK will send e-mail to the users at the e-mail addresses that you entered for their user IDs.
Modify user preferences
Jazz allows users to modify their profiles by using User Preferences. Users can modify their profile details, customize their e-mail preferences, upload image files for their profiles, and schedule their time-away information by using Rational Team Concert. Next, you will modify the user Joe to upload a photo for him and customize the e-mail alerts for him.
- Open the Team Organization view by selecting Windows > Show View > Others > Team > Team Organization.
- Right-click on Joe and select Open to open the multi-page editor.
- On the Overview page, open the Photos section and browse to upload any image file that you want to add for this user. You will be able to see a preview of the image that you upload.
- Select the Mail Configuration page in the editor.
- Uncheck the check box for the Tags Added of Removed option. This will disable e-mail notification when tags are modified for a given work item.
- You can also enable HTML formatting of e-mail messages by checking the check box under the Format section.
- Save the user preference and close the editor.
Figure 10. Modify User Preferences
If you want to subscribe to notifications for any event generated by a specific user (for example, Creation of Work Item or Modification), you can right-click on the user name and select Subscribe to Events Generated by User. You will receive a notification whenever the user's action creates an event.
Create a Team Area
- To create a new Team Area, open the Project Area in the editor if it is not open already. Click the arrow beside the Project Area heading, and navigate to the Team Area option (Figure 11).
Figure 11. Team Area view
- Select an existing repository connection and click Next.
- Enter the name as
Core(see Figure 12).
- Enter the summary as
This Team Area will consist of the core development team.
- Click the Browse button beside the Project Area and select PetStore.
- If Main Development is not selected as the development line, click Browse and select Main Development Line.
- Leave the defaults for the other options and click Finish.
Figure 12. Create new Team Area
Add users to the Team Area
After you have created the Team Area, it will open it in the editor space and you can add users.
- Click the Members section to expand it if it is collapsed.
- Click Add users (to add existing users) (Figure 13), select Joe and Larry, and click Next.
Figure 13. Add users to the Team Area
- Select Contributor as the role and then click Finish to close the dialog. This will add the user to the Team Area.
You can also create new users from this page and then add them to the Project Area.
- Create a new user,
John, who will be the team lead:
- Name: John
- User ID: john
- E-mail address: firstname.lastname@example.org
- Click Next.
- Select JazzUser for the repository group and click Next.
- Select Contributor and Developer as the Client Access license and then click Finish (see Figure 14).
Figure 14. Client Access License view
- Select John from the Member section and click Process Roles.
- Select teamlead as the Role and click OK to close the dialog.
- Save the Core Team Area.
- On Save, select the users that you want to send e-mail to, and then click OK.
By default, because you created the user John in a Team Area, John will not have access to the Project Area. Therefore, you need to add John to the Project Area members. See the Add users to the Project Area section of this article for details.
Create components in the stream
A project can include multiple components. For this exercise, you will create one component named PetStore, where you will add new plug-in projects. You can create components in your repository workspace and then deliver them to the stream. Given that you have not manipulated your repository area, you will do this from the stream definition.
- In the Team Artifacts view, navigate to PetStore Project Area > Streams > PetStore Team Stream.
- If you open the PetStore team stream, you will see that Jazz has created a default component. Double-click on the stream and then double-click on the PetStore Team Stream tab in the upper right of the workspace to expand the stream definition view.
- Under the Components section, select the default component and remove it.
- Click New (Figure 15), and click OK for any warning that you get.
PetStoreas the name of the component and then click OK.
- Save the stream definition.
Figure 15. Add a new component
Define a stream
A project can have multiple streams during a development cycle. For example, in agile development, the current milestone could be M5, but you might have a separate stream for maintenance for M4 installation bits. Another scenario could be that a product comprises various smaller projects, all of which have separate streams. For the project to build, all internal project streams should flow into what is called an integration stream. From there, the overall project is built. You will define an integration stream from which you will build your application. The main stream (PetStore Team Stream) and its various components will flow into the integration stream.
- In the Team Artifact view, right-click the Stream node and select New Stream.
- Provide the name as
PetStore Integration Stream(see Figure 16).
- Browse to select the Owner of this stream as Core [Main Development].
- Under the Flow Targets collapsible section, click Add.
- Select the PetStore Team Stream. This will enable the stream to flow into the integration stream.
- Select the PetStore stream and click the Edit button on the right.
- You need all of the components in this stream to flow into the PetStore integration stream; therefore, select the Flow all components radio button and click OK.
- Save the stream before proceeding.
Figure 16. Create a new stream
Manage the Project Area
Next, you will create a work item for John, the team lead, for him to create empty projects and then share them in the Project Area. John has no information about the work item that is being created for him. He will receive e-mail notification when he is added to the Team Area and when a work item is assigned to him.
Create a work item and assign it to a user
- From the File menu, select New > Others.
- From the wizard, under the Work Items node, select Workitem and click Next.
- Select PetStore Project Area and click Next (see Figure 17).
- The next screen will ask you to specify the type of work item. By default, Rational Team Concert provides Defect, Task, and other types of work items, which are listed on this screen. Select Task and click Finish.
- In the work item editor, enter this information:
- Summary: Create project structures and share them in the PetStore project area
- Description: Create three plug-in projects:
- Add these projects to the Core component.
- Change Filed Against to
- You need to assign this work item to the team lead, John, so change the Owned
By field to
- Change the Priority to High and change "Planned for"
Because you are using the Eclipse way as the process and agile planning, Rational Team Concert has created Milestone 1 (M1), and you are assigning the work item to that milestone.
Figure 17. Create work items
The work item assigned to John will need modifications to the stream, component, build system, and so forth, which only users who have certain privileges can make. With Jazz Beta 3, only one user per installation has the Administrator rights. In this case, that is presently the ADMIN user. Therefore, ADMIN will now reassign the administrator rights to John, the team lead.
- In the Team Artifacts view, right-click the repository connection, select Administer and Open Users.
ADMINas the name of the user, and click OK.
- On the ADMIN user page, in the Client Access License section, deselect the Build System check box and save the user definition.
- Following the same process, open the entry for the user John and select the check box for Build System in the Client Access License section.
- In the Repository Group section, select Jazz Admins so that John has the Administrator rights, as well.
- Save the user definition.
You have completed some of the initial tasks that must be done by the ADMIN user. You will now log in as John and do the rest of the tasks. You can do this either from the same Rational Team Concert instance by changing the user name and password of the repository connection or by logging in from a different machine or instance of Rational Team Concert.
To log in as John (use
john as the user name and
password), refer to the initial section of this article where you created a repository connection
and logged in as the ADMIN user.
By default, all of the users have the same passwords as their user names.
As John logs into the Project Area, he will see his Team Artifacts view, which is similar to the one shown in Figure 18.
Figure 18. Team Artifacts view
In the Team Artifacts view, John can see all of the changes that the ADMIN made. He can see the Project Area, streams component, his Team Area, and the other users in the Team Area. Similarly, the other users, Joe and Larry, can see these changes.
Next, you will open the My Work view to see the work items assigned to John, and you will modify the estimated time of the work items.
- Navigate to Window > Show View > Others > Workitems > My Work.
- You can see in the newly assigned work (PetStore), there is a work item that ADMIN created yesterday and assigned to John.
- Double-clicking on the Summary will open the description of the work item. This is a quick view of the work item.
- Click the clock icon in the right corner of the work item, and change the estimated time to 4 hours (Figure 19).
Figure 19. Provide a time estimate for the work item
- Click the Accept all Work link in the inbox so that you can save your estimate for the work item.
- Use the Save icon inside of the My Work view to save the work item with your estimate.
- The text box at the bottom of this view allows you to search, filter, and color code the work items. This view also allows you to drag work items from one section to another.
- You can also open the Work Item view and see the work items assigned to you. Double-clicking on the work item will open the work item, and you can modify the fields in the editor (Figure 20).
Figure 20. Work item editor
The estimated time in the work item appears as 4hrs, which we had modified from the My Work view.
Create the repository workspace
John realizes that to complete this work item, he will need a workspace to create projects. Then, from his workspace, he can deliver the changes to the stream.
- In the Team Artifacts view, right-click My Repository workspaces and select New Repository workspace
Figure 21. New repository workspace
- Select the stream:
- From the Repository drop-down menu, select john@localhost. Note: If the server is running on a remote machine, localhost will be replaced by the network name of the machine.
- Select the radio button for Flow with the stream. Choosing this option enables you to receive the latest changes in the stream. When others check in their code, you will see it as incoming to your workspace.
- Select the PetStore Project Area and the PetStore Team Stream (see Figure 22).
Figure 22. Select a stream for the repository
- You can change the name of the workspace but, for now, leave it as the default and click Next.
- The next screen shows the various components available in the stream, including the PetStore component. Select it and click Finish.
- This will create a repository workspace for John.
- John will be prompted to load the repository. Performing this action will fetch all of the files available in the repository in John's local workspace. Because there aren't any files in the repository yet, you can skip this step for now. Click Cancel to close the dialog.
There are three places where the code resides, in this order:
- Your local workspace on your development machine
- Your Jazz repository, like the one that you just created
- The project main code stream, which is where it is picked up during the build.
When code is to be
moved from location A to location B, you must call a
action. When you want
to push the changes from location B to location C, you call a
Later, you will see how to perform all of these actions. By default, everything
that you write and save on the local workspace (location A) gets checked into your
Jazz workspace (location B). You can modify this setting by using the Preference
option of Rational Team Concert.
Create blank plug-in projects and add them to the component
Now you will update the work item to show the status as In Progress.
- Open the work item by using the Work Item view to change the state to Start Working. This will change the start to In Progress.
Now you will create blank plug-in projects (common, service and Web) and then add them to the PetStore component.
- Select File >New >Project >Plug-in Development >Plug-in Project.
- Enter the Name as
com.ibm.petstore.example.commonand click Next.
- Deselect Activator generation and the contribution to UI check boxes and click Finish.
- Create two more plug-in projects,
com.ibm.petstore.example.web, by following the same procedure.
- In the Package Explorer view, right-click the com.ibm.petstore.example.common package and select Team > Share Project (Figure 23).
Figure 23. Share a project
- Select Jazz Source Control and click Next.
- Select PetStore component under PetStore Team Stream Workspace (Figure 24) and click Next.
Figure 24. Select a component to share projects
- Select the three newly created projects and click Finish.
The Pending Changes view
This view is useful in visualizing what files, folders, and components are different from the ones that are in the stream. You have added three new projects to the stream, but you have not delivered them yet. These are available only to John right now, but they will be available to other users also when they are delivered to the stream.
- Select Window > Show View > Others > Pending Changes to open the view.
- In this view, you can see an Outgoing node (Figure 25) for the three projects created.
Figure 25. The Outgoing node in the Pending Changes view
- The Share Project comment is added to this change set by default. You can change the comment of the change set to make it more descriptive by clicking on the comment and editing it.
- You should always associate the change set with a work item before delivery to the steam. This enables better traceability of the change sets. Therefore, right-click on the change set and select Associate with work item (Figure 26)
Figure 26. Associating work items with the change set
- Enter the initial few words of the work item or the work item number in the filter box, and the work item will be visible in the bottom section.
- Select the work item and click OK. This will associate the change set with the work item.
- Again, right click on the change set and select Deliver to push the changes into the stream.
You have delivered the first change into the stream. Hereafter, whenever users log in and try to create workspaces, they will be able to see these changes by default. John has completed the work item, so he can now resolve the work.
- Open the work item from the Work Item view.
- Change the state to Resolve and save the work item.
Link work items
John now decides to create a few more work items for himself, Joe, and Larry:
- Create a model definition (John)
- Create services to access data from the model (Joe)
- Create a Web UI for displaying the data (Larry)
John also creates a work item for himself to define a process for running and testing the project from the workspace (Run/Debug configuration). This will enable developers to test their plug-ins without the need to deploy the projects on the server. The definition will pick up the latest code from the workspace and use that whenever you start the server.
To understand how to create work items and assign them to users, review this topic: Create a work item and assign it to a user.
Figure 27. Work Item view updated
Given that Joe's and Larry's work items are related to each other, you will create a link between those work items.
- Open Joe's work item for creating services.
- The work item editor is a multi-page editor, so you need to click the Links page
- In the Links section, click Add to open a menu
- Select the Add Related option (Figure 28).
Figure 28. Link work items
- In the Work Item Selection dialog, select Larry's work item and click OK.
- Save the work item.
- Now that both work items are linked, if you open Larry's work item, under the Links section, you will see Joe's work item for creating services marked as a related work item.
Joe and Larry have received e-mail notifications of their work items, and they have logged in to create repository workspaces (see the Create the repository workspace topic): "Joe's PetStore Team Stream Workspace" and "Larry's PetStore Workspace." Load all of the plug-ins into the workspaces when prompted to do so.
Because you have multiple workspaces now, any changes made and delivered from one workspace will be seen as incoming changes in other user's workspace. These incoming changes will be visible in the Pending Changes view.
In cases of conflicting incoming changes (when you have made changes in the file that was modified by another user, for example) you will see another node in the Pending Changes view named Unresolved. Most of the time, the built-in file comparison feature and Auto Merge will resolve the changes. If Auto Merge is unable to do that, you will have to resolve the disparities manually. You can use the Compare editor to resolve conflicts.
You have the initial environment to develop projects. You have created a Project Area and defined the team. You have also created a stream and a component in it where your source code will reside, and you learned about repository workspace, work items, views, how to use them, and so forth.
John has created a few work items for defining a models, providing services, and creating a Web user interface.
- Get an overview of the Jazz platform.
- Visit the official Jazz Web site (registration required, free), where you will find videos, news, downloads, and plug-ins.
- Check the Jazz wiki where you can find many related articles and ask questions
- Found a bug? Create a new work item so that our Jazz developers can fix it. Make sure to check first to see that the bug is not already filed to avoid duplications.
- Interested in learning about how to use the Scrum Process to manage your Rational Team Concert projects? Read IBM author Millard Ellingsworth's article How to use the Scrum project management method with IBM Rational Team Concert and the Jazz platform.
- In the Architecture area on developerWorks, get the resources you need to advance your skills in the architecture arena.
- Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- Download a free trial version of IBM Rational Team Concert Standard Edition.
- Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
- Join the Jazz Forum where you can ask specific questions related to the platform.
- Check out developerWorks blogs and get involved in the developerWorks community.