An Overview of Project Fundamentals in Rational Team Concert


Various discussions with customers and questions in the forums indicate that new projects starting to use Rational Team Concert often struggle to understand how Work Items, Planning, Build and SCM integrate. These fundamentals of RTC however are needed to boostrap and customize a project. This article provides a basic introduction of the underlying fundamental concepts of Rational Team Concert. The basic concepts described in this article apply also to newer versions of RTC.

A good overview about the features with links to more details can be found here:

Process Configuration Fundamentals

One basic task when setting up a project is to configure the basic process. This section introduces the basic concepts to consider.

Project Areas

In Rational Team Concert, project areas define the process used by everything they include. The initial process definition and description are provided by a process template. RTC ships with several predefined process templates that are a good starting point for various different project types.

The project area's Process Configuration editor is the main area for defining the basic process. It allows you to define roles, the permissions and process behavior for artifacts owned by the project area and it's enclosed teams.

Team Areas

A project area can contain team areas that inherit the project area's process, roles, permissions and operational behavior. Users are defined as members of project and team areas and along with their roles.  This combination of membership and role provides them with permissions and defines the behavior when working with artifacts owned by a project or team. Team areas may modify the permissions and the operational behavior they inherit from their parent.


Users care added to project areas and team areas as members of said area. Membership in a team or project area is used to control access to the data owned by the area. A special membership is the project administrator. This membership allows the user to configure the process of the project area.


Members of project and team areas have roles assigned. By default every member of an area has the Everyone role assigned. The project and team area can define additional roles that can be assigned to users. Roles are used to control permissions and operational behavior. A user can have multiple roles. The roles are ordered and the order of the roles a user has controls operational behavior.

Please note, some permissions are not managed on project area level, but at repository level. Special Repository Roles like JazzAdmin are available to control them.


The project area defines one or more timelines which define how a given planned period of time is partitioned into iterations such as releases, milestones, sprints etc. A project area can be assigned to exactly one project timeline to work against at any instance in time. Team areas contained in a project can also each be assigned to exactly one timeline to work against at any instance in time.  


Iterations typically have a start and end date. Iterations can be planned to deliver a result by marking them with "A release is planned for this iteration". These iterations show up in plans and can be selected in work items as "Planned for". The start and end dates are used by the planning component to calculate progress, time available, load and other information.

Iterations can have an iteration type. The iteration type can be used to configure process behavior.

Iterations with no "A release is planned for this iteration" and with no dates configured can be used to control the process behavior within a parent iteration. 

Work Item Types

The project area's process configuration is also used to define which types of work items are available in this project area, which workflow they follow, which attributes they provide, and how they are displayed. It also provides a user interface to configure the planning component.

The project area configuration allows you to define a work item type to be a top level work item type. This controls how the planning component uses the work items of these types for work breakdown and effort tracking. Work items that don't belong to a top level work item type are called execution items.

Permissions and operational behavior can be configured for work item types to govern the process and prevent deviating from the process.

Work Items

Work items represent work that needs to be done, such as tasks or defects. A work item has a work item type which defines the attributes and the workflow of the work item. Special attributes provided by default are used to provide mechanisms required to organize many work items across teams. 

The most basic data required for planning is which team area is the responsible owner of the work item and in which iteration is the work item planned to be completed as described below.


To allow users to assign a work item to a team, the project area provides categories. A category is basically a human readable text. Each category is associated to a project or team area.  

It is possible to have multiple categories assigned to a team area. This can help with planning, work balance and reporting. For example it is possible to create a category "MyProduct" with subcategories "Core", "User Interface" assigned to one team. These are also typical categories.


It is a common need to know for which release or version a work item has been created.  To support this, the project area provides a central place to maintain releases.  Releases such as "1.0", "2.0", "2.0 M3" can be created and maintained manually. It is also possible to create a release from a build result. 


The process of a project area provides available Plan Types to create a new plan. The plan type determines what the plan will show. Which plan types are available depends on the Process Template that was used when creating the project.


Permissions can be configured on project area and on team area level for various operations based on the roles a user has.  See Process permissions lookup in Rational Team Concert 2.0 for details on how permissions work.

Permissions control which artifacts a user can create, modify and save.

Permissions can be configured not only for project and team areas, but also for the temporal aspect represented by iterations. 

Operational Behavior

Operational behavior can be configured on project area and on team area level for various operations based on the role a user has.  See Process behavior lookup in Rational Team Concert 2.0 for details on how operational behavior works.

Operational behavior can be used to govern the process of a project or team area using preconditions and follow up actions.

Operational behavior can be configured not only for project and team areas, but also for the temporal aspect represented by iterations. 

Source Control

To use the RTC Jazz Source Control Management various items need to be created and maintained. There is some information related to the process configuration that can be maintained.

