Last Update: 6/21/2017

Work Item Form Service

This API is in private preview and subject to change.

The work item form service allows you to interact with the currently active work item form. You can use the service to get or update the work item data that is currently displayed in the work item form UI from your extension. Service functions Will throw an error when there is no open work item.

See Work Item Tracking REST APIs, if you want to interact with work items that are not in view.

Example

    // Get work item form service
    VSS.require(["TFS/WorkItemTracking/Services"], function(workItemServices) {
        workItemServices.WorkItemFormService.getService().then(function (workItemFormSvc) {
            if(workItemFormSvc.hasActiveWorkItem()) {
                console.log("Active work item is available.");
            }
            else {
                console.log("Active work item is NOT available.");
            }
        });
    });

See a full example in the work-item-form sample extension found in the vsts-extension-samples repository.

Methods

hasActiveWorkItem()

Returns true if active work item is available.

Syntax

 IPromise<boolean> hasActiveWorkItem()

Returns

  • IPromise<boolean>. A promise that returns a boolean value indicates whether the active work item is available.

getId()

Gets the id of active work item.

Syntax

 IPromise<number> getId()

Returns

  • IPromise<number>. A promise that returns the active work item id.

getRevision()

Gets the active work item's latest revision.

Syntax

 IPromise<number> getRevision()

Returns

  • IPromise<number>. A promise that returns the active work item's latest revision id.

getFields()

Gets the active work item fields.

Syntax

 IPromise<WorkItemField[]> getFields()

Returns

getFieldValue()

Gets field value of active work item.

Syntax

 IPromise<Object> getFieldValue(fieldReferenceName, returnOriginalValue)

Parameters

  • fieldReferenceName: string. Field reference name.
  • returnOriginalValue: boolean. Optional. If false, gets the unsaved field values. Default is false.

Returns

  • IPromise<Object>. A promise that returns the value of the work item field.

getFieldValues()

Gets field values of active work item.

Syntax

 IPromise<IDictionaryStringTo<Object>> getFieldValues(fieldReferenceNames, returnOriginalValue)

Parameters

  • fieldReferenceNames: string[]. An arrary of field reference names.
  • returnOriginalValue: boolean. Optional. If false, gets unsaved field values. Default is false.

Returns

  • IPromise<IDictionaryStringTo<Object>>. A promise that returns a dictionary of work item field values (refName to values pairs).

setFieldValue()

Sets field value of active work item.

Syntax

 IPromise<boolean> setFieldValue(fieldReferenceName, value)

Parameters

  • fieldReferenceName: string. Field reference name.
  • value: Object. Field value.

Returns

  • IPromise<boolean>. A promise that returns a boolean value indicates whether the function completed successfully.

setFieldValues()

Sets field values of the work item.

Syntax

 IPromise<IDictionaryStringTo<boolean>> setFieldValues(fields)

Parameters

  • fields: IDictionaryStringTo. A dictionary of field reference name/value.

Returns

  • IPromise<IDictionaryStringTo<boolean>>. A promise that returns a dictionary of field value update results (refName to results pairs).

getAllowedFieldValues()

Gets the allowed values for the field on active work item.

Syntax

 IPromise<Object[]> getAllowedFieldValues(fieldReferenceName)

Parameters

  • fieldReferenceName: string. Field reference name.

Returns

  • IPromise<Object[]>. A promise that returns an array of allowed values.

isDirty()

Returns true if active work item is dirty.

Syntax

 IPromise<boolean> isDirty()

Returns

  • IPromise<boolean>. A promise that returns a boolean value indicates whether the active work item is dirty.

isNew()

Returns true if active work item is new.

Syntax

 IPromise<boolean> isNew()

Returns

  • IPromise<boolean>. A promise that returns a boolean value indicates whether the active work item is new.

isValid()

Returns true if active work item fields are all valid.

Syntax

 IPromise<boolean> isValid()

Returns

  • IPromise<boolean>. A promise that returns a boolean value indicates whether all field values are valid.

getInvalidFields()

Gets invalid fields who are in an invalid state according to the work item rules. These fields need to be changed before the work item can be saved.

Syntax

 IPromise<WorkItemField[]> getInvalidFields()

Returns

addWorkItemRelations()

Adds links of another work items or artifacts (e.g. commits, hyperlinks) to the work item. Attachment is currently not supported by this function. Please see Work Item Tracking REST APIs for alternatives of updating work item attachments.

Syntax

 IPromise<void> addWorkItemRelations(workItemRelations)

Parameters

Returns

removeWorkItemRelations()

Removes links to another work items or artifacts (e.g. commits, hyperlinks) from the work item. Attachment is currently not supported by this function. Please see Work Item Tracking REST APIs for alternatives of updating work item attachments.

Syntax

 IPromise<void> removeWorkItemRelations(workItemRelations)

Parameters

Returns

getWorkItemRelations()

Returns an array of the work item's links to another work items or artifacts (e.g. commits, hyperlinks). Attachment is currently not supported by this function. Please see Work Item Tracking REST APIs for alternatives of updating work item attachments.

Syntax

 IPromise<WorkItemRelation[]> getWorkItemRelations()

Returns

getWorkItemResourceUrl()

Returns the REST url of the specified work item resource.

Syntax

 IPromise<string> getWorkItemResourceUrl(workItemId)

Parameters

  • workItemId: number. The id of the work item that the resource url is requested for.

Returns

  • IPromise<string>. A promise that returns the REST url of the specified work item resource.

getWorkItemRelationTypes()

Returns an array of work item relation types.

Syntax

 IPromise<WorkItemRelationType[]> getWorkItemRelationTypes()

Returns

save()

Saves the work item.

Syntax

 IPromise<void> save()

Returns

  • IPromise<void>. A promise that is resolved after the work item save succeeds, and rejected if the work item save fails or if the work item form has errors.

refresh()

Refresh the workitem. Will prompt user for confirmation if the work item is dirty.

Syntax

 IPromise<void> refresh()

Returns

reset()

Reset the work item. Revert all work item changes if the user confirms.

Syntax

 IPromise<void> reset()

Returns

setError()

Sets a specified error on the work item form and marks the work item as invalid.

Syntax

 IPromise<void> setError(errorMessage)

Returns

clearError()

Clears the error set by setError method and marks the work item as valid if there are no other errors on the form.

Syntax

 IPromise<void> clearError()

Returns