Define global lists

By using global lists in Team Foundation Server (TFS), you can minimize the work that is required to update a list that multiple types of work items share. Global lists are pick lists that you can include within one or more fields and types of work item. You can define a global list within a work item type that you add to a team project, as a global list for a team project collection, or within a global workflow. You can share list items among multiple types of work items for a collection by including the list items in one or more GLOBALLIST elements.

As you define types of work items, you might find that some fields share the same values. Frequently, you can share across several types of work items and even across several team projects. Some of these values, such as the build number of nightly builds, change frequently, which requires an administrator to frequently update these lists in many locations. Global lists can be especially useful when a list must be derived from an external system. For example, suppose a company maintains a separate customer database. When you file a bug that a customer discovered, the customer's name is entered into a custom Found By Customer field.

You can manage global lists for a collection as an XML file that you can list, import, export, and delete. The name of each global list can have up to 254 Unicode characters and must be unique within a collection.

Note Note

There are no system-defined global lists, nor predefined global lists in the default process templates that TFS provides.

Note Note

To add or modify a global list, use the witadmin command-line tool to import and export the definition for global lists. See Manage global lists for work item types [witadmin]. To use a global list, add it to the FIELD definition within a work item type. See All FIELD XML elements reference.

A global list is a set of LISTITEM elements that is stored and used globally by all team projects in a collection. Global lists are useful for fields that are defined within several types of work items, such as Operating System, Found in Build, and Fixed in Build.

You can define global lists and their items by using one of the following methods:

  • Process template: You can define global lists within the definition for a work item type in a process template. Each team project that is created from that template has access to the global lists.

  • Team project collection: You can export, modify, delete, and import the global lists that are defined for a team project collection. These global lists are available to all team projects in the collection.

  • Work item type definition: After a team project is created, you can add the global lists that you want to have available for a type of work item to its definition.

  • Global workflow definition: After a team project is created, you can add the global lists that you want to have available for all types of work items to the global workflow definition for a team project or collection. For more information, see Customize global workflow .

The following table describes the GLOBALLIST and LISTITEM elements. You can use these elements to enumerate a list of values that is presented to the user as a pick list or drop-down menu of items.

Element

Syntax

Description

GLOBALLIST

<GLOBALLIST name="globalListName">
    <LISTITEM> . . . </LISTITEM>
</GLOBALLIST>
 

Defines a set of LISTITEM elements that is stored for a collection and that all team projects in a collection can use.

globalListName: A string of text that contains between 1 and 255 characters.

GLOBALLIST is a required child element of the GLOBALLISTS element and an optional child element of the ALLOWEDVALUES, SUGGESTEDVALUES, and PROHIBITEDVALUES elements. For more information, see Define pick lists.

LISTITEM

<LISTITEM value="Name" />

Defines a valid list value.

Note Note

Global lists must not include project-scoped groups because they are not scoped to a project.

LISTITEM is a required child element of GLOBALLIST and an optional child element of the ALLOWEDVALUES, SUGGESTEDVALUES, and PROHIBITEDVALUES elements.

By adding the following syntax, you can define a global list within an XML definition file for a type of work item or a global workflow:

<GLOBALLISTS>
    <GLOBALLIST name="name of global list">
        <LISTITEM value="List item 1" />
        <LISTITEM value="List item 2" />
        <LISTITEM value="List item 3" />
        <LISTITEM value="List item 4" />
        . . .
        <LISTITEM value="List item n" />
    </GLOBALLIST>
</GLOBALLISTS>

By using the following syntax, you can reference a global list within an XML definition file for a type of work item:

<GLOBALLISTS>
   <GLOBALLIST name=" name of global list 1" />
   <GLOBALLIST name=" name of global list 2" />
   . . .
   <GLOBALLIST name=" name of global list n" />
</GLOBALLISTS>

For information about the structure and location of definition files for types of work items or global workflow, see All WITD XML elements reference or Global Workflow XML Element Reference, respectively.

To add a global list to a project collection, you can import the following syntax by using the witadmin importgloballist command:

<gl:GLOBALLISTS xmlns:gl="http://schemas.microsoft.com/VisualStudio/2008/workitemtracking/globallists">
    <GLOBALLIST name="NameOfGlobalList">
        <LISTITEM value="ListItem1" />
        <LISTITEM value="ListItem2" />
        <LISTITEM value="ListItem3" />
        <LISTITEM value="ListItem4" />
        . . .
        <LISTITEM value="ListItemN" />
    </GLOBALLIST>
</gl:GLOBALLISTS>

A global list cannot be empty. Each GLOBALLIST element must have at least one LISTITEM element defined.

A: Yes. The global list named Builds – TeamProjectName gets appended each time a build is run. Over time, the list can become very long. Best practice is to routinely remove unused items from the list.

To learn more about using this list, see Fields that support integration with test, build, and version control.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft