Add and Customize a Type of Work Item
You can add and customize types of work items for use with your specific team project. With each type of work item, you can add fields, states and transitions, and change the form layout. For each field defined for the type, you can add rules and define allowed values.
In this walkthrough, as you modify each component of the type, you import your changes into the team project and verify the changes by opening a new work item of that type.
Topic Contents
Perform the following procedures to add and customize a type of work item:
Create a Team Project Named WITLab
View the Work Item Form for the Task Type
Export the Task Type
Copy and Rename Task Type to Special Task Type
Import the Special Task Type and Check Your Changes
Add a New Field Named Category to the Special Task Type
Add Rules to the Category Field
Create a Pick List for the Category Field
Change the Workflow for the Special Task Type
Change the Form Layout for the Special Task Type
Prerequisites
To complete the steps in this walkthrough, the following conditions must be met:
You must have a copy of Visual Studio that has Team Explorer installed and have a connection to Team Foundation Server. For more information, see Connect to Team Projects in Team Foundation Server.
If you can establish a connection to a Team Foundation Server and have the appropriate permissions set, you can make basic customizations to a work item type at a command prompt, batch file, or script file.
Required Permissions
To perform this procedure, you must be a member of the Team Foundation Administrators group or a member of the Project Administrators group for the project. For more information, see Team Foundation Server Permissions.
Create a Team Project Named WITLab
To create a team project
Start Visual Studio.
In Visual Studio, on the Tools menu, click Connect to Team Foundation Server.
Note
If you do not see this option, you have not installed Team Explorer. You must install Team Explorer before you will have the option to connect to Team Foundation Server.
In the Connect to Team Project dialog box, select from the Team Foundation Server list a server that is running Team Foundation Server.
In the Connect to Team Project dialog box, select from the Team Foundation Server list the server that contains the team project collection to which you want to add your team project.
Note
If the drop-down list is empty, click the Servers button to manually enter the server connection settings. Contact your Team Foundation administrator or team project administrator to obtain the connection settings.
Click the name of the project collection to which you want to add your team project from the Directory list.
Click Connect.
On the File menu, click New Team Project.
Note
If you are not using the Project Management environment settings, then on the File menu, point to New, and then click Team Project.
The New Team Project wizard appears.
Note
If you have not connected to a Team Foundation Server, you will be prompted to connect to one now. Review steps 2 through 6.
On the Specify the Team Project Settings page, under What is the name of the team project?, type WITLab, and then click Next.
On the Select a Process Template page, under Which process template should be used to create the team project?, click MSF for Agile Software Development - <version number>, and then click Finish.
Creating the team project may take several minutes.
When the Team Project Created page appears, clear the Launch the Process Guidance box, and then click Close.
The new team project named "WITLab," appears as a node in Team Explorer.
View the Work Item Form for the Task Type
Prerequisites: You must have completed Create a Team Project Named WITLab. The "WITLab" team project appears in a node in Team Explorer.
To view a work item form
Start Visual Studio and open Team Explorer.
In Team Explorer, expand the WITLab team project, and wait several seconds for its folders to load.
In the team project, right-click the Work Items node, point to Add Work Item, and then click Task.
A form that represents a new Task work item appears. Some of its fields contain default values. Later in this topic you can customize the Task work item type from which this work item was created.
Export the Task Type
Prerequisite: You must have completed Create a Team Project Named WITLab. The "WITLab" team project appears in a node in Team Explorer.
To export a work item type
Open a Visual Studio command prompt.
At the command prompt, type the following command and then press ENTER:
witadmin exportwitd /collection:http://ServerName:Port/VirtualDirectoryName/CollectionName**/p:WITLab /n:Task/f:"File Path\task.xml"**
This exports the Task work item type from Team Foundation Server to the task.xml file to the folder that you specify for File Path. The following appears when the export operation finishes:
Work item type export complete.
(Optional) To view the XML definition for the Task work item type, type "File Path**\ task.xml"** at the command prompt and then press ENTER.
Copy and Rename Task Type to Special Task Type
Prerequisite: You must have completed the Export the Task Type procedure.
To copy and rename the type
In Visual Studio, click File, and then click Open File.
This displays the Open File dialog box.
Under Look in, move to the location where you exported the file.
If you are modifying a type of work item to customize a process template, move to the location where you downloaded the process template.
Note
If you are running Windows Vista you might not have permissions set to certain folders. If you try to export the work item type to a location where you do not have permissions set, the registry virtualization technology automatically redirects the exported file and saves it to the virtual store. To avoid this redirection, you can export the file to a location where you have permissions set. For more information about registry virtualization, see the Microsoft Web site: Registry Virtualization and Common file and registry virtualization issues in Windows Vista.
Click the task.xml file and then click Open. When you are prompted about line endings, click No.
This opens task.xml, the XML file that contains the definition for the Task work item type.
Locate the following element in the XML file.
<WORKITEMTYPE name="Task">Change the value of the name attribute to Special Task.
<WORKITEMTYPE name="Special Task">Save your change to a new XML file. To do this, on the Visual Studio File menu, click Save task.xml As.
The Save File As dialog box displays.
For File name, type specialtask.xml, and then click Save.
Import the Special Task Type and Check Your Changes
Prerequisite: You must have completed the Copy and Rename the Task Type to Special Task Type procedure.
To import the new type
Open a Visual Studio command prompt.
Import the Special Task type into Team Foundation Server. To do this, at a Visual Studio command prompt, type the following command and then press ENTER:
witadmin importwitd /collection:http://ServerName:Port/VirtualDirectoryName/CollectionName**/p:WITLab /f:"File Path\specialtask.xml"**
This imports the Special Task type into the WitLab project on Team Foundation Server. The following appears when the import operation finishes:
Work item type import complete.
In Team Explorer, select your team project, and then on the View menu, click Refresh to download the latest updates from the server.
These updates include the new Special Task type that you just imported. Wait several seconds until all the nodes are loaded. Nodes that are still loading display the word working.
Create a Special Task work item. To do this, right-click the Work Items node, point to Add Work Item, and then click Special Task.
This work item is created from the work item type that you changed and imported.
Add a New Field Named Category to the Special Task Type
Prerequisite: You must have completed the Copy and Rename the Task Type to Special Task Type procedure.
To add a field
Open the file that contains the Special Task work item type definition. To do this, in Visual Studio, click the tab labeled SpecialTask.xml.
Find the following section of the XML file:
<FIELDS>To create a string field that is named Category and Help text for a tooltip, type FIELD and HELPTEXT elements, as in the following sample:
<FIELDS> <FIELD name="Category" refname="MyCompany.MyProcess.Category" type="String"> <HELPTEXT>Describes the category to which this special task belongs.</HELPTEXT> </FIELD>Note
The Reference Name, or refname, is the programmatic name for the field. All other rules should refer to this refname. For more information, see Naming Conventions for Work Item Tracking Objects.
Find the section of the XML file that describes the work item form.
<FORM>Find the following lines in the <FORM> section:
<Group Label="Classification"> <Column PercentWidth="100"> <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area" LabelPosition="Left" /> <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="Iteration" LabelPosition="Left" /> </Column> </Group>To insert a control to display the Category field, type the Control element with Type="FieldControl" following the control for System.IterationPath, as in the following sample:
<Group Label="Classification"> <Column PercentWidth="100"> <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area" LabelPosition="Left" /> <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="Iteration" LabelPosition="Left" /> <Control Type="FieldControl" FieldName="MyCompany.MyProcess.Category" Label="Category" LabelPosition="Left" /> </Column> </Group>On the File menu, click Save to save changes to the XML file.
Import the changed Special Task type into Team Foundation Server. To do this, repeat the steps provided in the procedure: Import the Special Task Type and Check Your Changes.
Notice the new Category field on the form. Move the mouse pointer over the label of the field to see the tool tip.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.
Add Rules to the Category Field
Prerequisite: You must have completed the Add a New Field Named Category procedure.
To add rules to a field
Open the file that contains the Special Task work item type definition. To do this, in Visual Studio, click the tab labeled SpecialTask.xml.
Find the <FIELDS> section of the XML file, and in it, the Category field.
To make Category a required field, add the REQUIRED element, as in the following sample:
<FIELD name="Category" refname="MyCompany.MyProcess.Category" type="String" reportable="dimension"> <HELPTEXT>Describes the category to which this special task belongs.</HELPTEXT> <REQUIRED /> </FIELD>On the File menu, click the Save to save changes to the XML file.
Import the changed Special Task work item type into Team Foundation Server. To do this, repeat the steps provided in the procedure earlier in this topic: Import the Special Task Type and Check Your Changes.
witadmin importwitd /collection:http://ServerName:Port/VirtualDirectoryName/CollectionName**/p:WITLab /f:"File Path\specialtask.xml"**
The Category field is now highlighted, indicating that it is required.
Select the Title field on the Special Task work item and type "Sample Task."
On the toolbar, click Save to save the work item.
An error dialog box appears that states that the Category field cannot be empty. Click OK to close the dialog box.
In the Category field on the Special Task work item, type A category.
Click Save to save the work item.
The option to save the work item is now available.
Click Close to close the new Special Task.
Create a Pick List for the Category Field
Prerequisite: You must have completed the Add Rules to the Category Field procedure.
To create a pick list
Open the file that contains the Special Task work item type definition. To do this, in Visual Studio, click the tab labeled SpecialTask.xml.
Find the <FIELDS> section of the XML file, and in it, the Category field.
To add a list of allowed values for the Category field, insert the ALLOWEDVALUES element and a LISTITEM child element for each allowed value.
<FIELD name="Category" refname="MyCompany.MyProcess.Category" type="String" reportable="dimension"> <HELPTEXT>Describes the category to which this special task belongs.</HELPTEXT> <REQUIRED /> <ALLOWEDVALUES> <LISTITEM value="Process Management" /> <LISTITEM value="Planning" /> <LISTITEM value="Execution" /> <LISTITEM value="Review" /> </ALLOWEDVALUES> </FIELD>To make Category an optional field, delete the REQUIRED element listed above the ALLOWEDVALUES element.
<FIELD name="Category" refname="MyCompany.MyProcess.Category" type="String" reportable="dimension"> <HELPTEXT>Describes the category to which this special task belongs.</HELPTEXT> <REQUIRED /> <ALLOWEDVALUES> <LISTITEM value="Process Management" /> <LISTITEM value="Planning" /> <LISTITEM value="Execution" /> <LISTITEM value="Review" /> </ALLOWEDVALUES> </FIELD>Click Save to save changes to the XML file.
Import the changed Special Task work item type into Team Foundation Server. To do this, repeat the steps provided in the procedure earlier in this topic: Import the Special Task Type and Check Your Changes.
Create a Special Task work item. To do this, right-click the Work Items node, point to Add Work Item, and then click Special Task.
This work item is created from the work item type that you changed and imported.
Click the list box for the Category field.
Notice that the field now supports only the values specified by the ALLOWEDVALUES rules.
Note
The allowed values in the drop-list always appear in alphabetical order regardless of the order of the LISTITEM elements in the XML file.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.
Change the Workflow for the Special Task Type
Prerequisite: You must have completed the Create a Pick List for the Category Field procedure.
To change the workflow
Open the file that contains the Special Task work item type definition. To do this, in Visual Studio, click the tab labeled SpecialTask.xml.
Find the definition of the work item type’s workflow, in the <WORKFLOW> section of the XML file, as shown in the following XML:
<WORKFLOW> <STATES> <STATE value="Active"> <FIELDS> <FIELD refname="Microsoft.VSTS.Common.ClosedDate"> <EMPTY /> </FIELD> <FIELD refname="Microsoft.VSTS.Common.ClosedBy"> ...Notice that only two states are defined- Active and Closed. The transitions between these states are also defined, in addition to an opening transition from the null state that is used when the work item is created.
To add an Unapproved state to the type definition, insert another STATE element above the active state.
<WORKFLOW> <STATES> <STATE value="Unapproved"> </STATE> <STATE value="Active"> <FIELDS> <FIELD refname="Microsoft.VSTS.Common.ClosedDate"> <EMPTY /> </FIELD> <FIELD refname="Microsoft.VSTS.Common.ClosedBy"> ...Create a transition between the null state and the unapproved state. To do this, find the section of the workflow definition for transitions. Then, insert a TRANSITION element for the unassigned state to the Unapproved state. Because of this change, all new work items of this type will start in the Unapproved state with the default reason of New.
<TRANSITIONS> <TRANSITION from="" to="Unapproved"> <REASONS> <DEFAULTREASON value="New" /> </REASONS> </TRANSITION> <TRANSITION from="" to="Active"> <REASONS> <DEFAULTREASON value="New" /> </REASONS> <FIELDS> <FIELD refname="Microsoft.VSTS.Common.ActivatedBy"> <COPY from="currentuser" /> </FIELD> <FIELD refname="Microsoft.VSTS.Common.ActivatedDate"> <COPY from="clock" /> </FIELD> <FIELD refname="System.AssignedTo"> <COPY from="currentuser" /> </FIELD> </FIELDS> </TRANSITION>Delete the TRANSITION element for unassigned to Active and all its child elements, which appear in the following sample. Perform this step because there can only be one opening transition, and you will want to use an opening transition called "Ported," which you will define in the following step.
<TRANSITIONS> <TRANSITION from="" to="Unapproved"> <REASONS> <DEFAULTREASON value="New" /> </REASONS> </TRANSITION> <TRANSITION from="" to="Active"> <REASONS> <DEFAULTREASON value="New" /> </REASONS> <FIELDS> <FIELD refname="Microsoft.VSTS.Common.ActivatedBy"> <COPY from="currentuser" /> </FIELD> <FIELD refname="Microsoft.VSTS.Common.ActivatedDate"> <COPY from="clock" /> </FIELD> <FIELD refname="System.AssignedTo"> <COPY from="currentuser" /> </FIELD> </FIELDS> </TRANSITION>Add a "Ported" reason for the opening transition by inserting a REASON element following the default reason. If you make this change, users can verify whether a work item is new or was ported from another tracking system.
<TRANSITIONS> <TRANSITION from="" to="Unapproved"> <REASONS> <DEFAULTREASON value="New" /> <REASON value="Ported" /> </REASONS> </TRANSITION> ...Insert the COPY rule in the following sample. This rule makes the name of the user who created the work item the default value of the Assigned To field, and this rule can be evaluated only during the opening transition.
<TRANSITIONS> <TRANSITION from="" to="Unapproved"> <REASONS> <DEFAULTREASON value="New" /> <REASON value="Ported" /> </REASONS> <FIELDS> <FIELD refname="System.AssignedTo"> <COPY from="currentuser" /> </FIELD> </FIELDS> </TRANSITION> ...Note
Inserting this rule under other <TRANSITION> or <STATE> elements will scope the rule to other Transitions or States.
To create a transition from the Unapproved state to the Active state, insert the TRANSITION element and its child elements, as in the following sample. Because of this change, when a Special Task is approved, it can undergo this transition.
<TRANSITIONS> <TRANSITION from="" to="Unapproved"> <REASONS> <DEFAULTREASON value="New" /> <REASON value="Ported" /> </REASONS> <FIELDS> <FIELD refname="System.AssignedTo"> <COPY from="currentuser" /> </FIELD> </FIELDS> </TRANSITION> <TRANSITION from="Unapproved" to="Active"> <REASONS> <DEFAULTREASON value="Approved" /> </REASONS> </TRANSITION> <TRANSITION from="Active" to="Closed"> <REASONS> <DEFAULTREASON value="Completed" /> <REASON value="Deferred" /> <REASON value="Obsolete" /> <REASON value="Cut" /> </REASONS> ...Click Save to save changes to the XML file.
Import the changed Special Task work item type into Team Foundation Server. To do this, repeat the steps provided in the procedure: Import the Special Task Type and Check Your Changes.
Notice that the initial State is now Unapproved and that the Reason defaults to New. Additionally, the Assigned To value defaults to your account name. Click the Reason field to see a list box that lists the reasons New and Ported.
In the Title field, type a title, and then click Save to save the work item. Wait until the save operation finishes, as indicated by Item(s) Saved on the status bar.
In the State field, select the Active value to approve the work item and transition it again. Notice that the Reason field defaults to Approved.
Click Save to save this transition.
Click Close to close the Special Task.
Change the Form Layout for the Special Task Type
Prerequisite: You must have completed the Change the Workflow for the Special Task Type procedure.
To change the form layout
Open the file that contains the Special Task work item type definition. To do this, in Visual Studio, click the tab labeled SpecialTask.xml.
Find the <TabGroup> section of the XML file. Notice that there are <Tab> elements for Links and File Attachments in which each <Tab>element contains a <Control> element that renders the respective control.
<Tab Label="Links"> <Control Type="LinksControl" /> </Tab> <Tab Label="File Attachments"> <Control Type="AttachmentsControl" /> </Tab>Merge the two <Tab> elements into a single Links and Attachments <Tab> element that contains both controls by replacing the XML shown in the previous step with the new XML that follows.
<Tab Label="Links and Attachments"> <Control Type="LinksControl" Label="Links" LabelPosition="Top" /> <Control Type="AttachmentsControl" Label="Attachments" LabelPosition="Top" /> </Tab>Find the section of the <FORM>, <Layout> definition that describes the Classification and Status groups.
<Group Label="Classification"> <Column PercentWidth="100"> <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area" LabelPosition="Left" /> <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="Iteration" LabelPosition="Left" /> <Control Type="FieldControl" FieldName="MyCompany.MyProcess.Category" Label="Category" LabelPosition="Left" /> </Column> </Group>Note
For best results, every Control or Group should display in a Column even if the Column spans the full width of the form. In turn, every Column should display in a Group even if the Group has no visible label or boundary.
Select the CONTROL element lines in the following sample, and then on the Edit menu, click Copy to copy this content to the Clipboard for later use.
<Column PercentWidth="70"> <Group> <Column PercentWidth="100"> <Group Label="Classification"> <Column PercentWidth="100"> <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area" LabelPosition="Left" /> <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="Iteration" LabelPosition="Left" /> <Control Type="FieldControl" FieldName="MyCompany.MyProcess.Category" Label="Category" LabelPosition="Left" /> </Column> </Group>To remove the Classification group from its current position on the form, delete the following lines from the sample: from <Group Label="Classification"> to </Group>.
<Layout> <Group> <Column PercentWidth="70"> <Control Type="FieldControl" FieldName="System.Title" Label="&Title:" LabelPosition="Left" /> </Column> <Column PercentWidth="30"> <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Discipline" Label="&Discipline:" LabelPosition="Left" /> </Column> </Group> <Group Label="Classification"> <Column PercentWidth="100"> <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="&Area:" LabelPosition="Left" /> <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="&Iteration:" LabelPosition="Left" /> <Control Type="FieldControl" FieldName="MyCompany.MyProcess.Category" Label="Category" LabelPosition="Left" /> </Column> </Group>In the <TabGroup> section, find the following lines that define the Details tab:
<Tab Label="Details"> <Group> <Column PercentWidth="50"> <Group Label="General"> <Column PercentWidth="100"> <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Issue" Label="Iss&ue:" LabelPosition="Left" /> <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.ExitCriteria" Label="E&xit criteria:" LabelPosition="Left" /> <Control Type="FieldControl" FieldName="Microsoft.VSTS.Build.IntegrationBuild" Label="Integration &build:" LabelPosition="Left" /> </Column> </Group> </Column> <Column PercentWidth="50"> <Group Label="Schedule"> <Column PercentWidth="100"> <Control Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.RemainingWork" Label="Remaining &work (hours):" LabelPosition="Left" /> <Control Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.CompletedWork" Label="Com&pleted work (hours):" LabelPosition="Left" /> </Column> </Group> </Column> </Group> </Tab>To move these controls to the Details tab, paste the contents of your Clipboard after the <Tab Label="Details"> element.
<Tab Label="Details"> <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area" LabelPosition="Left" /> <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="Iteration" LabelPosition="Left" /> <Control Type="FieldControl" FieldName="MyCompany.MyProcess.Category" Label="Category" LabelPosition="Left" /> <Group> <Column PercentWidth="50"> <Group> <Column PercentWidth="100"> <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Issue" Label="Issue" LabelPosition="Left" /> ...To create a grouping around the moved fields and to divide the fields into two columns, add the Group and Column elements, as in the following sample,:
<Tab Label="Details"> <Group Label="Classification"> <Column PercentWidth="50"> <Group> <Column PercentWidth="100"> <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area" LabelPosition="Left" /> <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="Iteration" LabelPosition="Left" /> </Column> </Group> </Column> <Column PercentWidth="50"> <Group> <Column PercentWidth="100"> <Control Type="FieldControl" FieldName="MyCompany.MyProcess.Category" Label="Category" LabelPosition="Left" /> </Column> </Group> </Column> </Group> <Group> <Column PercentWidth="50"> <Group> <Column PercentWidth="100"> <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Issue" Label="Issue" LabelPosition="Left" /> ...Click Save to save changes to the XML file.
Import the changed Special Task work item type into Team Foundation Server. To do this, repeat the steps provided in the procedure: Import the Special Task Type and Check Your Changes.
Notice that the Classification group is no longer on the main form. Click the Links and Attachments tab and the Details tab to see the results of the changes that you made.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.
See Also
Concepts
Customize Project Tracking Data, Forms, Workflow, and Other Objects