WorkItemTrackingRestClient class

Base class that should be used (derived from) to make requests to VSS REST apis

Extends

Constructors

WorkItemTrackingRestClient(IVssRestClientOptions)

Properties

RESOURCE_AREA_ID

Methods

createAttachment(any, string, string, string, string)

Uploads an attachment.

createField(WorkItemField, string)

Create a new field.

createOrUpdateClassificationNode(WorkItemClassificationNode, string, TreeStructureGroup, string)

Create new or update an existing classification node.

createQuery(QueryHierarchyItem, string, string, boolean)

Creates a query, or moves a query.

createTemplate(WorkItemTemplate, string, string)

Creates a template

createWorkItem(JsonPatchDocument, string, string, boolean, boolean, boolean, WorkItemExpand)

Creates a single work item.

deleteClassificationNode(string, TreeStructureGroup, string, number)

Delete an existing classification node.

deleteField(string, string)

Deletes the field. To undelete a filed, see "Update Field" API.

deleteQuery(string, string)

Delete a query or a folder. This deletes any permission change on the deleted query or folder and any of its descendants if it is a folder. It is important to note that the deleted permission changes cannot be recovered upon undeleting the query or folder.

deleteTemplate(string, string, string)

Deletes the template with given id

deleteWorkItem(number, string, boolean)

Deletes the specified work item and sends it to the Recycle Bin, so that it can be restored back, if required. Optionally, if the destroy parameter has been set to true, it destroys the work item permanently. WARNING: If the destroy parameter is set to true, work items deleted by this command will NOT go to recycle-bin and there is no way to restore/recover them after deletion. It is recommended NOT to use this parameter. If you do, please use this parameter with extreme caution.

destroyWorkItem(number, string)

Destroys the specified work item permanently from the Recycle Bin. This action can not be undone.

exportWorkItemTypeDefinition(string, string, boolean)

Export work item type

getAccountMyWorkData(QueryOption)

INTERNAL ONLY: USED BY ACCOUNT MY WORK PAGE. This returns Doing, Done, Follows and activity work items details.

getAttachmentContent(string, string, string, boolean)

Downloads an attachment.

getAttachmentZip(string, string, string, boolean)

Downloads an attachment.

getClassificationNode(string, TreeStructureGroup, string, number)

Gets the classification node for a given node path.

getClassificationNodes(string, number[], number, ClassificationNodesErrorPolicy)

Gets root classification nodes or list of classification nodes for a given list of nodes ids, for a given project. In case ids parameter is supplied you will get list of classification nodes for those ids. Otherwise you will get root classification nodes for this project.

getComment(number, number, string)

Gets a comment for a work item at the specified revision.

getComments(number, string, number, number, CommentSortOrder)

Gets the specified number of comments for a work item from the specified revision.

getDeletedWorkItem(number, string)

Gets a deleted work item from Recycle Bin.

getDeletedWorkItems(number[], string)

Gets the work items from the recycle bin, whose IDs have been specified in the parameters

getDeletedWorkItemShallowReferences(string)

Gets a list of the IDs and the URLs of the deleted the work items in the Recycle Bin.

getField(string, string)

Gets information on a specific field.

getFields(string, GetFieldsExpand)

Returns information for all fields. The project ID/name parameter is optional.

getQueries(string, QueryExpand, number, boolean)

Gets the root queries and their children

getQueriesBatch(QueryBatchGetRequest, string)

Gets a list of queries by ids (Maximum 1000)

getQuery(string, string, QueryExpand, number, boolean, boolean)

Retrieves an individual query and its children

getQueryResultCount(string, string, string, boolean, number)

Gets the results of the query given the query ID.

getRecentActivityData()

Gets recent work item activities

getRecentMentions()

INTERNAL ONLY: USED BY ACCOUNT MY WORK PAGE.

getRelationType(string)

Gets the work item relation type definition.

getRelationTypes()

Gets the work item relation types.

getReportingLinksByLinkType(string, string[], string[], string, Date)

Get a batch of work item links

getRevision(number, number, string, WorkItemExpand)

Returns a fully hydrated work item for the requested revision

getRevisions(number, string, number, number, WorkItemExpand)

Returns the list of fully hydrated work item revisions, paged.

getRootNodes(string, number)

Gets root classification nodes under the project.

getTemplate(string, string, string)

Gets the template with specified id

getTemplates(string, string, string)

Gets template

getUpdate(number, number, string)

Returns a single update for a work item

getUpdates(number, string, number, number)

Returns the deltas between work item revisions

getWorkArtifactLinkTypes()

Get the list of work item tracking outbound artifact link types.

getWorkItem(number, string, string[], Date, WorkItemExpand)

Returns a single work item.

getWorkItemIconJson(string, string, number)

Get a work item icon given the friendly name and icon color.

getWorkItemIcons()

Get a list of all work item icons.

getWorkItemIconSvg(string, string, number)

Get a work item icon given the friendly name and icon color.

getWorkItemIconXaml(string, string, number)

Get a work item icon given the friendly name and icon color.

getWorkItemNextStatesOnCheckinAction(number[], string)

Returns the next state on the given work item IDs.

getWorkItems(number[], string, string[], Date, WorkItemExpand, WorkItemErrorPolicy)

Returns a list of work items (Maximum 200)

getWorkItemsBatch(WorkItemBatchGetRequest, string)

Gets work items for a list of work item ids (Maximum 200)

getWorkItemStateColors(string[])

INTERNAL ONLY: It will be used for My account work experience. Get the work item type state color for multiple projects

getWorkItemTemplate(string, string, string, Date, WorkItemExpand)

Returns a single work item from a template.

getWorkItemType(string, string)

Returns a work item type definition.

getWorkItemTypeCategories(string)

Get all work item type categories.

getWorkItemTypeCategory(string, string)

Get specific work item type category by name.

getWorkItemTypeColorAndIcons(string[])

INTERNAL ONLY: It is used for color and icon providers. Get the wit type color for multiple projects

getWorkItemTypeColors(string[])

INTERNAL ONLY: It will be used for My account work experience. Get the wit type color for multiple projects

getWorkItemTypeFieldsWithReferences(string, string, WorkItemTypeFieldsExpandLevel)

Get a list of fields for a work item type with detailed references.

getWorkItemTypeFieldWithReferences(string, string, string, WorkItemTypeFieldsExpandLevel)

Get a field for a work item type with detailed references.

getWorkItemTypes(string)

Returns the list of work item types

getWorkItemTypeStates(string, string)

Returns the state names and colors for a work item type.

queryById(string, string, string, boolean, number)

Gets the results of the query given the query ID.

queryByWiql(Wiql, string, string, boolean, number)

Gets the results of the query given its WIQL.

queryWorkItemsForArtifactUris(ArtifactUriQuery, string)

Queries work items linked to a given list of artifact URI.

readReportingRevisionsGet(string, string[], string[], string, Date, boolean, boolean, boolean, boolean, ReportingRevisionsExpand, boolean, number)

Get a batch of work item revisions with the option of including deleted items

readReportingRevisionsPost(ReportingWorkItemRevisionsFilter, string, string, Date, ReportingRevisionsExpand)

Get a batch of work item revisions. This request may be used if your list of fields is large enough that it may run the URL over the length limit.

replaceTemplate(WorkItemTemplate, string, string, string)

Replace template contents

restoreWorkItem(WorkItemDeleteUpdate, number, string)

Restores the deleted work item from Recycle Bin.

searchQueries(string, string, number, QueryExpand, boolean)

Searches all queries the user has access to in the current project

sendMail(SendMailBody, string)

RESTful method to send mail for selected/queried work items.

updateClassificationNode(WorkItemClassificationNode, string, TreeStructureGroup, string)

Update an existing classification node.

updateField(UpdateWorkItemField, string, string)

Update a field.

updateQuery(QueryHierarchyItem, string, string, boolean)

Update a query or a folder. This allows you to update, rename and move queries and folders.

updateWorkItem(JsonPatchDocument, number, string, boolean, boolean, boolean, WorkItemExpand)

Updates a single work item.

updateWorkItemTypeDefinition(WorkItemTypeTemplateUpdateModel, string)

Add/updates a work item type

Constructor Details

WorkItemTrackingRestClient(IVssRestClientOptions)

new WorkItemTrackingRestClient(options: IVssRestClientOptions)

Parameters

Property Details

RESOURCE_AREA_ID

static RESOURCE_AREA_ID: string

Property Value

string

Method Details

createAttachment(any, string, string, string, string)

Uploads an attachment.

function createAttachment(content: any, project?: string, fileName?: string, uploadType?: string, areaPath?: string): Promise<AttachmentReference>

Parameters

content

any

Content to upload

project

string

Project ID or project name

fileName

string

The name of the file

uploadType

string

Attachment upload type: Simple or Chunked

areaPath

string

Target project Area Path

Returns

createField(WorkItemField, string)

Create a new field.

function createField(workItemField: WorkItemField, project?: string): Promise<WorkItemField>

Parameters

workItemField
WorkItemField

New field definition

project

string

Project ID or project name

Returns

Promise<WorkItemField>

createOrUpdateClassificationNode(WorkItemClassificationNode, string, TreeStructureGroup, string)

Create new or update an existing classification node.

function createOrUpdateClassificationNode(postedNode: WorkItemClassificationNode, project: string, structureGroup: TreeStructureGroup, path?: string): Promise<WorkItemClassificationNode>

Parameters

postedNode
WorkItemClassificationNode

Node to create or update.

project

string

Project ID or project name

structureGroup
TreeStructureGroup

Structure group of the classification node, area or iteration.

path

string

Path of the classification node.

Returns

createQuery(QueryHierarchyItem, string, string, boolean)

Creates a query, or moves a query.

function createQuery(postedQuery: QueryHierarchyItem, project: string, query: string, validateWiqlOnly?: boolean): Promise<QueryHierarchyItem>

Parameters

postedQuery
QueryHierarchyItem

The query to create.

project

string

Project ID or project name

query

string

The parent id or path under which the query is to be created.

validateWiqlOnly

boolean

