Import and export process configuration

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018 - TFS 2013

You customize the process configuration to modify the display of the web portal Agile tools. A few additional tools require that you map workflow states to metastate mappings.

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

• exportprocessconfig: Exports the process configuration definition to an XML file or the Command Prompt window.
• importprocessconfig: Imports the process configuration definition XML file.

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.

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.

Prerequisites

• To export process configuration definitions, you must be a valid user of the 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 Change project collection-level permissions.

Syntax

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

Parameters

Remarks

Installing the latest version of TFS upgrades existing projects. If you are updating an upgraded project, see Configure features after an upgrade.

If you encounter problems accessing existing test plans or test suites after an upgrade, see Manual updates to support test management.

Examples

The following values apply in each example:

• URL for the collection: http://AdventureWorksServer:8080/tfs/DefaultCollection
• Project: Contoso
• Port number for the server website: 8080

To add a field to the quick add panel

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

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. See Add a work item type to a backlog and board.

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

2. Open a Command Prompt window according to the instructions provided in How to run the witadmin command-line tool. For example:

   cd %programfiles(x86)%\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer
   

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>  
   

   Tip

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

Update metastate mappings to support Test Manager

If you customize the WORKFLOW section of the test plan or test suite, you must map the states to metastates.

In the following example, the test plan workflow has been updated to use the Design, Testing, and Signed Off states. To support backward compatibility, the TestPlanWorkItems is added to the ProjectProcessConfiguration section of the process configuration definition.

Workflow

<WORKFLOW>
      <STATES>
        <STATE value="Design" />
        <STATE value="Testing" />
        <STATE value="Signed Off" />
      </STATES>
      <TRANSITIONS>
        <TRANSITION from="" to="Design">
          <REASONS>
            <DEFAULTREASON value="New test plan" />
          </REASONS>
        </TRANSITION>
     <TRANSITION from="Design" to="Testing">
          <REASONS>
            <DEFAULTREASON value="Authoring complete" />
          </REASONS>
        </TRANSITION>        
     <TRANSITION from="Testing" to="Signed Off">
          <REASONS>
            <DEFAULTREASON value="Signed Off testing" />
          </REASONS>
        </TRANSITION>
        <TRANSITION from="Signed Off" to="Design">
          <REASONS>
            <DEFAULTREASON value="Reactivating to authoring phase" />
          </REASONS>
        </TRANSITION>
        <TRANSITION from="Signed Off" to="Testing">
          <REASONS>
            <DEFAULTREASON value="Reactivating to run tests" />
          </REASONS>
        </TRANSITION>
        <TRANSITION from="Testing" to="Design">
          <REASONS>
            <DEFAULTREASON value="Back to authoring" />
          </REASONS>
        </TRANSITION>
      </TRANSITIONS>
    </WORKFLOW>

Metastate mappings

<TestPlanWorkItems category="Microsoft.TestPlanCategory" pluralName="Test Plans" singularName="Test Plan">
    <States>
      <State type="InProgress" value="Design" />
      <State type="InProgress" value="Testing" />
      <State type="Complete" value="Signed Off" />
    </States>
  </TestPlanWorkItems>
<TestSuiteWorkItems category="Microsoft.TestSuiteCategory" pluralName="Test Suites" singularName="Test Suite">
    <States>
      <State type="Proposed" value="In Planning" />
      <State type="InProgress" value="In Progress" />
      <State type="Complete" value="Completed" />
    </States>
  </TestSuiteWorkItems>

If you modify the test suite workflow, then you have to make a similar update if you want to map new states. You would add it within a TestSuiteWorkItems section. See ProcessConfiguration.

Related articles

• Configure features after an upgrade
• Control XML element reference
• Change the work item form layout
• Edit a work item type definition to add web content to a work item form

Q & A

Q: What customizations can I make and still use the Configure Features Wizard to update my project after a TFS upgrade?

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

Other changes might require you to perform some manual operations when updating your 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.

Q: When do I need to map workflow states to metastates?

A: When you add or remove workflow states to the following work item types, you should consider updating the process configuration to add or remove corresponding metastate mappings.

• Work item types that belong to the Requirement Category or Task Category: Metastate mappings support the display of the Agile planning tools.

• Work item types that belong to the Bug Category: Metastate mappings to support My Work tool (Agile and CMMI-based projects).

• Test Plan and Test Suite: Updates to the workflow of these work item types must be mapped only when you support team members connecting to Azure DevOps from a version of Test Manager that is based on Visual Studio 2013.2 or earlier version.

  Update the metastate mappings if you receive an Application detected an unexpected fault error when you connect to your project.

  

How do I resolve process configuration errors?

A: When you make one of the following changes to a project, you'll need to update the definitions for the work item type, categories, or process configuration. To avoid errors, always make your changes in this order: (1) work item types, (2) categories, and (3) process configuration.

Q: Do you want to work with two or more portfolio backlogs?

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

Q: Do you want to add or change the work item types that appear on your task board or product backlog?

A: If you've added a custom work item type 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 work item types to backlogs and boards.