Defining and Customizing Objects for Tracking Work Items By Using the Work Item Tracking Plug-in

By using the plug-in for tracking work items, you define a team project's initial objects for tracking work. These objects include types of work items, work item queries, categories, link types, global lists, and instances of work items. After you create a team project, you can modify these objects by using the witadmin command-line tool.

In the plug-in file, you specify one or more tasks and their dependencies. In general, you specify one task for each major upload activity, such as link types, work item types, queries, and categories.

Important

You must specify the tasks to upload files and define queries in a specific sequence: link types first, then work item types, and then queries. Each definition file for these objects depends on the definitions that are specified in the tasks that precede them. In general, you should maintain the task sequence that is defined in the process template that you are customizing. For more information, see Defining Dependencies for Task Groups and Tasks in Plug-in Files.

In this topic

• Work Item Tracking Plug-in Name and Location

• Work Item Tracking Plug-in Syntax Structure

• Element Reference for the WorkItemTracking Plug-in

For specific information about each type of object that you can define, see one of the following topics:

• Add Type Definitions for Work Items to a Process Template

• Add Type Definitions for Work Item Links to a Process Template

• Add Type Definitions for Work Item Categories to a Process Template

• Add Work Item Queries to a Process Template

• Add a Work Item Instance to a Process Template

Work Item Tracking Plug-in Name and Location

The following table summarizes the name and location of the file for the process templates for Microsoft Solutions Framework (MSF), in addition to the name of the plug-in.

File name:	WorkItems.xml
File location:	WorkItem Tracking folder
Plug-in name:	Microsoft.ProjectCreationWizard.WorkItemTracking

Note

You can change the name and location of the XML file but not the name of the plug-in. Visual Studio Team Foundation Server does not include a mechanism for the deployment of client-side plug-ins, policies, or other modifications. If you want to deploy this kind of functionality, you must use your own distribution and installation program.

Back to top

Work Item Tracking Plug-in Syntax Structure

The plug-in file for work item tracking must conform to the schema definition that is defined in the WorkItemMethodology.xsd file, and the plug-in must be specified in its own file. You can download the schema files for process templates from the following page on the Microsoft website: Process Template and Work Item Schemas for Visual Studio Team Foundation.

The following syntax shows the high-level structure of the WorkItemTracking plug-in. Four tasks are specified, one each to upload the definitions for link types, types of work items, queries, and categories. If you were to add definitions for work item instances, you would specify an additional task for each.

For a description of each element, see Element Reference for the WorkItemTracking Plug-in later in this topic.

<?xml version="1.0" encoding="utf-8"?>
<tasks>
  <task id="LinkTypes" name="LinkType definitions" plugin="Microsoft.ProjectCreationWizard.WorkItemTracking" completionMessage="Work item link types created">
    <taskXml>
      <LINKTYPES>
        <LINKTYPE />
   . . . 
      </LINKTYPES>
    </taskXml>
  </task>
  <task id="WITs" name="WorkItemType definitions" plugin="Microsoft.ProjectCreationWizard.WorkItemTracking" completionMessage="Work item types created">
    <dependencies>
      <dependency taskId="LinkTypes" />
    </dependencies>
    <taskXml>
      <WORKITEMTYPES>
        <WORKITEMTYPE />
   . . . 
      </WORKITEMTYPES>
    </taskXml>
  </task>
  <task id="Queries" name="Stored Query Definitions" plugin="Microsoft.ProjectCreationWizard.WorkItemTracking" completionMessage="Work item queries uploaded">
    <dependencies>
      <dependency taskId="WITs" />
    </dependencies>
    <taskXml>
      <QUERIES>
        <Permission />
   . . . 
        <QueryFolder >
          <Query />
   . . . 
        </QueryFolder>
   . . . 
      </QUERIES>
    </taskXml>
  </task>
  <task id="Categories" name="Categories definitions" plugin="Microsoft.ProjectCreationWizard.WorkItemTracking" completionMessage="Work item type categories created">
    <dependencies>
      <dependency taskId="WITs" />
    </dependencies>
    <taskXml>
      <CATEGORIES fileName="WorkItem Tracking\Categories.xml" />
    </taskXml>
  </task>
