Walkthrough: Make Advanced Customizations to a Work Item Type

Article
11/16/2012

In this walkthrough, you will make more complex customizations to the work item type that you modified in Walkthrough: Make Basic Customizations to a Work Item Type.

In the following procedures, you will work with several features including dependent pick lists, user pick lists, and rules that are scoped to users and to groups.

Set Default Values. In this procedure, you first assign a default value to a field of a work item type. Then, you create a work item of that type, in which you see the default value in that field.
Create a Dependent Pick List. In this procedure, you create a rule that bases the allowed values of one field on the value of another field.
Make String Fields Match Patterns. In this procedure, you define a pattern that the values used in a field can match.
Customize the Assigned To Field. In this procedure, you limit the values of a field to certain users.
Define Rules based on Groups. In this procedure, you apply a rule to a specific field.
Use Global Lists. In this procedure, you create and populate a global list, so that you can share its values between work item types or across team projects.
Customize a Field Label. In this procedure, you change the label of a field.

Prerequisites

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

If you can establish a connection to a server that is running Visual Studio Team System Team Foundation Server and have the appropriate permissions, you can make advanced customizations to 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.

Set Default Values

Prerequisite: You have completed the "Change the Form Layout" procedure in Walkthrough: Make Basic Customizations to a Work Item Type.

To set default values

In Visual Studio, open the file that contains the Special Task work item type definition. This file is called specialtask.xml.

If specialtask.xml is not still open from your working in Walkthrough: Make Basic Customizations to a Work Item Type, open it by:
1. Click File, point to Open, and then click File.
2. In the Open File dialog box, under Look in, move to the location where you exported the file.
  
  If you are modifying a work item type 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 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.
3. When you are prompted about line endings, click No.
Find the <FIELDS> section of the XML file. In the file is the Category field.

Set the default value for the Category field by adding the DEFAULT 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>
        <ALLOWEDVALUES>
            <LISTITEM value="Process Management" />
            <LISTITEM value="Planning" />
            <LISTITEM value="Execution" />
            <LISTITEM value="Review" />
        </ALLOWEDVALUES>
    <DEFAULT from="value" value="Execution" />
</FIELD>

On the toolbar, click Save to save changes to the XML file.
Import the changed Special Task work item type into the 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

Note

This assumes that you have access to the WITLab project that you created in the "Create a Team Project" procedure in Walkthrough: Make Basic Customizations to a Work Item Type. If you no longer have access to that project, use the name of a different team project in this and subsequent witimport commands in this walkthrough.

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

Work item type import complete.
In the Team Explorer window in Visual Studio, click Refresh to download the latest updates from the server.

These updates include the changes that you just imported. Wait several seconds until all the nodes are loaded. Nodes that are still loading are labeled "working."
Create a new 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.
Notice that the Category field now uses the specified value.

Note

DEFAULT rules come into effect only if the targeted field is empty. Default rules do not cause existing values to be overwritten. COPY rules can be used to copy values into fields and overwrite existing values. For XML that illustrates the COPY rule, see the "Change the Workflow" procedure in Walkthrough: Make Basic Customizations to a Work Item Type. The example also illustrates how to dynamically copy values from the current user's account name instead of from a static value.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.

Create a Dependent Pick List

Prerequisite: You have completed the Set Default Values procedure.

To create a dependent 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. Within this section is the Category field.

To set the allowed values for the Category field to depend on the value of the Discipline field, add the WHEN and WHENNOT group of elements, 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>
  <WHEN field="Microsoft.VSTS.Common.Discipline" value="Requirements"> 
    <ALLOWEDVALUES> 
      <LISTITEM value="Planning" /> 
      <LISTITEM value="Review" /> 
    </ALLOWEDVALUES> 
  </WHEN> 
  <WHENNOT field="Microsoft.VSTS.Common.Discipline" value="Requirements">
    <ALLOWEDVALUES>
      <LISTITEM value="Process Management" />
      <LISTITEM value="Planning" />
      <LISTITEM value="Execution" />
      <LISTITEM value="Review" />
    </ALLOWEDVALUES>
  </WHENNOT>