If you only want to validate your WIQL query without actually creating one, set it to true. Default is false.

Returns

createTemplate(WorkItemTemplate, string, string)

Creates a template

function createTemplate(template: WorkItemTemplate, project: string, team: string): Promise<WorkItemTemplate>

Parameters

template
WorkItemTemplate

Template contents

project

string

Project ID or project name

team

string

Team ID or team name

Returns

Promise<WorkItemTemplate>

createWorkItem(JsonPatchDocument, string, string, boolean, boolean, boolean, WorkItemExpand)

Creates a single work item.

function createWorkItem(document: JsonPatchDocument, project: string, type: string, validateOnly?: boolean, bypassRules?: boolean, suppressNotifications?: boolean, expand?: WorkItemExpand): Promise<WorkItem>

Parameters

document
JsonPatchDocument

The JSON Patch document representing the work item

project

string

Project ID or project name

type

string

The work item type of the work item to create

validateOnly

boolean

Indicate if you only want to validate the changes without saving the work item

bypassRules

boolean

Do not enforce the work item type rules on this update

suppressNotifications

boolean

Do not fire any notifications for this change

expand
WorkItemExpand

The expand parameters for work item attributes. Possible options are { None, Relations, Fields, Links, All }.

Returns

Promise<WorkItem>

deleteClassificationNode(string, TreeStructureGroup, string, number)

Delete an existing classification node.

function deleteClassificationNode(project: string, structureGroup: TreeStructureGroup, path?: string, reclassifyId?: number): Promise<void>

Parameters

project

string

Project ID or project name

structureGroup
TreeStructureGroup

Structure group of the classification node, area or iteration.

path

string

Path of the classification node.

reclassifyId

number

Id of the target classification node for reclassification.

Returns

Promise<void>

deleteField(string, string)

Deletes the field. To undelete a filed, see "Update Field" API.

function deleteField(fieldNameOrRefName: string, project?: string): Promise<void>

Parameters

fieldNameOrRefName

string

Field simple name or reference name

project

string

Project ID or project name

Returns

Promise<void>

deleteQuery(string, string)

Delete a query or a folder. This deletes any permission change on the deleted query or folder and any of its descendants if it is a folder. It is important to note that the deleted permission changes cannot be recovered upon undeleting the query or folder.

function deleteQuery(project: string, query: string): Promise<void>

Parameters

project

string

Project ID or project name

query

string

ID or path of the query or folder to delete.

Returns

Promise<void>

deleteTemplate(string, string, string)

Deletes the template with given id

function deleteTemplate(project: string, team: string, templateId: string): Promise<void>

Parameters

project

string

Project ID or project name

team

string

Team ID or team name

templateId

string

Template id

Returns

Promise<void>

deleteWorkItem(number, string, boolean)

Deletes the specified work item and sends it to the Recycle Bin, so that it can be restored back, if required. Optionally, if the destroy parameter has been set to true, it destroys the work item permanently. WARNING: If the destroy parameter is set to true, work items deleted by this command will NOT go to recycle-bin and there is no way to restore/recover them after deletion. It is recommended NOT to use this parameter. If you do, please use this parameter with extreme caution.

function deleteWorkItem(id: number, project?: string, destroy?: boolean): Promise<WorkItemDelete>

Parameters

id

number

ID of the work item to be deleted

project

string

Project ID or project name

destroy

boolean

Optional parameter, if set to true, the work item is deleted permanently. Please note: the destroy action is PERMANENT and cannot be undone.

Returns

Promise<WorkItemDelete>

destroyWorkItem(number, string)

Destroys the specified work item permanently from the Recycle Bin. This action can not be undone.

function destroyWorkItem(id: number, project?: string): Promise<void>

Parameters

id

number

ID of the work item to be destroyed permanently

project

string

Project ID or project name

Returns

Promise<void>

exportWorkItemTypeDefinition(string, string, boolean)

Export work item type

function exportWorkItemTypeDefinition(project?: string, type?: string, exportGlobalLists?: boolean): Promise<WorkItemTypeTemplate>

Parameters

project

string

Project ID or project name

type

string

exportGlobalLists

boolean

Returns

getAccountMyWorkData(QueryOption)

INTERNAL ONLY: USED BY ACCOUNT MY WORK PAGE. This returns Doing, Done, Follows and activity work items details.

function getAccountMyWorkData(queryOption?: QueryOption): Promise<AccountMyWorkResult>

Parameters

queryOption
QueryOption

Returns

getAttachmentContent(string, string, string, boolean)

Downloads an attachment.

function getAttachmentContent(id: string, project?: string, fileName?: string, download?: boolean): Promise<ArrayBuffer>

Parameters

id

string

Attachment ID

project

string

Project ID or project name

fileName

string

Name of the file

download

boolean

If set to <c>true</c> always download attachment

Returns

Promise<ArrayBuffer>

getAttachmentZip(string, string, string, boolean)

Downloads an attachment.

function getAttachmentZip(id: string, project?: string, fileName?: string, download?: boolean): Promise<ArrayBuffer>

Parameters

id

string

Attachment ID

project

string

Project ID or project name

