Advanced customizations in Rational Team Concert project areas: Part 1. Create a custom work item in Rational Team Concert

A hands-on example of using advanced customizations in a project area

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.

Share:

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

author photoSeema 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.



02 August 2011

Also available in Chinese

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 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.
    1. Define a custom attribute for work item (which will hold the enumeration value)
  2. Create a workflow.
    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.
  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
Selected Enumerations under Work Items
  1. Click Add to open the dialog window shown in Figure 2.
Figure 2. Providing ID and Name for an enumeration
Populated Name and ID for the new enumeration
  1. Provide values as shown previously, and click OK. This will create a new enumeration called "Risk Level."
Figure 3. Risk Level enumeration
Screen showing 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.

  1. 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
Add Literal view, high.gif selected
  1. 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.

  1. 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
Types and Attributes view open

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.

  1. 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
Populated Name, ID, and Category for new type

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.

  1. For this example, create a new category for Risk.
  2. Click OK.
  3. 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
Initial screen shown for new Risk type

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.

  1. Scroll down to the Attributes panel.
  2. 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
Providing Name, ID, and Type for custom attribute
  1. Besides Name and ID, for Type, select the Risk Level enumeration, which you already created.
  2. 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
Workflow definition for a Risk work item
  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
  1. 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.

  1. 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
Defined Identified state for Risk in 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.

  1. 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.
  2. 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
Table with all states added

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
Populated values for Open action in 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.

  1. Click OK to create the Open action.
  2. 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
Actions columns: Name, Target State, Description

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
Workflow action fields selected

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
Group: Closed

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

  1. Click OK to create the Contained resolution.
  2. 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
Resolutions for 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
Resolutions associated with the Close action

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
Identified, Analyzing, Blocking, Closed options

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
Transitions selected 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
Editor Presentation area in the Project Area view

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.

  1. Select Overview, and click Duplicate.
  2. 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.

  1. Select Details and click Duplicate once again.
  2. 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
Duplicated Overview tab and Details section

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.

  1. 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.

  1. 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.

  1. 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
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.

  1. Choose Kind as an Enumeration, because Risk Level is an enumeration type.
  2. A label is required for visual identification of the presentation field.
  3. 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
Risk Level presentation added under Details

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.

  1. 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.
    1. (Figure 24) In the Project Area screen, under the Types and Attributes view, for Work Item Types, select Risk from the list.
    2. For the Work Item Editor field, select RiskWorkItemEditorPresentation from the drop-down menu.
    3. (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
Selection of the appropriate editor presentation
Figure 25. Binding the workflow with the Risk type
Risk workflow selected for 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.

  1. 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
Shows Risk under Work Item Types
  1. 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
Initial screen after a new Risk is 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.

  1. Save this Risk, and the state will change to Identified.
Figure 28. Risk now shown in the Identified state
Risk state shows as Identified

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

  1. As an example, select Assign for this new Risk.
Figure 29. Performing an Assign action on a risk
Identified changes to Assign

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
Risk in Analyzing state after completion of Assign

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
Risk Details view

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
Performing Close action on a Risk

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

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=749890
ArticleTitle=Advanced customizations in Rational Team Concert project areas: Part 1. Create a custom work item in Rational Team Concert
publish-date=08022011