How to: Use a Global List

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 may find that some fields share the same set of values. Frequently this set of values is across several work item types and even across several team projects. Some of these lists may frequently change; such as the build number of nightly builds. Requiring an administrator to update these lists in many locations on a frequent basis is not ideal. Global lists help solve this problem. Global lists must not include project-scoped groups because global lists do not have the same scope as a project.

The following procedures tell 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. 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. For more information, see Team Foundation Server Permissions.

To use Team Foundation commands at the command prompt

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

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

    Note

    You must have Microsoft Visual Studio 2005 installed to use the Visual Studio 2005 Command Prompt.

To add a global list to your Team Foundation Server

  1. In Visual Studio, click File, click New, and then click File.

  2. In the Categories pane, click General.

  3. In the Templates pane, click XML File, and then click Open.

  4. 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>
    
  5. On the toolbar, click Save to save changes to the XML file.

    The Save File As dialog box is displayed.

    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 access rights to certain folders. If you try to save the global list to a location where you do not have access rights, the registry virtualization technology automatically redirects the 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 save the file to a location where you have access rights.

  6. Open a Visual Studio Command Prompt window.

  7. Import this global list onto the Team Foundation Server by typing the following command, and then pressing ENTER:

    glimport /f " File Path " /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. For more information, see glimport.

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

To use global lists in a work item type

  1. Run witexport to export Task.xml. For more information, see How to: Export a Work Item Type from an Existing Project.

  2. In Visual Studio, click File, click Open, and then click File.

    This displays the Open File dialog box.

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

  4. Select Task.xml, and then click Open. When you are prompted about line endings, click No.

  5. 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>
    
  6. 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>
    
  7. 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>
    
  8. On the toolbar, click Save to save changes to the XML file.

  9. Import the changed task into Team Foundation Server. For more information, see How to: Import a Work Item Type to an Existing Project.

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

  11. Create a new 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.

  12. Select the Discipline box on the new work item form.

    Notice that the allowed values are now populated from the global Disciplines list.

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

  1. To add values to the Discipline field without editing and re-importing the work item type definition file, open the disciplines.xml file using Visual Studio and add the following new values, as shown 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>
    
  2. On the toolbar, click Save to save changes to the XML file.

  3. Open a Visual Studio Command Prompt window.

  4. Import this global list onto the Team Foundation Server by typing the following at the command prompt, and then pressing ENTER.

    glimport /f " File Path " /t " Team Foundation Server name "

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

  6. Create a new task. To do this, right-click the Work Items node, point to Add Work Item, and then click Task.

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

  8. Click Close to close the new task. Click No when you are prompted to save the task.

See Also

Reference

GLOBALLISTS Element (Global Lists Schema)
GLOBALLISTS Element (Work Item Type Definition Schema)

Concepts

Global Lists

Other Resources

Work Item Type Definition Schema