On-premises XML process customization
TFS 2017 | TFS 2015 | TFS 2013
The On-premises XML process model provides support for customizing work tracking objects and Agile tools for a 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 customize your work tracking experience to support your business and reporting needs. The most common customizations include adding a custom field, modifying a work item form, or adding a custom work item type.
Team Foundation Server uses the On-premises XML process model to support customizations. This model relies on updating and importing XML files using the witadmin command line tool.
Important
To customize an Azure DevOps Services project, see About process customization and inherited processes. This article applies to on-premises deployments only.
Supported customizations
You can perform the following tasks when you work with the On-premises XML process model.
Area
Customization support
Fields
Pick lists
Work item types
Backlogs and process configuration
Process template
Link types
Customization sequence
When you manage an on-premises deployment, 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.
In addition, you can use the witadmin tool to list objects, rename WITs, permanently remove WITs, and more.
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 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 project when you upgrade your application-tier server.
Upgrades to an on-premises deployment 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 deployment.
To minimize the amount of manual work you'll need to do after an 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 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 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 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
TypeFieldin 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 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.
Recommended practices
- 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 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
The default configuration for 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.