Managing complex work item structures using templates in Rational Team Concert 3.0
A work item template is a blueprint for a set of linked work items. Instantiating a template creates and links the work items and initializes their attributes with data specified in the blueprint. No matter what kind of work item structure you have, a single pre-configured task with a complex approval structure, a highly specialized story with pre-set values for custom attributes, or an entire work breakdown structure, they all can be easily created with templates.
Overview
In Rational Team Concert (RTC) 2.0.0.2 we made an early preview of work item templates available. This functionality has been extended significantly in RTC 3.0. We added support for capturing work breakdown structures, quick access to frequently used templates, and for import/export of templates. Also, templates now support all work item attributes including links to work items and other resources, attachments, and approvals. All functionality presented in this article works also with RTC 3.0.1.
This article illustrates how you can use work item templates in your daily work. It shows what templates are capable of, but also their limitations. The main part of this article is twofold. It first summarizes the tool support provided in RTC 3.0 before it describes scenarios in which we see high potential for using work item templates in daily tracking and planning activities.
If you are new to Rational Team Concert or have not used work items before, we recommend to read the article ‘Getting Started with Work Items in Rational Team Concert’ before you continue. We also use customized work items in our illustrations. If you like to know more about customizing work items, you may want to read ‘Work Item Customization in Rational Team Concert’.
Getting started with Templates
The Eclipse client of Rational Team Concert provides support for creating templates, for instantiating templates, and for importing and exporting templates. The Web UI only supports to instantiate templates. This section introduces basic functionality and might be skipped if you are familiar already with the tool support for work item templates.
Creating Templates
A new template can be created by capturing it from existing work items. You select one or more work items, e.g. by opening them in the editor or running a query. In the Work Items view, the Work Item History, or directly from within the Editor you open the context menu and choose Create Work Item Template….
A wizard guides you through the process of capturing work items connected through links. A template description can be provided to document the purpose of the template. You can also configure specific attributes to become late-bound variables, which can be assigned to a user-selected value at template instantiation time.
The new template is saved in the work items’ project area and can be used within this project only. Technically a template is a process attachment and is stored within the process specification. You may need explicit permissions to modify the process specification and may not be able to create new templates otherwise. Moreover, every work item template is scoped by its project area, that is you cannot capture work items from different project areas within a single template.
Instantiating Templates
A work item template is turned into work items via template instantiation. The Eclipse client and the Web UI of RTC provide a New Work Items from Template… action in all the places where work items can be created. This action opens a wizard to guide you through the process of selecting a template and optionally binding variables to selected values. The newly created work items are automatically shown in the work items view to make transparent what has been created and to give the user a chance for some ‘final editing touches’.
In particular for frequent activities with similar work items, we created a ‘Template Instantiation History’ in the Eclipse client of Rational Team Concert. It provides instant access to recently used templates and allow you to create frequently used work items more easily.
Its entries are sorted by usages (more recently used templates on top) and indicate whether a template has unbound variables (menu entry with ‘…’). Templates without any unbound variables can be instantiated with a single-click.
Managing Templates
All work item templates are stored with a project area and are shared among its members. The project area editor (Open in the context menu) provides an aspect editor for managing work item templates. This aspect editor can be found on the Process Configuration tab under the Project Configuration > Configuration Data > Work Items > Templates section. It lists all templates that are available in the selected project area and allows you to change name and description of a template, as well as to delete it entirely.
Import/Export of Templates
If a template has shown its usefulness you may want to make it available for other project areas. Sharing of templates across project areas is accomplished by exporting the template from the source project area and importing it into the target project area. Only the Eclipse client of Rational Team Concert provides export and import wizards for saving/loading templates to/from files.
On exporting, the wizard will warn you if the template contains any references to items that are specific to its project area and therefore cannot be imported into a target project area. You still can export the template safely in order to save a specific version on disk or to edit its specification, but you should be careful when importing the template into another project area since attachments, users, and other values not contained in the template won’t be valid.
The rule of thumb is to export only templates with attributes that are not configured or customized in the process specification, such as ‘Category’ and ‘Iteration’. Also, do not link to repository items, such as other work items and attachments, when you plan to use a template in project areas stored in a different repository.
The import of a work item template will also warn you in such cases and may not succeed. Besides incompatibility issues, the importer can be configured to replace existing templates with the same name and/or same identifier. This can be useful in cases where you want to edit and update an existing template. Moreover, it can import templates from any XML file that follows our specification format, e.g. as the output of other tools. The XML format for specifying work item templates is based on OSLC and is described briefly in a design document in the RTC Wiki.
Working with Templates
Work item templates have been built with certain use-cases in mind. This section describes three scenarios in which we see good potential for using work item templates for your development activities.
Frequently Created Work Items
Some tracking and planning activities may require the frequent creation of work items with lots of pre-filled data. We use, for example, dedicated work items to track the status of our builds or to manage our retrospectives. Build Tracking Items always have a description with a specific structure, a long list of subscribers and an approval with all component team leaders as approvers. Retrospectives have the proposed outline of a retrospective session as their description. Also for more development related activities, such as adding a new plug-in to a build or adopting API changes, specific work items are created.
The ‘Template Instantiation History’ in the Eclipse client of RTC provides instant access to frequently used templates. More recently used templates are placed on top. Templates with no unbound variables can be instantiated with a single click. Especially in traditional software development where heavy processes often require the creation of many work items, work item templates are vital to create work items with lots of pre-filled attribute values frequently and without any pain. Also, if there is not much overhead in your tracking and planning activities you will find tasks that can be automated with a template.
Work Breakdown Structures, and complex Tasks
A work breakdown structure (WBS) can be used in system engineering and project management to define and group tasks. It helps to organize and define the scope of an entire project or a complex task in a hierarchical way. For example, the task of adding a new plug-in to the Jazz build system can be defined by the WBS shown on the right hand side. Such tasks are done frequently and associated work items have to be created every time from scratch. A work item template can simplify the creation of all work items that belong to complex task.
Since the Eclipse client of Rational Team Concert captures templates from existing work items, the first step would be to find (or create) all the work items of the WBS. Regardless whether you capture the template from newly created or already existing work items, make sure you only assigned values to attributes that should be pre-filled by the template, and that all links are established correctly. In order to capture the entire WBS you only select the root item, the template creation wizard will help you to discover all related, child and dependent items from an initial selection. So for the example from above you do not have to find all work items of the WBS, but you can just search for the root work item ‘Add plug-in to JCB build’ by running a quick query that searches for “build” in your work items and would find the work items shown below.
You select the root work item of the WBS and run the Create Work Item Template… action from the context menu. A wizard opens up and shows selected work items, and also every linked work item with its association to the initial selection.
The wizard for creating templates fetches all child, depend and related work items automatically and shows the complete WBS in a tree-view presentation. You can select those work items that should be contained in the template. The next wizard page allows you to configure variables, e.g. for using the same WBS in a different iteration or with another category. The resulting template holds all work items of the WBS with all specified attributes and represents sub-tasks as links to child work items. This way, even complex work breakdown structures can be populated easily with the Eclipse client of Rational Team Concert.
Initial Work Items when creating Plans
Work item templates can also be useful when creating new plans. In particular, in traditional planning you can have several work items to track initial work that has to be done to setup newly created plans. Such work items can layout an initial planning structure, outline basic development phases or assign standard tasks to responsible team leads or managers. If you want to create initial work items with pre-filled attribute values whenever you create a new plan, the Eclipse client of Rational Team Concert allows you to instantiate a work item template as part of the plan creation wizard.Conclusions
This article has shown basic functionality to create and instantiate work item templates. It also describes typical scenarios for using work item templates in daily tracking and planning activities. If you are interested in more details about the XML format that is used to specify templates, we recommend to read ‘XML Format of Work Item Templates’. In case you want to know more about large-scale tool-support for work breakdown structures, the following two articles describe how the Rational Method Composer can be used to document work breakdown structures and how to export them into Rational Team Concert using work item templates:
- Agile practices enactment with Rational Team Concert and Rational Method Composer
- How to document your team’s processes for IBM Rational Team Concert using IBM Rational Method Composer
About the Author
Jan Wloka is a member of the Jazz Tracking & Planning team and has worked mainly in the area of work item editor, work item front-end, OSLC-CM and CLM. He works for the IBM Rational Research Lab in Zurich, Switzerland, and can be contacted at jan_wloka@ch.ibm.com
© Copyright 2010 IBM Corporation