Move, change, or delete work items

VSTS | TFS 2018 | TFS 2017 | TFS 2015

Often times you find that someone created a work item of the wrong work item type (WIT) or within an incorrect team project. You can correct these issues for individual work items or bulk modify several work items. You can also remove work items added to your backlog or task board that aren't relevant anymore.

In this topic you'll learn:

  • How to change the work item type of one or more work items (VSTS)
  • How to move one or more work items to another team project (VSTS)
  • How to remove work items from the backlog by changing the State to Removed
  • How to delete work items and test artifacts
  • How to restore or permanently delete work items (web portal)
  • How to permanently delete work items (command-line tool)
  • What permissions are required to delete work items and test artifacts
Note

Feature availability: The following features are available from VSTS (cloud service) or from the web portal of the listed on-premises TFS version or a later version. Those not annotated are available from all platforms and versions. Visit the Visual Studio Downloads page to get the latest TFS update. Additional resources may be required as annotated. To determine your platform or TFS version, see Provide product and content feedback

You only have access to those actions that are supported on your platform and for which you have permissions. If you are a member of the Contributors group (anyone who has been added as a team member) or Project Administrators groups, you have access to the following features. For a simplified view of permissions assigned to built-in groups, see Permissions and access.

Contributors Project Administrators
- Change work item type 1, 2 (VSTS)
- Remove work items (change State) 2, 3
- Delete work items 1, 2 (VSTS, TFS 2015.2)
- Restore work items 1, 2, 5 (VSTS, TFS 2015.2)
- Move a work item to another team project 1, 2, 4
- Permanently delete work items (web portal) 1, 2, 5 (VSTS, TFS 2015.2)
- Permanently delete work items (command-line tool) 5
- Permanently delete test artifacts 6 (TFS 2017.1)

Notes:

  1. You can't change type, move work items, or delete/restore work items whose WITs support test management or that belong to the Hidden Types Category. This includes all work items that track tests—such as test cases, shared steps, and shared parameters—code review requests and responses, and feedback requests and responses.
  2. 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.
  3. Changing the State to Remove causes work items to be removed from a backlog or board view (product, portfolio, and sprint backlogs, Kanban board, and task boards).
  4. To move work items to another team project, you must be a member of the Project Administrators group or be granted explicit permissions to move work items.
  5. To permanently delete work items from the web portal, you must be a member of the Project Administrators group or be granted explicit permissions to delete or restore work items.
  6. To delete test artifacts, the following restrictions and operations apply:
    • You must be a member of the Project Administrators group or have the Delete test artifacts permission set to Allow. You must also have permissions set to manage test plans and test suites, and your access level set to Advanced, which provides access to the full Test feature set.
    • Users with Basic access and with permissions to permanently delete work items and manage test artifacts can only delete orphaned test cases. That is, they can delete test cases created from the work hub that aren't linked to any test plans or test suites.
    • When you delete a test plan, test suite, test case, shared steps, or shared parameters, you not only permanently delete them, you also delete all associated test artifacts such as test results.
    • You can't bulk delete test artifacts. If test artifacts are part of a bulk selection to be deleted, all other work items except the test artifact(s) will get deleted.
Tip

To change, move, delete, or restore several work items at the same time, see Bulk modify work items.

Note

The images you see from your web portal may differ from the images you see in this topic. These differences result from updates made to VSTSor your on-premises TFS, options that you or your admin have enabled, and which process was chosen when creating your team project—Agile, Scrum, or CMMI. However, the basic functionality available to you remains the same unless explicitly mentioned.

Work items are denoted with icons for VSTS and TFS 2017.2 and later versions. For an overview of changes in the navigation experience and working within the user and administration contexts, see Work in the web portal.

Change the work item type

Note

Feature availability: The Change type… menu option is supported only from VSTS. You can't change the work item type of work items associated with test management. Both Contributors and users assigned Stakeholder access can change the work item type.

Changing the work item type refreshes the work item form with the fields defined for the type selected. For example, you can change a bug to a task and the form will refresh with the fields defined for a task.

You can change a single work item or several multi-selected work items to a new type.

Tip

When you connect to TFS, you can't change the work item type for an existing work item, but you can copy the work item and specify a new type. Also, if you have several work items with type changes you want to make, you can export them using Excel, and then re-add them as a new type.

  1. Select the Change team project icon Change type... option from the work item form's Action icon Actions menu.

    Work item form, Change work item type menu option

    Or, from the backlog or query results page, multi-select several work items whose type you want to change. You can select several work items of the same type or different type so long as you want to change them all to the same work item type.

    Click actions icon to open the context menu of one of the selected work items, and choose the Change team project icon Change type… option.

    Important

    From the Query results page, the Change type… option becomes unavailable if you have checked the Query Editor's Query across projects checkbox.

    VSTS, backlog, multi-select, open menu, choose Change type option

  2. Select the type and optionally enter a comment.

    Change work item type dialog

    Comments are automatically added to the Discussion control.

  3. Save the work item to complete the change.

    Note

    The system automatically resets the State and Reason fields to the default initial values of the specified type.

    Work item form, changed type to bug

  4. From the Query results page, you must save all work items that you bulk-modified. When you bulk modify items from the backlog, they are automatically saved. Work items shown in bold text indicate that local changes have not yet been saved to the data store. The system automatically saves each work item. Refresh the page to reflect your changes.

