IWorkItemFormService interface
Host service for interacting with the currently active work item form (work item currently displayed in the UI). Form service depends on the current active work item context. Will throw an error when there is no open work item.
Methods
| add |
Adds links of another work items or artifacts (e.g. commits, hyperlinks) to the work item. Attachment is currently not supported by this function. |
| begin |
@deprecated: Please use save |
| clear |
Clears the error set by setError method and unblocks saving of the work item in the form. |
| get |
Gets the allowed values for the field on the active work item. |
| get |
Gets fields that have been changed either by user or by a work item rule and are in a dirty state. |
| get |
Gets active work item fields. |
| get |
Gets field value of the active work item. |
| get |
Gets field value of the active work item. |
| get |
Gets field values of the active work item. |
| get |
Gets field values of the active work item. |
| get |
Gets id of active work item. |
| get |
Gets identity field value of the active work item. |
| get |
Gets 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. |
| get |
Gets active work item's latest revision. |
| get |
Returns an array of work item links to other work items or artifacts (e.g. commits, hyperlinks). Attachment is currently not supported by this function. |
| get |
Returns an array of work item relation types. |
| get |
Returns the REST API url of the specified work item resource. |
| has |
Returns true if the active work item available. |
| is |
Returns true if the active work item is dirty. |
| is |
Returns true if the active work item is new. |
| is |
Returns true if the active work item fields are all valid. |
| refresh() | Refreshes the active work item. Will prompt the user if the work item is dirty. |
| remove |
Removes links to another work items or artifacts (e.g. commits, hyperlinks) from the work item. Attachment is currently not supported by this function. |
| reset() | Reset any changes in the active work item. Will prompt the user to confirm. |
| save() | Saves the active work item. |
| set |
Marks the work item as invalid and disable saving the work item on the form. |
| set |
Sets field value of the active work item. |
| set |
Sets field values of the active work item. |
Method Details
addWorkItemRelations(WorkItemRelation[])
Adds links of another work items or artifacts (e.g. commits, hyperlinks) to the work item. Attachment is currently not supported by this function.
function addWorkItemRelations(workItemRelations: WorkItemRelation[]): Promise<void>Parameters
- workItemRelations
Work item links to add.
Returns
Promise<void>
An empty promise.
beginSaveWorkItem(() => void, () => void)
@deprecated: Please use save
function beginSaveWorkItem(successCallback: () => void, errorCallback: () => void): Promise<void>Parameters
- successCallback
-
() => void
- errorCallback
-
() => void
Returns
Promise<void>
clearError()
Clears the error set by setError method and unblocks saving of the work item in the form.
function clearError(): Promise<void>Returns
Promise<void>
getAllowedFieldValues(string)
Gets the allowed values for the field on the active work item.
function getAllowedFieldValues(fieldReferenceName: string): Promise<Object[]>Parameters
- fieldReferenceName
-
string
Field reference name
Returns
Promise<Object[]>
A promise that returns an array of allowed values.
getDirtyFields(boolean)
Gets fields that have been changed either by user or by a work item rule and are in a dirty state.
function getDirtyFields(includeSystemChanges?: boolean): Promise<WorkItemField[]>Parameters
- includeSystemChanges
-
boolean
A boolean value indicating if the result should include changes set by work item rules.
Returns
Promise<WorkItemField[]>
A promise that returns an array of dirty work item fields.
getFields()
Gets active work item fields.
function getFields(): Promise<WorkItemField[]>Returns
Promise<WorkItemField[]>
A promise that returns an array of work item field.
getFieldValue(string, boolean)
Warning
This API is now deprecated.
Please use options instead of returnOriginalValue
Gets field value of the active work item.
function getFieldValue(fieldReferenceName: string, returnOriginalValue?: boolean): Promise<Object>Parameters
- fieldReferenceName
-
string
Field reference name
- returnOriginalValue
-
boolean
(Optional) If false, gets unsaved field values. Default is false.
Returns
Promise<Object>
A promise that returns the value of the work item field.
getFieldValue(string, WorkItemOptions)
Gets field value of the active work item.
function getFieldValue(fieldReferenceName: string, options?: WorkItemOptions): Promise<Object>Parameters
- fieldReferenceName
-
string
Field reference name
- options
- WorkItemOptions
work item options
Returns
Promise<Object>
A promise that returns the value of the work item field.
getFieldValues(string[], boolean)
Warning
This API is now deprecated.
Please use options instead of returnOriginalValue
Gets field values of the active work item.
function getFieldValues(fieldReferenceNames: string[], returnOriginalValue?: boolean): Promise<{[fieldName: string]: Object}>Parameters
- fieldReferenceNames
-
string[]
An arrary of field reference names
- returnOriginalValue
-
boolean
(Optional) If false, gets unsaved field values. Default is false.
Returns
Promise<{[fieldName: string]: Object}>
A promise that returns a dictionary of work item field values (refName to values pairs).
getFieldValues(string[], WorkItemOptions)
Gets field values of the active work item.
function getFieldValues(fieldReferenceNames: string[], options?: WorkItemOptions): Promise<{[fieldName: string]: Object}>Parameters
- fieldReferenceNames
-
string[]
An arrary of field reference names
- options
- WorkItemOptions
work item options
Returns
Promise<{[fieldName: string]: Object}>
A promise that returns a dictionary of work item field values (refName to values pairs).
getId()
Gets id of active work item.
function getId(): Promise<number>Returns
Promise<number>
A promise that returns the active work item id.
getIdentityFieldValue(string, WorkItemOptions)
Gets identity field value of the active work item.
function getIdentityFieldValue(fieldReferenceName: string, options?: WorkItemOptions): Promise<IdentityRef>Parameters
- fieldReferenceName
-
string
Field reference name
- options
- WorkItemOptions
work item options
Returns
Promise<IdentityRef>
A promise that returns the value of the work item field.
getInvalidFields()
Gets 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.
function getInvalidFields(): Promise<WorkItemField[]>Returns
Promise<WorkItemField[]>
A promise that returns an array of invalid work item fields.
getRevision()
Gets active work item's latest revision.
function getRevision(): Promise<number>Returns
Promise<number>
A promise that returns the active work item's latest revision id.
getWorkItemRelations()
Returns an array of work item links to other work items or artifacts (e.g. commits, hyperlinks). Attachment is currently not supported by this function.
function getWorkItemRelations(): Promise<WorkItemRelation[]>Returns
Promise<WorkItemRelation[]>
A promise that returns an array of work item relations of active work item.
getWorkItemRelationTypes()
Returns an array of work item relation types.
function getWorkItemRelationTypes(): Promise<WorkItemRelationType[]>Returns
Promise<WorkItemRelationType[]>
A promise that returns an array of work item relation types.
getWorkItemResourceUrl(number)
Returns the REST API url of the specified work item resource.
function getWorkItemResourceUrl(workItemId: number): Promise<string>Parameters
- workItemId
-
number
Id of the work item that the resource url is requested for.
Returns
Promise<string>
A promise that returns the requested resource url of the work item.
hasActiveWorkItem()
Returns true if the active work item available.
function hasActiveWorkItem(): Promise<boolean>Returns
Promise<boolean>
A promise that returns a boolean value indicates whether the active work item is available.
isDirty()
Returns true if the active work item is dirty.
function isDirty(): Promise<boolean>Returns
Promise<boolean>
A promise that returns a boolean value indicates whether the active work item is dirty.
isNew()
Returns true if the active work item is new.
function isNew(): Promise<boolean>Returns
Promise<boolean>
A promise that returns a boolean value indicates whether the active work item is new.
isValid()
Returns true if the active work item fields are all valid.
function isValid(): Promise<boolean>Returns
Promise<boolean>
A promise that returns a boolean value indicates whether all field values are valid.
refresh()
Refreshes the active work item. Will prompt the user if the work item is dirty.
function refresh(): Promise<void>Returns
Promise<void>
removeWorkItemRelations(WorkItemRelation[])
Removes links to another work items or artifacts (e.g. commits, hyperlinks) from the work item. Attachment is currently not supported by this function.
function removeWorkItemRelations(workItemRelations: WorkItemRelation[]): Promise<void>Parameters
- workItemRelations
Work item links to remove.
Returns
Promise<void>
An empty promise.
reset()
Reset any changes in the active work item. Will prompt the user to confirm.
function reset(): Promise<void>Returns
Promise<void>
save()
Saves the active work item.
function save(): Promise<void>Returns
Promise<void>
A promise that is resolved if the work item is saved successfully and rejected if it fails.
setError(string)
Marks the work item as invalid and disable saving the work item on the form.
function setError(errorMessage: string): Promise<void>Parameters
- errorMessage
-
string
A custom error message that would be shown on top of the work item form.
Returns
Promise<void>
setFieldValue(string, Object)
Sets field value of the active work item.
function setFieldValue(fieldReferenceName: string, value: Object): Promise<boolean>Parameters
- fieldReferenceName
-
string
Field reference name
- value
-
Object
Field value
Returns
Promise<boolean>
A promise that returns a boolean value indicates whether the function completed successfully.
setFieldValues({[fieldName: string]: Object})
Sets field values of the active work item.
function setFieldValues(fields: {[fieldName: string]: Object}): Promise<{[fieldName: string]: boolean}>Parameters
- fields
-
{[fieldName: string]: Object}
A dictionary of field refName/values
Returns
Promise<{[fieldName: string]: boolean}>
A promise that returns a dictionary of field value update results (refName to results pairs).
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for