IBM Rational Team Concert
The Process Template
Let’s face it. There are many tools out there in the ALM/SCM space and RTC is just one of them. There comes a time when a person decides they would like to try and make changes to work items in RTC but the trouble is, they have never done this before and considering the complexity of RTC, the intimidation sets in. To clarify, by changes to work items in RTC, I mean as an admin not a user.
I decided to write this article to inspire people to come out of that shell of uncertainty. I will walk you through an introduction of the important areas you need to know about. This will only be a brief introduction and there will be very few screen shots. We won’t cover every area, but I will hit the primary ones. By the way there are many primary areas that come into play when customizing an RTC Process Template. If you have experience customizing RTC process Templates, you probably can stop reading now. This article is not designed to be advanced or a tutorial. I will not be showing you step by step how to add new attributes or work items. Those topics would be articles on their own and can already be found on jazz.net.
The Eclipse Shell Client is used for this presentation.
Introduction
How do we get into the process template?
- Create a Repository Connection
- Right click a Repository Connection and select “Manage Connected Project Areas”
- Select a Project you want to administer and click OK
- Right click the project that now appears under your repository connections and click Open
- * ALM Rollout is a project I created for this article.
This will open the project page where you can modify the process template.
NOTE: You will need to be sure you have the proper credentials before you can make changes and save those changes to the process template, so test out the SAVE button early!
Now that the project is open in the right side pane of the Eclipse client (by default), double click the tab at the top of the pane that has the project name on it and the tab will grow to full screen mode, taking up the space of the entire eclipse shell.
In full screen mode, you can double click the tab again to make the eclipse shell go back into separate panes.
Default Panes
By default the eclipse shell opens in three main areas (Left side (LS), Right side top (RST), Right side bottom (RSB)). Creating a 4th area can be done simply by dragging any tab to the middle of the RST pane.
Since this is an Eclipse shell, you can fully customize what tabs appear on which panes. But before you do there is one thing you must know.
Look up on the toolbar and click on “Window”. On this menu you will see “Open Perspective” and “Show View”.
The perspective will change what all of your panes look like. For example, one perspective is about Work Items, another is Jazz Administration and another is Java. There are many more perspectives than this but these are the one I selected for this article. Looking at the names of each perspective you will see they can be related to area of responsibility. That means if I am a Java developer and need to write Java code, the Java perspective would be the best perspective for me to use, same for the other two.
The views are the tabs you see in each of the panes. If you close a tab by mistake, click on show view and search for the tab with the name of the one you closed. Like perspectives, there are many.
Before we go on to the next section, I need to point out a difference of tabs. It is possible to be on a view tab where that view tab has settings tabs. These settings tabs are specific to that view and will not be available if the view is closed (tab is “x” out).
- Blue Arrow – View
- Red Box – Settings tabs for this view
The Tabs
The view we are looking at contains the project properties and opens by default in the RST pane. Each project has the following tabs:
- Overview
- Links
- Process Configuration
- Process Configuration Source
- Access Control
- Work Item Categories
- Releases
This article will be primarily using the Overview, Process Configuration and the Work Item Categories tabs. These are the primary locations you will need to modify in order to customize your project.
Overview Tab
Details
An area where you can type a summary and description of the process template.
Members
Everyone who needs access to this project will need to be a member of the project.
Administrators
Members of this area will have extra rights to perform functions that regular members cannot.
Process Sharing
RTC has the ability to implement a parent-child hierarchy between multiple projects. You would use this hierarchy if you had multiple projects you wanted to host off of a single process template. The available options here are to make this project be a parent, or to link this project to a parent (making it a child). Optionally, you can do nothing and leave this project unshared. Any changes you make to an unshared project will have to be duplicated in all unshared projects unless you intend for the projects to be different.
Process Description
This area can tell you what template was used to create this project. When you create a project you can create one from an out of the box RTC process template, such as Scrum or OpenUp. This area will tell you which process template was used as that foundation.
Timelines
Define all of your timelines and iterations for your project here. Keep this location in mind because we will refer back to it again later.
Process Configuration Source Tab
It is strongly advised to stay out of here unless you know what you are doing. A minimum of 6 months of process template customization and a familiarity with XML coding will be required.
Work Item Categories Tab
Left Side
The left side of this pane is a three column box. On this tab you create “Categories.” A category is something you can use to identify the kind of work you are doing.
Right Side
The right side of this pane is a list of Team Areas. These are the teams that you configured for this project.
What does it all mean
Having the ability to define categories and teams allows you to make associations. As you design your project keep this tab in mind. This area provides you the opportunity to state which team will be responsible or associated with each category.
First select a category from the left side, then select a team from the right side, then click the associate button in the middle to make the association.
There is a magic that happens under the covers in RTC and these categories are part of that. See the next section for more information about this area and how it related to one of three special fields/attributes.
Three Special Attributes
In Rational Team Concert, we refer to a field on a form as an attribute. We also refer to the form as a presentation. These three attributes are enumerated lists, but you have to go to three special areas in order to configure the values that appear on these enumerated lists.
Found In
The found in attribute is used to identify which release a particular bug or issue was discovered in. For example, you can think of submitting a defect and on that defect you identify the defect was “found in” version 3 or release 3.0.1.3, etc.
The values for the found in attribute are created on the “Releases” tab. The last tab in the red box identified above.
Filed Against
The filed against attribute is used to identify which team is responsible for fixing the defect. But more than this, when you select the team, you do so by selecting a category. This sets up a relational concept that says this defect is “filed against” permissions or whatever you have used to define your categories of work. By selecting the correct category, RTC related this to a team and enables that team to now plan for the completion of this work.
The values for the filed against attribute are created on the “Work Item Categories” tab. The second to last tab in the red box identified above.
Planned For
The planned for attribute is used to identify which iteration a defect is targeted to be fixed in. We won’t get into the lengthy discussion about planning such as how to plan, what to plan or what does a plan look like in this article. A good practice however, would be to have a core timeline and to store all of the iterations that belong to this timeline together. See the Scaled Agile Framework by Dean Leffingwell for great information on how plans can be structured to match a scaled environment, and by scaled I refer to any team greater than 50 people.
A timeline can be broken up into several iterations. These iterations are setup to align the business with development cycles. It is key to mention that these iterations do not define a release cycle. That is to say, it is OK to release software during the iteration. Do not feel you must wait for the iteration to close before the product can be released. When selecting a value for the planned for attribute, you are essentially committing to delivering the work defined by the work item during the iteration selected.
The values for the planned for attribute are created on the “Overview” tab. The first tab in the red box identified above.
NOTE: While the “Defect” work item type was used to describe the usage of these attributes, this should not imply that these attributes are only valid for defects. Most of the work item types in Rational Team Concert use a combination of these three attributes depending on the logic of each work item type. For example: it would not be logical to have the found in attribute on a task when a task is something that gets created by a team member to represent their work for the item they are being asked to deliver.
Process Configuration Tab
You may have realized by now, that I skipped over this tab, saving it for last. There is a lot of information to understand before coming into this tab to make changes. As I go through the different sections of this tab below. You should open a project in RTC to follow along as this will aid in the understanding of what is being presented.
When you first open a project and click on this tab, you will see a very compressed version of the content that really exists in here. See screen shot below:
At a high level RTC breaks down the ability to customize a projects process template into project specific items and team specific items. Properties that will apply to an entire project will exist in Project Configuration, while properties that allow you to designate rules for team and more team based functions will be in the Team Configuration section.
An example of each would be work item type look and feel in project config and work items type behavior in team config.
Let’s begin!
Roles
This is where you go to create and define all of the roles in this project. Once a role is created, it can be defined and then members can be added to it. These are the roles you see available when adding someone to the project or a team as a member.
Project Configuration
Now that you have created the roles for your project you need to identify what actions each role will be allowed to perform. When you expand the Project Configuration node, you will see a Permissions section. Click on permissions and to the right you will see a grid showing each role and the permitted actions that each role is allowed to perform. By default, the permissions are displayed on a per role basis.
If you prefer, there is an optional way you can view this information. At the top of the permissions section you will see two radio buttons.
By selecting the other radio button “show all actions and roles” you will see a grid with multiple columns. Each column is a different role and each row is a different actions. This can be a more efficient way to set permitted actions on roles by having scope to what is permitted for the other roles at the same time.
Configuration Data
There are two sections in here that I refer to as primary sections that you would want to go into. That is Planning and Work Items.
The Planning section is where you can define which work item types are to be considered planning types as opposed to execution types. This designation on a work item type will change how information on that work item type is rolled up to parent work item types and how these work item types are presented in plan views.
Think about this. When you are looking at a plan one of the filters you can use to add or remove information being presented by the plan is execution types. An execution type is your organization’s way of saying any work item types we deem to be execution types will represent physical work that is being done whereas the plan types will represent when that physical work will be done.
The Work Item section is where you can define new attributes, place those attributes on the presentation, create new work item types, rename work item types and change the workflow of work item types.
Planning/General
Here is where you can set how the project tracks progress based on hours entered on the Task work item types. You can set this value to either Time Spent or Time Remaining and check the box to display these estimates in hours.
Planning/Work Item Type Categorization
This is the area where you identify which work item types are planning versus execution. In the box where is says select plan items, is a list of work item types for this project. Each work item type that is checked, rtc will treat these work item types as planning types. The unchecked work item types will be considered execution types.
Work Items/Types and Attributes
This section will display a list of the work item types for this project. Here you can add new work item types, change the name of existing work item types, create new work item type attributes and set the work item editor for each work item type. There are four different editors that are used in RTC.
- Work Item Editor – General editor used for creating and editing work items
- Inline Work Item Editor – Editor displayed when a user modifies a work item from a query in the web client
- Lightweight Work Item Creation Dialog – Editor displayed when a user creates a work item while delivering a change set or from an integrated application such as RQM
- Plan Editor Preview – General editor used to view and modify work items in a plan. The preview pane in Eclipse client and the inline editor in the web client.
Here is a jazz.net article that digs deeper into work item customization.
https://jazz.net/library/article/565
Work Items /Enumerations
All drop-down boxes in RTC are called Enumerated Lists. These lists are created here. Once the list is created you can go back to the Types and Attributes section to create a new attribute and set the type of the attribute to the enumerated list. You can then go to the Editor Presentations section, select the correct work item type editor and place the attribute on the appropriate presentation layer.
Enumerated lists allow you to select a default literal and an unassigned literal for each list. The default literal will be the value that appears by default when a new work item is created that has this enumerated list attribute on the presentation. Picking a default literal value is required. The unassigned literal is used for times when you want a value on this list to be treated as an unassigned value. Sometimes this is left to none.
Work Items /Attribute Customization
This is where you would go to define more advanced attribute behavior. For example if you have an attribute that needs to perform a calculation or if you want an attribute to have a specific default value and it is not an enumerated list. Often the customizations in here will require scripting but not everything does.
Work Items /Workflows
Each work item type has a workflow. For those of you familiar with ClearQuest, this would be your state transition matrix. Essentially, you are defining what state a new work item get instantiated with, and what actions will take that work item to other desired states. For example, from the state of Open I can select the action Review Complete, which will put the work item into the Reviewed state.
In order to define workflow on a work item type you will need to understand how RTC uses workflow states. RTC has an area in this section called State Groups. These state groups map all of the states into grouping such as Open, In Progress or Closed. Recognize that it is possible to have multiple states on a work item where the state of that work item could still be considered in progress. Think about Open, Under Review, Pending Deploy to UAT, etc. These various states can all represent a work item that is not yet closed.
So create your states, set actions to get into desired target states and define each state into a state group. Then you can use the matrix to decide the FROM/TO for all of the states. FROM state X TO state Y.
Work Items /Editor Presentations
Each work item type has four editors as presented above. All of these editors are represented by Java class files. Some editors are used by multiple work item types, but the entire list is here in this section. Select the drop down list to view the editor desired.
Each editor is broken down into several sections. At the top is the header. When you open a work item you see at the top a summary line and some drop down boxes. This is the area defined as the header.
Next you will see sections for each tab. For example, the default editor has Overview, Links, Approvals, and History. Each tab is additionally broken down into sections. The Overview tab has 4 sections, Details, Quick Information, Description and Discussion.
Looking at the Overview tab for example, if you expand the details section you will see attributes similar to the ones on the work item itself. Here is a screenshot for you to compare the work item to the editor.
Here is a jazz.net article that digs deeper into the editor presentations.
https://jazz.net/library/article/130
Work Items /Change Management Types
This is a small section but it has some key functionality that can be configured here for the project. On this page you can set which work item type should be used for certain change management bindings. You can also map these types to specific states for specific purposes. For example, you can select the defect work item type as the work item type that is used to represent all defects and then you can specify which state should be considered for Testing and which should would indicate resolution.
Team Configuration
Permissions
This is the same section as the permissions section above but it allows you to set Team specific permissions. There are some key areas to note in here under the work items menu tree.
Work Items -> Work Items (server) ->
o Trigger a workflow action
o Create a work item
o Modify the work item
Each of these sections are very large and offer the ability to do some very specific fine tuning of settings per role.
Trigger a workflow will list out every workflow state for every work item type. This allows you to allow a role to put a work item of type specified into a particular state specified. For example, Close (Task Workflow) allows the ability for a user to close a task. If the stakeholder column does not have a checkmark on this row, then a stakeholder will not be able to close a task.
Create a work item is a short list. It basically lists out each work item type in the project. For example, If Create a ‘Task’ work item is not checked for stakeholder role, then someone who is a stakeholder, will be able to create a new task work item but upon trying to save the work item they will get an error stating they do not have permission to perform this action.
Modify the work item is a full list of every attribute in the project. This enables on a per role basis who can modify an attribute. An example here would be the Filed Against field. You would not want everyone in the project to be able to modify this attribute, so you would remove the check box under the roles you do not want to be able to modify this attribute.
Operational Behavior
This is the last section I will cover for this article.
Operational Behaviors allow you to setup pre and post conditions in RTC. Pre and post conditions are follow-up actions that apply to a corresponding operation and role. There are many out of the box operational conditions that can be applied to your project, but if you want something else or one that is like an out of the box condition but slightly different, you will need to write your own custom plugin code for whatever behavior you are looking to accomplish.
Examples of popular conditions are “Required properties upon trying to save a work item” or “Restricting access to closed work items” or “Require an association of a work item and a comment upon deliver”. These are just three to name a few.
In the operational behavior section, you select a role, and an operation. Place the cursor into the grid at the location you are trying to specify then click add to add a condition to the operation. Once added, if there are any additional properties to be set, you will see those by selecting the condition and they will appear to the right. Here is a screenshot for you to follow along.
Zombie Code Kill 