Jazz Library Getting Started with Rational Team Concert: A Deployment Guide
Author name

workflow-management,rational-team-concert

Wed, 20 Jan 2010
5 min read
0

Getting Started with Rational Team Concert: A Deployment Guide

The Jazz Jumpstart Team: Jim D’Anjou, Original Author
The Jazz Jumpstart Team: Dan Toczala, Technical Focal Point
Last updated: June 9, 2011
Build basis: Rational Team Concert 2.0.0.2

Note:This article is outdated and is replaced by Rational Solution for Collaborative Lifecycle Management 2012 deployment guide in the Deployment wiki. In the future, all deployment guidance and best practices will be published in the Deployment wiki rather than as Jazz.net articles.

Note: This guide is no longer being updated, and has been superceeded by Getting Started with Rational Team Concert 3.x: A Deployment Guide.

Introduction

This guide provides a roadmap as you embark on a deployment of Rational Team Concert (RTC) into your organization. It is designed to be a lightweight guide that identifies the appropriate questions and considerations and then points to other information sources for details and more expansive discussions of the topic. It is written from the perspective of the Jazz Jumpstart team and their collective experiences from executing numerous product deployments around the world coupled with liberal references to tutorials, articles, videos, and product documentation created by the experts: the Team Concert development team.

For your deployment of RTC you probably need only examine a subset of the topics below. Topics are grouped together based on what elements of RTC you are adopting. Every deployment requires examination of the topics in the first grouping named Required. If you are using RTC for planning and project management you will be interested in Project Management grouping. If you are developing applications then the Application Development grouping will be of interest. Many deployments require some interoperability with your existing tooling environment and you will want to explore the Integration grouping.

You will notice as you read this guide that it achieves its lightweight appearance by liberally referencing existing information on Jazz.net. It is not possible to keep up with all the relevant new information. The Jazz.net library is your friend. Here is the link for the Rational Team Concert Library. The library is large and growing. All the library items have tags associated with them to help you find what you are looking for. For example the tag SCM will get you all the source control topics. There is a tag list on the page to help you as well. For each deployment topic the suggested library tag (s) are included under heading: References for Further Reading. You can also stay current by subscribing to the RSS feeds for the Jazz Library, Jazz Announcements, the Planet Jazz, and the Jazz Team Blog.

This presentation from Rational Software Conference 2009 provides a useful road map for adopting RTC: RSC 2009: SDP20 – Getting Starting with IBM Rational Team Concert. Also you may find the topic of interest from IBM Dan Toczala’s personal blog: How Do I Deploy Jazz?

If you are interested in the basic functionality of Rational Team Concert, and would like a chance to experiment with some of the features and capabilities of the Jazz platform, then please go and try using the Jazz Sandbox environment.  This is a temposrary, hosted environment, where you can create your own instance of RTC over the internet, and see what Jazz and RTC have to offer.

Table of Contents

Note: Product documentation links are to Rational Team Concert 2.0.0.2.

Jazz Team Server Installation

Return to top

Getting Started

Installation is generally pretty straight forward. For a basic installation with the Express-C edition you may simply install the server with it’s embedded Derby database, start the server, and move on to the next phase of your deployment. In a large global enterprise you will probably want to consider your hardware needs, your network configuration, database requirements, possible deployment on IBM Websphere Application Server, as well as high availability requirements. If you are upgrading to a new product release then migration is also a consideration.

Generally, the following basic steps are common to most installations. Some of these installation steps are also are re-occurring administrative steps that will be covered in the Jazz Team Server Initial Setup and Administration section of this guide.
  1. Pre-plan your installation
  2. Install Team Concert
  3. Set up the database
  4. Configure your server
  5. Populate users
  6. License key management
Most of the installation information is contained in the Team Concert product documentation. A number of articles on Jazz.net supplement this information.
  1. Pre-plan your installation
  2. Install Team Concert (including database setup, and server configuration)
  3. Populate users
  4. License key management

Going Further

Depending on your needs, the following information will assist you with specialized installation requirements.

Rational Team Concert Library (tags install, installation manager)

  1. Database
    TN0036: Configuring IBM DB2 V9.5 for online backups for Rational Team Concert V1.0
    [1391062] Creating a DB2 temporary tablespace for use with Rational Team Concert 2.0
    [1391063] Additional configuration required when using the RTC Server with Microsoft SQL Server J2EE datasource
    [1391050] Rational Team Concert Server connection to a Microsoft SQL Server 2005/2008 using a Java 1.6 VM
  2. Performance and Scalability
    Using content caching proxies for Jazz Source Control
    2.0 and 1.0.1 – TN0032: Configuring proxy server caching with Rational Team Concert
  3. Using Websphere and High Availability
    Deploying Rational Team Concert 2.0 on WebSphere Application Server for high availability using idle standby
    Tech Tip: Installing Rational Team Concert 2.0 with WebSphere Application Server 6.1.0.25 / 7.0.0.3
    [1391790] Required updates for WebSphere Application Server to install the IBM JRE 1.5 or 1.6 required for RTC 2.0
    [1390685] Rational Team Concert repository database collocation recommendation
  4. Special topics
    TN0022: Installing from a DVD on Linux
    TN0031: Deploying the Rational Team Concert Help WAR for internal access
    TN0010: Running Jazz Team Server in Tomcat as a Windows Service
    [1391231] Setting up a Rational Team Concert local update repository served by an HTTP server
  5. Rich client installation
    Installing the Rational Team Concert Client
Wiki Pages

Jazz Team Server Initial Setup and Administration

Return to top

Getting Started

At this point, your server should be correctly installed. You will have to start it so it can be configured.
This section will explain:
  1. Database creation
  2. The Jazz Team server startup process,
  3. The setup wizard which guides you through the steps configure your server
  4. The Admin web UI to complete or change the server configuration.

Database Creation

If you will be running against a database other than the default Derby database included in the installation, then you will need to create a database before continuing to setup the application. See Product documentation: Setting up the database. DB2, Oracle, and SQL Server databases are supported.

Starting the server

Depending on the application server (Apache Tomcat server or a WebSphere Application server) you have deployed, starting your Jazz server will be different.

Setup wizard

Running the setup wizard guides you through the server configuration steps. This procedure assumes your server is available using the default port 9443. If you are using the Apache Tomcat server installed with the product, start the setup wizard open the URL https://<your server>:9443/jazz/setup in a supported web browser. If you are installing against Tomcat, the default user name is ADMIN and the associated password is ADMIN. If you are installing against WebSphere Application Server (WAS) then you should have already repository access to your user directory with the JazzAdmin repository permission assigned. Login with that ID. 

The wizard will assist you in setting up:
  1. Database configuration: To specify the database vendor (DB2, Derby, Oracle or SQL Server) and the database connection properties.
  2. E-Mail server configuration: to specify the SMTP server to use for mail notifications.
  3. Public URL: The repository may have an alternate host name through which it can be publicly accessed. When this property has been set this URL will be used for as the basis of absolute URIs that are made available outside of the client and server, such as e-mails, URIs copied to the clipboard, the web UI, etc.
  4. User registry: To specify how the user authentication will be performed (Tomcat user authentication, connected to an LDAP server, Windows Active directory, or to a Non-LDAP External Registry). This step will also assist you in creating or designating the user who will administrate the server.
The setup wizard will ask you to choose between the Fast Path Setup or Custom Setup. The Fast Path Setup uses the default configuration for the 3 first steps to directly configure the User registry. This option is good for people who want to quickly experience Jazz technology. Custom Setup goes through all the steps and is what you should use when setting up a production, enterprise deployment. You can always start by the Fast Path Setup and come back later to configure the other points either by using the setup wizard or directly using the Administrative Web UI.

Administering the Jazz Team Server through the Web interface

After you install and start your server you can access the web interface to perform administrative tasks such as managing users and configuring or troubleshooting the server. To access the Admin web UI, use a supported web browser to navigate to the administrative page https://<your server>:9443/jazz/admin. Use the user name and the associated password that you defined in step 4 of the Setup Wizard (User registry) when you designated the user who will administrate the server. The product ships with a user named ADMIN which has administrative privileges. If you haven’t disabled the default ADMIN user, it is recommended that you disable it after you have defined your administrative user.

This Web UI allows you to:

Going Further

If there is a requirement for interoperability with other Jazz team servers see this deployment topic: Integrating

If there is a requirement for interoperability with other Jazz team servers see this deployment topic: Integrating products based on Jazz.

References for Further Reading

Project Area Setup

Return to top

Getting Started

At this point your server is up and running, and your user id is defined with a repository permission of at least JazzProjectAdmins and you have been assigned a developer license. This will allow you to create and manage project areas. This section covers the following:

  1. Preparation, including a discussion of scoping a project area to an organization.
  2. Choosing a process template.
  3. Creating a project area.
  4. Basic project area customization.
  5. Defining your teams to the project.

If you are creating a new project area that is designed for exploration and evaluation you can disregard most of this information for now. It becomes relevant when you create a project area that will host real application assets and a team responsible for managing them. Much of the information is contained in the Team Concert product documentation. A number of articles on Jazz.net supplement this information.

Preparation

  1. Start by reviewing Working with projects, teams, and process in the product documentation to get familiar with the terminology and concepts. The article, Getting Started with Project Areas and Process in Rational Team Concert 2.0 is very helpful. You need not read it all initially but you will be referring to it along the way. Your first decision is to decide the scope of your project area. A project area defines both an organization and the software artifacts that it is responsible for (plans, work items, code streams, builds, reports, and dashboards). The scope could be very small with just a 1 or 2 people who own a single application to a very large project involving hundreds of people, many teams, and multiple applications. The reason this is a consideration is that project areas cannot be split or combined so it is important to make this decision with care. Note that dashboards can roll up information across project areas, work items can be copied or moved between project areas, and source code components can be made accessible to other projects. Here are some guidelines:
    1. The highest degree of collaboration is within a project area. Evaluate the common collaboration boundries in your organization and chose a project area scope that maps most effectively to your needs. You have the ability to define project area membership into teams and sub teams. Artifacts like plans, streams, builds, and dashboards are scoped to specific teams so that even in a large project a specific team doesn’t get overloaded with content that is logically in the domain of another team.
    2. By default the content in all project areas is readable by everyone who has a repository user id. If you have a need to restrict data access to just members of the project area, limiting read access could help determine your project area boundaries (see Project Area Access Control).
    3. As you grow you may find that your usage is exceeding the capacity of the server hosting your team server. At this time it is not possible to move or copy a project area for capacity management purposes. However, you can duplicate a repository and selectively archive a subset of projects in each duplicate.
    4. For organizations with significantly differing development processes it is advisable to scope a project area to match an organizational segment that shares a common or nearly common process. Process is scoped at the project area level. Teams areas within a project can further customize their process but generally they are following the majority of the process defined for the project. (see Process Configuration for information)
  2. The first decision you must make when creating a project area is decide on a process template that will define the initial process for the project. A set of predefined templates are provided. Prior to creating your project area you should review the process template descriptions listed under the topic Process Templates in the product documentation table of contents. See also this Jazz team wiki page: Comparing the predefined process templates. You can modify the process for your project later but it is useful to pick a process that is a reasonable match to your needs. You cannot assign a different template after the project area is created. There are some legacy process templates that are no longer in the product but can be found here: [1391603] Agile and Eclipse Way process templates available as a separate download.
  3. You can create the project area from the Web interface or from the Eclipse client after you have logged in as yourself with the JazzProjectAdmins repository permission and a Developer Client Access License (the predefined ADMIN user cannot do this operation).
  4. After the project area is created assign your project leads to the project area. If the process template applied to the project area has defined a leadership role (teamlead or scrum master, for example) associate that role to the project leaders so that they have adequate project operation permissions (this can be fine tuned later). It is advisable to assign a user as administrator who can make changes in cases where the other project members do not have the necessary permissions to do this. Generally, project area initialization process will create a team area, a default timeline structure, a source code stream for the newly defined team area, and some initial work item categories. Note that when you assign users to the project area and a team area you will have the opportunity to send them an email invitation if e-mail notifications have been configured for the Jazz Team server (see the Joining a Team in Rational Team Concert 2.0 for more information about invitations).
  5. This completes the basic project area and team area setup. Before you open the project up to member usage you should make sure you protect your information properly.
    1. Project area permissions: In the project area you should examine the repository operation permissions for the various project area roles that you will assign to users to ensure that you are limiting repository operations to those users that need them. For example, you should limit source control operations to developers. It may be necessary to create new roles to provide the granularity that you require. Some users may be assigned multiple roles. See Product documentation: Working with projects, teams, and process, Modifying permissions, Modifying permissions in the Web client and video Rational Team Concert 2.0 Permissions Overview.
    2. Project area access control: By default any user with a repository user id has read access to all repository content. If you need to limit this access you should define access control rights in the project area. See Product documentation: Restricting read access to the project area.
  6. Next you will assign your initial team members to your team area and possibly expand the team area structure with peer teams and sub-teams to match your organization. You can create your team structure and team membership and roles using the web UI or the Eclipse client. In the Eclipse client you should do this in the Team Organization view. See the subtopics Product documentation: Creating and modifying a team area. For larger or highly distinct teams, team areas allow for more manageable access to artifacts of interest to the team. A team can have its own distinct timeline, plans, code streams, work items, and builds. Also a team can have it’s own customized process that might deviate from the overall project process (see Process Configuration for information). This allows for a project area with a common process model yet contains teams with diverse operational needs.
