Azure DevOps Custom Work Item Type Setup and Best Practices

Setting up a custom work item type in Azure DevOps is a game-changer for teams that need more flexibility in their workflow.

You can create a custom work item type by using the Work Item Tracking (WIT) process template, which provides a solid foundation for your custom work item.

This template allows you to define the fields, layout, and behavior of your custom work item, giving you full control over its structure and functionality.

To get started, you'll need to create a new WIT process template or clone an existing one, depending on your needs.

For more insights, see: Azure Devops Work Item Types

To create a custom work item type, you'll need to add or modify a field to an existing work item type. This involves making changes to the work item form.

You must have the necessary permissions to perform this task. To list work item types, you need to have your View project-level information permission for the project in the collection set to Allow.

Here are the specific actions you can take when creating or modifying a work item type:

Creating a custom work item type involves defining its core components, which can be modified or added to suit your needs. You can add or modify a field to an existing work item type or even create a new custom work item type.

To start, you can add a custom work item type, which allows you to define a new type of work item that meets your specific requirements. This can be done by modifying an existing work item type or creating a new one from scratch.

You can also change the workflow of your work item type, which includes modifying the states, reasons, and transitions. This is a crucial aspect of customizing your work item type, as it allows you to tailor the process to your team's needs.

Here are some key objectives you can achieve when defining a work item type:

To create a custom work item type, you need to meet certain prerequisites.

You must have your View project-level information permission set to Allow for the project in the collection.

To add or customize a work item type by customizing a process template, you need to be a member of the Project Collection Administrators group or have your Edit process permission set to Allow.

To get added as an administrator, you should see the article section on "Change project collection-level permissions" for more information.

Modifying a custom work item type in Azure DevOps requires attention to detail and a solid understanding of the process. You can add or modify fields, field rules, labels, or empty text in the FIELDS section of the definition file.

To add a field, you must specify the XML syntax within the FIELDS section. For example, adding the work item ID to a form requires specifying the XML syntax within the FORM section of the definition.

On a similar theme: Delete Work Item in Azure Devops

You can modify the workflow by adding or removing states, reasons, or transitions in the WORKFLOW section. This includes specifying valid transitions between states.

To customize the workflow, follow these two steps: modify the WORKFLOW of the work item type definition and modify the process configuration to map new workflow states to metastates.

Here's a quick rundown of the steps to modify the workflow:

Remember, modifying the workflow for work item types that appear on Agile tool pages requires an additional step to map new workflow states to metastates.

You can completely remove a custom WIT and all work items based on that WIT by choosing Destroy from the WIT context menu. This operation deletes all associated data, including historical values, and cannot be recovered.

To delete a WIT, you must be a member of the Project Collection Administrators group or have explicit permissions to edit a specific process.

You can also disable a custom WIT to prevent users from adding new work items using it, while existing work items remain available. Disabling a WIT removes it from the New drop down and add experiences, but no changes are made to existing work items.

To disable a WIT, choose Disable from the WIT context menu, and to re-enable it, choose Enable from the WIT context menu.

Here are the steps to follow when importing and exporting work item type definition files:

These steps allow you to modify or add a field, change a field label, rearrange fields, and more. You can also use the Process Editor or other tools to import and export definition files.

To enable or disable a custom work item type, you can use the WIT context menu. You can disable a custom WIT to prevent users from adding new work items using it.

Disabling a WIT removes it from the New dropdown and add experiences, and creating a work item of that WIT is also blocked via REST APIs.

You can re-enable the WIT by choosing Enable from the WIT context menu. This will make the WIT available again for users to create new work items.

No changes are made to existing work items of that type when disabling or re-enabling a WIT.

Readers also liked: Azure Devops Work Items

To manage a custom work item type, you'll need to import and export files. You can use the witadmin commands to do this, and it's a crucial step in customizing your work item type.

If you're using the Hosted XML process model, you'll need to import and export the process template used by your project. To export a work item type definition file, use the command `witadmin exportwitd /collection:CollectionURL /p:ProjectName /n:TypeName /f:"DirectoryPath/FileName.xml"`. For example, if your CollectionURL is `http://MyServer:8080/tfs/TeamProjectCollectionName`, you would use `witadmin exportwitd /collection:http://MyServer:8080/tfs/TeamProjectCollectionName /p:ProjectName /n:TypeName /f:"DirectoryPath/FileName.xml"`.

Editing the file is the next step. The file has three main sections: FIELDS, WORKFLOW, and FORM. You can modify these sections to add or remove fields, change the workflow, or customize the form.

To import the definition file, use the command `witadmin importwitd /collection:CollectionURL /p:ProjectName /f:"DirectoryPath/FileName.xml"`. For example, if your CollectionURL is `http://MyServer:8080/tfs/TeamProjectCollectionName` and your file path is `DirectoryPath/FileName.xml`, you would use `witadmin importwitd /collection:http://MyServer:8080/tfs/TeamProjectCollectionName /p:ProjectName /f:"DirectoryPath/FileName.xml"`.

For your interest: Migrate Tfs to Azure Devops

The easiest way to add a new work item type is to copy an existing work item type and then modify the definition file. You can use the Process Editor to do this, or install the Process Template editor from the Visual Studio Marketplace.

Here are the steps to import and export definition files:

To extend a custom work item type, you'll need to use the Work Item Types REST API to work with WITs programmatically.

The backlog level you add a custom work item type to determines the parent work item type(s) for the work item type.

You can add custom work item types to any level of the backlog, but the parent work item type will be determined by the level you choose.

To track your custom work item type in Azure DevOps, you can use the "Track It Like a Requirement" approach. This involves creating a custom field to track the status of your work item.

In this approach, you can use the "State" field to track the status of your work item, just like you would with a requirement. The State field can have multiple values, such as "New", "In Progress", and "Done".

You can also use the "Priority" field to track the priority of your work item, which can be useful when you have multiple work items competing for attention. The Priority field can have values such as "High", "Medium", and "Low".

By using these fields, you can create a simple and effective way to track the status and priority of your custom work item type in Azure DevOps.

Intriguing read: Azure Dev Ops Status

You can customize the appearance and layout of your custom work item type in Azure DevOps.

To change the description, icon, or color of a custom work item type, choose Edit from the WIT context menu. This will allow you to make changes to the description, icon, and color of your custom work item type.

You can also change the color or icon associated with an existing work item type by editing the process configuration. Additionally, you can add the color to use for a new work item type through the process configuration.

Customizing the work item form is another way to change the appearance and layout of your custom work item type. You can add or modify a field, change a field label, rearrange fields, add a group or page, and more.

Here are some common elements you can customize on a work item form: