Inside TFS

Work Item Customization: Working With Global Lists

How to use global lists in work item type definitions.

• By Mickey Gousset
• 10/21/2011

In a previous column, we looked at how to add a new field, called "Cost Center", to an existing work item type definition (WITD) in Team Foundation Server 2010. In that column, we made the field a string field, which in turn was generated as a simple text box on the form. This time, we're going to turn that field into a dropdown list box, while examining how lists work both locally in a WITD, as well as globally, using global lists.

Creating a Dropdown List Box

A field that can only contain certain values should be made a dropdown list box on the work item. First, we need to export the Task WITD from TFS. We do this using the witadmin.exe command-line tool, as shown before:

Witadmin exportwitd /collection:http://localhost:8080/tfs
/p:"Tailspin Toys" /n:Task /f:Task.xml

This takes the latest WITD for the task work item and stores it in the Task.xml file. Open the Task.xml file in your favorite text editor, and navigate to the field definition for Cost Center:

<FIELD name="Cost Center" refname="Contoso.CostCenter" 
  type="String" reportable="dimension">
  <HELPTEXT>Cost Center to be billed for this task</HELPTEXT>

  <REQUIRED />

  </FIELD>

Turning a field into a dropdown list box is relatively easy; we just need to provide a list of possible values for the field. This is done by specifying an ALLOWEDVALUES tag. Let's take a look at the new field definition for Cost Center:

 <FIELD name="Cost Center" refname="Contoso.CostCenter"
    type="String" reportable="dimension">
    <HELPTEXT>Cost Center to be billed for this task</HELPTEXT>

    <ALLOWEDVALUES expanditems="true">

       <LISTITEM value="001">

       <LISTITEM value="002">

       <LISTITEM value="003">

    </ALLOWEDVALUES>

      <REQUIRED />

</FIELD>

Notice the addition of the ALLOWEDVALUES section. This section specifies to what values the Cost Center field may be set. Setting these values limits the field to only contain those values. This automatically turns the field into a dropdown list box on the form -- no other changes are necessary to the WITD. To verify this change, import the new WITD into TFS:

Witadmin importwitd  /collection:http://localhost:8080/tfs 
/p:"Tailspin Toys" /f:Task.xml

Now open Team Explorer, refresh the Tailspin Toys team project, and open a new Task work item. As shown in Figure 1, the Cost Center field is now a dropdown list box, containing only the values that we specified in the WITD.

[Click on image for larger view.]

Figure 1. Cost Center is now a dropdown list box.

The same change can also be made using the Process Editor, found in the Team Foundation Power Tools. Open the Task WITD using the Process Editor. The Task WITD opens as a tab in Visual Studio 2010. On the Fields tab, select Cost Center and click the Edit button to open the Field Definition window for the Cost Center field. On the Field definition window, select the Rules tab. Select the ALLOWEDVALUES rule and click the Edit button to open the ALLOWEDVALUES window, shown in Figure 2.

[Click on image for larger view.]

Figure 2. The ALLOWEDVALUES window for the Cost Center field.

Figure 2 shows the list of allowed values for this field. Click the New button to add new values, Edit to modify existing values, or Delete to remove values from the list. Save your changes and reimport the WITD to see the changes made to the Cost Center list.

Working with Global Lists

Adding items to fields in the above method works well, but it does have one drawback: adding the Cost Center field to every work item type in the team project involves adding the Cost Center field, and the list of potential values, to every WITD. Adding a new Cost Center to our organization in the future means modifying every WITD that contains the Cost Center field, to update its allowed values list.

It makes more sense in this scenario to create one list that can be shared by multiple work items. This is accomplished using a Global List. A Global List is a list of potential values for a field that can be accessed by multiple work item types. Global Lists exist at the Team Project Collection level, so they can be accessed by multiple WITDS in multiple team projects in the same Team Project collection.

To create a new Global List containing Cost Center values, create a new XML file named GlobalList.xml, open it in a text editor, and add the following:

 <GLOBALLISTS>

  <GLOBALLIST  name="CostCenterGlobalList">

   <LISTITEM value="001" />

   <LISTITEM value="002" />

   <LISTITEM value="003" />

  </GLOBALLIST>

  </GLOBALLISTS>

This defines a new global list named CostCenterGlobalList, with three values. This Global List can be imported using the following command line:

Witadmin  importgloballists /collection:http://localhost:8080/tfs /f:GlobalList.xml

This imports the list into the default team project collection.

With the Global List imported, the next step is to modify the Task WITD to use this Global List for the Cost Center field. In the Cost Center field definition, change the ALLOWEDVALUES tag to the following:

 <ALLOWEDVALUES expanditems="true">

       <GLOBALLIST  name="CostCenterGlobalList" />

 </ALLOWEDVALUES>

This specifies that the list of allowed values for the Cost Center field should be pulled from the CostCenterGlobalList Global List. If we import the modified Task WITD and create a new Task, the Cost Center field will now use the items specified in the Global List.

We can now add the Cost Center field to multiple WITDs. All the Cost Center fields will use the same Global List; if we need to add new Cost Centers, all we have to do is export the Global List, add the new values, import the new Global List, and all the Cost Center fields in all the work item types will begin using the new values.