Move a work item to another team project

Note

Feature availability: The Move to team project… menu option is supported only from VSTS. You can only move work items from one team project to another team project within the account or collection. You can't move work items associated with test management.

When you discover that a work item belongs to a different team project within your account or collection, you can move it where it belongs. You can move a single work item or several multi-selected work items.

  1. Open the work item and choose the Move work item icon Move... option from the work item form's Action icon Actions menu.

    Work item form, Change team project menu option

    If you don't see the option, then you haven't been granted permissions to move work items out of the project.

    Or, from the backlog or query results page, multi-select several work items whose type you want to change. You can select several work items of the same type or different type so long as you want to change them all to the same work item type.

    Click actions icon to open the context menu of one of the selected work items, and choose the Move work item icon Move… option.

  2. Select the destination team project and optionally enter a comment.

    Work item form, Change team project menu option

    Comments are automatically added to the Discussion control and an entry is made to the History control. Also, the system automatically resets the State and Reason fields to the default initial values for the work item type that you move.

Remove work items by changing the State

By changing the State of a work item to Removed, you effectively remove it from all backlogs and boards.

Change State to Removed

To cause removed items to not show up in queries, you must add a clause that indicates which states you want the query to filter for.

Delete work items

Note

Feature availability: The Delete and Recycle bin features are available from VSTS and from the web portal for TFS 2015.2 or later versions.

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 WITS, see Delete test artifacts.

  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.

    Delete work item from the form

    To delete work items, you must be a member of the Project Administrators group or have the Delete work items in this project set to Allow. By default, this permission is Not Set for Contributors.

    • For VSTS and TFS 2015.2 and later versions, the Contributors group has Delete and restore work items at the project-level set to "Allow" by default.
    • For TFS 2015.1 and earlier versions, the Contributors group has Delete work items in this project at the project-level set to "Not set" by default. This setting causes the Contributors group to inherit the value from the closest parent that has it explicitly set.
  2. Confirm you want to actually delete the item(s).

    Confirm delete dialog

  3. Using multi-select from a backlog or query results list, you can delete several work items at once.

    Delete multiple items from backlog

  4. You can also delete work items from your Kanban or task board.

    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.

Restore or permanently delete work items

Note

Feature availability: The Delete and Recycle bin features are available from VSTS and from the web portal for TFS 2015.2 or later versions.

  1. To restore deleted items, open the Recycle bin from the web portal.

    Open Recycle bin

  2. Select the items you want to restore and then choose restore or to permanently delete the items.

    Restore selected items

    Note

    You'll only see the Permanently delete option if your Permanently delete work items permission is set to Allow.

  3. Confirm your selection.

Delete test artifacts

Important

Feature availability: The permanently delete feature of test artifacts is available from the from the Test and Work hubs for VSTS and the web portal of TFS 2017.1 and later versions.

We only support permanent deletion of test artifacts such as test plans, test suites, test cases, shared steps and shared parameters. Deleted test artifacts won't appear in the recycle bin and cannot 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.

  1. To delete a test case, open it from the web portal and choose the Permanently delete option from the actions menu. (Bulk deletion is not supported from a query results page.)

    Delete a test case and associated test artifacts from the web form

    Note

    You'll only see the Permanently delete option if you have the necessary permissions and access. You must be a member of the Project Administrators group or have the Delete test artifacts permission set to Allow. You must also have your access level set to Advanced, which provides access to the full Test feature set. Users with Basic access and with permissions to permanently delete work items and manage test artifacts can only delete orphaned test cases. That is, they can delete test cases created from the work hub that aren't linked to any test plans or test suites.

  2. Confirm you want to actually delete the item.

    Confirm delete

  3. You can also delete test plans and test suites directly from the Test hub.

    Delete test artifacts from Test hub

  4. To delete shared steps and shared parameters you need to first manually remove all references to them before you can delete them.

    Delete shared steps from form

To add fields or customize a work item form, see Customize your work tracking experience. The method you use depends on the process model that supports your team project.

To learn more about managing test artifacts, see:

Delete and restore actions performed under the hood

Delete work items

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 can'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 WIT 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.

Restore work items

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 2 new revisions, one for deletion, and one for restore
  • Reattaches WIT 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 similar
  • Sets the area or iteration path fields to the root node if the previous area path or iteration paths were deleted.

Delete test artifacts

  1. Removes the deleted test artifact from the test case management (TCM) data store and deletes the underlying work item
  2. Runs a job to delete all the child items both from the TCM side and the underlying work items. This action may take time (up to a few minutes) depending on the number of artifacts to be deleted.
  3. Causes all information in the WIT data store and TCM data store to be deleted and cannot be reactivated nor restored.