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
This content is part # of # in the series: Advanced customizations in Rational Team Concert project areas, Part 1
This content is part of the series:Advanced customizations in Rational Team Concert project areas, Part 1
Stay tuned for additional content in this series.
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 Related topics 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
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:
- Define a new work item type with attributes.
- Define a custom attribute for work item (which will hold the enumeration value)
- Create a workflow.
- Add all states of a Risk work item.
- Add all actions applicable for a risk.
- Add all applicable resolutions for a risk.
- Associate appropriate actions with resolutions.
- Identify transitions between various states of risk.
- Create an editor presentation.
- 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.
- Select Process Configuration > Project Configuration > Project Configuration Data > WorkItems > Enumerations.
Figure 1. Creating Enumerations in Rational Team Concert
- Click Add to open the dialog window shown in Figure 2.
Figure 2. Providing ID and Name for an enumeration
- 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.
- 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
- 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.
- 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.
- 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.
- 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.
- For this example, create a new category for Risk.
- Click OK.
- 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.
- Scroll down to the Attributes panel.
- 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
- 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
- Besides Name and ID, for Type, select the Risk Level enumeration, which you already created.
- 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
- 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).
- 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
- 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:
- Add all states of a Risk work item.
- Add all actions applicable for a risk.
- Add all applicable resolutions for a risk.
- Associate appropriate actions with resolutions.
- 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
- 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.
- 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:
- In Progress
Because a Risk in the Identified state is an open work item, the Open group has been chosen.
- 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.
- 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.
- 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.
- Click OK to create the Open action.
- 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.
- 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
The screen capture provided here reflects values for Contained resolution.
- Click OK to create the Contained resolution.
- 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.
- 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
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.
- 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.
- 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.
- 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.
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.
- Select Overview, and click Duplicate.
- In the dialog window that opens, provide an appropriate name
Overviewin 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.
- Select Details and click Duplicate once again.
- 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.
- 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.
- 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.
- 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.
- Choose Kind as an Enumeration, because Risk Level is an enumeration type.
- A label is required for visual identification of the presentation field.
- 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.
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.
- 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.
- 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.
- (Figure 24) In the Project Area screen, under the Types and Attributes view, for Work Item Types, select Risk from the list.
- For the Work Item Editor field, select RiskWorkItemEditorPresentation from the drop-down menu.
- (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
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.
- 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
- 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
- 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.
- 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.
- 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
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.
- Watch the Using Rational Team Concert in a globally distributed team webcast or a demonstration of the Dashboards and reports.
- Download Rational Team Concert from Jazz.net (requires registration).
- Evaluate IBM software.