Other project area items like timelines will be covered under adopting Plans and work item categories will be covered under adopting Work Items. Process configuration and customization will be covered under Process Configuration.

References for Further Reading

Rational Team Concert Library (tag project area)
[1390870] The 2.0 Rational Team Concert predefined Process Templates
[1390698] Upgrading process templates when migrating from Rational Team Concert 1.X to 2.X
[1391603] Agile and Eclipse Way process templates available as a separate download

Process Configuration

Return to top

Getting Started

At this point you have a working project area and have had some exposure to process configuration as defined in Project Area and Team Area Setup by assigning roles to users, setting repository operation permissions, and specifying any read access control that might have been necessary. After this you should review and possibly modify the process configuration associated with key operations like saving a work item, delivering a source control change set, or managing builds. The process template associated with the project area usually sets some permission for these operations and minimally they should be reviewed and modified to match the needs of the project. Other topics like work item customization which are enacted in the project area are covered in their respective adoption topic.

Start by reviewing Working with projects, teams, and process in the product documentation to get familiar with the terminology and concepts. The article, Getting Started with Project Areas and Process in Rational Team Concert 2.0 is essential.
  1. If you are adopting Work Items then you should review and adjust the process permissions associated with the work item save operation.
  2. If you are adopting Source Control then you should review and adjust the process permissions associated with the source control deliver operation.
  3. If you adopting Build then you should review and adjust the process permissions associated with the various build operations particularly the delete operations.
  4. In general you should review the permissions for all artifact delete operations to ensure that they are assigned to a responsible role.

Going Further

Advanced process modification may involve the following types of activities that require deeper understanding of the Jazz process component.
  1. Defining new roles that meet the needs of the organization and specifying what repository operation permissions are associated with this role. This is covered in the Product documentation: Roles section.
  2. Creating a new process template that reflects the needs of the organization (usually after some experience). This is often seeded from a working project area and then revised for general use. This is covered in the Product documentation: Process Templates.
  3. Modifying the process configuration source (XML data) to do things that are not possible in the process configuration UI. An example would be tailoring the team invitation a user receives to create a set of invitation work items that better fits the project (hint: search for com.ibm.team.process.server.generateTeamInvitation in the process configuration source).
  4. Adding team area specific process customizations that allows a team to refine the project area process to meet the needs of the team. This is done in the team area editor but the process is the same as with a project. See Process behavior lookup in Rational Team Concert 2.0.
  5. Adding iteration-specific process customizations that adjust the process for a given iteration and its child iterations. Often, it involves setting a more restrictive process for source control delivery such as requiring an approved work item. Sometimes you will want to share process customizations between iterations that are not related hierarchically. For this you can use iteration types as described in this development wiki entry on Custom Process Creation (see the “Usage of iteration types” section). Iteration types can be created while editing any iteration from the project area editor Overview page and can then be customized on the Process Configuration page.
  6. And the most advanced activity is extending the capabilities of Process by authoring new preconditions or follow-up actions. This requires extending the Team Concert Eclipse client or the Jazz Team Server. See this development wiki page which discusses this topic. Also see the Team Concert SDK and Jazz Foundation Services SDK.

References for Further Reading

Rational Team Concert Library (tag process)
Rational Team Concert 2.0 Permissions Overview
Creating a Process Template – Part 9 – RTC Temperature Conversion Demo
Translatable Process Templates
Translatable Process Templates in Rational Team Concert 2.0
Process permissions lookup in Rational Team Concert 2.0
Creating a Process Template – Part 9 – RTC Temperature Conversion Demo
RSDC 2008, SDP27: Bring Your Process to Life: Process Enactment in IBM Rational Team Concert
From The Eclipse Way to Jazz
Blog: Sprinting towards Scrum
[1391603] Agile and Eclipse Way process templates available as a separate download
[1391039] Development lines have been renamed to timelines
[1390698] Upgrading process templates when migrating from Rational Team Concert 1.X to 2.X
[1390870] The 2.0 Rational Team Concert predefined Process Templates

Adopting Work Items

Return to top

Getting Started

Organizations that are adopting the work items feature of Team Concert are usually taking advantage of its planning capabilities as well. This section covers work item adoption. See the Plans section for information on that topic. Adopting work items generally involves these major tasks.
  1. Configuring your project area to support your use of work items.
  2. Possibly customizing work items content to better fit the data needs of the project team.
  3. Possibly importing data from other change management tools.
  4. Learning to use work items.
  5. Using and creating work item queries.
The Product documentation: Tracking Work Items covers the work item topic. A number of articles on Jazz.net supplement this information. The article Getting Started with Work Items in Rational Team Concert is a thorough introduction to work item functionality and is recommended before getting started. The configuration and customization activities require use of the Team Concert Eclipse Client.
  1. Configuring your project area to support your use of work items.
    When the project area is created some default configuration settings are defined that allow work item creation right away. Configuring your project area to support your project’s use of work items is recommended. This is pretty straight forward and is covered in Product documentation: Setting up work items. The article Configuring Project and Team Areas for Work Items is a very helpful addition. The work items types that are available are set based on the process template chosen when the project area is created.
  2. Customizing work items to better fit the data needs of the project team.
    This is a more complex task and can be deferred unless there are mandatory requirements for custom work items before the project can get started. Here is the relevant information on this topic.
    Product documentation: Customizing work items
    Work Item Customization
    Work Item Editor Presentations
    RSC 2009: SDP24 – Customizing IBM Rational Team Concert Work Items and Process
    Work Item Customization – Part 7 – RTC Temperature Conversion Demo
    Work Item Customization – Part 8 – RTC Temperature Conversion Demo
    Work Item Attribute Value Providers (advanced customization including emerging scripting support)
  3. Importing data from other change management tools.
    Data can be imported from Bugzilla or in a format that is compatible with it, files using the CSV (comma separated variable) format, and ClearQuest. Here is the relevant information:
    Product documentation: Setting up work items (this covers Bugzilla and CSV files).
    Product documentation: Using the ClearQuest Import Wizard to import records (the ClearQuest client is required)
    Guide to migrating defects from Rational ClearQuest to Rational Team Concert 2.0
    TN0007: Guide for Importing Jazz Work Items from Bugzilla and Other Systems
  4. Using work items.
    The article Getting Started with Work Items in Rational Team Concert is a good overview. Also see the “Working in …” topics in Product documentation: Tracking Work Items. Of course, you will want to keep track of what is happening to your work items. See Tracking Work Item Changes in Rational Team Concert 2.0 for the best practices specific to work items. See Best practices for using news feeds to track events in Rational Team Concert for best practices for tracking events in general.
    1. Using and creating work item queries. Nearly all users will find it useful to understand the query capability.

Going Further

Most of the information was conveyed above. It is important to review the process configuration for work items. Review the role access for repository operations like work item save and work item query. It is also useful to review and determine if modification to any work item fields requires restriction to specific roles. It is common for some fields like Planned for to be the restricted to roles like team lead and not the originator of the work item who maybe a stakeholder. Work item work flow changes, bulk work item update, work item types, and field modification can be restricted by role. See the section on Process Configuration.

References for Further Reading

Rational Team Concert Library (tag work items)
Product Documentation: Rational Team Concert and Rational ClearQuest
Product Documentation: Linking work items to Subversion repositories
Simplified bug reporting in Rational Team Concert


Adopting Plans

Return to top

Getting Started

Plans are one of the most popular Team Concert features. A prerequisite is the adoption of work items. A short video tour of plans in the product documentation is available here. A good visual introduction to plans, the breadth of function, and a case study of the Team Concert development team can be found here: RSC 2009: SDP21 – Agility at Scale: Agile Planning and Best Practices with IBM Rational Team Concert. A more thorough introduction is here: Getting Started with Planning in Rational Team Concert 2.0.

It is important to understand how the project team(s) currently plans their work, any issues with their current planning process, and what they hope to achieve by adopting plans using Team Concert. This will help in defining a planning model using Team Concert. A thorough understanding of the relationship between a plans, work items, teams, and iterations is critical. Before continuing read the short topic Product Documentation: Plans and work item management. There a number of plan types and it is worthwhile to know what they are. Though the product automatically anticipates the plan types for you there is a useful summary in Product Documentation: Plans. An underlying expectation is the requirement for the participants to estimate their work and report their actual time as discussed in Work Item estimates and beyond with Rational Team Concert 2.0.

If the organization’s process is centered around the Scrum agile planning model, their planning process will closely follow the planning model defined by Team Concert Scrum template during Project Area and Team Area Setup. Also note that when the Scrum process template is used to create a new project area, project area initialization predefines plans for you and makes a number of assumptions to quickly setup your backlog, release backlog, and the first sprint plans as well as a fully functional dashboard.

The following is a suggested order for configuring plans and enabling plans. For complex planning needs it may be useful to create a project area for prototyping a usable planning structure prior to formalizing it in the project area that will be used by the project organization.

  1. Since plans are often owned by teams, specifying the organizational structure as defined by parent and child team areas is important. For example, a Team Concert release plan may be associated with a parent team (or the project area) and sub-teams may define and manage their own team plans. The team structure can be defined in the web UI under Project Area Management or in the Team Organization view of the Eclipse client.
  2. A plan is also associated with a specific iteration. Iterations are defined in one or more parallel timelines on the Overview tab of the project area editor. Parallel activities (like application maintenance) could employ a peer team to the development team or could utilize the same team structure. Either way, the parallel activity will need its own timeline so that it can have its own plans. The project area timelines and iteration structure needs to be defined and kept up to date as the project evolves.
  3. A work item is associated to a specific plan using the Planned For (iteration) and Filed Against (work item category) fields. The categories for the Filed Against field are defined in the project area editor under the tab Work Item Categories. A definition is provided in the Product documentation: Work item category (Filed Against). Note that work item category to team assignments can vary by timeline offering additional flexibility.
  4. Some plan configuration may be necessary beyond the default defined by the project area’s process template. Plan configuration can only be done by editing the project area using the Eclipse client. A review and decision on what is a top level work item (visible in a release plan) versus execution items that are visible in other plans should be performed. There are other planning attributes like complexity and ranking that should be reviewed and set according to the needs of the organization. The article Customizing the Agile Planning tools in Rational Team Concert 2.0 provides a thorough discussion of the topic.
  5. Next define the required plans. In a simple planning structure, each team has a plan, defines its content as work items and executes their plan by keeping the work items up to date in terms of work item status, time estimates, and actual time spent.When more sophisticated planning is required then a combination of a release plans, team plans, and iteration plans come into play. See this article Effective Planning with Rational Team Concert 2.0 for more information.
  6. There is support for individual planning which in turn is reflected in the team’s plans. See this article Using the My Work view in Rational Team Concert 2.0 for more information.
  7. A plan’s progress needs to be interpreted. This article Progress Bars, Load Bars, and the importance of estimating your work in Rational Team Concert 2.0 explains this.
  8. Many organizations will do their planning using the web UI. This topic is covered the article: Planning in the Web UI with Rational Team Concert 2.0.

