Tutorial: Create a custom work item in Rational Team Concert

Tutorial: Create a custom work item in Rational
Team Concert
A hands-on example of using advanced customizations in a
project area

Skill Level: Intermediate

Seema Gupta (Seema.Gupta@in.ibm.com)
Project Manager, Smart Deployment Factory
IBM

28 Jul 2011

You can customize or add entirely new work items in IBM® Rational Team Concert™
project management tools to fit your team's needs. The team in this example uses
agile development methods and the scrum process. Their project is highly dynamic,
so they need to closely monitor potential risks. In following this article, you will create
and test a fully functional, new type of work item called Risk, using the Rational Team
Concert Eclipse client, rather than the web client. Thereafter, because there is a an
additional type of work item added to the project called Risk, you can create and
track more types of Risk work items using Rational Team Concert.

Prerequisite software
To follow this article, you need to have following software running and configured
properly:

• IBM® Rational Team Concert™ version 3.0, which runs on the IBM®
Rational® Jazz™ server
• Rational Team Concert 3.0, client for the Eclipse IDE
This software can be installed and configured according to instructions provided in
the "Extending Rational Team Concert" tutorial (see Resources for a link). After

Tutorial: Create a custom work item in Rational Team Concert Trademarks
© Copyright IBM Corporation 2011 Page 1 of 34

developerWorks® ibm.com/developerWorks

completing that tutorial, you will have a local IBM® Rational® Jazz™ server up and
running, named localrtcjazz.com. It can be accessed using this public URI:
https://localrtcjazz.com:9443/ccm. The default administrator access on this server
has been disabled, and a new admin user has been added as seemag, because
these customizations are done by an administrator user.

After you have the server running, open the Rational Team Concert client for the
Eclipse IDE, and establish a connection to this local repository by using the option to
Create a new jazz repository connection. Provide the public URI,
https://localrtcjazz.com:9443/ccm, and the admin user name and
password for the repository.

Use case scenario
Consider the role of project lead of a team that is working in an agile development
project and using Rational Team Concert for project planning, tracking, and
management activities. Assume that the project environment is very dynamic and
there are too many risks, so there is a requirement to identify each risk carefully and
track it until it ends. This can be achieved if the project team creates a custom work
item type called Risk and tracks it. This article shows how to do this in Rational
Team Concert 3.0.

Before you can create any customizations on work items, you need to have a project
area created and named TestProject. For this tutorial, it has been created
already by using the Scrum Process template.

Create a new Risk work item type
Any creation or customization of a work item requires the configuration of several
different aspects of work items in Rational Team Concert: enumerations, work item
type categories, types, attributes, workflows and workflow bindings, editor
presentations and editor presentation bindings. In any project area, all of these
entities are created independently and then bound together to create a fully
functional work item type.

The following steps are required to create a new Risk work item type that can be
categorized as High Risk, Low Risk, or Medium Risk:

1. Define a new work item type with attributes.

a. Define a custom attribute for work item (which will hold the
enumeration value)


ibm.com/developerWorks developerWorks®

2. Create a workflow.

a. Add all states of a Risk work item.

b. Add all actions applicable for a risk.

c. Add all applicable resolutions for a risk.

d. Associate appropriate actions with resolutions.

e. Identify transitions between various states of risk.

3. Create an editor presentation.

4. Bind the workflow and editor presentation with new work item type.

Define an enumeration called Risk Level

In Rational Team Concert any process configurations are done in Process
Configuration tab.

1. Select Process Configuration > Project Configuration > Project
Configuration Data > WorkItems > Enumerations.

Figure 1. Creating Enumerations in Rational Team Concert



2. Click Add to open the dialog window shown in Figure 2.

Figure 2. Providing ID and Name for an enumeration

3. Provide values as shown previously, and click OK. This will create a new
enumeration called "Risk Level."

Figure 3. Risk Level enumeration



