Skip to content

Latest commit

 

History

History
182 lines (143 loc) · 6.24 KB

work-items.md

File metadata and controls

182 lines (143 loc) · 6.24 KB

Work Item Tools

This document describes the tools available for working with Azure DevOps work items.

Table of Contents

get_work_item

Retrieves a work item by its ID.

Parameters

Parameter Type Required Description
workItemId number Yes The ID of the work item to retrieve
expand string No Controls the level of detail in the response. Defaults to "All" if not specified. Other values: "Relations", "Fields", "None"

Response

Returns a work item object with the following structure:

{
  "id": 123,
  "fields": {
    "System.Title": "Sample Work Item",
    "System.State": "Active",
    "System.AssignedTo": "user@example.com",
    "System.Description": "Description of the work item"
  },
  "url": "https://dev.azure.com/organization/project/_apis/wit/workItems/123"
}

Error Handling

  • Returns AzureDevOpsResourceNotFoundError if the work item does not exist
  • Returns AzureDevOpsAuthenticationError if authentication fails
  • Returns generic error messages for other failures

Example Usage

// Using default expand="All"
const result = await callTool('get_work_item', {
  workItemId: 123,
});

// Explicitly specifying expand
const minimalResult = await callTool('get_work_item', {
  workItemId: 123,
  expand: 'None'
});

create_work_item

Creates a new work item in a specified project.

Parameters

Parameter Type Required Description
projectId string Yes The ID or name of the project where the work item will be created
workItemType string Yes The type of work item to create (e.g., "Task", "Bug", "User Story")
title string Yes The title of the work item
description string No The description of the work item
assignedTo string No The email or name of the user to assign the work item to
areaPath string No The area path for the work item
iterationPath string No The iteration path for the work item
priority number No The priority of the work item
additionalFields object No Additional fields to set on the work item (key-value pairs)

Response

Returns the newly created work item object:

{
  "id": 124,
  "fields": {
    "System.Title": "New Work Item",
    "System.State": "New",
    "System.Description": "Description of the new work item",
    "System.AssignedTo": "user@example.com",
    "System.AreaPath": "Project\\Team",
    "System.IterationPath": "Project\\Sprint 1",
    "Microsoft.VSTS.Common.Priority": 2
  },
  "url": "https://dev.azure.com/organization/project/_apis/wit/workItems/124"
}

Error Handling

  • Returns validation error if required fields are missing
  • Returns AzureDevOpsAuthenticationError if authentication fails
  • Returns AzureDevOpsResourceNotFoundError if the project does not exist
  • Returns generic error messages for other failures

Example Usage

const result = await callTool('create_work_item', {
  projectId: 'my-project',
  workItemType: 'User Story',
  title: 'Implement login functionality',
  description:
    'Create a secure login system with email and password authentication',
  assignedTo: 'developer@example.com',
  priority: 1,
  additionalFields: {
    'Custom.Field': 'Custom Value',
  },
});

Implementation Details

The tool creates a JSON patch document to define the fields of the work item, then calls the Azure DevOps API to create the work item. Each field is added to the document with an 'add' operation, and the document is submitted to the API.

list_work_items

Lists work items in a specified project.

Parameters

Parameter Type Required Description
projectId string Yes The ID or name of the project to list work items from
teamId string No The ID of the team to list work items for
queryId string No ID of a saved work item query
wiql string No Work Item Query Language (WIQL) query
top number No Maximum number of work items to return
skip number No Number of work items to skip

Response

Returns an array of work item objects:

[
  {
    "id": 123,
    "fields": {
      "System.Title": "Sample Work Item",
      "System.State": "Active",
      "System.AssignedTo": "user@example.com"
    },
    "url": "https://dev.azure.com/organization/project/_apis/wit/workItems/123"
  },
  {
    "id": 124,
    "fields": {
      "System.Title": "Another Work Item",
      "System.State": "New",
      "System.AssignedTo": "user2@example.com"
    },
    "url": "https://dev.azure.com/organization/project/_apis/wit/workItems/124"
  }
]

Error Handling

  • Returns AzureDevOpsResourceNotFoundError if the project does not exist
  • Returns AzureDevOpsAuthenticationError if authentication fails
  • Returns generic error messages for other failures

Example Usage

const result = await callTool('list_work_items', {
  projectId: 'my-project',
  wiql: "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'Task' ORDER BY [System.CreatedDate] DESC",
  top: 10,
});