Manage Global Lists for Work Item Types

Global lists are pick lists that you can include in one or more fields and types of work items. Use them to minimize the work that is required to update a list that is shared by multiple types of work items. Because global lists are defined for a team project collection, they can be included in work item types for all team projects within the collection.

You can define a global list within its own definition file, in the definition file for a type of work item, or in global workflow. The global-list definition manages the global lists that are defined for a collection. The global-list definition uses the following commands in the witadmin command-line tool:

• destroygloballist:  Destroys a global list.

• exportgloballist:  Exports the global lists to an XML file, or to the Command Prompt window. It exports a single file, which contains all global lists that have been defined for the team project collection.

• importgloballist:  Imports global lists from an XML file. If you try to import a global list that already exists on the server, a warning asks if you want to overwrite the global list that is on the server. If you try to import a global list that does not already exist, the command creates a new global list.

• listgloballist:  Displays the name of each global list defined on the server.

See Define Global Lists and Customize Global Workflow.

To run the witadmin command-line tool, open a Command Prompt window where either Visual Studio or Team Explorer is installed and enter:

cd %programfiles%\Microsoft Visual Studio 11.0\Common7\IDE

On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%.

Requirements

For the team project collection where the global lists are defined, you must have the following permissions set:

• To export or list global lists, you must be a member of the Project Collection Valid Users group or have your View collection-level information permission set to Allow

• To destroy or import global lists, you must be a member of the Team Foundation Administrators security group or the Project Administrators security group.

See Team Foundation Server Permissions and Team Foundation Server Default Groups, Permissions, and Roles.

witadmin destroygloballist /collection:CollectionURL /n:GlobalListName [/noprompt] [/force]

witadmin exportgloballist /collection:CollectionURL [/f:FileName] [/e:Encoding] 

witadmin importgloballist /collection:CollectionURL /f:FileName [/e:Encoding]

witadmin listgloballist /collection:CollectionURL

Parameters

Remarks

Importing a global list creates a list if one does not exist. If the list already exists, the witadmin importgloballist command will warn you that the current list will be overwritten. You can write your own program to update an existing global list, or you can update the global list yourself with the new data.

To create a new global list, start with the following code and modify it as needed. This example defines a global list of disciplines that you can assign to tasks.

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

To add a global list to a field, export the definition for the work item type that contains the field and add it to the field definition, as shown in the following example:

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

To view the changes, import the type definition and refresh your browser or client cache. You might need to close any work items that reference the field and reopen them.

For information about export and import of type definitions, see Customize and Manage Work Item Types [witadmin].

Examples

Unless otherwise specified, the following values apply in each example:

• URI for the team project collection: http://AdventureWorksServer:8080/tfs/DefaultCollection

• Server Web site port number: 8080

Display the names of global lists

The following example shows the global lists defined on the server. The example exports the global lists using the default UTF-8 encoding:

witadmin listgloballist /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection 

Export the definition of global lists

The following example exports the global lists:

witadmin exportgloballist /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /f:C:mygloballists.xml

The following example exports the same global lists to the same server, but uses Unicode (UTF-7) encoding:

witadmin exportgloballist /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /f:C:mygloballists.xml /e:utf-7

Import the definition of global lists

The following example imports global lists:

witadmin importgloballist /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /f:C:mygloballists.xml 

The following example imports the same global lists to the same server, but uses Unicode (UTF-7) encoding:

witadmin importgloballist /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /f:C:mygloballists.xml /e utf-7

See Also

Concepts

Define Global Lists

Other Resources

Customize Global Workflow

witAdmin: Customize and Manage Objects for Tracking Work Items