Because a risk can take a value of High Risk, Low Risk, or Medium Risk, the next
step would be to associate these values with the previously created Risk Level
enumeration.

4. To add these literals in the Risk Level enumeration, click the Add button
(see the previous screen, Figure 5), which will open the dialog window
shown in Figure 4.

Figure 4. Adding a high-risk enumeration literal in the Eclipse client



5. For each literal, select a name and (optionally) and icon.

Using icons as visual cues is a best practice and makes it much easier to pick out
useful information than using a screen full of text. If you don't see the icon that you
want, you can add more icons to the available icon list. Clicking OK will add High
Risk literal.

6. Add the other two literals, Low Risk and Medium Risk, in the same way.

Define a new work item type with attributes

After the enumeration is created, you need to create a new type of work item.

1. To add a work item, in the Project Area directory, select Process
Configuration > Project Configuration > Project Configuration Data >
WorkItems > Types and Attributes.

Figure 5. Adding new types of work items



Initially, selecting the Types and Attributes tab will list all types of work items that
are available with the current process template of the Project Area, which is the
Scrum Project template in this case.

2. To add a new type to this list, click Add to open the Add Type dialog
window shown in Figure 6, so you can provide a name and an ID for the
new type.

Figure 6. Providing Name, ID and Category for a work item



Each type of work item is associated with a category. You can choose a new
category for the Risk work item type or reuse any existing default category.

3. For this example, create a new category for Risk.

4. Click OK.

5. On the resulting screen (see Figure 7), select a visual icon for this new
type Risk.

Figure 7. Initial screen after a Risk type is created



Scrolling down the screen will show other sections of a work item type, such as
WorkFlow, Attributes, and so on. You will add a new attribute to Risk type first.

6. Scroll down to the Attributes panel.

7. Make sure that you check the check box labeled Show only custom
attributes to avoid viewing all default attributes required for functionality
of the tool. Initially, there will not be any custom attribute for new Risk
work item type.

Define a custom attribute that can hold the enumeration value

You will define a new custom attribute that can hold values from enumeration risk
level and name it Risk Level.

1. To add this custom attribute, click Add on the right side of Attributes
section to open the dialog window shown in Figure 8.

Figure 8. Adding custom attributes for a work item



2. Besides Name and ID, for Type, select the Risk Level enumeration,
which you already created.

3. Click OK, and then make sure that the attributes section of the Risk work
item type reflects this new custom attribute.

Create a workflow for the newly created work item type

A workflow is a definition of the states, actions, resolutions, and transitions that
represent the life cycle of any work item type. Hence, any work item must have a
workflow. Based on stakeholder discussions, the following workflow illustrated in
Figure 9 has been identified for the Risk work item type.

Figure 9. Workflow for a Risk type

1. To start creating a workflow for a work item in Rational Team Concert,
open the project area and select Process Configuration > Project
Configuration > Configuration Data > WorkItems > Workflows (see
Figure 5).

2. On the right side of the Workflows pane, click Add to open a new dialog
window, so you can provide an ID and Name for the workflow that you are
defining:

• ID: RiskWorkFlow
• Name: Risk WorkFlow



3. Click OK, and a new workflow with the name Risk WorkFlow will be
created.

The workflow created in this state acts as a container that will be populated with five
data elements for Risk, as mentioned in the descriptions of the steps that follow:

1. Add all states of a Risk work item.

2. Add all actions applicable for a risk.

3. Add all applicable resolutions for a risk.

4. Associate appropriate actions with resolutions.

5. Identify transitions between various states of risk.

In the following subsections, you will populate the Risk WorkFlow with previous data.

Add all states of a Risk work item

1. To add states in a workflow, go to Workflows tab and select the Risk
Workflow that you created.

As the state diagram in Figure 9 shows, a Risk can be in one of four states:
Identified, Analyzing, Blocking, and Closed. The workflow will have various
sections such as States, Actions, and Transitions.

2. Scroll down to States section and click Add to open the Add State dialog
window shown in Figure 10 (this screen was captured with different
values specified for the Identified state).

