Remove, delete, or restore work items

Azure Boards | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2013

Work items can live forever in your work tracking data store. You never have to delete them. However, depending on your business needs, you may want to perform one or more of these actions:

  • Change state: Remove work items from appearing on backlogs and boards by simply changing the work item State to Remove or Cut.
  • Delete: Remove work items from backlogs, boards, and queries. Deleted work items are moved to a Recycle Bin. From the Recycle Bin you can restore or permanently delete them.
  • Destroy: Permanently delete work items, deleting all data from the work tracking data store.
  • Restore: Recover deleted work items, restoring them from the Recycle Bin.
  • Change state: Remove work items from appearing on backlogs and boards by simply changing the work item State to Remove or Cut.
  • Destroy: Permanently delete work items, deleting all data from the work tracking data store.

The ability to archive work items or projects isn't a supported feature at this time.

Note

For information about the Azure Artifacts Recycle Bin, see Delete and recover packages.

Prerequisites

  • To remove, modify, or delete work items, you must be a member of the Contributors group or have the following permissions set to Allow.
    • Remove work items: Have the View work items in this node and Edit work items in this node Area Path permissions set to Allow.
    • Delete work items and Restore work items: Have the Delete and restore work items project-level permission set to Allow. Also, to restore work items, you must have Basic access or higher. Users with Stakeholder access can view the contents of the Recycle Bin, but can't restore or permanently delete items in the bin.
  • To remove, modify, or delete work items, you must be a member of the Contributors group or have the following permissions set to Allow.
    • Remove work items: Have the View work items in this node and Edit work items in this node Area Path permissions set to Allow.
  • To Restore or destroy work items, you must be a member of the Project Administrators group or have the Delete work items in this project project-level permission set to Allow.
  • To Destroy work items (witadmin CLI), you must be a member of the Project Administrators group or have the Delete work items in this project project-level permission set to Allow.

Note

By default, for TFS 2015.1 and earlier versions, the Contributors group has Delete work items in this project set to Not set. This setting causes the Contributors group to inherit the value from the closest parent that has it explicitly set.

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 details, see About access levels.

Important

Select a version from Azure DevOps Content Version selector.

To view the content available for your platform, make sure that you select the correct version of this article from the version selector which is located above the table of contents. Feature support differs depending on whether you are working from Azure DevOps Services or an on-premises version of Azure DevOps Server, renamed from Team Foundation Server (TFS).
To learn which on-premises version you are using, see What platform/version am I using?

Remove or delete multiple work items

You can perform operations 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 and perform 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 will act in a similar way.

Change State to Removed

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 test suite, or other test-related work item types, see Delete test artifacts.

  1. You can delete a work item from within the work item form, by multi-selecting work items from a backlog or query results page, or from a Kanban board or taskboard.

    To delete a single work item, open the work item, choose the actions icon and select Delete.

    work item form, actions menu, Delete
    To delete several work items, multi-select them from a backlog or a query results list and then choose the actions icon and select Delete.

    List of work items, actions menu, Delete

    To delete a work item from your Kanban or taskboard, choose the actions icon of the card and select Delete.

    Delete work item from Kanban board

  2. Confirm you want to actually delete the item(s).

    Confirm delete dialog

Note

The Delete and Recycle bin features are available from TFS 2015.2 and later versions.

  1. 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 icon and select Delete.

    work item form, actions menu, Delete

    To delete several work items, multi-select them from a backlog or a query results list and then choose the actions icon and select Delete.

    List of work items, actions menu, Delete

    You can also delete work items from your Kanban or taskboard.

    Delete work item from Kanban board

    Or, you can drag them to the Recycle bin (Recycle bin). You can only access the (Recycle bin) from the Work hub.

  2. Confirm you want to actually delete the item(s).

    Confirm delete dialog

    Note

    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.

Restore or destroy work items

You restore deleted work items or permanently delete them from the web portal Recycle Bin.

  1. Choose Boards>Work Items and then choose the Recycle Bin.

    Boards>Work Items page, Open Recycle bin

    If you don't see the Recycle Bin option, choose More commands … and choose it from the menu of options.

    Note

    Deleted test artifacts won't appear in the Recycle Bin and can't be restored. Deletion of test artifacts not only deletes the selected test artifact but also all 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.

  2. A new browser tab opens with the query which lists work items added to the Recycle Bin.

  3. Select the items you want to restore and then choose Restore.
    Restore selected items

    Optionally, you can choose to permanently delete the items.

    Note

    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.

  4. Confirm your selection.

You restore deleted work items from the web portal Recycle Bin.

Note

The Delete and Recycle Bin features require TFS 2015.2 or later version.

  1. Choose Work>Backlogs or Work>Queries and then choose the Recycle Bin.

    Open Recycle bin

    A new browser tab opens with the query which lists work items added to the Recycle Bin.

  2. Select the items you want to restore and then choose Restore.

    Restore selected items

    Optionally, you can choose to permanently delete the items.

    Note

    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.

  3. Confirm your selection.

Delete or destroy work items (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 using git 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 using git config.
  • yes: Optional. Do not 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 --yes

Destroy work items (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 cannot 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

For example, you would change to the following directory for TFS 2017. (For other versions, see Remove work items permanently (witadmin destroywi)).

%programfiles(x86)%\Microsoft Visual Studio\2017\Professional\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

For example, you would change to the following directory for TFS 2015. (For other versions, see Remove work items permanently (witadmin destroywi)).

cd %programfiles(x86)%\Microsoft Visual Studio 14.0\Common7\IDE

For example, you would change to the following directory for TFS 2013. (For other versions, see Remove work items permanently (witadmin destroywi)).

cd %programfiles(x86)%\Microsoft Visual Studio 12.0\Common7\IDE

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,23
    
  • To delete a single work item, simply enter the ID as shown:

      witadmin destroywi /collection:http://TFSServerName:8080/tfs/DefaultCollection /id:2003
    

How delete and restore actions work

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 work item to become non-queryable and therefore won't appear in any work tracking experience, query result, or report
  • Updates charts accordingly, 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 accordingly, 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.

REST API

To programmatically delete, restore, and destroy work items, see one of the following REST API resources: