- Article
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018
Work items can live forever in your work tracking data store. You never have to delete them. However, you might want to set up a work item management process for one of the following actions:
- Change state: Remove work items from appearing on backlogs and boards by changing the work item State to Remove or Cut. The state available to you is based on the workflow assigned to the work item type.
- Delete: Remove work items from backlogs, boards, and queries. Deleted work items are moved to a Recycle Bin.
- Restore: Recover deleted work items by restoring them from the Recycle Bin.
- Destroy: Permanently delete work items, which deletes all data from the work tracking data store.
Note
The ability to archive work items or projects isn't a supported feature at this time.
To move a work item from one project to another, or to change the work item type, see Move work items, change work item type.
Note
For information about the Azure Artifacts Recycle Bin, see Delete and recover packages.
Prerequisites
In general, members of the Contributors group can remove, delete, and restore work items. To permanently delete work items, you must be a member of the Project Administrators group, or be granted the required permission. Users with Stakeholder access can view the contents of the Recycle Bin, but can't restore or permanently delete items in the bin regardless of the permissions they're granted.
Task
Required permission(s)
Change state to Remove or Cut
- Have the Area Path permission set to Allow: Edit work items in this node
- By default, members of the Contributors group have this permission.
Delete work items and
Restore work items
- Have the project-level permission set to Allow: Delete and restore work items
- Have Basic access or higher.
- By default, members of the Contributors group have this permission.
Permanently delete or destroy work items from the command line
Be a member of the Project Administrators group.
Permanently delete or destroy work items
- Have the project-level permission set to Allow: Permanently delete work items
- By default, members of the Project Administrators group have this permission.
Delete or destroy work items from the command line
- Have the project-level permission set to Allow: Permanently delete work items
- By default, members of the Project Administrators group have this permission.
For a simplified view of permissions assigned to built-in groups, see Permissions and access.
Note
Users with Stakeholder access for a public project have full access to all work tracking features just like users with Basic access. For more information, see Stakeholder access quick reference.
Remove or delete multiple work items
You can act on individual work items or bulk modify several work items.
From the web portal, you can multi-select several work items from a backlog or query results page. You can also do a bulk update using the associated feature. To delete or restore several work items at the same time, see Bulk modify work items.
Remove work items
By changing the State of a work item to Removed, you effectively remove it from a backlog or board view (product, portfolio, and sprint backlogs, Kanban board, and Taskboards). The Removed state corresponds to the Removed workflow category state. If you define custom workflow states, any state you map to the Removed workflow category state act in a similar way.
To cause removed items to not show up in queries, you must add a clause that filters on the State field.
Note
The Removed state isn't supported with the Basic process. It is only supported with the Agile, Scrum, and CMMI process work item types. The Basic process is available when you add a project to Azure DevOps Services or Azure DevOps Server 2019 Update 1.
Delete work items
Deleted work items won't appear in your backlogs, boards, or queries. Deleted items are moved to a Recycle Bin from which you can recover them if needed. To delete a test case, test plan, or other test-related work item types, see Delete test artifacts.
You can delete work items in one of the following ways:
- From within the work item form
- From the Work Items page
More Actions menu - From the Kanban board card context menu
- From a backlog or query results page.
More Actions menuTo initiate a delete operation:
From the work item form, open the work item, choose
Actions, and select Delete.To delete several work items, multi-select them from a backlog or a query results list, choose the
context menu, and then select Delete.To delete a work item from your Kanban or taskboard, choose the
context menu for the card and select Delete.Confirm you want to actually delete the item(s).
You can delete a work item from within the work item form, or by multi-selecting work items from a backlog or query results page.
To delete a single work item, open the work item, choose the
Actions, and select Delete.To delete several work items, multi-select them from a backlog or a query results list. Then, choose the
actions icon and select Delete.You can also delete work items from your Kanban or taskboard.
Or, you can drag them to the
Recycle bin. You can only access the Recycle bin from the Work hub.Confirm you want to actually delete the item(s).
(Video) Azure DevOps - Lesson 07 | Managing Teams | Managing Team wise Work Items, Boards, Sprint TaskboardsNote
The Delete work items confirmation dialog for on-premises Azure DevOps may indicate there are auto-delete settings (disabled). There are no settings you can enable or disable. There is only a background process which permanently deletes work items that have been set to delete.
Recycle bin. You can only access the Recycle bin from the Work hub.
Restore or destroy work items
You can't open work items that have been moved to the Recycle Bin. Also, you'll only see the Permanently delete option if your Permanently delete work items project-level permission is set to Allow.
You restore deleted work items or permanently delete them from the web portal Recycle Bin.
Choose Boards>Work Items and then choose the Recycle Bin.
If you don't see the Recycle Bin option, choose More commands … and choose it from the menu of options.
A new browser tab opens with the query that lists work items added to the Recycle Bin.
Select the items you want to restore and then choose Restore.
Optionally, you can choose to permanently delete the items.
Confirm your selection.
You restore deleted work items from the web portal Recycle Bin.
Choose Work>Backlogs or Work>Queries and then choose the Recycle Bin.
A new browser tab opens with the query that lists work items added to the Recycle Bin.
Select the items you want to restore and then choose Restore.
Note
Deleted test artifacts won't appear in the Recycle Bin and can't be restored. Deletion of test artifacts deletes the selected test artifact and all of its associated child items, such as child test suites, test points across all configurations, testers (the underlying test case work item doesn't get deleted), test results history, and other associated history.
Delete or destroy work items from the command line
You can delete or destroy a work item with the az boards work-item delete command. To get started, see Get started with Azure DevOps CLI.
Note
You can restore work items you delete, but you can't restore work items you choose to destroy.
az boards work-item delete --id [--destroy] [--org] [--project] [--yes] Parameters
- id: Required. The ID of the work item.
- destroy: Optional. Permanently delete this work item.
- org: Azure DevOps organization URL. You can configure the default organization using
az devops configure -d organization=ORG_URL. Required if not configured as default or picked up usinggit config. Example:--org https://dev.azure.com/MyOrganizationName/. - project: Name or ID of the project. You can configure the default project using
az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up usinggit config. - yes: Optional. Don't prompt for confirmation.
Example
The following command permanently deletes the bug with the ID 864 and doesn't prompt you for confirmation.
az boards work-item delete --id 864 --destroy --yesDestroy work items from the command line
Use the witadmin destroywi command to permanently remove work items from the data store. A permanent delete means all information in the work tracking data store is deleted and can't be restored nor reactivated.
Note
Deleting work items from the witadmin command line is deprecated for TFS 2018.2 and later versions, and not supported for Azure Boards cloud service.
Open a Command Prompt window where the latest version of Visual Studio is installed and change the directory to where the witadmin.exe tool has been installed.
For example, you would change to the following directory for TFS 2018. (For other versions, see Remove work items permanently (witadmin destroywi)).
%programfiles(x86)%\Microsoft Visual Studio\2018\Professional\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer
On a 32-bit edition of Windows, replace %programfiles(x86)% with %programfiles%.
The witadmin command-line tool installs with any version of Visual Studio or Team Explorer. You can access this tool by installing the free version of Visual Studio Community.
To delete several work items, enter the server name and directory path to the collection. For example:
witadmin destroywi /collection:http://TFSServerName:8080/tfs/DefaultCollection /id:12,15,23To delete a single work item, enter the ID as shown:
witadmin destroywi /collection:http://TFSServerName:8080/tfs/DefaultCollection /id:2003
Delete and restore processes
When you delete a work item, the following actions occur:
- Generates a new revision of the work item
- Updates the Changed By/Changed Date fields to support traceability
- Preserves the work item completely, including all field assignments, attachments, tags, and links
- Causes the work item to become non-queryable and, as such, won't appear in any work tracking experience, query result, or report
- Updates charts correctly. The CFD, velocity, burndown, and lightweight charts are updated to remove deleted work items
- Removes work tracking extensions
- Preserves trend data except for the latest value
- Removes the work item from the data warehouse/cube similar to as if it was permanently removed.
When you restore a work item, the following actions occur:
- Causes a new revision of the work item to be made
- Updates the Changed By/Changed Date fields to support traceability
- Becomes queryable
- All fields remain unchanged
- History contains two new revisions, one for deletion, and one for restore
- Reattaches work tracking extensions
- Updates charts correctly. The CFD, velocity, burndown, and lightweight charts are updated to include the restored work items
- Restores trend data
- Adds the work item back to the data warehouse/cube
- Sets the area or iteration path fields to the root node if the previous area path or iteration paths were deleted.
Use a REST API to delete, restore, and destroy work items
To programmatically delete, restore, and destroy work items, see one of the following REST API resources:
- Recycle bin REST API Reference
- Work Items - Delete REST API Reference
Related articles
- View and add work items using the Work Items page
- Delete test artifacts
- Set permissions and access for work tracking
- Change project-level permissions
- Stakeholder access quick reference
FAQs
Remove, delete, and restore work items in Azure Boards - Azure Boards? ›
You restore deleted work items or permanently delete them from the web portal Recycle Bin. Choose Boards>Work Items and then choose the Recycle Bin. If you don't see the Recycle Bin option, choose More commands … and choose it from the menu of options.
How do I delete items from Azure boards? ›To delete a single work item, open the work item, choose the Actions, and select Delete. To delete several work items, multi-select them from a backlog or a query results list. Then, choose the actions icon and select Delete.
How do I recover deleted items from Azure? ›To restore an application from the Azure portal, select App registrations > Deleted applications. Select the application registration to restore, and then select Restore app registration. Currently, service principals can be listed, viewed, hard deleted, or restored via the deletedItems Microsoft Graph API.
How do I restore deleted artifacts in Azure DevOps? ›Sign in to your Azure DevOps organization, and then navigate to your project. Select Artifacts, and then select Recycle Bin. Select your package, and then select Restore.
How do I delete a work item template in Azure DevOps? ›Delete a template
From the web portal, open Project Settings>Team configuration>Templates. Choose the actions icon to open the menu, and choose Delete.