fileName

string

Name of the file

download

boolean

If set to <c>true</c> always download attachment

Returns

Promise<ArrayBuffer>

getClassificationNode(string, TreeStructureGroup, string, number)

Gets the classification node for a given node path.

function getClassificationNode(project: string, structureGroup: TreeStructureGroup, path?: string, depth?: number): Promise<WorkItemClassificationNode>

Parameters

project

string

Project ID or project name

structureGroup
TreeStructureGroup

Structure group of the classification node, area or iteration.

path

string

Path of the classification node.

depth

number

Depth of children to fetch.

Returns

getClassificationNodes(string, number[], number, ClassificationNodesErrorPolicy)

Gets root classification nodes or list of classification nodes for a given list of nodes ids, for a given project. In case ids parameter is supplied you will get list of classification nodes for those ids. Otherwise you will get root classification nodes for this project.

function getClassificationNodes(project: string, ids: number[], depth?: number, errorPolicy?: ClassificationNodesErrorPolicy): Promise<WorkItemClassificationNode[]>

Parameters

project

string

Project ID or project name

ids

number[]

Comma separated integer classification nodes ids. It's not required, if you want root nodes.

depth

number

Depth of children to fetch.

errorPolicy
ClassificationNodesErrorPolicy

Flag to handle errors in getting some nodes. Possible options are Fail and Omit.

Returns

getComment(number, number, string)

Gets a comment for a work item at the specified revision.

function getComment(id: number, revision: number, project?: string): Promise<WorkItemComment>

Parameters

id

number

Work item id

revision

number

Revision for which the comment need to be fetched

project

string

Project ID or project name

Returns

Promise<WorkItemComment>

getComments(number, string, number, number, CommentSortOrder)

Gets the specified number of comments for a work item from the specified revision.

function getComments(id: number, project?: string, fromRevision?: number, top?: number, order?: CommentSortOrder): Promise<WorkItemComments>

Parameters

id

number

Work item id

project

string

Project ID or project name

fromRevision

number

Revision from which comments are to be fetched (default is 1)

top

number

The number of comments to return (default is 200)

order
CommentSortOrder

Ascending or descending by revision id (default is ascending)

Returns

Promise<WorkItemComments>

getDeletedWorkItem(number, string)

Gets a deleted work item from Recycle Bin.

function getDeletedWorkItem(id: number, project?: string): Promise<WorkItemDelete>

Parameters

id

number

ID of the work item to be returned

project

string

Project ID or project name

Returns

Promise<WorkItemDelete>

getDeletedWorkItems(number[], string)

Gets the work items from the recycle bin, whose IDs have been specified in the parameters

function getDeletedWorkItems(ids: number[], project?: string): Promise<WorkItemDeleteReference[]>

Parameters

ids

number[]

Comma separated list of IDs of the deleted work items to be returned

project

string

Project ID or project name

Returns

getDeletedWorkItemShallowReferences(string)

Gets a list of the IDs and the URLs of the deleted the work items in the Recycle Bin.

function getDeletedWorkItemShallowReferences(project?: string): Promise<WorkItemDeleteShallowReference[]>

Parameters

project

string

Project ID or project name

Returns

getField(string, string)

Gets information on a specific field.

function getField(fieldNameOrRefName: string, project?: string): Promise<WorkItemField>

Parameters

fieldNameOrRefName

string

Field simple name or reference name

project

string

Project ID or project name

Returns

Promise<WorkItemField>

getFields(string, GetFieldsExpand)

Returns information for all fields. The project ID/name parameter is optional.

function getFields(project?: string, expand?: GetFieldsExpand): Promise<WorkItemField[]>

Parameters

project

string

Project ID or project name

expand
GetFieldsExpand

Use ExtensionFields to include extension fields, otherwise exclude them. Unless the feature flag for this parameter is enabled, extension fields are always included.

Returns

Promise<WorkItemField[]>

getQueries(string, QueryExpand, number, boolean)

Gets the root queries and their children

function getQueries(project: string, expand?: QueryExpand, depth?: number, includeDeleted?: boolean): Promise<QueryHierarchyItem[]>

Parameters

project

string

Project ID or project name

expand
QueryExpand

Include the query string (wiql), clauses, query result columns, and sort options in the results.

depth

number

In the folder of queries, return child queries and folders to this depth.

includeDeleted

boolean

Include deleted queries and folders

Returns

Promise<QueryHierarchyItem[]>

getQueriesBatch(QueryBatchGetRequest, string)

Gets a list of queries by ids (Maximum 1000)

function getQueriesBatch(queryGetRequest: QueryBatchGetRequest, project: string): Promise<QueryHierarchyItem[]>

Parameters

queryGetRequest
QueryBatchGetRequest
project

string

Project ID or project name

Returns

Promise<QueryHierarchyItem[]>

getQuery(string, string, QueryExpand, number, boolean, boolean)

Retrieves an individual query and its children

function getQuery(project: string, query: string, expand?: QueryExpand, depth?: number, includeDeleted?: boolean, useIsoDateFormat?: boolean): Promise<QueryHierarchyItem>

Parameters

project

string

Project ID or project name

query

string

ID or path of the query.

expand
QueryExpand

Include the query string (wiql), clauses, query result columns, and sort options in the results.

depth

number

In the folder of queries, return child queries and folders to this depth.

includeDeleted

boolean

Include deleted queries and folders

useIsoDateFormat

boolean

DateTime query clauses will be formatted using a ISO 8601 compliant format

Returns

getQueryResultCount(string, string, string, boolean, number)

Gets the results of the query given the query ID.

function getQueryResultCount(id: string, project?: string, team?: string, timePrecision?: boolean, top?: number): Promise<number>

Parameters

id

string

The query ID.

project

string

Project ID or project name

team

string

Team ID or team name

timePrecision

boolean

Whether or not to use time precision.

top

number

The max number of results to return.

Returns

Promise<number>

getRecentActivityData()

Gets recent work item activities

function getRecentActivityData(): Promise<AccountRecentActivityWorkItemModel2[]>

Returns

getRecentMentions()

INTERNAL ONLY: USED BY ACCOUNT MY WORK PAGE.

function getRecentMentions(): Promise<AccountRecentMentionWorkItemModel[]>

Returns

getRelationType(string)

Gets the work item relation type definition.

function getRelationType(relation: string): Promise<WorkItemRelationType>

Parameters

relation

string

The relation name

Returns

getRelationTypes()

Gets the work item relation types.

function getRelationTypes(): Promise<WorkItemRelationType[]>

Returns

getReportingLinksByLinkType(string, string[], string[], string, Date)

Get a batch of work item links

function getReportingLinksByLinkType(project?: string, linkTypes?: string[], types?: string[], continuationToken?: string, startDateTime?: Date): Promise<ReportingWorkItemLinksBatch>

Parameters

project

string

Project ID or project name

linkTypes

string[]

A list of types to filter the results to specific link types. Omit this parameter to get work item links of all link types.

types

string[]

A list of types to filter the results to specific work item types. Omit this parameter to get work item links of all work item types.

continuationToken

string

Specifies the continuationToken to start the batch from. Omit this parameter to get the first batch of links.

startDateTime

Date

Date/time to use as a starting point for link changes. Only link changes that occurred after that date/time will be returned. Cannot be used in conjunction with 'watermark' parameter.

Returns

getRevision(number, number, string, WorkItemExpand)

Returns a fully hydrated work item for the requested revision

function getRevision(id: number, revisionNumber: number, project?: string, expand?: WorkItemExpand): Promise<WorkItem>

Parameters

id

number

revisionNumber

number

project

string

Project ID or project name

Returns

Promise<WorkItem>

getRevisions(number, string, number, number, WorkItemExpand)

Returns the list of fully hydrated work item revisions, paged.

function getRevisions(id: number, project?: string, top?: number, skip?: number, expand?: WorkItemExpand): Promise<WorkItem[]>

Parameters

id

number

project

string

Project ID or project name

top

number

skip

number

Returns

Promise<WorkItem[]>

getRootNodes(string, number)

Gets root classification nodes under the project.

function getRootNodes(project: string, depth?: number): Promise<WorkItemClassificationNode[]>

Parameters

project

string

Project ID or project name

depth

number

Depth of children to fetch.

Returns

getTemplate(string, string, string)

Gets the template with specified id

function getTemplate(project: string, team: string, templateId: string): Promise<WorkItemTemplate>

Parameters

project

string

Project ID or project name

team

string

Team ID or team name

templateId

string

Template Id

Returns

Promise<WorkItemTemplate>

getTemplates(string, string, string)

Gets template

function getTemplates(project: string, team: string, workitemtypename?: string): Promise<WorkItemTemplateReference[]>

Parameters

project

string

Project ID or project name

team

string

Team ID or team name

workitemtypename

string

Optional, When specified returns templates for given Work item type.

Returns

getUpdate(number, number, string)

Returns a single update for a work item

function getUpdate(id: number, updateNumber: number, project?: string): Promise<WorkItemUpdate>

Parameters

id

number

updateNumber

number

project

string

Project ID or project name

Returns

Promise<WorkItemUpdate>

getUpdates(number, string, number, number)

Returns the deltas between work item revisions

function getUpdates(id: number, project?: string, top?: number, skip?: number): Promise<WorkItemUpdate[]>

Parameters

id

number

project

string

Project ID or project name

top

number

skip

number

Returns

Promise<WorkItemUpdate[]>

getWorkArtifactLinkTypes()

Get the list of work item tracking outbound artifact link types.

function getWorkArtifactLinkTypes(): Promise<WorkArtifactLink[]>

Returns

Promise<WorkArtifactLink[]>

getWorkItem(number, string, string[], Date, WorkItemExpand)

Returns a single work item.

function getWorkItem(id: number, project?: string, fields?: string[], asOf?: Date, expand?: WorkItemExpand): Promise<WorkItem>

Parameters

id

number

The work item id

project

string

Project ID or project name

fields

string[]

Comma-separated list of requested fields

asOf

Date

AsOf UTC date time string

expand
WorkItemExpand

