Walkthrough: Administer Fields in a Work Item Type

Article
09/24/2007

In this walkthrough, you will view, rename, and delete fields used by work item types on a Team Foundation Server. Fields can span many work item types across team projects.

This section contains the following procedures:

View Fields In this procedure, you output and then view the fields of a work item type.
Rename Fields In this procedure, you change the name of a field, and see where the change appears on the form.
Delete Fields In this procedure, you delete a field that you added to the work item form in a previous procedure.

Prerequisites

Complete the steps in Walkthrough: Make Basic Customizations to a Work Item Type and Walkthrough: Make Advanced Customizations to a Work Item Type.

If you can establish a connection to a Team Foundation Server and have the appropriate permissions, you can administer fields in a work item type at a command prompt, batch file, or script file. To do this, you must either use the Visual Studio 2008 Command Prompt utility or set several environment variables in your current command prompt by using vsvars32 as described in the following example. For more information about joining a team project, see Walkthrough: Joining a Team Project.

To enable Team Foundation commands at a command prompt

Click Start, click All Programs, point to Microsoft Visual Studio 2008, point to Visual Studio Tools, and then click Visual Studio 2008 Command Prompt.

Alternatively, you can run vsvars32 in the Visual Studio installation path that is usually DriveLetter:\Program Files\Microsoft Visual Studio 9.0\Common7\Tools.

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.

View Fields

To view fields

Open a Visual Studio command prompt.
Output all the fields defined on the Team Foundation Server to a text file by typing the following at the command prompt and then pressing ENTER.

witfields view /s:" Team Foundation Server name "

This displays the list of fields and includes the following information:

Field:	The field's reference name.
Name:	The field's friendly name.
Type:	The field's data type.
Reportable As:	The field's reporting settings.
Use:	The team projects that use this field and the work item types in which the field appears.

Rename Fields

To rename fields

At the Visual Studio command prompt, type the following, and then pressing ENTER.

witfields rename /s:" Team Foundation Server name " Microsoft.VSTS.Common.Rank Importance

This command renames the Rank field to Importance.
At the confirmation prompt type y and then press ENTER. Wait until you receive the following message:

Field renamed.
In the Team Explorer window in Visual Studio, click Refresh to download the latest updates from the server.

Wait several seconds until all the nodes are loaded. Nodes that are still loading display working.
Right-click the Work Items node, and then select Add Query to create a new query.
Click the area labeled Click here to add a clause to add a new row. Then select the blank Field cell. Type Rank into the cell. Notice the following message that appears above the results list. This message indicates that the Rank cannot be found.

Run the query to see the query results. TF51005: The query references a field that does not exist. The error is caused by <<Rank>>.
Delete the value Rank from the Field cell, and type Importance into the cell.
Select <> in the Operator cell, and type 1 into the Value cell.
From the Team menu, click Run Query.
Right-click any row in the results and select Column Options. Scroll down in the Available columns list. Note that the Rank field is no longer present but the Importance field is present.
Select Importance in the Available columns box and then click the add selected columns button, (>). Click OK.

Notice that the friendly name for Microsoft.VSTS.Common.Rank has been renamed from Rank to Importance throughout the query builder and results list.
Click Close to close the query. Click No when you are prompted to save the query.
Create a new Special Task work item. To do this, right-click the Work Items node, point to Add Work Item, and then click SpecialTask.

This work item is created from the work item type that you changed and imported.
Notice, in the Status box, that the label for the renamed field, Rank, has not changed. This is because the field labels on the work item forms are scoped to the parent team project and are independent of the server-wide field name just specified.

Note

See the "Customize a Field Label" procedure in Walkthrough: Make Advanced Customizations to a Work Item Type for more information about how to change field labels on work item forms.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.

Delete Fields

Prerequisite: You have completed the "Add a Field" procedure in Walkthrough: Make Basic Customizations to a Work Item Type.

To delete fields

Try to delete the Category field that was added in the Add a Field procedure. To do this, type the following at the Visual Studio command prompt, and then press ENTER.

witfields delete /s:" Team Foundation Server name " MyCompany.MyProcess.Category

The error message returned states that the field cannot be deleted because it is being used by a team project.
Type the following command and then press ENTER.

witexport /f " File Path \specialtask.xml" /t " Team Foundation Server name " /p WITLab /n "SpecialTask"

This re-exports to an XML file the Special Task work item type definition from Team Foundation Server that includes the new definition of the Microsoft.VSTS.Common.Rank field that uses its new friendly name after it was renamed in the Rename Fields procedure.

Note

If you are running Windows Vista, you might not have access rights to certain folders. If you try to export the work item type to a location where you do not have access rights, the registry virtualization technology automatically redirects the exported file and saves it to the virtual store. For more information, see https://go.microsoft.com/fwlink/?LinkId=92325 and https://go.microsoft.com/fwlink/?LinkId=92323. To avoid this redirection, you can export the file to a location where you have access rights.

You receive the following message when the export operation finishes:

Work item type export complete.
In Visual Studio, click File, point to Open, and then click File.

This displays the Open File dialog box.

Note

If SpecialTask.xml is open, you may receive a message asking you if you want to reload the file in Visual Studio. Click Yes to reload it.
Under Look in, move to the location where you exported the file.
Click the specialtask.xml file, and then click Open.
Click No if you are prompted about line endings.

Find and delete the definition of the Category field, shown in the following XML:

                <FIELD name="Category" refname="MyCompany.MyProcess.Category" type="String" reportable="dimension">
<HELPTEXT>Describes the category to which this special task belongs.</HELPTEXT>
  <WHEN field="Microsoft.VSTS.Common.Discipline" value="Business Analyst">
    <ALLOWEDVALUES>
      <LISTITEM value="Planning" />
      <LISTITEM value="Review" />
    </ALLOWEDVALUES>
  </WHEN>
  <WHENNOT field="Microsoft.VSTS.Common.Discipline" value="Business Analyst">
    <ALLOWEDVALUES>
      <LISTITEM value="Process Management" />
      <LISTITEM value="Planning" />
      <LISTITEM value="Execution" />
      <LISTITEM value="Review" />
    </ALLOWEDVALUES>
  </WHENNOT>
</FIELD>

In the <Layout> section, find the following XML, and delete the highlighted sections to remove the field:

<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>

Click Save to save changes to the XML file.
Import the changed Special Task work item type into Team Foundation Server. To do this, at a Visual Studio command prompt, type the following and then press ENTER:

witimport /f " File Path \specialtask.xml" /t " Team Foundation Server name " /p WITLab

This imports the specialtask work item type into Team Foundation Server. You receive the following message when the import operation finishes:

Work item type import complete.
Verify that the Category field is no longer being used by any work item types by typing the following at the command prompt, and then pressing ENTER.

witfields view /s:" Team Foundation Server name " MyCompany.MyProcess.Category

The witfields tool shows that Category is “Not In Use.”

Field: MyCompany.MyProcess.Category

Name: Category

Type: String

Reportable As: dimension

Use: Not In Use
Now that the Category field is no longer used by any work item types, delete the field permanently from Team Foundation Server by typing the following text at the command prompt, and then pressing ENTER. Enter y at the confirmation prompt to complete this step.

witfields delete /s:" Team Foundation Server name " MyCompany.MyProcess.Category

Walkthrough: Administer Fields in a Work Item Type

Prerequisites

To enable Team Foundation commands at a command prompt

View Fields

To view fields

Rename Fields

To rename fields

Delete Fields

To delete fields

See Also

Tasks

Other Resources

Additional resources