Add, Use, and Manage Global Lists

Article
02/04/2013

You can share list items among multiple work item types by including them within one or more GLOBALLIST elements.

As you define work item types, you might find that some fields share the same set of values. Frequently, this set of values spans across several work item types and even across several team projects. Some of these lists may change frequently, such as the build number of nightly builds, which requires an administrator to update these lists in many locations often. Global lists help solve this problem.

Note

Global lists must not include project-scoped groups because global lists do not have the same scope as a project. Global lists are managed for a project collection.

The following procedures show you how to create a global list named Disciplines for the task work item type.

Required Permissions

To export a global list, you must be a member of the Team Foundation Valid Users group for the project collection. To import a global list, you must be a member of the Team Foundation Administrators group or a member of the Project Administrators group for the project collection. For more information, see Team Foundation Server Permissions.

To add a global list to your team project collection

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

To this new file, add the following XML, shown as highlighted in the following example. This example defines a global list of disciplines 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 the changes to the XML file.

The Save File As dialog box appears.
In the Save File As dialog box, under Save in, browse to the location where you want to save the file. Name the file and then click Save.

Note

If you are running Windows Vista you might not have permissions set to access 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.
Open a Visual Studio 2010 Command Prompt window.
Import this global list to the project collection by typing the following command, and then pressing Enter:

witadmin importgloballist /collection:http://ServerName:Port/VirtualDirectoryName/CollectionName /f:"File Path"

For more information, see Managing Global Lists for Work Item Types [witadmin].
Display the global lists on the Team Foundation Server by typing the following at the command prompt, and then pressing Enter:

witadmin exportgloballist /collection:http://ServerName:Port/VirtualDirectoryName/CollectionName

Notice that the newly added list is displayed.

To use global lists in a work item type

Run witadmin exportwitd to export Task.xml. For more information, see Customizing and Managing Work Item Types [witadmin].
In Visual Studio, click File, click Open, and then click 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 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 may not have access permissions set to access 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.
Select Task.xml, and then click Open. When you are prompted about line endings, click No.

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 list of allowed values by removing the following XML, shown as highlighted in the following example:

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

Set the allowed values of the Discipline field to the global list that you defined previously, by adding the following XML 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 the changes to the XML file.
Import the changed task into Team Foundation Server. For more information, see Customizing and Managing Work Item Types [witadmin]..
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 load. Nodes that are still loading are labeled working.
Create a task. To do this, right-click the Work Items node, point to Add Work Item, and then click Task.

This task is created from the work item type that you changed and imported.
Select the Discipline box on the new work item form.

Notice that the allowed values are now populated from the global Disciplines list.
Click Close to close the new task. Click No when you are prompted to save the task.

To add values to a field without editing and importing a work item type XML file

To add values to the Discipline field without editing and re-importing the work item type definition file, open the disciplines.xml file by using Visual Studio and add the following new values, shown as highlighted in the following example:

<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 the changes to the XML file.
Open a Visual Studio Command Prompt window.
Import this global list to the project collection by typing the following at the command prompt, and then pressing Enter:

witadmin importgloballist /collection:http://ServerName:Port/VirtualDirectoryName/CollectionName /f:"File Path"
In Team Explorer, 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 load. Nodes that are still loading are labeled working.
Create a task. To do this, right-click the Work Items node, point to Add Work Item, and then click Task.
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 among 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 task. Click No when you are prompted to save the task.

Add, Use, and Manage Global Lists

To add a global list to your team project collection

To use global lists in a work item type

To add values to a field without editing and importing a work item type XML file

See Also

Concepts

Other Resources

Additional resources