The expand parameters for work item attributes. Possible options are { None, Relations, Fields, Links, All }.

Returns

Promise<WorkItem>

getWorkItemIconJson(string, string, number)

Get a work item icon given the friendly name and icon color.

function getWorkItemIconJson(icon: string, color?: string, v?: number): Promise<WorkItemIcon>

Parameters

icon

string

The name of the icon

color

string

The 6-digit hex color for the icon

v

number

The version of the icon (used only for cache invalidation)

Returns

Promise<WorkItemIcon>

getWorkItemIcons()

Get a list of all work item icons.

function getWorkItemIcons(): Promise<WorkItemIcon[]>

Returns

Promise<WorkItemIcon[]>

getWorkItemIconSvg(string, string, number)

Get a work item icon given the friendly name and icon color.

function getWorkItemIconSvg(icon: string, color?: string, v?: number): Promise<any>

Parameters

icon

string

The name of the icon

color

string

The 6-digit hex color for the icon

v

number

The version of the icon (used only for cache invalidation)

Returns

Promise<any>

getWorkItemIconXaml(string, string, number)

Get a work item icon given the friendly name and icon color.

function getWorkItemIconXaml(icon: string, color?: string, v?: number): Promise<any>

Parameters

icon

string

The name of the icon

color

string

The 6-digit hex color for the icon

v

number

The version of the icon (used only for cache invalidation)

Returns

Promise<any>

getWorkItemNextStatesOnCheckinAction(number[], string)

Returns the next state on the given work item IDs.

function getWorkItemNextStatesOnCheckinAction(ids: number[], action?: string): Promise<WorkItemNextStateOnTransition[]>

Parameters

ids

number[]

list of work item ids

action

string

possible actions. Currently only supports checkin

Returns

getWorkItems(number[], string, string[], Date, WorkItemExpand, WorkItemErrorPolicy)

Returns a list of work items (Maximum 200)

function getWorkItems(ids: number[], project?: string, fields?: string[], asOf?: Date, expand?: WorkItemExpand, errorPolicy?: WorkItemErrorPolicy): Promise<WorkItem[]>

Parameters

ids

number[]

The comma-separated list of requested work item ids. (Maximum 200 ids allowed).

project

string

Project ID or project name

fields

string[]

Comma-separated list of requested fields

asOf

Date

AsOf UTC date time string

expand
WorkItemExpand

The expand parameters for work item attributes. Possible options are { None, Relations, Fields, Links, All }.

errorPolicy
WorkItemErrorPolicy

The flag to control error policy in a bulk get work items request. Possible options are {Fail, Omit}.

Returns

Promise<WorkItem[]>

getWorkItemsBatch(WorkItemBatchGetRequest, string)

Gets work items for a list of work item ids (Maximum 200)

function getWorkItemsBatch(workItemGetRequest: WorkItemBatchGetRequest, project?: string): Promise<WorkItem[]>

Parameters

workItemGetRequest
WorkItemBatchGetRequest
project

string

Project ID or project name

Returns

Promise<WorkItem[]>

getWorkItemStateColors(string[])

INTERNAL ONLY: It will be used for My account work experience. Get the work item type state color for multiple projects

function getWorkItemStateColors(projectNames: string[]): Promise<ProjectWorkItemStateColors[]>

Parameters

projectNames

string[]

Returns

getWorkItemTemplate(string, string, string, Date, WorkItemExpand)

Returns a single work item from a template.

function getWorkItemTemplate(project: string, type: string, fields?: string, asOf?: Date, expand?: WorkItemExpand): Promise<WorkItem>

Parameters

project

string

Project ID or project name

type

string

The work item type name

fields

string

Comma-separated list of requested fields

asOf

Date

AsOf UTC date time string

expand
WorkItemExpand

The expand parameters for work item attributes. Possible options are { None, Relations, Fields, Links, All }.

Returns

Promise<WorkItem>

getWorkItemType(string, string)

Returns a work item type definition.

function getWorkItemType(project: string, type: string): Promise<WorkItemType>

Parameters

project

string

Project ID or project name

type

string

Work item type name

Returns

Promise<WorkItemType>

getWorkItemTypeCategories(string)

Get all work item type categories.

function getWorkItemTypeCategories(project: string): Promise<WorkItemTypeCategory[]>

Parameters

project

string

Project ID or project name

Returns

getWorkItemTypeCategory(string, string)

Get specific work item type category by name.

function getWorkItemTypeCategory(project: string, category: string): Promise<WorkItemTypeCategory>

Parameters

project

string

Project ID or project name

category

string

The category name

Returns

getWorkItemTypeColorAndIcons(string[])

INTERNAL ONLY: It is used for color and icon providers. Get the wit type color for multiple projects

function getWorkItemTypeColorAndIcons(projectNames: string[]): Promise<{ key: string, value: WorkItemTypeColorAndIcon[] }[]>

Parameters

projectNames

string[]

Returns

Promise<{ key: string, value: WorkItemTypeColorAndIcon[] }[]>

getWorkItemTypeColors(string[])

INTERNAL ONLY: It will be used for My account work experience. Get the wit type color for multiple projects

function getWorkItemTypeColors(projectNames: string[]): Promise<{ key: string, value: WorkItemTypeColor[] }[]>

Parameters

projectNames

string[]

Returns

Promise<{ key: string, value: WorkItemTypeColor[] }[]>

getWorkItemTypeFieldsWithReferences(string, string, WorkItemTypeFieldsExpandLevel)

Get a list of fields for a work item type with detailed references.

function getWorkItemTypeFieldsWithReferences(project: string, type: string, expand?: WorkItemTypeFieldsExpandLevel): Promise<WorkItemTypeFieldWithReferences[]>

Parameters

project

string

Project ID or project name

type

string

Work item type.

expand
WorkItemTypeFieldsExpandLevel

Expand level for the API response. Properties: to include allowedvalues, default value, isRequired etc. as a part of response; None: to skip these properties.

Returns

getWorkItemTypeFieldWithReferences(string, string, string, WorkItemTypeFieldsExpandLevel)

Get a field for a work item type with detailed references.

function getWorkItemTypeFieldWithReferences(project: string, type: string, field: string, expand?: WorkItemTypeFieldsExpandLevel): Promise<WorkItemTypeFieldWithReferences>

Parameters

project

string

Project ID or project name

type

string

Work item type.

field

string

expand
WorkItemTypeFieldsExpandLevel

Expand level for the API response. Properties: to include allowedvalues, default value, isRequired etc. as a part of response; None: to skip these properties.

Returns

getWorkItemTypes(string)

Returns the list of work item types

function getWorkItemTypes(project: string): Promise<WorkItemType[]>

Parameters

project

string

Project ID or project name

Returns

Promise<WorkItemType[]>

getWorkItemTypeStates(string, string)

Returns the state names and colors for a work item type.

function getWorkItemTypeStates(project: string, type: string): Promise<WorkItemStateColor[]>

Parameters

project

string

Project ID or project name

type

string

The state name

Returns

Promise<WorkItemStateColor[]>

queryById(string, string, string, boolean, number)

Gets the results of the query given the query ID.

function queryById(id: string, project?: string, team?: string, timePrecision?: boolean, top?: number): Promise<WorkItemQueryResult>

Parameters

id

string

The query ID.

project

string

Project ID or project name

team

string

Team ID or team name

timePrecision

boolean

Whether or not to use time precision.

top

number

The max number of results to return.

Returns

queryByWiql(Wiql, string, string, boolean, number)

Gets the results of the query given its WIQL.

function queryByWiql(wiql: Wiql, project?: string, team?: string, timePrecision?: boolean, top?: number): Promise<WorkItemQueryResult>

Parameters

wiql
Wiql

The query containing the WIQL.

project

string

Project ID or project name

team

string

Team ID or team name

timePrecision

boolean

Whether or not to use time precision.

top

number

The max number of results to return.

Returns

queryWorkItemsForArtifactUris(ArtifactUriQuery, string)

Queries work items linked to a given list of artifact URI.

function queryWorkItemsForArtifactUris(artifactUriQuery: ArtifactUriQuery, project?: string): Promise<ArtifactUriQueryResult>

Parameters

artifactUriQuery
ArtifactUriQuery

Defines a list of artifact URI for querying work items.

project

string

Project ID or project name

Returns

readReportingRevisionsGet(string, string[], string[], string, Date, boolean, boolean, boolean, boolean, ReportingRevisionsExpand, boolean, number)

Get a batch of work item revisions with the option of including deleted items

function readReportingRevisionsGet(project?: string, fields?: string[], types?: string[], continuationToken?: string, startDateTime?: Date, includeIdentityRef?: boolean, includeDeleted?: boolean, includeTagRef?: boolean, includeLatestOnly?: boolean, expand?: ReportingRevisionsExpand, includeDiscussionChangesOnly?: boolean, maxPageSize?: number): Promise<ReportingWorkItemRevisionsBatch>

Parameters

project

string

Project ID or project name

fields

string[]

A list of fields to return in work item revisions. Omit this parameter to get all reportable fields.

types

string[]

A list of types to filter the results to specific work item types. Omit this parameter to get work item revisions of all work item types.

continuationToken

string

Specifies the watermark to start the batch from. Omit this parameter to get the first batch of revisions.

startDateTime

Date

Date/time to use as a starting point for revisions, all revisions will occur after this date/time. Cannot be used in conjunction with 'watermark' parameter.

includeIdentityRef

boolean

Return an identity reference instead of a string value for identity fields.

includeDeleted

boolean

Specify if the deleted item should be returned.

includeTagRef

boolean

Specify if the tag objects should be returned for System.Tags field.

includeLatestOnly

boolean

Return only the latest revisions of work items, skipping all historical revisions

expand
ReportingRevisionsExpand

Return all the fields in work item revisions, including long text fields which are not returned by default

includeDiscussionChangesOnly

boolean

Return only the those revisions of work items, where only history field was changed

maxPageSize

number

The maximum number of results to return in this batch

Returns

readReportingRevisionsPost(ReportingWorkItemRevisionsFilter, string, string, Date, ReportingRevisionsExpand)

