Import and export process configuration [witadmin]

You customize the process configuration to modify the display of the product backlog, task board, and portfolio backlog pages. You view these pages through Team Web Access (TWA). You can change the quick add panel, change the workflow state-to-metastate mappings, add a portfolio backlog, and more. For an overview of how to customize these pages, see Configure and customize Agile planning tools for a team project.

Note Note

If you receive error message TF400917, an invalid configuration has occurred in TWA. Re-import the process configuration file to your team project using witadmin importcommonprocessconfig. You’ll get the messages you need to resolve the error.

To manage the process configuration for a team project, use the witadmin command line tool to export and import the process configuration XML definition file. To learn about process configuration, see Process configuration XML element reference.

Process for customizing a WIT object
  • exportprocessconfig:  Exports the process configuration definition to an XML file or the Command Prompt window.

  • importprocessconfig:  Imports the process configuration definition XML file.

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(x86)%\Microsoft Visual Studio 12.0\Common7\IDE

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

Requirements

  • To export process configuration definitions, you must be a valid user of the team project or collection.

  • To import process configuration definitions, you must be a member of the following security groups: Team Foundation Administrators or Project Administrators.

For more information, see Team Foundation Server permissions and Team Foundation Server default groups, permissions, and roles.

witadmin exportprocessconfig /collection:CollectionURL /p:ProjectName [/f:FileName] [/e:encoding] 
witadmin importprocessconfig /collection:CollectionURL [/p:ProjectName] /f:FileName [/e:encoding] [/v]

Parameter

Description

/collection:CollectionURLx

Specifies the URL of the collection. You must specify the URI in the following format: http://ServerName:Port/VirtualDirectoryName/CollectionName

If you do not specify a virtual directory, you must specify the URI in the following format:

http://ServerName:Port/CollectionName.

/p:ProjectName

Required. The team project for which you want to export or import the process configuration. This team project must be defined in the collection that you specified by using the /collection parameter. You do not need to specify a team project when you specify the /v switch.

/f:FileName

The path and the name of the XML definition file for the process configuration to export or import.

Note Note

If the client computer is running 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 following pages on the Microsoft website: Registry Virtualization and Common file and registry virtualization issues in Windows Vista. To avoid this redirection, you can export the file to a location where you have permissions.

/e:Encoding

Optional. 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 uses UTF-8 if detection fails.

/v

Optional. Validates the XML that defines the process configuration but does not import the definition file.

/? or help

Displays help about the command in the Command Prompt window.

Note Note

Installing VS TFS 2013 upgrades existing team projects. They will use the process configuration file, which combines the agile configuration files and the common configuration files that are supported in TFS 2012. The following witadmin commands have been deprecated along with their corresponding configuration files:

  • exportagileprocessconfig

  • exportcommonprocessconfig

  • importagileprocessconfig

  • importcommonprocessconfig

If you are updating an upgraded team project, see Configure features after a TFS upgrade.

The following values apply in each example:

  • URL for the collection: http://AdventureWorksServer:8080/tfs/DefaultCollection

  • Team project: Contoso

  • Port number for the server website: 8080

You can add fields for any quick add panel. For example, the following example adds Business Value to the product backlog panel.

Backlog panel with Business Value field added

The panel only displays fields that are included in the FIELDS section of the WIT definition for the WIT selected. For example, if you select the bug WIT, then only Title displays, as Business Value isn’t defined for bugs. To add another WIT to the panel, you add it to the Requirements Category as described here.

  1. If you don't have administrative permissions for your team project, get them.

  2. 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)%. You can download Team Explorer for free.

  3. Export the process configuration file.

    witadmin exportprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\ProcessConfiguration.xml"
    

    An example of a CollectionURL is http://MyServer:8080/tfs/TeamProjectCollectionName.

  4. Add the field reference name to the AddPanel section.

    For example, the following syntax adds the Priority element to the panel.

    <AddPanel>
       <Fields>
          <Field refname="System.Title" />
          <Field refname="Microsoft.VSTS.Common.BusinessValue" />
       </Fields>
    </AddPanel>
    

    Tips:

    • You can look up the reference name for a field using this index.

    • Add all required fields for work item types defined for the Requirements Category. That way, you avoid having to open the work item form to fill them in when you add backlog items through the panel.

  5. Import the process configuration file.

    witadmin importprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\ProcessConfiguration.xml"
    
  6. Refresh your backlog page to view the updated panel.

A: You can customize the quick add panel. The Configure Features Wizard will update your team projects and you’ll get access to the latest features.

Other changes might require you to perform some manual operations when updating your team project. To learn about which customizations you can safely make and which you should avoid, see Customize the work tracking experience: Before you customize, understand the maintenance and upgrade implications.

A: Some customizations can be done through the user interface. Others require editing process configuration or other team project objects. For an overview, see Configure and customize Agile planning tools for a team project.

A: The default experience supports one level of portfolio backlog. You can add up to five levels as described in Add a backlog to Agile portfolio management.

A: If you’ve added a custom WIT and want to add that to either the backlog or task board, you can. You just can’t have them appear in both places. Learn how by reading Add bugs to the task board or backlog.

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