<DEFAULT from="value" value="Execution" />
</FIELD>

Note

The WHEN and WHENNOT rules used in this example can be applied also to other rules to specify when those rules should be evaluated.

From this Category field, delete the DEFAULT rule toward the end of the following sample. You can delete it because the allowed values for the Category field now depend on the Discipline field.

<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="Requirements">
    <ALLOWEDVALUES>
      <LISTITEM value="Planning" />
      <LISTITEM value="Review" />
    </ALLOWEDVALUES>
  </WHEN>
  <WHENNOT field="Microsoft.VSTS.Common.Discipline" value="Requirements">
    <ALLOWEDVALUES>
      <LISTITEM value="Process Management" />
      <LISTITEM value="Planning" />
      <LISTITEM value="Execution" />
      <LISTITEM value="Review" />
    </ALLOWEDVALUES>
  </WHENNOT>
<DEFAULT from="value" value="Execution" />
</FIELD>

On the toolbar, click Save to save changes to the XML file.
Import the changed Special Task work item type into the 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 the Team Foundation Server. The following is displayed when the import operation finishes:

Work item type import complete.
In the Team Explorer window in Visual Studio, click Refresh to download the latest updates from the server.

These updates include the changes that you just imported. Wait several seconds until the Work Items node is loaded. Nodes that are still loading are labeled "working."
Create a new 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.
Select the Category field to see its box values.
Select Requirements in the Discipline field, click the Details tab, and then select the Category field to see how its box values change.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.

Make String Fields Match Patterns

Prerequisite: You have completed the Create a Dependent Pick List procedure.

To make string fields match patterns

Open the file that contains the Special Task work item type definition. To do this, in Visual Studio, click the tab labeled specialtask.xml.
In the <WORKITEMTYPE> section, find the <FIELDS> section of the XML file.

Add the following XML shown in bold text to add a Version field that tracks the version of the product to which this Task applies.

<FIELDS>
<FIELD name="Version" refname="MyCompany.MyProcess.Version" type="String"> 
  <HELPTEXT>The version of the product to which this task is related.</HELPTEXT> 
</FIELD>

Add the MATCH element to make sure that all Version values start with the letter v followed by two digits, a period, two more digits, another period, a letter, and then any character.

<FIELDS>
    <FIELD name="Version" refname="MyCompany.MyProcess.Version" type="String">
    <HELPTEXT>The version of the product to which this task is related.</HELPTEXT>
    <MATCH pattern="vNN.NN.AX"/>
</FIELD>

Find the <TabGroup> section of the XML file. Within this section, the following lines define controls. Add the Control element that has the Label="Version" to display the Version field on the work item form.

<Column PercentWidth="100">
  <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Issue" Label="Issue" LabelPosition="Left" />
  <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.ExitCriteria" Label="Exit Criteria" LabelPosition="Left" />
  <Control Type="FieldControl" FieldName="Microsoft.VSTS.Build.IntegrationBuild" Label="Integration Build" LabelPosition="Left" />
  <Control Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.TaskHierarchy" Label="Task Context" LabelPosition="Left" ReadOnly="True" />
  <Control Type="FieldControl" FieldName="MyCompany.MyProcess.Version" Label="Version" LabelPosition="Left" />
</Column>

On the toolbar, click Save to save changes to the XML file.
Import the changed Special Task work item type into the 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 the Team Foundation Server. The following is displayed when the import operation finishes:

Work item type import complete.
In the Team Explorer window in Visual Studio, click Refresh to download the latest updates from the server.

These updates include the changes that you just imported. Wait several seconds until the Work Items node is loaded. Nodes that are still loading are labeled "working."
Create a new 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 Details tab. Type different values into the Version field to see which values are allowed. The field is highlighted when it contains an illegal value.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.

Customize the Assigned To Field