References for Further Reading

Rational Team Concert Library (tags agile planning, iteration planning)
Aligning development and test plans (Integrating RTC and RQM)
Blog: Sprinting towards Scrum
Effective use of Rational Team Concert for daily scrums

Adopting Dashboards

Return to top

Dashboards generally do not require a special effort in terms of planning and deploying Team Concert. Dashboards are certainly a very important element of a successful deployment because of the value they bring to the overall collaboration effort of the projects and teams. Here are some considerations when getting started with dashboards.

Getting Started

  1. Dashboards are fully supported in the Standard and Enterprise editions and limited in the express editions. See Product Documentation: Managing dashboards in the Web interface.
  2. Dashboards are available to project areas, team areas, and users.
  3. Dashboard content can include information across multiple projects on the same server and across servers (when configured correctly). For example content like named queries, query results, plans, and feeds from more than one project area can be included on a dashboard.
  4. Dashboard templates can be defined in the project area process specification. These templates control the initial content and layout of dashboards for each type (project, team, and user).
  5. Permission to create, modify, and delete dashboards can be assigned to specific user roles.
  6. Try to integrate the team dashboard into your team meetings so it becomes an integral part of your process.
  7. Inform team members that they can create their own personal dashboards (Standard and Enterprise editions).
  8. It may be of interest to examine the publicly available dashboards for the various Jazz based products that are available form Jazz.net.

Adopting Reports

Return to top

Note that support for reports in Team Concert is limited to the Standard and Enterprise editions. Also note that work item query results are a form of report, the results are real-time, and are an effective way to get timely operational information. Work item queries as part of a project or team dashboard can be very useful. Work item queries are supported in all editions of Team Concert.

Getting Started

Data Warehouse Background and Administration

The general design for reports in Team Concert is that the data source is a repository data warehouse containing aggregate and trend data. This data is managed in the repository as a logically separate database from the operational data containing the development artifacts (work items, plans, source control, build, etc). This classic data warehouse design minimizes access contention to operational data. The data warehouse is updated daily (default is midnight) from the operational database. There is some administrative support for the data warehouse and a special repository role, JazzDWAdmins, exists to support this. The data warehouse database is not physically separable from the operational database.

Except for “live reports” like a Scrum burndown report, the report data may be up to 24 hours old. A user with data warehouse administrative authority can manually refresh the data warehouse for a given project area from the Admin tasks available on the Reports page in the web UI. Manual update of the data warehouse during periods of high operational usage may impact users.