</tasks>

Back to top

Element Reference for the WorkItemTracking Plug-in

The following table describes the elements that you use to upload work item tracking objects. You specify these elements within a taskXml container element in the WorkItemTracking plug-in file. For information about the task, dependency, and taskXml elements, see Defining the Tasks to Process a Plug-in.

Element	Syntax	Description
CATEGORIES	<CATEGORIES fileName="CategoriesFilePathName" />	Optional child element of the taskXml element for the WorkItemTracking plug-in. Specifies the path and name of the file that contains the category definitions to be uploaded when the WorkItemTracking plug-in task is processed.
FIELD	<FIELD refname="FieldReferenceName" value="Value" />	Required child element of WI. Defines a value for a field in the work item instance.
GLOBALLISTS	<GLOBALLISTS fileName="GlobalListFilePathName" />	Optional child element of the taskXml element for the WorkItemTracking plug-in. Specifies the path and name of the file that contains the definitions for global lists to be uploaded when the WorkItemTracking plug-in task is processed.
HYPERLINK	<HYPERLINK URL="URL" relativePath="false" />	Optional child element of WI. Defines a hyperlink for the work item instance.
LINKTYPE	<LINKTYPE fileName="LinkTypeFilePathName" />	Required child element of LINKTYPES. Specifies the path and name of a file that contains a link type definition to upload.
LINKTYPES	<LINKTYPES>    <LINKTYPE />  . . . </LINKTYPES>	Optional child element of the taskXml element for the WorkItemTracking plug-in. Contains a collection of LINKTYPE elements that each specify a definition file to upload.
Permission	<permission allow="ListOfPermissions" identity="GroupName" />	Optional child element of Query. Specifies the default permissions that are assigned to team queries. For more information, see Assigning Permissions for Work Item Queries.
Query	<Query name="QueryName" fileName="QueryFilePathName" />	Required child element of QUERIES. Specifies the name and the path of the .wiq file that defines a query to upload.
QueryFolder	<QueryFolder name=" FolderName ">	Optional child element of QUERIES. Specifies the name of a query folder.
QUERIES	<QUERIES> . . . </QUERIES>	Optional child element of the taskXml element for the WorkItemTracking plug-in. Specifies which query definition files to use to create default queries.
WI	<WI type="WorkItemType">    <FIELD> . . .</FIELD>    <HYPERLINK> . . .</HYPERLINK> </WI>	Required child element of WORKITEMS. Defines a type of work item to create and the values to assign to specific fields.
WORKITEMS	WORKITEMS>    <WI>       <FIELD> . . .</FIELD>       <HYPERLINK> . . .</HYPERLINK>    </WI> </WORKITEMS >	Optional child element of the taskXml element for the WorkItemTracking plug-in. Contains a collection of WI elements that each define a work item instance.
WORKITEMTYPE	<WORKITEMTYPE fileName="WITFilePathName" />	Required child element of WORKITEMTYPES. Specifies the path and name of the file that contains a type definition to upload.
WORKITEMTYPES	<WORKITEMTYPES>    <WORKITEMTYPE />  . . . </WORKITEMTYPES>	Required child element of the WorkItemTracking plug-in. Contains a collection of WORKITEMTYPE elements that each specify a definition file to upload.

Back to top

See Also

Tasks

Verify Work Item Type Definition Changes

Concepts

Customizing Process Templates

Step-by-Step Customization Process

Customizing Project Tracking Data, Forms, Workflow, and Other Objects

Working with Process Template Files

Customizing Functional Areas within a Process Template

Change History

Date	History	Reason
August 2012	Removed reference to adding global lists to a process template. This function is not supported.	Content bug fix.
April 2011	Added element reference section and links to individual topics that address each type of tracking object. Removed links to deleted topics.	Information enhancement.