On-premises XML process model

TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013


Feature availability: The On-premises XML process model is supported for on-premises TFS.

The On-premises XML process model provides support for customizing work tracking objects and Agile tools for a team project. With this model, you can update the XML definition of work item types, the process configuration, categories, and more. You can also update the attributes of fields.

You can perform the following tasks when you work with the On-premises XML process model.

When you manage an on-premises TFS, you perform most customizations using the following sequence. This sequence supports updating the XML definition for WIT, global lists, process configuration, and categories. This sequence supports individual updates through the import of their respective modified XML definition files. We recommend that you maintain your XML definition files in a repository for version control.

Export XML definition fileEdit XML definition fileImport WIT definition fileRefresh and verify changes

In addition, you can use the witadmin tool to list objects, rename WITs, permanently remove WITs, and more.


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.


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 TFS Power Tools. Or, you can use the TFS Team Project Manager, an open-source client available from github.

Maintenance and upgrade implications

Before you customize, you should understand how your customizations may impact your team project when you upgrade your application-tier server.

Upgrades to an on-premises TFS can introduce new features that require updates to the objects used to track work. These objects include work item types, categories, and process configuration. Minimizing changes to the workflow for a WIT or the process configuration can help minimize the work you must do when you upgrade your TFS.

To minimize the amount of manual work you'll need to do after a TFS upgrade, understand which customizations support an easy update path and which do not.

Compatible for quick updating

With the following customizations, you can use the Configure Features Wizard to automatically apply any changes to your team project required for new features.

  • Fields: Add custom fields, customize a pick list, add or modify area and iteration paths, add rules to a field
  • WITs: Add custom WITs, change the form layout
  • Categories: Add custom categories
  • Agile tools: Customize the columns on the Kanban board, customize the quick add panel
  • Office integration: Add or change how Project fields map to TFS fields

To learn more about the Configure Features Wizard, see Configure features after an upgrade.

Compatible, but may require manual updates

The Configure Features Wizard requires that specific work item types, workflow states, and fields exist in the team project. When you make the following customizations, you might need to modify your custom process for the wizard to run, or you might have to update your team project manually.

  • Fields: Change attributes of an existing field, remove fields that are referenced in the process configuration
  • WITs: Change the workflow
  • Agile tools: Change the WITs defined for the Requirement Category, Task Category, or Feature Category.
  • Agile tools: Change the metastate mapping defined in the process configuration.
  • Agile tools: Change a field specified for a TypeField in the process configuration.

In addition, changes you make to WITs or the workflow could require updates to other artifacts provided with your process, such as Excel or SQL Server Reporting Services reports.

Customizations to avoid

You should avoid making the following customizations because they can result in schema conflicts in the data warehouse or cause problems when updating team projects after a TFS upgrade.

  • Fields:
    • Change the friendly name of a field (a field specified within a WIT definition file)
    • Change one or more reporting attributes, or the attribute to synchronize person names with Active Directory of a default field
  • WITs: Rename or delete WITs
  • Categories: Change the name of default categories, or change the WITs specified within default categories

To learn more about reporting attributes, see Add or modify work item fields to support reporting.

  • Identify the best options for customizing WITs that support your tracking requirements. When you change objects that track work items, you should identify how these changes will affect existing and future team projects.
  • Put processes and all XML definition files under version control. Do not deploy objects that you define but have not stored in a repository.
  • Test your customized objects just as you would test your software.
  • Minimize the number of custom fields that you introduce. Minimize the number of fields that you make reportable.

Replace team area path with a team field (On-premises TFS)

The default configuration for team projects associates each team with an area path. If your organization has several teams that work from a common backlog and across many product areas, this configuration might not fit how you want to organize your work. By adding a custom field to represent teams in your organization, you can reconfigure the agile planning tools and pages to support your teams and decouple assignment to teams and area paths.

Use team fields instead of area paths to support teams describes how to change the default configuration.