Manage global lists for work item types
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018 - TFS 2013
Important
For the On-premises XML process model, you can use witadmin to list, import, export, and modify a process for a project. For the Inherited and Hosted XML process models, you can only use witadmin to list and export process information. For an overview of process models and what is supported, see Customize your work tracking experience.
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 project collection, they can be included in work item types for all projects within the collection.
Note
The Hosted XML process model supports adding and updating global lists. To learn more, see Process template customizations differences.
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 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 GLOBALLIST XML element reference.
How to run the witadmin command-line tool
To run the witadmin command-line tool, open a Command Prompt window where Visual Studio is installed. The witadmin command-line tool installs with any version of Visual Studio. You can access this tool by installing the free version of Visual Studio Community or Visual Studio Team Explorer.
Note
If you are connecting to an on-premises server, you must use the same or later version of Visual Studio or Team Explorer as Azure DevOps Server. For example, if you connect to a TFS 2017 instance, you must connect from Visual Studio 2017 or Team Explorer 2017. There is no Team Explorer 2015 version.
Visual Studio 2017 or Team Explorer 2017 client:
%programfiles(x86)%\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer
or, TeamExplorer, Professional or Enterprise in place of Community, depending on the version you've installed.
On a 32-bit edition of Windows, replace %programfiles(x86)% with %programfiles%. You can install Visual Studio Community (which provides access to Team Explorer) or Visual Studio Team Explorer 2017 for free.
Tip
With witadmin, you can import and export definition files. Other tools you can use include the Process Editor (requires that you have installed a version of Visual Studio). Install the TFS Process Template editor from the Visual Studio Marketplace. You can use this version of the Process Editor to modify the old-style work item forms. You can't use it to edit forms associated with the new web forms.
Or, you can use the TFS Team Project Manager, an open-source client available from GitHub.
Prerequisites
For the 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 import global lists, you must be a member of the Project Collection Administrators security group.
- To destroy a global list using witadmin destroygloballist, you must be a member of the Project Collection Administrators security group.
Note
Even if you sign in with administrative permissions, you must open an elevated Command Prompt window to perform this function on a server that is running Windows Server 2008. To open an elevated Command Prompt window, choose Start, open the Command Prompt shortcut window, and choose Run as Administrator. For more information, see this page on the Microsoft Web site: User Access Control.
Syntax
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
| Parameter | Description |
|---|---|
/collection:CollectionURL |
Specifies the URI of the project collection. For example: On-premises TFS format: http://ServerName:Port/VirtualDirectoryName/CollectionName If no virtual directory is used, then the format for the URI is the following: http://ServerName:Port/CollectionName. |
/n:GlobalListName |
The name of the global list to destroy. |
/f:FileName |
The path and the name of the global list XML definition file to export or import. Note: If the client computer runs Windows Vista, you might not have permissions to certain folders. If you try to export the global list to a location where you do not have permissions, the registry virtualization technology automatically redirects the exported file and saves it to the virtual store. For more information, see the Registry Virtualization page on the Microsoft Web site. To avoid this redirection, you can export the file to a location where you have permissions. |
/e:Encoding |
The name of a .NET Framework 2.0 encoding format. The specified encoding will be used to export or import the XML data. For example, /e utf-7 specifies Unicode (UTF-7) encoding. If you omit this parameter, witadmin attempts to detect the encoding, and if detection fails, witadmin uses UTF-8. |
| /noprompt | Disables the prompt for confirmation. |
| /? or help | Displays help about the command in the Command Prompt window. |
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="http://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>
Don't include project-scoped security groups within a global list, because global lists are scoped to a collection and not a project.
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 Import, export, and manage work item types.
Examples
Unless otherwise specified, the following values apply in each example:
- URI for the 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