Besides the Name, Icon, and Description fields, there are two more parameters
here: Group and Show Resolution.

Figure 10. Adding a new state to the Risk workflow



Any state in Rational Team Concert can be categorized into one of three standard
groups:

• Open
• In Progress
• Closed
Because a Risk in the Identified state is an open work item, the Open group has
been chosen.

3. The Show Resolution check box needs to be checked only if it tags the
work item as Closed with a proper resolution. In Figure 10, this check box
is unchecked, because the Identified state doesn't tag the work item as



Closed.

4. Click OK to create the identified state.

You can create Analyzing, Blocking and Closed states in a similar way. The only
difference is that, while creating a Closed state, the Show Resolution check box
needs to be checked. After all the states are created, the States section will look
something like Figure 11.

Figure 11. States of the Risk work item in the Risk workflow

Add all actions applicable for a risk

In this step, all actions applicable on a Risk will be added. In the state diagram
(Figure 9), arrows represent actions and eclipses represent states. As an example,
initial action for any Risk is Open, which will create a Risk in Identified state.

1. To add this action, scroll to Actions section of Risk Workflow editor and
click on Add to open a dialog window to add details about actions, as
Figure 12 shows.

Figure 12. Adding Open Action in Risk Workflow



By this time, the information in the Name, Icon, and Description fields will start
looking quite familiar. Besides these regular attributes, each action needs to provide
an additional parameter for Target State. Because the Open action leads to the
Identified state, the Target State in the previous diagram is selected as Identified.

2. Click OK to create the Open action.

3. Add all other actions for a Risk work item in a similar fashion.

After all of the actions have been added, the Actions section of the Risk workflow will
look like Figure 13.

Figure 13. Actions section of workflow after adding all actions for Risk



The workflow for a work item also needs to provide the primary actions such as
Start action, Resolve action, and Reopen action. These are the actions for the
Risk work item:

• Start action = Open
• Resolve Action = Close
• Reopen action = Reopen
You can select these values in the workflow.

Figure 14. Associating the Risk workflow with Start, Resolve, and Reopen
actions

Add all applicable resolutions for a risk

In this step, all possible resolutions for a Risk work item will be added in the Risk
workflow. Assume that, based on stakeholders' discussions, a risk can be handled in
only three ways: mitigating, containing, or declaring it invalid. So you will add three
resolutions: Mitigated, Contained, and Invalid.

1. Scroll down to the Resolutions section and click Add to open the dialog
window shown in Figure 15.

Figure 15. Add Resolution dialog window in the Risk workflow



Note:
The screen capture provided here reflects values for Contained resolution.

2. Click OK to create the Contained resolution.

3. Add two other resolutions, Mitigated and Invalid, in the same way.

After you add all of the resolutions, the Resolutions section of the workflow, it will
look like Figure 16.

Figure 16. Resolutions section of the Risk workflow



Associate appropriate actions with resolutions

After you have added all of the resolutions, it's time to revisit actions in the workflow
and associate resolutions with actions that can lead to resolutions of a Risk. In the
current scenario, only the Close action can resolve the Risk.

1. To associate this action with Resolutions, select Close and select the
check boxes for all resolutions (Contained, Mitigated, and Invalid). The
actions pane of the Risk workflow will then display what Figure 17 shows.

Figure 17. Actions in the Risk workflow after adding resolutions to actions

The end user is presented these resolutions in the same order as they appear in the
workflow. You can move items up or down with the buttons toward the right side of
Actions pane.

Identify transitions between various states of a Risk item

In this step, you need to identify the transitions between various states of a work
item. If you do not identify this, the Transitions pane of the Risk workflow will appear
as the matrix in Figure 18 shows.

Figure 18. Initial Transitions Section in the Risk workflow



The matrix for various states has already been created. The transitions for various
stages need to be identified and populated in the matrix. Looking at the state
diagram closely, the following observations can be made:

• An Identified risk can get into only an Analyzing state, and the action with
which the state can change is Assign. It cannot directly go to any other
state.
• A risk in the Analyzing state can move into the Blocking state or Closed
state, depending on whether an Escalate action or Close action has been
taken.
• A risk in Blocking state can get into the Analyzing or Closed state,
depending on whether a Revisit or Close action has been taken.
• A risk in Closed state can get into the Analyzing state if a Reopen action
has been taken.
Based on these observations, you can provide the transitions shown in Figure 19:

• Identified to Analyzing with an Assign action
• Analyzing to Blocking with an Escalate action and Analyzing to Closed
with close action
• Blocking to Analyzing with a Revisit action and from Blocking to Closed
with close action
• Closed to Analyzing with a Reopen action
Figure 19. Final Transitions section in the Risk workflow



With the creation of transitions, you have finished creating the workflow for the Risk
work item.

Create an editor presentation for the new work item type

An editor presentation acts as the form to present a work item to users. In current
versions of Rational Team Concert, a work item can be displayed four different
ways:

• Work Item Editor, the presentation used in the Eclipse client and the web
client when displaying a work item in the Editor view
• Inline Work Item Editor, used in web client to display work item details in a
Plan view
• Lightweight Work Item Creation dialog, used in the web client when
creating work items
• Plan Editor Preview, displayed as a pop-up window in the Eclipse client
when the user moves the cursor over a work item in the Plan Editor view
Important:
A work item can be viewed in any type of presentation, so all four editor
presentations need to be created for any work item type. All of the editor
presentations are created in same way. This article covers only creation of the Work
Item editor presentation for a Risk, but you need to create the three other editor
presentations before using the new work item type in a project area.

Rational Team Concert provides a default editor presentation that includes most of
the fields, tabs, and so forth that are required to present any work item. The default
layout can be changed by adding a few custom attributes.

1. To start adding or editing the Risk work item editor presentation, go back
to Process Configuration > Project Configuration > Project
Configuration Data > WorkItems > Editor Presentations, as shown in
Figure 20.



2. Look at combination box with title of Choose the editor presentation to
edit. By default, the value will be com.ibm.team.workitem.editor.default.
Retain the default value, and click Duplicate.

3. A dialog window will open for you to provide the ID for the duplicated
editor presentation. Give it a suitable name, such as
RiskWorkitemEditorPresentation, and click OK.

Figure 20 shows the RiskWorkitemEditorPresentation.

Figure 20. Duplicated Risk editor presentation based on the default one

A presentation or view is divided into various tabs, sections, and presentations. The
Header, Overview, Links, Approvals, and so on form the tabs, and each tab has
more parts. For example, the Overview tab contains all details of a work item, and
links refer to links for a work item. Depending on where you want to change the
view, the editor presentation needs to be modified. For this example, you are adding
only one attribute in Details for the work item, and it can hold the value of Risk Level.

Details are part of the Overview tab, so you start these modifications there.

Important:
Shared content should not be modified directly in an editor presentation, because
this would be shared between multiple editor presentations.

The Overview tab in Risk Work Item editor presentation has a "content shared" tag



against it, and this should be duplicated before making any modifications.

4. Select Overview, and click Duplicate.

5. In the dialog window that opens, provide an appropriate name (Overview
in this case), and click OK.

This will create an additional Overview tab that will not have a[content shared]
notation. After the Overview tab is created, it's time to modify the Details sections to
show the new Risk Level custom attribute in the Work Item editor presentation.
Again, the Details section is shown with a [content shared] notation; therefore, it
needs to be duplicated first.

6. Select Details and click Duplicate once again.

7. When you are prompted for an ID for duplicated section, provide an
appropriate name and click OK.

At this stage, there will be two Overview tabs and two Details sections, one with the
[content shared] notation and one without it, as shown in Figure 21.

Figure 21. Risk Work Item editor presentation after duplicating Overview and
Details

Because you have Overview tabs and Details sections created specifically for the
Risk editor presentation, you don't need the shared Overview tab and Details section



anymore.

8. To remove those sections or particular elements of the editor
presentation, select the appropriate element (Overview [shared content]
and Details [shared content]), and click Remove.

After you remove the shared Overview tab and Details, notice that you have only
one Overview and Details section, without any shared content in the
RiskWorkitemEditorPresentation view.

The next step is to modify the presentation for the custom attribute that you want to
show in the Risk Work Item Editor: Risk Level.

9. Expand the Details section by clicking on the plus sign + of the Overview
tab, and then click Add Presentation.

This will open a dialog window to provide values for presentation field. The
presentation can be attribute-based or non-attribute-based.

10. Since you are adding the presentation field for a custom attribute of a
Risk work item, select Attribute-based presentation.

Figure 22. Provide values for an attribute-based presentation



The Risk Level has been chosen as the attribute, because the presentation is being
added for the Risk Level attribute of the Risk work item type.

11. Choose Kind as an Enumeration, because Risk Level is an enumeration
type.

12. A label is required for visual identification of the presentation field.



13. Click OK.

There will now be a new presentation created for Risk Level in the Details section.
You can change the position of this presentation by clicking the Move Up or Move
Down button.

Figure 23. Risk Level presentation added to the presentation

With this, you have finished creating the Work Item Editor for the Risk work item.

Reminder:
Remember to add the other three types of editor presentations to be able to view the
work item properly in all views.

Bind the workflow and editor presentation with the Risk work item

Until now, the workflow and editor presentations that you created exist as
independent identities, without any link to the Risk work item type created earlier.

1. To link these entities, go back to Process Configuration > Project
Configuration > Configuration Data > WorkItems > Types and
Attributes, and select the newly created type, Risk.



Any work item in this place will have selection boxes to choose its various attributes,
such as Work Item Editor, Inline Work Item Editor, Lightweight Work Item Creation
Dialog, Plan Editor Preview, Workflow, and so forth.

2. To select the editor presentations and workflow that you created as
values of the Work Item editor presentation and workflow for the Risk
type, choose the values shown in following two screen captures.

a. (Figure 24) In the Project Area screen, under the Types and
Attributes view, for Work Item Types, select Risk from the list.

b. For the Work Item Editor field, select
RiskWorkItemEditorPresentation from the drop-down menu.

c. (Figure 25) In the next view, under Workflow, select Risk
Workflow from the drop-down menu.

Figure 24. Binding the Work Item Editor Presentation with the Risk type of
work item

Figure 25. Binding the workflow with the Risk type



Reminder:
Remember to bind other three types of editor presentations (inline work item editor,
Lightweight Workitem Creation dialog and Plan Edior Preview) to be able to view the
work item properly in all views.

3. Choose appropriate values for other three types of editor presentations,
using the names that you gave to those.

You have now created a fully functional type of work item called "Risk."

Test the new Risk work item

1. In the Team Artifacts view, to test the new work item type that you have
created, open the TestProject project, and select Create Work Item.

Figure 26 shows the resulting Create Work Item screen.

Figure 26. Creating a new work item in Rational Team Concert



2. Notice that there is now a type of work item called Risk. Select it, and
then click Finish.

This will create a new Risk work item. Notice the highlighted parts in the screen
capture (Figure 27): Low Risk and Uninitiated [inactive]. A Risk Level attribute is
displayed in the third row, with a default value of Low Risk, and the initial state of
Risk is Uninitialized.

Figure 27. New risk created



As you recall from the workflow, a risk should move into the Identified state as soon
as it is opened. Rational Team Concert treats the Risk as Opened only when it is
saved to the project.

3. Save this Risk, and the state will change to Identified.

Figure 28. Risk now shown in the Identified state



To test the workflow of this Risk work item, take specific actions.

4. As an example, select Assign for this new Risk.

Figure 29. Performing an Assign action on a risk

As soon as Assign action is applied, the state of risk is changed to Analyzing.

Figure 30. Risk in Analyzing state after performing the Assign action



At any point, you can choose to perform actions, as long as they are feasible from
current state of a risk. Based on the action taken, the state of the Risk work item will
keep changing. For example, an Escalate action will lead to a Blocking state, as
shown in Figure 31.

Figure 31. Risk in Blocking state after an Escalate action

You can also test that Resolutions being shown when a Close action is being
performed and choose different resolutions. Using the second highlighted drop-down
menu, to the right of the state (status) field, you can choose various resolutions.
They are in the same order as you defined them in the workflow. When the
resolution is selected and saved to the Project Area, the resolution can no longer be
edited.

Figure 32. Performing a Close action on a Risk work item

Larger view of Figure 32.

Summary



Rational Team Concert provides extensive process configuration options to meet
requirements of almost every project. This article covered one of those
customizations for work items in Rational Team Concert. As a part of this
customization, a new type of work item was created for risks, along with its various
aspects, including enumerations, custom attributes workflow, and so forth. There
were details about various parts of the workflow, focusing on states, transitions,
resolutions, and actions. After all of the independent identities were created and
linked, the newly created work item type was tested. Team members can now create
custom work items for different risks, based on that "umbrella type" of Risk work
item.



Resources
Learn
• Find Rational Team Concert articles and links to many other resources on the
IBM developerWorks page. You can also watch the Using Rational Team
Concert in a globally distributed team webcast or a demonstration of the
Dashboards and reports, or listen to the podcast about IBM Rational Team
Concert and Jazz.
• Follow the Extending Rational Team Concert tutorial to install and configure
Rational Team Concert and the Eclipse client.
• Visit the Rational software area on developerWorks for technical resources and
best practices for Rational Software Delivery Platform products.
• Stay current with developerWorks technical events and webcasts focused
on a variety of IBM products and IT industry topics.
• Attend a free developerWorks Live! briefing to get up-to-speed quickly on
IBM products and tools, as well as IT industry trends.
• Watch developerWorks on-demand demos, ranging from product
installation and setup demos for beginners to advanced functionality for
experienced developers.

• Improve your skills. Check the Rational training and certification catalog, which
includes many types of courses on a wide range of topics. You can take some
of them anywhere, any time, and many of the "Getting Started" ones are free.
Get products and technologies
• Rational Team Concert trial downloads (free):
• Enterprise Edition
• Express Edition
• Standard Edition

• Evaluate IBM software in the way that suits you best: Download it for a trial, try
it online, use it in a cloud environment, or spend a few hours in the SOA
Sandbox learning how to implement service-oriented architecture efficiently.
Discuss
• Join the Rational Team Concert discussions or ask questions in the Jazz.net
forums.
• Share your knowledge and help others who use Rational software by writing a



developerWorks article. You'll get worldwide exposure, RSS syndication, a
byline and a bio, and the benefit of professional editing and production on the
developerWorks Rational website. Find out what makes a good
developerWorks article and how to proceed.
• Follow Rational software on Facebook and Twitter (@ibmrational), and add your
comments and requests.
• Ask and answer questions and increase your expertise when you get involved
in the Rational forums, cafés, and wikis.
• Connect with others who share your interests by joining the developerWorks
community and responding to the developer-driven blogs.

About the author
Seema Gupta
Seema Gupta is a project manager at IBM Software Labs in Bangalore,
India. She has undergone several trainings on Rational Team Concert
and uses it extensively for all projects.


Tutorial: Create a custom work item in Rational Team Concert

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Destaque

Destaque (7)

Semelhante a Tutorial: Create a custom work item in Rational Team Concert

Semelhante a Tutorial: Create a custom work item in Rational Team Concert (20)

Mais de Bill Duncan

Mais de Bill Duncan (20)

Último

Último (20)

Tutorial: Create a custom work item in Rational Team Concert