Prerequisite: You have completed the Make String Fields Match Patterns procedure.

To customize the Assigned To field

Create a new Special Task work item. To do this, right-click the Work Items node, point to Add Work Item, and then click Special Task.
Click the down arrow of the Assigned To box.

Notice that the list of allowed values includes all users registered with the Team Foundation Server.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.
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 that describes the Assigned To field. Notice the VALIDUSER rule that allows any registered user on the Team Foundation Server as a field value.
```
<FIELDS>
<FIELD name="Assigned To" refname="System.AssignedTo" type="String" reportable="dimension">
  <HELPTEXT>The person assigned to do the work</HELPTEXT>
  <VALIDUSER />
</FIELD>
```

Delete the VALIDUSER rule from the FIELD definition for the Assigned To field.

<FIELDS>
<FIELD name="Assigned To" refname="System.AssignedTo" type="String" reportable="dimension">
  <HELPTEXT>The person assigned to do the work</HELPTEXT>
  <VALIDUSER />
</FIELD>

Add the ALLOWEDVALUES group of elements, as in the following sample. This limits the values of the Assigned To field to the members of the team project’s Contributors group and a special value to mark Special Tasks for triage.
```
<FIELDS>
<FIELD name="Assigned To" refname="System.AssignedTo" type="String" reportable="dimension">
  <HELPTEXT>The person assigned to do the work</HELPTEXT>
  <ALLOWEDVALUES expanditems="true"> 
      <LISTITEM value="[Project]\Contributors" /> 
      <LISTITEM value="Triage" /> 
  </ALLOWEDVALUES>
</FIELD>
```
Note

To show only the Contributors group without all its members in the Assigned To allowed values list, set the expanditems attribute of the <ALLOWEDVALUES> element to "false."
On the toolbar, click Save to save changes to the XML file.
Import the changed Special Task work item type into the 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 the Team Foundation Server. The following displays when the import operation finishes:

Work item type import complete.
In the Team Explorer window in Visual Studio, click Refresh to download the latest updates from the server.

These updates include the changes that you just imported. Wait several seconds until the Work Items node is loaded. Nodes that are still loading are labeled "working."
Create a new 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.
Select the Assigned To box. Notice that the list of allowed values has changed to include the group of users and values that you specified.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.

Define Rules based on Groups

Prerequisite: You have completed the Customize the Assigned To Field procedure.

To define rules based on groups

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 <WORKFLOW> section of the XML file. Within this section are the following lines that describe the Active state.

<STATE value="Active">
  <FIELDS>
    <FIELD refname="Microsoft.VSTS.Common.ClosedDate">
      <EMPTY />
    </FIELD>
    <FIELD refname="Microsoft.VSTS.Common.ClosedBy">
      <EMPTY />
    </FIELD>
  </FIELDS>
</STATE>

Add the following XML to make the Assigned To field required for Project Administrators who edit Special Tasks in the Active state.

<STATE value="Active">
  <FIELDS>
    <FIELD refname="System.AssignedTo"> 
      <REQUIRED for="[Project]\Project Administrators" not="[Global]\Team Foundation Administrators" /> 
    </FIELD>
    <FIELD refname="Microsoft.VSTS.Common.ClosedDate">
      <EMPTY />
    </FIELD>
    <FIELD refname="Microsoft.VSTS.Common.ClosedBy">
      <EMPTY />
    </FIELD>
  </FIELDS>
</STATE>

Note

The for and not attributes can be applied to many other rules.

On the toolbar, click Save to save changes to the XML file.
Import the changed Special Task work item type into the 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 the Team Foundation Server. The following is displayed when the import operation finishes:

Work item type import complete.
In the Team Explorer window in Visual Studio, click Refresh to download the latest updates from the server.

These updates include the changes that you just imported. Wait several seconds until all the nodes are loaded. Nodes that are still loading are labeled "working."
Create a new 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.
Fill in the Title field and then click Save to save the work item.