The RTC Jazz Source Control Management component provides Streams to share versioned source code. Streams contain Components that are used to partition the source code e.g. across architectural boundaries. 

Users have Repository Workspaces as their private sandbox to work on the code that is loaded to their disc. Changes in the local files are monitored. Users check changes back into the repository workspace.

Repository workspaces typically flow with one or more streams. The current flow target is the stream with which the source control component compares to the content of the repository workspace to analyze the changes on both ends. If a repository workspace has multiple flow target only one can be current.

Local changes that get checked-in by a user are stored in change sets. Each change set represents the changes to one or more files in one component. Change sets can have related work items for documentation and approvals. It is possible to navigate between change sets and related work items.

New change sets in a repository workspace that are not yet in the current flow target are outgoing. They can delivered to the flow target stream.

Changes delivered to a stream by others are showing as incoming change sets to a repository workspace that has the stream set as current flow target. The owner of the repository workspace can accept the incoming changes to get them in the repository workspace and on disk. 

Baselines can be created on a component to get a reproducible unchangeable configuration for a component. Baselines are accessible as elements in the source control system to create and replace component content.

Snapshots are composite baselines across all components of a stream using individual baselines on components to recreate the stream. Snapshots use baselines that exist, if possible and create baselines where necessary or if requested to do so.

See the Jazz Source Control FAQ for more information.


The build system in Rational Team Concert integrates the build process with the work item based change management and the Jazz Source Control Management.

Build definitions control what is built and how it is built. Build Engines do the build. The Jazz Build Engine is available in the product. Other build engines can be used. The Build System Toolkit and the ant tasks are used in build scripts and for build publishing. For each build definition RTC maintains the build results.

Timeline and Iteration Fundamentals

When considering setting up timelines and iterations some best practices have shown to be useful.

If a project performs parallel types of work, such as development for a new release and maintenance of old releases and wants to do separate planning for these kinds of activities, separate timelines and teams. For example, the project and a couple of teams work on the project timeline and develop for new releases. Some other maintenance teams work against a maintenance timeline. 

Planning needs an iteration for time-boxing. If something should show up as a duration in planning an iteration that represents the release.

When defining iterations it is useful to have a consistent naming and identifier schema. Some typical examples are below. The format used "Iteration 1 (M1 R1) [i1.m1.r1]" can be interpreted as follows. The first part is the display name "Iteration 1 (M1 R1)" and the text in the brackets represents the identifier "i1.m1.r1".

Release based development.
TimelineIteration Level1Iteration Level2Iteration Level2
Main Development Timeline
Release 1 [r1]
Milestone 1 (R1) [m1.r1]
Iteration 1 (M1 R1) [i1.m1.r1]
Iteration 2 (M1 R1) [i2.m1.r1]
Milestone 2 (R1) [m2.r1]
Iteration 1 (M2 R1) [i1.m2.r1]
Iteration 2 (M2 R1) [i2.m2.r1]
Release 2 [r2]
Milestone 1 (R2) [m1.r2]
Iteration 1 (M1 R2) [i1.m1.r2]
Iteration 2 (M2 R2) [i2.m2.r2]

Quarterly maintenance:

TimelineIteration Level1Iteration Level2
Maintenance Timeline
2012 [2012]
Q1 (2012) [q1.2012]
Q2 (2012) [q2.2012]
Q3 (2012) [q3.2012]
Q4 (2012) [q4.2012]
2013 [2013]
Q1 (2013) [q1.2013]
Q2 (2013) [q2.2013]

When setting the start and end dates of iterations make sure the dates of iterations don't overlap. The iterations on each level should be a partition of the given time of the iterations on the next higher level. If iterations overlap the progress information in plans gets inaccurate.

Each timeline has a current iteration that controls the current process behavior. The current iteration needs to be set manually e.g. by the project lead.

Work Item Fundamentals

Required Work Item Attributes

When creating work items it is necessary to provide some basic information. Work items require to at least have a type and a summary. It is possible to define which information is needed to be present when saving a work item in the process configuration.

The work item type is selected when creating a work item. The type can be changed later. Only the types available in the project the work item is created for are available. The work item summary needs to be provided in the Summary attribute.

Common Work Item Attributes

In an environment with multiple teams and multiple releases it is necessary to provide ways to make the amount of work items more manageable. The following work item attributes are used to do just that.
The work item's attribute Filed against allows to select and set the work item's category. Setting the category also sets the team area associated with it the owner of the work item.

The work item's attribute Found In allows to select and set the release the work item was created for.

The work item also has a workflow state which is driven by selecting actions in the workflow.

A work item can have exactly one responsible person, the Owner.

Planning a Work item for an Iteration