Get a batch of work item revisions. This request may be used if your list of fields is large enough that it may run the URL over the length limit.

function readReportingRevisionsPost(filter: ReportingWorkItemRevisionsFilter, project?: string, continuationToken?: string, startDateTime?: Date, expand?: ReportingRevisionsExpand): Promise<ReportingWorkItemRevisionsBatch>

Parameters

filter
ReportingWorkItemRevisionsFilter

An object that contains request settings: field filter, type filter, identity format

project

string

Project ID or project name

continuationToken

string

Specifies the watermark to start the batch from. Omit this parameter to get the first batch of revisions.

startDateTime

Date

Date/time to use as a starting point for revisions, all revisions will occur after this date/time. Cannot be used in conjunction with 'watermark' parameter.

Returns

replaceTemplate(WorkItemTemplate, string, string, string)

Replace template contents

function replaceTemplate(templateContent: WorkItemTemplate, project: string, team: string, templateId: string): Promise<WorkItemTemplate>

Parameters

templateContent
WorkItemTemplate

Template contents to replace with

project

string

Project ID or project name

team

string

Team ID or team name

templateId

string

Template id

Returns

Promise<WorkItemTemplate>

restoreWorkItem(WorkItemDeleteUpdate, number, string)

Restores the deleted work item from Recycle Bin.

function restoreWorkItem(payload: WorkItemDeleteUpdate, id: number, project?: string): Promise<WorkItemDelete>

Parameters

payload
WorkItemDeleteUpdate

Paylod with instructions to update the IsDeleted flag to false

id

number

ID of the work item to be restored

project

string

Project ID or project name

Returns

Promise<WorkItemDelete>

searchQueries(string, string, number, QueryExpand, boolean)

Searches all queries the user has access to in the current project

function searchQueries(project: string, filter: string, top?: number, expand?: QueryExpand, includeDeleted?: boolean): Promise<QueryHierarchyItemsResult>

Parameters

project

string

Project ID or project name

filter

string

The text to filter the queries with.

top

number

The number of queries to return (Default is 50 and maximum is 200).

expand
QueryExpand
includeDeleted

boolean

Include deleted queries and folders

Returns

sendMail(SendMailBody, string)

RESTful method to send mail for selected/queried work items.

function sendMail(body: SendMailBody, project?: string): Promise<void>

Parameters

project

string

Project ID or project name

Returns

Promise<void>

updateClassificationNode(WorkItemClassificationNode, string, TreeStructureGroup, string)

Update an existing classification node.

function updateClassificationNode(postedNode: WorkItemClassificationNode, project: string, structureGroup: TreeStructureGroup, path?: string): Promise<WorkItemClassificationNode>

Parameters

postedNode
WorkItemClassificationNode

Node to create or update.

project

string

Project ID or project name

structureGroup
TreeStructureGroup

Structure group of the classification node, area or iteration.

path

string

Path of the classification node.

Returns

updateField(UpdateWorkItemField, string, string)

Update a field.

function updateField(payload: UpdateWorkItemField, fieldNameOrRefName: string, project?: string): Promise<WorkItemField>

Parameters

payload
UpdateWorkItemField

Payload contains desired value of the field's properties

fieldNameOrRefName

string

Name/reference name of the field to be updated

project

string

Project ID or project name

Returns

Promise<WorkItemField>

updateQuery(QueryHierarchyItem, string, string, boolean)

Update a query or a folder. This allows you to update, rename and move queries and folders.

function updateQuery(queryUpdate: QueryHierarchyItem, project: string, query: string, undeleteDescendants?: boolean): Promise<QueryHierarchyItem>

Parameters

queryUpdate
QueryHierarchyItem

The query to update.

project

string

Project ID or project name

query

string

The ID or path for the query to update.

undeleteDescendants

boolean

Undelete the children of this folder. It is important to note that this will not bring back the permission changes that were previously applied to the descendants.

Returns

updateWorkItem(JsonPatchDocument, number, string, boolean, boolean, boolean, WorkItemExpand)

Updates a single work item.

function updateWorkItem(document: JsonPatchDocument, id: number, project?: string, validateOnly?: boolean, bypassRules?: boolean, suppressNotifications?: boolean, expand?: WorkItemExpand): Promise<WorkItem>

Parameters

document
JsonPatchDocument

The JSON Patch document representing the update

id

number

The id of the work item to update

project

string

Project ID or project name

validateOnly

boolean

Indicate if you only want to validate the changes without saving the work item

bypassRules

boolean

Do not enforce the work item type rules on this update

suppressNotifications

boolean

Do not fire any notifications for this change

expand
WorkItemExpand

The expand parameters for work item attributes. Possible options are { None, Relations, Fields, Links, All }.

Returns

Promise<WorkItem>

updateWorkItemTypeDefinition(WorkItemTypeTemplateUpdateModel, string)

Add/updates a work item type

function updateWorkItemTypeDefinition(updateModel: WorkItemTypeTemplateUpdateModel, project?: string): Promise<ProvisioningResult>

Parameters

project

string

Project ID or project name

Returns