An error displays stating that the Assigned To field contains an unsupported value.
Select the Assigned To field and delete its contents, and then click Save.
Set the State field to Active.

Notice that the Assigned To field is highlighted now because you are a member of the Project Administrators group.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.

Use Global Lists

Prerequisite: You have completed the Scope Rules to Groups procedure.

To use global lists

In Visual Studio, click File, and then New File.
In the Categories pane, click General.
In the Templates pane, click XML File, and then click Open.

To this new file, add the XML tags, as in the following sample. This defines a global list of disciplines that are relevant to your organization.

<?xml version="1.0" encoding="utf-8"?>
<gl:GLOBALLISTS xmlns:gl="https://schemas.microsoft.com/VisualStudio/2005/workitemtracking/globallists">
    <GLOBALLIST name="Disciplines">
        <LISTITEM value="Architecture" />
        <LISTITEM value="Requirements" />
        <LISTITEM value="Development" />
        <LISTITEM value="Release Management" />
        <LISTITEM value="Project Management" />
        <LISTITEM value="Test" />
    </GLOBALLIST> 
</gl:GLOBALLISTS>

On the toolbar, click Save to save changes to the XML file.

The Save File As dialog box is displayed.
Select the location where you want to save the file, type disciplines.xml in the File name field, and then click Save.
Import this global list onto the Team Foundation Server by typing the following command and then pressing ENTER:

glimport /f "File Path\disciplines.xml" /t "Team Foundation Server name"

Note

Because a global list has global effect on the Team Foundation Server, you do not specify a team project when you run the glimport command.
Display the global lists on the Team Foundation Server by typing the following at the command prompt and then pressing ENTER:

glexport /t "Team Foundation Server name"

Notice that the newly added list is displayed.
In Visual Studio, open the file that contains the Special Task work item type definition. To do this, click the tab labeled specialtask.xml.

Find the following section of the XML file that defines the Discipline field.

<FIELD name="Discipline" refname="Microsoft.VSTS.Common.Discipline" type="String" reportable="dimension">
  <HELPTEXT>The discipline to which the task belongs</HELPTEXT>
  <ALLOWEDVALUES expanditems="true">
    <LISTITEM value="Development" />
    <LISTITEM value="Test" />
    <LISTITEM value="Project Management" />
    <LISTITEM value="Requirements" />
    <LISTITEM value="Architecture" />
    <LISTITEM value="Release Management" />
  </ALLOWEDVALUES>
</FIELD>

Delete the ALLOWEDVALUES and LISTITEM elements from the XML definition for the Discipline field.

<FIELD name="Discipline" refname="Microsoft.VSTS.Common.Discipline" type="String">
  <HELPTEXT>The discipline to which the task belongs</HELPTEXT>
  <ALLOWEDVALUES expanditems="true"> 
    <LISTITEM value="Development" /> 
    <LISTITEM value="Test" /> 
    <LISTITEM value="Project Management" /> 
    <LISTITEM value="Requirements" /> 
    <LISTITEM value="Architecture" /> 
    <LISTITEM value="Release Management" /> 
  </ALLOWEDVALUES>
</FIELD>

To set the allowed values of the Discipline field to the global list that you defined previously, add the ALLOWEDVALUES and GLOBALLIST elements to the file.

<FIELD name="Discipline" refname="Microsoft.VSTS.Common.Discipline" type="String">
  <HELPTEXT>The discipline to which the task belongs</HELPTEXT>
  <ALLOWEDVALUES> 
    <GLOBALLIST name="Disciplines" /> 
  </ALLOWEDVALUES>
</FIELD>

On the toolbar, click Save to save changes to the XML file.
Import the changed Special Task work item type into the 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 the Team Foundation Server. The following is displayed when the import operation finishes:

Work item type import complete.
In the Team Explorer window in Visual Studio, click Refresh to download the latest updates from the server.

These updates include the changes that you just imported. Wait several seconds until all the nodes are loaded. Nodes that are still loading are labeled "working."
Create a new 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.
Select the Discipline box on the new work item form.

Note that the allowed values are now populated from the global "Disciplines" list.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.

Add values to the Discipline field without editing and re-importing the work item type definition file specialtask.xml. To do this, first click the disciplines.xml tab in Visual Studio to add three LISTITEM elements and values, as in the following sample.

<GLOBALLIST name="Disciplines">
  <LISTITEM value="Architecture" />
  <LISTITEM value="Requirements" />
  <LISTITEM value="Development" />
  <LISTITEM value="Release Management" />
  <LISTITEM value="Project Management" />
  <LISTITEM value="Test" />
  <LISTITEM value="Marketing and Sales" /> 
  <LISTITEM value="General Management" /> 
  <LISTITEM value="Other" />
</GLOBALLIST>

On the toolbar, click Save to save changes to the XML file.
To import this global list into Team Foundation Server, type the following at the command prompt, and then press ENTER.

glimport /f "File Path\disciplines.xml" /t "Team Foundation Server name"
In the Team Explorer window in Visual Studio, click Refresh to download the latest updates from the server.

These updates include the changes that you just imported. Wait several seconds until all the nodes are loaded. Nodes that are still loading are labeled "working."
Create a new 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.
Select the Discipline box.

Notice that the new values in the global list now appear as choices in the box.

Note

You can reference global lists for allowed values that are shared between several work item types or across team projects. This enables a single update to the global list to automatically update the allowed values of all work item types that refer to the list.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.

Customize a Field Label

Prerequisite: You have completed the Use Global Lists procedure.

To customize a field label

Open the file that contains the Special Task work item type definition. To do this, in Visual Studio, click the tab labeled specialtask.xml.

In the <FORM> and then <Layout> sections, find the definition of the Title field.

<Column PercentWidth="70">
  <Control Type="FieldControl" FieldName="System.Title" Label="Title" LabelPosition="Left" />
</Column>

Change the label for the field so that the Portuguese branch office working on this particular team project can read the name of the Title field when they work with the work item form. Modify the XML, as in the following sample, by adding the Portuguese word for "Title" to the field label in parentheses.
```
<Column PercentWidth="70">
  <Control Type="FieldControl" FieldName="System.Title" Label="Title (Título):" LabelPosition="Left" />
</Column>
```
On the toolbar, click Save to save changes to the XML file.
Import the changed Special Task work item type into the 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 the Team Foundation Server. The following displays when the import operation finishes:

Work item type import complete.
In the Team Explorer window in Visual Studio, click Refresh to download the latest updates from the server.

These updates include the changes that you just imported. Wait several seconds until all the nodes are loaded. Nodes that are still loading are labeled "working."
Create a new 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.

Notice the new parenthetical Portuguese label for the Title field.
Click Close to close the new Special Task. Click No when you are prompted to save the work item.
Right-click the Work Items node again and select Add Query to create a new query.
Click the area labeled Click here to add a clause to add a new row.
Select the blank Field cell.
Type Title into the cell.
Press ENTER.

Notice that the Title field still appears without the Portuguese label in the query grid and results list column.

Note

Customizing the label is useful for making isolated changes to a specific team project’s work item forms as it affects neither other team projects, nor results list column labels, nor query grid, as shown in the last few steps. These labels are shared across the Team Foundation Server and are derived from the fields’ names. See the "Renaming Fields" Task in the "Administering Fields" Walkthrough for information about how to author server-wide field renames.
Click Close to close the new Query. Click No when you are prompted to save the query.

Next Steps

For step-by-step instructions in making additional customizations of a work item type, see Walkthrough: Administer Fields in a Work Item Type.

Change History

Date	History	Reason
June 2010	Revised references to bold text for content that is not bold.	Customer feedback.
June 2010	Changed the global list schema reference to point to 2005 (<gl:GLOBALLISTS xmlns:gl="https://schemas.microsoft.com/VisualStudio/2005/workitemtracking/globallists">).	Customer feedback.