Move, change, or delete work items

Last Update: 3/30/2017

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

Depending on whether you work in the cloud in Visual Studio Team Services or an on-premises Team Foundation Server (TFS), you have these options for removing or deleting work items.

NOTE

Feature availability: The following features are available from Team Services (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

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 Team Services or 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 Team Services 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 Team Services. 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.

    Team Services, 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 Team Services. 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 Team Services 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.

  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 (web portal)

NOTE

Feature availability: The Delete and Recycle bin features are available from Team Services 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.

Permanently delete work items (command-line tool)

Use the witadmin destroywi command to permanently remove work items from the data store. A permanent delete means all information in the WIT data store is deleted and cannot be restored nor reactivated.

You can run witadmin destroywi against an on-premises TFS server or Team Services account.

  1. Open a Command Prompt window where the latest version of Visual Studio is installed and enter:

    cd %programfiles(x86)%\Microsoft Visual Studio 14.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. You can access this tool by installing the free version of Visual Studio Community.

  2. To delete several work items from an account hosted on Team Services, enter the following specifying the account name and separating the IDs with commas.

    witadmin destroywi /collection:http://AccountName/DefaultCollection /id:12,15,23

  3. To delete several work items from an on-premises collection, enter the server name and directory path to the collection. For example:

    witadmin destroywi /collection:http://TFSServerName:8080/tfs/DefaultCollection /id:12,15,23

  4. To delete a single work item, simply enter the ID as shown:

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

    NOTE

    Required permissions: For Team Services and TFS 2015.2 or later versions, you must have Permanently delete work items permission set to Allow. For TFS 2015.1 or earlier versions, you must be a member of the Project Administrators group of have Edit project-level information permissions set to Allow.

Delete test artifacts

IMPORTANT

Feature availability: The permanently delete feature of test artifacts is available from the from the Test and Work hubs for Team Services 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

Each work item represents an object stored in the work item data store. Each work item is assigned a unique identifier, an ID, which is unique within an account or project collection.

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 tracking work, see:

To learn more about managing test artifacts, see:

Hidden types category

You can use TFS Team Project Manager, an open-source client available from github to quickly determine which WITs belong to the Hidden Types Category.

To learn more, see Hidden Types Category.

Set permissions to delete work items

By default, Project Administrators and Contributors can change the work item type and delete work items by moving them to the Recycle bin. Only Project Administrators can permanently delete work items and test artifacts. Project admins can grant permissions to other team members as needed.

For example, as a project admin you can grant a user, team group, or other group you've created to have these permissions. Open the Security page for the team project and choose the user or group you want to grant permissions. (To learn how to access the admin pages, see Work in the web portal.)

In this example, we grant the Team Admins group permissions to move work items to another team project and to permanently delete work items.

Set Team Admin permissions

Restrict users from deleting work items

You can restrict users from deleting work items by changing their permissions to Dlete work items in this project. For more information about restricting permissions, see Restrict access to resources, Work items.

Additional permissions and access level required to delete test artifacts

In addition to the project-level permissions set in the previous section, team members need permissions to manage test artifacts which are set for an area path.

Open the Security page for the area path and choose the user or group you want to grant permissions.

Open Area path permissions for the team project

Set the permissions for Manage test plans and Manage test suites to Allow.

Set Area path permissions for the team project

To have full access to the Test feature set, your access level must be set to Advanced. Users with Basic access and with permissions to permanently delete work items and manage test artifacts can only delete orphaned test cases.

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.