On-premises XML process customization

Azure DevOps Server 2022 - Azure DevOps Server 2019

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.

Note

For more information, see the following articles:

• About backlogs
• Configure and customize Azure Boards
• Create a project using the process of your choice
• Customize your work tracking experience (process models)
• Manage inherited processes

For Azure DevOps Server 2019 and later versions, you have a choice of process models. When you create a project collection, you'll need to choose between On-premises XML process model and Inheritance process model. To learn more, see Customize work tracking, Choose the process model for your project collection.

Important

Migration of projects or collections from Hosted XML to the inherited model is not support for Azure DevOps Server. It is only available on the Azure DevOps Sevice.

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

• Add or modify a field
• Add a checkbox (Boolean) field (TFS 2017.2)
• Add rules to a field
• Change a field label
• Add a custom control field
• Remove a field from a form
• Change a field attribute
• Add fields that integrate with test, build, and version control
• Delete a field

Pick lists

• Area paths
• Iteration paths
• Add a custom pick list
• Modify a predefined pick list
• State or Reason fields (customize workflow)
• Person-name field (add users)
• Resolution State & Failure Type
• Define global lists

Work item types

• Add or modify a work item type
• Change the workflow (States, Reasons, Transitions)
• Customize the form
• Specify the WIT color
• Specify the WIT icon
• Specify the workflow state color

Backlogs and process configuration

• Add WITs to backlogs or boards
• Add portfolio backlogs
• Configure the quick add panel
• Configure the default backlog columns
• Set maximum number of task board items
• Set default weekend days (Scrum)
• Set default bug management behavior
• Set default hidden backlogs
• Process configuration
• Categories

Process template

• Customize
• Manage (upload/download)
• Maintenance and upgrade implications

Link types

• Add a custom link type
• Delete a custom link type
• Deactivate/activate a custom link type

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 the Process Template editor from the Visual Studio Marketplace.

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

Related articles

• Customize work
• witAdmin: Customize and manage objects for tracking work