A work item can be planned for an iteration by setting the Planned for attribute. The work item can only be planned for an iteration belonging to the timeline the owning team is working against. To be selectable an iteration must also have the A release is planned for this iteration check box selected. 

Work items provide attributes to map to the basic process concepts
The image above shows the most important attributes used with work items and how they relate to the fundamental concepts above.

Planning Fundamentals

The process configuration provides the available plan types to choose from when creating a plan. Plans are configurable queries on life data provided by work items selected by the plan.  

Each plan type provides some Plan Views, also referred to as Plan Modes. The Plan views configure how the data will be presented on the planned items tab. Each plan can have multiple plan views. New plan views can be created to present the data in a convenient way. Plan views are global. Changing a plan view of a plan changes it for all users.

Plan Details

Creating and configuring a plan defines the scope of the plan, which defines the data that is going to be presented in the plan. The plan's scope is defined by configuring the following Plan Details:

  • The owner of the plan specifies which team area contributes to the plan. Since the team area is also assigned to one time line this specifies which iterations can be selected.

  • The iteration of the plan specifies that only work items planned for this iteration are included into the plan.  The iteration selected can only be part of the timeline the plan owner is working against. Also it is only possible to select iterations that are planned to deliver something. The latter is specified by setting the A release is planned for this iteration property for the iteration.

  • The plan type that determines how the plan views, as well as which of the work items qualified by the above information, will be presented. The choice is to include only top level work items or all work item types.

Planned Items

Plans only show work items in their scope within the Planned Items tab. Plans will only consider work items in scope that have the Planned For attribute set to the iteration or nested iterations the plan is configured for.  Plans will also only consider work items that are filed against the team area or one of its child team areas the plan is configured for.

By default several plan types will also only show top level work items to reduce the amount of details presented.

Plans that show only work items of types defined as Top Level Work Item Type can be configured to also show execution items. This can be done for example in the Web UI. Edit the Plan Details and select the check box Include All Items to include execution items in the view. The impact of this is longer load times for the plans. The filter Execution Items can be used to filter these work items out for a better overview when the plan is configured to load execution items.

 Configure a plan to show execution items

Where is my work item?

If a work item disappears from a plan or one you expected is missing from your plan it is probably filtered out or out of the plan's scope. Check for the active filters and if execution items are included in the plan. Carefully check the work items attributes, especially Planned For and Filed against.

Independent of its configuration, in RTC 3.x a plan will only show and consider work items that are planned for an iteration that belongs to the the plans owners timeline. Although you can create work items on a plan and plan them for a different timeline, the next time the plan is loaded these work items will not be presented on the plan. 

In work breakdown structures child work items planned for a different timeline will also not be presented and their estimation and effort values will not be calculated or rolled up by the plan.

Source Control Fundamentals

To integrate changes from one stream to another, use a repository workspace that has two stream targets. When the repository workspace is in sync with the first string change the flow target to the other string. The source control system calculates the differences between the repository workspace and the new flow target. It then allows to deliver, accept and merge changes to bring the repository workspace and the stream to the same state. If the repository workspace was changed in this operation, changing the flow target to the original stream allows to deliver integrations back to that stream.

A stream can have another stream as a flow target. If there are no conflicting changes the pending changes view can be used to accept and deliver the changes between the streams. If there are conflicting changes a repository workspace is required to solve the conflicts.

Source Control Data is not confined to the project area. Streams and components are only owned by project areas, team areas or users. The ownership controls permissions and operational behavior. Ownership can also be used to control visibility. However, it is possible to create a stream based on a stream or component baselines owned by a different project area. Data can also flow across project areas.

See the Jazz Source Control FAQ for more information.

Build Fundamentals

The build engines like the Jazz Build Engine require users with permissions and licenses configured to access the data and to publish build results. Special build system licenses are available for technical users.

The technical user performing the build must have access to the data which usually means the user needs to be member of the project area and some role.

All builds are run in the context and with the credentials of this user.

The build definition require a repository workspace to build. It should be owned by the build user.

During a build, if the build user has the required permissions, a snapshot is generated on the repository workspace. This snapshot is used to compare it to the build before to determine the change sets that went into the build compared to the one before. From this information the build result also shows the work items related to this build.

Private builds use the users repository workspace to load the data. They need to be visible to the build user for this to work. The build user can however not create a snapshot on that workspace and therefore the data can not be compared to previous builds.

It is possible to create work items for build results for example to track progress of builds towards release.

It is possible to create a release from a build result, this also protects the build result from being deleted.

For more information

General PlanningCustomizing the processJazz Source Control

About the author

Ralph Schoon is a member of the Jazz Jumpstart team.  The Jazz Jumpstart team is a worldwide group of development specialists who bring new and advanced Jazz-based technologies to customers. Please direct feedback and comments to .

Was this information helpful? Yes No 27 people rated this as helpful.