Retrieving Information on Work Items

Functions are provided to retrieve information about a specified work item.

These functions are in the WorkItemManagementService and WorkListService services:

  • previewWorkItemFromList - Use this function to retrieve information on one or more specified work items in a work list. The request specifies the GUID of the requesting organizational entity, the IDs of one or more work items, and optionally a list of the fields about which information is required. You can use this function:
    • To get the type and value of one or more specific fields. You can filter the information returned by specifying one or more field names as requiredField parameters. If you do, the function returns information only on those named fields.
    • To get information on all fields. If you do not include the requiredField parameter, the response returns the name, type, and value of all fields.
  • getWorkItemHeader - Use this function to retrieve the header information for a specified work item.

    The request specifies the workItemID of the required work item, which you can get from the response to a previous call to getWorkListItems or getAllocatedWorkListItems.

    The response returns the work item header information. The header information includes the work item's:
    • name
    • description
    • distributionStrategy
    • priority
    • startDate
    • endDate

    These attributes can be used as criteria for sorting or filtering work items in a work item list; see Sort Filter Criteria .

    You can use this function to bring a work item up to date if you have called an obsolete version. For more information, see Work Item Versions.

  • getOfferSet - Use this function to get the initial offered set for a work item, that is, the collection of organizational entities to which the work item was initially offered.

    The request specifies the unique ID of the required work item and the response returns the IDs of all entities in the offer set.

    Note: You can specify whether this function returns only the GUIDs of the organizational entities, or additional information, including the GUID, the major version of the organization model in use, and the type of the organizational entity.

    This information can then be used to allocate the work item to a particular resource from within this set; see Allocating a Work Item to a Target Resource.