The hour at which the update of the data warehouse is performed can be modified from its default value of midnight. This may be necessary if midnight at the server location conflicts with high user access in another geographic locale. Updating the data warehouse requires a user with Jazz administrator repository access. From the Admin WebUI console (https://your.jazz.server:9443/jazz/admin) select the Advanced Properties menu item. Scroll to the Data Warehouse section and locate the com.ibm.team.datawarehouse.service.internal.InternalDataWarehouseService service. Select Edit and set the value to an integer from 1-24. Click the Save button at the top of the properties page.

Using Reports

  1. Generally, utilizing Team Concert reports does not require any special planning during deployment. Actual usage will generally determine what kinds of reports the project and teams decide to use. The Product Documentation: Tracking data with reports provides detailed information on the use of reports.
  2. A contributor client access license is required to view reports. Report creation and modification requires a developer license.
  3. The reports that are available are defined by the process template chosen when a project area is created. Additional reports can be added afterwards. The Available reports and templates are listed in the product documentation.
  4. There may be a need for custom reports in addition to the out-of-the-box reports. The reporting engine is based on the BIRT (Business Intelligence and Reporting Tools), an open source Eclipse project (http://www.eclipse.org/birt). A working knowledge of BIRT is necessary to create custom reports. See Product documentation: Creating and managing report templates. Here are links to additional information on custom reports. Most are in the form of videos:
    1. Creating a report in Rational Team Concert 2.0: Open work items
    2. Creating a report in Rational Team Concert 2.0 – Work item query
    3. Part 1 – Creating a report in RTC 2.0 – Custom work item attributes
    4. Part 2 – Creating a report in RTC 2.0 – Custom work item attributes
    5. Custom report for reporting across item links in Rational Team Concert 2.0
    6. Externalizing a string in a custom report template in Rational Team Concert 2.0

References for Further Reading

Rational Team Concert Library (tags report, report template)

Tech Notes
TN0015: Jazz Reports Component Requires X11 Libraries on a Linux Server
TN0016: Manually Editing Report Template Path Fails to Update Path
TN0019: Viewing reports in the Eclipse client with XULrunner 1.9 and Linux
TN0020: Reports PDF export issues
TN0021: Incorrect report data after drill-in from dashboard
[1391218] Reports with non-Western characters might require installation of server fonts
[1391061] Exporting reports with chart or images to Microsoft Excel format

Adopting Source Control

Return to top

Getting Started

Team Concert source control basics are not very complicated. Sometimes the biggest challenge is overcoming one’s previous SCM experience. Source control can be adopted without adopting other Team Concert components. This 5 minute video tour provides an introduction: Tour: IBM Rational Team Concert source control.

A working knowledge of the following Team Concert source control artifacts and their relationship to each other is essential:

  • Streams
  • Repository workspaces
  • Components
  • Change sets, change set flow, conflict resolution
  • Baselines
  • Snapshots

A good starting point is the article Getting Started with Jazz Source Control, which discuss the concepts and contains links to many of the same articles and documents referenced here. A companion introduction is the Product documentation: Overview of Rational Team Concert source control. The Team Concert example project based on JUnit is a quick way to create a working source control environment in which to learn the basics. It works with the Team Concert Eclipse client. Here are the tutorial instructions.

Planning the Adoption

In most adoptions, application code already exists and needs to be moved under Team Concert source control. This requires some planning and examination. Here are the relevant considerations.

  1. If the application is not going to be moved under source control immediately, applications using existing SCM systems like ClearCase and Subversion can be setup to have their changes linked to work items. References:
    Product documentation: Using the ClearCase Bridge to Rational Team Concert (Enterprise edition only)
    Product documentation: Linking work items to Subversion repositories
    It is possible to accomplish this with other source control systems. This is discussed in Integrating other SCM Systems with Rational Team Concert 2.0.
  2. A source control stream is owned by the project area or a team defined within the project area.
  3. It is not mandatory that streams be predefined. Initially, everything is done in an individual’s repository workspace. However, there should be a good understanding of what the organization’s stream requirements are. Here are some considerations:
    1. How is the code managed now? What are the current pain points?
    2. What is the structure of the code base and how will it map to the component model used in Team Concert source control? If the application is not structured to take advantage of components then the entire application can be loaded into a single component. It can be refactored later into separate components. There are advisory limits on the number of files to load in a single component after which performance degrades. See the Rational Team Concert (RTC) 2.0 sizing guide under Source Control.
    3. How is the code consumed? That is, are there needs for higher level integration streams? Is there parallel development going on; application maintenance, for example? A good understanding of source control flow targets is important. Here are some useful references:
      RSDC 2008, SDP22: Parallel Development with IBM Rational Team Concert
      Multi-Stream Development with Jazz Source Control
      Implementation of the remote development pattern
    4. Is there any shared code and/or code dependencies? If so, how is it currently managed between the code producer and code consumers? This article may be of interest: Managing vendor/third-party code in Rational Team Concert source control.
    5. Are there access control considerations that might require special considerations? Does code need to be protected from read access? If so, examine Patterns for read-protecting source code.
    6. Are there any special needs for file locking? In some cases it may be important to single thread updates to certain files, especially where there is not easy way to resolve a conflict (an image for example)? See Locking Resources in the product documentation.
    7. Is there a need to keep the code in sync with other source control systems? For ClearCase, a synchronization connector is available. See Product documentation: Getting started with the ClearCase Connector. In some situations it may be feasible through Team Concert build (see Adopting Build) to keep another repository up to date on a periodic basis. Such an approach is beyond the scope of this material.
  4. Is code currently under source control now? If so can it be imported directly from ClearCase and Subversion and is covered in the product documentation? External tools that can import from other source control systems to Subversion may offer help as well. Importing the application content will include change history. For other importing alternatives see this Team Concert development wiki page: Importing from other SCMs.

    Note that some source control systems may maintain meta data files along side the application code that need to be removed. The files and folders may also be set to read only in the local file system. If so, they all need to be set to read/write.

  5. Are there users who cannot manage their application using the Team Concert Eclipse or Visual Studio IDE’s? If so they can use their IDE of choice but will have to use the Team Concert IDE to manage their source control activities. Alternatively, they could use the command line interface. Some command line scripts may need to be developed to make this easier. This article Loading Content from a Jazz Source Control Repository in Rational Team Concert 2.0 offers guidance for both approaches. In particular, examine the sections titled: Advanced Load Scenarios and Loading using the Source Control Command Line Client. Lightweight source control management can be done through the web UI as described in: Share and manage documents through the Rational Team Concert Web UI.
  6. Evaluate your build environment and determine how the application content can be delivered to your build system. The Team Concert build system supports this (see Adopting Build), and its build toolkit can be used to adapt to other build systems. Also the Team Concert source control command line interface can be used. Determine if a working build environment needs to be established before adoption of Team Concert source control.
  7. If the application cannot be imported directly then it can be placed under Team Concert source control using the Team > Share Project… wizard available in the Team Concert Eclipse and Visual Studio clients. There is command line support also. Any prior SCM history is not included.
  8. Another consideration prior to placing content under source control is to identify what content (files and folders) should NOT be placed under source control. These are usually binaries, and other transient files that get recreated when the application is compiled and/or built. Team Concert provides for defining the file and folder names or patterns to ignore.
  9. The code is initially brought into a repository workspace before it is delivered to a target stream. Once in the repository workspace, the content is now under source control. Before delivering the content to the stream make the following determinations:
    1. Review all the content in the repository workspace to see if anything that should have been ignored was overlooked.
    2. To make sure that all the required content is under source control load (or reload) the repository workspace to your IDE and validate that it still compiles and builds OK.
    3. If any additional change sets were created after the initial share of the application code then additional component baselines and a snapshots are recommended.
    4. When this is complete then the content in the repository workspace can be delivered to the stream. A snapshot is promoted to the stream.
  10. Once the application code is in the stream the expectation is that other member of the application team will use it. All team members should have a working understanding on how to use Team Concert source control as outlined at the top of this page.
  11. If some code should be protected from read access by others in repository then it should be in its own component and the component owner(s) well defined. See Controlling access to source control in Rational Team Control 2.0 for more information.
  12. Who can deliver updates to the stream should limited to those who are authorized application contributors. This is best manged by defining a role for these users and set the repository permission for the deliver operation to users with that role. Also examine other source control operations (like deleting a stream, for example) to ensure that the operations are assigned to an appropriate role See this video: Rational Team Concert 2.0 Permissions Overview.
  13. Review the delivery process to ensure appropriate process compliance. In particular, are comments and/or a work item required for delivery.
  14. Since source control operations can at times be data intensive, if members of the application team are distant from the location of the Jazz Team server then it may be advisable to set up a caching proxy server closer to their physical location. Proxy caches can be placed as needed throughout the WAN as necessary. See Using content caching proxies for Jazz Source Control for more information.

Executing the Adoption

  1. It may be useful to define a temporary server and database to load the application code. This allows you to work out any issues in advance. It also offers the opportunity for the team to test drive development under RTC prior to formally cutting over. Alternatively, a parallel pilot may be warranted.
  2. Assuming the team has been trained on Team Concert source control basics they will still be feeling their way the first week or so. There should expertise available to handle issues and situations as they arise.
  3. Invariably, new users make mistakes. Be prepared to know how to undo changes that were mistakenly delivered.

References for Further Reading

Rational Team Concert Library (tags scm, source control)
Source Control FAQ
Resolving Conflicts with Jazz Source Control
Finding Lost Content with Rational Team Concert 2.0
Demo: Automating code reviews by integrating Rational Software Analyzer with Team Concert
Advanced Gestures and Workflows
Merging by example
Comparing Microsoft Word Documents
Resolving Conflicts
Product Documentation: Rational Team Concert and Rational ClearCase
Product Documentation: Rational Team Concert and Subversion

Adopting Build

Return to top

Getting Started

Adopting Jazz Team Build usually goes hand in hand with adopting source control; however, adopting source control does not mandate use of Jazz Team Build. The architecture of Jazz Team Build is designed to adapt to existing build environments. A lightweight build engine is offered out of the box.

A very short visual overview of build is provided in RSDC 2008, SDP26: Integrating your build with Jazz team build. The getting started document: Getting Started with Setting up Jazz Builds provides a more thorough examination. Reviewing these two items should give you a reasonable understanding of how Jazz Team Build works in Team Concert. The build section of the Jazz Tutorial is very worthwhile. The product documentation is available here: Product Documentation: Building with Jazz. The first two topics: About Jazz Team Build and A typical Jazz Team Build provide a good overview.

To gain some experience with Jazz Team Build the easiest approach is to install the Team Concert Example project (JUnit project) which includes a working build that you can run and evaluate. See these instructions.

When Jazz Team Build is downloaded you get the runtime environment called the Jazz Build Engine (JBE) and the build toolkit. Whether or not the Jazz build engine is used or you adapt to your existing build environment you will use the build toolkit Ant tasks and/or the Team Concert source control command line. The Ant tasks perform many of the source control operations for you and is the recommended approach.

Planning the Adoption

When you adopt Jazz Team Build you need to decide if it will integrate with an existing build system or you will use the JBE. If you don’t have any build system now then the JBE should be given serious consideration. Team Concert development has managed successfully with the JBE since it began. If you are using an existing lightweight build system, Ant scripts or Cruise Control, for example, the JBE is a good option to consider. If you are attracted to the personal build feature of Jazz Team Build (see About Personal Builds) the JBE provides excellent support that may be more difficult in to achieve in another build system. A JBE generally runs on a dedicated build machine (separate from the server). Depending your needs you might run multiple instances of the JBE on a given machine and/or define a number of machines dedicated to running JBE builds (make sure each JBE is uniquely named uses independent data areas). The JBE should run using the JDK included with Team Concert as described in this build FAQ topic. If you decide to use the JBE choice you have these objectives:

  1. Create or adapt existing build scripts (the JBE supports command line, Ant, Maven, or generic which gives you full control)
  2. Determine what hardware you will dedicate to build and how many JBE’s will be defined. A specific JBE is assigned one or more build definitions. Personal builds can significantly add to the demands of your build environment but it often pays off in fewer team build problems.

If you have an existing build system that you like and wish to continue with then you will probably choose to adapt it to work with Team Concert. If you do, the adoption will have the following objectives:

  1. Get your content to build from Team Concert source control to your build system.
  2. Run the build.
  3. Publish build status back to Team Concert during the build.
  4. Publish build results back to Team Concert.

Note that a specific build, as defined in its build definition, is associated with a project area or a specific team.

You need to define an anonymous build user to your Jazz team server that will login during the build to perform the various Team Concert build operations. The build user requires a build system license or developer license and process permissions on the various build operations. If you are using an LDAP directory this user will need to be defined there. See Product documentation: Best practices for more information.

Each build definition will require a dedicated source control repository workspace owned by the build user that is associated with the source control stream that is being built. You can manage what goes into the build by explicitly defining the components to build in the build repository workspace. You can further refine the build content by using component load rules to specify a component’s folders and files to be built.

The Jazz Build System toolkit is recommended and a working knowledge of Ant is required. When you download the build system the toolkit contains two parts:

  • In the buildengine directory there is the Jazz build engine (jbe command line), which runs as a client to the Jazz server, polls for build requests, and processes them.
  • In the buildtoolkitdirectory there is the Ant build toolkit, a set of Ant tasks available for use from your Ant scripts for publishing artifacts (e.g. downloads, logs, compilation and JUnit results) back to the build result on the server, reporting build progress, and other tasks. The toolkit contains a modest number of Ant tasks devoted to Jazz Team Build. The toolkit has example build scripts for a JBE-based build and a build that runs standalone. It covers the full life cycle of a build.

Here is the Ant task reference: Product Documentation: Jazz build Ant task reference. Note that even if your build system does not directly support Ant, if you can run a system command you can call Java which in turn calls the Ant task. See General tips for using the build toolkit in a non-Ant environment in this Team Concert wiki page.

It is recommended that you avoid storing large build artifacts in your Jazz repository. It just takes up space and most likely the next build will create a newer version. Links to builds results are a preferred approach.

If you simply want to ensure that your existing builds will work with Team Concert source control and are not yet interested in publishing build results back to the team server you can opt to use the SCM command line operations to simply retrieve the content from stream (via the build workspace). This can be a quick validation that your build environment is compatible with Team Concert. See Using the SCM Command Line Interface in builds.

It also advisable to manage your build scripts and related content in Team Concert source control. They can be associated with the rest of the application stream content. Putting them in their own component is a good practice.

In addition to the earlier references, here are some other recommended information sources to help you get started.

  1. The Team concert development wiki has a rich set of wiki pages dedicated to build. See: Development wiki: Build Component Home. Here are some suggestions to get started with.
  2. If you are interested in an example on how to adapt to an existing build system this article should be of interest. It also illustrates use of the Ant tasks in support of the Jazz Team Build life cycle. Using the Hudson build integration system with Rational Team Concert.
  3. If you are in a Visual Studio environment, then you will want to look at the discussion in this Jazz Forum called Can’t Understand How To Run Build.  It covers the basic steps for setting up build in a Visual Studio environment.

At this point you should have enough information to begin creating your initial build or adapt an existing one. Below are references for further reading.

Using Team Concert Build Effectively

The intent with Jazz Team Build is to make build information readily accessible to the development team and other interested parties. They should be familiar with the build UI which is available in all the Team Concert clients.

Take advantage of build feeds to monitor builds.

Make build results visible in team dashboards.

Administering and Protecting your Build Environment

Once your build environment is operational with Team Concert you will want to manage and administer them. See Product documentation: Administering Jazz Team Builds.

Review the project area and/or team area permissions for build operations to ensure that appropriate roles are assigned to operations, especially the various delete operations.

Review the pruning policy in your build definitions. Keeping numerous build results could consume a significant amount of repository storage space. Add a descriptive tag to build results that you want to keep indefinitely and mark the build result as not deletable.

References for Further Reading

Rational Team Concert Library (tags build, builds)
Monitoring your build’s progress with build activities
Using build activities to monitor build progress
Using components when publishing build result data
Running Jazz Build Engine as a Windows Service
Running Jazz Build Engine on platforms other than windows/linux
Build-related Java programming examples
Manage builds with Jazz Team Build in the Rational Team Concert Client for Microsoft Visual Studio IDE

Visual Studio Considerations

Return to top

Getting Started

Overall, a deployment involving Visual Studio is not significantly different. Listed here are some possible considerations.

  1. Team Concert supports VS 2005 and VS 2008. You can’t mix and match different versions of Visual Studio in the same solution or project. This is not a Team Concert consideration but rather a Visual Studio constraint.
  2. Note that the RTC Visual Studio client has a dependency on Microsoft .Net 3.5 framework.
  3. This article, Source Controlling Projects and Solutions in Team Concert for Visual Studio, provides source control considerations unique to a Visual Studio environment.
  4. Mapping Visual Studio solutions and projects to the Team Concert’s component-based source control model is a consideration. This wiki article, Mapping your Visual Studio Projects and Solutions to Jazz Components, provides useful insight and recommendations.
  5. There may be considerations when integrating Visual Studio development projects with the Team Concert Jazz build engine (JBE). For example, if the build is based on a command line script (like a .bat file that calls MSBuild) then callbacks to Team Concert using the Jazz build system Ant tasks can be accomplished as described in this wiki page C++ / make build in the section titled: General tips for using the build toolkit in a non-Ant environment
  6. You may want to look at the discussion in this Jazz Forum called Can’t Understand How To Run Build.  It covers the basic steps for setting up build in a Visual Studio environment.

References for Further Reading

Rational Team Concert Library (tag Visual Studio)
Product documentation: Getting started with the Team Concert client for Microsoft Visual Studio IDE
Source Controlling Projects and Solutions in Team Concert for Visual Studio
RSC 2009: CRM27 – Heterogeneous Development using Eclipse and Rational Team Concert Visual Studio

Videos

Part 1: Heterogeneous development using RTC Client for Eclipse, RTC Client for Microsoft Visual Studio IDE, and RTC Web UI
Part 2: Heterogeneous development using RTC Client for Eclipse, RTC Client for Microsoft Visual Studio IDE, and RTC Web UI
Part 3: Heterogeneous development using RTC Client for Eclipse, RTC Client for Microsoft Visual Studio IDE, and RTC Web UI
Preserve component and workspace configuration in the Rational Team Concert Client for Microsoft Visual Studio IDE
Manage builds with Jazz Team Build in the Rational Team Concert Client for Microsoft Visual Studio IDE

Older Videos

Part 1 – Getting started with Rational Team Concert and Microsoft Visual Studio
Part 2 – Getting started with Rational Team Concert and Microsoft Visual Studio
Part 3 – Getting started with Rational Team Concert and Microsoft Visual Studio

Tech Tips

Tech Tip workaround: Wrong context menu in the Team Artifacts view (Rational Team Concert Client for Microsoft Visual Studio)
Tech Tip for known issue: Non-support of Guest users in Rational Team Concert Client for Microsoft Visual Studio on Windows Vista / Windows 7
Tech Tip workaround: User gets logged off from a repository when working simultaneously on multiple solutions in the same sandbox
Tech Tip: Workaround for Microsoft Visual Studio IDE becoming slow or unusable
Tech Tip: Workaround for Pending Changes view not updated with errors after a solution build
Tech Tip: Workaround for bulk editing of work items when using RTC 2.0 client for Microsoft Visual Studio IDE against an RTC 2.0.0.1 server
Tech Tip: Workaround for failed move in repository, unable to delete vshost.exe
Tech Tip: Workaround for known issue with tracking changes in a sandbox loaded directly under the drive
Tech Tip: Workaround for code window context menu of code-behind file acting on the XAML page instead
[1390715] Rational Team Concert 1.x to 2.0 (Eclipse or Visual Studio) Client Workspace migration
[1391270] Undoing unresolved changes from the Pending Changes View does not work
[1390713] Error while replacing in flow target from the Pending Changes view
[7015716] Detailed System Requirements for the Rational Team Concert 2.0 client for Microsoft Visual Studio

Integrating products based on Jazz

Return to top

Getting Started

Jazz Team Servers can be linked to provide product interoperability and sharing of certain data among repositories. Product interoperability provides collaboration capability among different Jazz based products that are cooperating in the application life cycle (C/ALM). Sharing of data among repositories allows for dashboards to integrate data from project areas spanning servers. In either case the servers have to be administratively set up to permit communication with other team servers. These information sources can assist with this configuration activity.

Product documentation: Products based on Jazz and its subtopics
TN0039: Configuring Rational Team Concert, Rational Quality Manager, and Rational Requirements Composer for the Collaborative ALM integration

References for Further Reading

Rational Team Concert Library (tags C/ALM, agile, integration, integrations)
What is Collaborative Application Lifecycle Management (C/ALM)?

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Wed, 20 Jan 2010