Share via

Work item tracking

  • Article

Work item tracking resources

Get, create, and update bugs, tasks, and other work items for your team. Queries allow you to use the full power of the work item query language to search for and filter work items. You can use the work item query language to get to each work item that satisfies the query. Work items retain a full history, and you can get each full revision of the work item, or just the updates that were made in each revision. Work items can also be tagged.

Common tasks

Get work items using a query

  1. Look up the query that you want to use.
  2. Get the results for that query.
  3. Get each of the work items by ID.

Update WorkItems in batch

Use Batch WorkItem Update api to update your workitems in batch.

Update a work item's fields

  1. Get the ID of the work item that you want to update.
  2. Update the fields of the work item.
  1. Get the ID of the work items that you want to link.
  2. Add a link between the work items.

Use the create a work item and add a link APIs in a batch call.

Attach a file to a work item

  1. Get the ID of the work item that you want to update.
  2. Upload the attachment to the attachment store.
  3. Add the attachment to the work item.

Create a work item

Create a work item. Make sure you provide at least a title. Some types of work items will require values for other fields.

Get a work item's full history

  1. Get the ID of the work item.
  2. Get a list of updates made to a work item.
  3. Get the whole work item as it appeared in any revision.

Delete a work item

  1. Get the ID of the work item.
  2. Delete the work item.

Get the fields used in a team project

  1. Get the types of work items used in a team project.
  2. Get each work item type to see the fields that it uses. (Skip past the xmlform to fieldinstances.)

Get categories of work items

Use categories of work items to get the types of work items used in a team project for different functions. For example, to see the work items that appear on the backlog, get the requirements category.

Get areas and iterations

Get the area hierarchy or iteration hierarchy for your team project.

Get types of work item relations

Get the available types of work item links that are available in your project collection.

Work item metadata resources

Work items are governed by metadata. Some of the metadata is scoped to a specific team project, and other metadata is scoped to a project collection (like your Azure DevOps Services account's default collection).

Project-scoped metadata

Your team project has a set of work item types. Each work item type may belong to a category such as "requirement" or "bug" to define its role in the project. Classification nodes define the set of values that can be used in the area and iteration fields for the work items in the team project.

Collection-scoped metadata

Work item types share fields and relation types (links and attachments) with other types of work items.

Work item batch update API

Performs multiple Work Item Update requests. Response contains individual responses for each of the requests in the batch. Failed requests do not affect subsequent requests in the batch.

REST API SEMANTICS

PATCH https://dev.azure.com/{organization}/_apis/wit/$batch?api-version=6.1

URI Parameters

Name In Required Type Description
organization Path True string The name of the Azure DevOps organization.
api-version query string Version of the API to use.
bypassRules query boolean Do not enforce the work item type rules on this update.
suppressNotifications query boolean Do not fire any notifications for this change.

Request Body

Request body is composed as list of Work Item Update requests. Each item from this list will conatin all the information about single Update Request including REST method, path, headers and body.

You can check Work Item Update documentation for detailed info about single request.

Batch Update example

Request

PATCH https://dev.azure.com/fabrikam/_apis/wit/$batch?api-version=6.1

Request Body

[
  {
    // Add priority and test rev on work item with id 1
    "method": "PATCH",
    "uri": "/_apis/wit/workitems/1?api-version=6.1",
    "headers": {
      "Content-Type": "application/json-patch+json"
    },
    "body": [
      {
        "op": "test",
        "path": "/rev",
        "value": 3
      },
      {
        "op": "add",
        "path": "/fields/Microsoft.VSTS.Common.Priority",
        "value": "1"
      }
    ]
  },
  {
    // Replace tags on work item with id 299x   
    "method": "PATCH",
    "uri": "/_apis/wit/workitems/299?api-version=6.1",
    "headers": {
      "Content-Type": "application/json-patch+json"
    },
    "body": [
      {
        "op": "replace",
        "path": "/fields/System.Tags",
        "value": "Tag1; Tag2"
      }
    ]
  },
  {
    // You can also use Work Item Create format
    "method": "PATCH",
    "uri": "/mytestprojectname/_apis/wit/workitems/$Bug?api-version=4.1",
    "headers": {
        "Content-Type": "application/json-patch+json"
    },
    "body": [
        {
            "op": "add",
            "path": "/id",
            "value": "-1"
        },
        {
            "op": "add",
            "path": "/fields/System.Title",
            "from": null,
            "value": "Sample 1"
        }
    ]
  },
]

Response

Response consist of individual responses for each batched update request.

  • count : number of batched update responses returned
  • value : list of response objects with its response code, headers and body
{
  "count": 2,
  "value": [
    {
      "code": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": "{work item object}"
    },
    {
      "code": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": "{work item object}"
    }
  ]
}