This documentation is archived and is not being maintained.

Walkthru:Extending Work Items 

Visual Studio 2005
Extensibility Guided Tour Send comments on this topic.
Walkthru:Extending Work Items

Glossary Item Box

Work Item Extensibility

Visual Studio Work Items improve communication

Visual Studio 2005 Team System groups activities and sub activities into collections of tangible work that form a hierarchy and help define systems and projects. The containers for these activities are called Work Items, and serve as a highly flexible framework that provides key metrics to developers, testers, managers, and other project shareholders as they work independently within their own spheres of influence to bring projects to fruition. The exact nature and structure of Work Items, as well as their defined points of interaction, are completely customizable, and help increase the frequency and consistency of success in development projects by facilitating communication.

Work Item Types in the MSF Agile Methodology

A quick overview of how Work Items are used in the MSF Agile methodology will help provide an example of how they translate tangibles into metrics (and will serve to provide some context for the walkthrough provided in this section where we'll create a new type of Work Item). In the MSF Agile Methodology, there are four types of Work Items. Scenarios are work items that roughly translate to use-cases – defining functionality and usability of the end product (the more scenarios, the more complex the application will be). Quality of Service Requirements represent service-level-agreement definitions – defining important things like scalability and uptime requirements, for example. Tasks are core work items that communicate the need to perform work – work which derives from a project's given scenarios and QoS Requirements. Vast in scope, Tasks can represent anything from the need for an architect to enable web services interaction, to a developer to add new admin functionality, or for a tester to test said functionality. However, because these tasks (as well as other work items) can be bound to project tangibles, such as source control checkins, bugs, test results, or even the project schema itself (i.e. a Task can be bound to the DAL, or to the GUI, for example), Tasks provide more than just simple ‘todo list' functionality – they provide the ability to track key metrics. The remaining work item type in the MSF Agile methodology is the Bug, which translates to a failure or problem – from which more Tasks can be generated to solve the bug.

Work Item Definitions

In order to facilitate flexibility, Visual Studio Team System provides a flexible object model that governs the definition and interaction of work items. Work Items are defined through an easy to understand XML Schema that maps fields (data points) and defines rules about how data in those fields can be manipulated. Further XML instructions define allowable work item states and transition rules allowing work items to reflect complex workflows. There are also XML definitions that allow the mapping of fields to entities used in reporting. A special public interface, known as the Work Item Object Model, allows for programmatic interaction with work items within Visual Studio, allowing automation and the ability to manage tracking through interrogation of work item objects. More details on Work Item Schema and interaction can be found in the VSTS SDK, along with several additional walkthroughs.

Extending Work Items 

To showcase the flexibility of Work Items, and to show their relation to logical entities, the walkthrough in this section will focus on creating a new type of Work Item which will represent actual tests to be run againt code and systems. In the interest of keeping this walkthrough in scope, the Test Work Item Type will implement most of the base functionality available to Work Items, but will provide two distinguishing features: a dropdown indicating what kind of test (unit, regression, etc.) is being run, as well as another dropdown to indicate what the result of the test was.

NOTE: In order to complete this Walkthrough, you must have completed the previous Walkthrough: Extending Process Templates.

1.  On your Desktop, open the MyProcessTemplate folder. Right click on ProcessTemplate.xml and select Edit (if you do not have an Edit choice, select Open With, and specify Visual Studio). Change the name of the Process Template by changing the contents of the <name> element to "WorkItemExtensibility Template". Save your changes and close the file. (Changing the name of the Process will avoid creating a naming collision with the previously created template when uploaded to the Team Foundation Server.)

2.  Navigate to the Desktop\WorkItem Tracking\TypeDefinitions folder. Create a copy of task.xml, and then rename it to "test.xml".

3.  Right click on test.xml and select Edit (or Open With | Visual Studio).

Take a second to look over the contents of the file. Information about the Work Item definition is broken into three key areas: Fields, Workflow, and Form (or layout). <FIELD> nodes serve to define the type of data stored as part of a Work Item's definition along with allowable values, defaults, and other attributes that define the data types. Constraints on how the values in fields are allowed to change are defined in the <WORKFLOW> section of the file, and are defined as <TRANSITIONS> which help ensure that process is correctly implemented by Work Items. In other words, a Bug Work Item, for example, can have a rule set up as a transition which makes it impossible to close the work item until it has been set to resolved. Finally, the <FORM> element provides definitions about the layout and placement of fields within Visual Studio.

In this Walkthrough, in order to keep things simple, you'll just, effectively, extend a copy of the Task Work Item to include new fields geared specifically towards testing. In a more realistic implementation (i.e. non sample implementation) you would likely make many more changes – but making those changes in this Walkthrough would result in many more steps and wouldn't do much more to help you learn the basic concepts involved.

4.  Locate the <WORKITEMTYPE> element and change the value of the name attribute from "Task" to "Test". (Not only is this an important step in terms of ensuring that the new definition accurately describes a Test Work Item (instead of a Task), but if you attempt to upload this definition as part of a Process Template a collision would occur on the already existent name – in other words, Work Item type names obviously need to be unique for a number of reasons.)

5.  Locate the <FIELD> with the name attribute set to "Discipline", and delete the <LISTITEM> entries for Business Analyst and Architect (pretend that they have no need to run Test Work Item Types for this specific Process Template.)

6.  Scroll down to the bottom of the <FIELDS> element, and paste in the following field definition:

<FIELD 
     name="Test Type" refname="VSIP_GT.TestType" type="String">
	<HELPTEXT>Describes the type of test for the work item</HELPTEXT>
	<ALLOWEDVALUES>
	  <LISTITEM value="Unit" />
	  <LISTITEM value="Integration" />
	  <LISTITEM value="Build" />
	  <LISTITEM value="Regression" />
	</ALLOWEDVALUES>	
</FIELD>

As you can see, this just adds a new Test Type field with a list of acceptable values. (The refname attribute just acts as a unique reference, or name, used to identify the field throughout the definition.)

7.  Scroll down to the <WORKFLOW> element and change the value of the value attribute for the last <STATE> element to "complete" (which is more logically sound for testing than the notion of Closed).

At this point, you have defined that a Test Work Item can only be in the Initial or "" state (the default state when it is instantiated), the Active state, or the Complete state. Rules for whether or not a Test can go directly from initialized to complete are defined by transitions. Transitions MUST contain at least one definition moving a Work Item to a non-default ("") state to a named state – otherwise any transition not explicitly defined will not be allowed (meaning, for example, that if you don't specify a transition from complete BACK to active (in the case where a Test needs to be re-opened) it won't be allowed to happen.

8.  Scroll down to the <TRANSITIONS> element, and delete the last two <TRANSITION> elements ( Active to Closed and Closed to Active). Paste in the following transition which only allows Active Tests to be promoted to the Complete state (i.e. no transitions from Complete to Active will be allowed as they are not explicitly defined.)

<TRANSITION from="Active" to="Complete">
	<REASONS>
		<DEFAULTREASON value="Passed" />
		<REASON value="Failed" />
		<REASON value="Deferred" />
		<REASON value="Other" />
	</REASONS>
	<FIELDS>
		<FIELD refname="System.AssignedTo">
			<COPY from="field" field="System.CreatedBy" />
		</FIELD>
		<FIELD refname="Microsoft.VSTS.Common.ActivatedDate">
			<READONLY />
		</FIELD>
		<FIELD refname="Microsoft.VSTS.Common.ActivatedBy">
			<READONLY />
		</FIELD>
		<FIELD refname="Microsoft.VSTS.Common.ClosedBy">
			<COPY from="currentuser" />
			<VALIDUSER />
			<REQUIRED />
		</FIELD>
		<FIELD refname="Microsoft.VSTS.Common.ClosedDate">
			<SERVERDEFAULT from="clock" />
		</FIELD>
	</FIELDS>
</TRANSITION>

As you can see, Transitions allow for a high degree of customization, and can be used to specify which fields should be marked as <READONLY />, populated automatically or copied from other fields. There is also the ability to specify a Reason for the transition – as well as functionality to set the default reason for a transition.

9.  Now locate the <Layout> element in the <FORM> node and navigate to the second <Group> element (with "Classication" set as the value for the group's label). Add the following code above the other two controls (AreaPath and Iteration):

<Control Type="FieldControl" 
	FieldName="VSIP_GT.TestType" 
	Label="T&amp;est Type" 
	LabelPosition="Left" />

With this simple directive, a new Test Type drop-down will be added to the Work Item's surface – and will populated with the values set for the VSIP_GT.TestType field, or data type.

10.  Save your changes, and close Test.xml.

11.  In Windows Explorer, open Desktop\MyProcessTemplate\WorkItem Tracking\workitems.xml for editing. In the first <task> element (with an id of WITs), add the following WORKITEMTYPE definition:

<WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Test.xml"/>

With this in place, the WorkItemType Plug-in will be instructed to upload your custom Work Item when a new project is created – meaning that developers and other team members will be able to create new Test Work Items in the project created from this Process Template. If you wanted, you could also specify the creation of Test Work Items when the project is created by adding a new <WI> element to the <WORKITEMS> element found in the second task found in this file. (You would just need to set the type attribute to "Test" and then populate any fields as needed.

12.  Save your changes and close workitems.xml.

13.  Return to Visual Studio, and select the Team | Team Foundation Server Settings | Process Template Manager menu option. Then Upload your newly modified MyProcessTemplate folder from the Desktop.

14.  Create a new Team Project by selecting File | New | Team Project. Specify "Test WIT Project" for the name of the Team Project, click Next, specify the WorkItemExtensibility Template that you just uploaded, and click Finish.

15.  Once Team Project creation is complete, create a new Test Work Item Type by selecting the Team | Add Work Item | Test menu option.

16.  Graphically this Work Item won't differ much from a Task, but the Test Type drop-down is an immediate visual difference.

17.  Also, try to change the State of this Work Item. You'll notice that you can't make a change until it has been first saved in the Active state. Once that's been done, then you can advance it only to the Complete state. Note too that the Reasons available for the transition are those that were specified in the Work Item's definition.

Show: