getWorkListItems

The getWorkListItems operation returns items in the work list either for a specified organizational entity, or for all organizational entities.

The request for this operation must specify one of the following:

  • A statement that worklists are required for all organizational entities. If you are using the REST API, this is specified by using a separate operation, REST API - getWorkListItemsAllResources. Otherwise you can specify that All resources are required. Generating a list of all work items on the system, regardless of what resource they are allocated or offered too, can produce an unmanageably large list. This option is primarily intended to allow you to return a list of all work items which match a supplied list of order and filter criteria.
  • The GUID of an organizational entity. You can get the GUID by various means, for example from a previous executeQuery operation, or for a resource (user) from a previous lookupUser operation. Optionally the request can also specify how many items from the work list to return, and whether to include the total number of work items in the work list. It can also specify sort and filter criteria to be applied to the work items returned.

    The request element (getWorkListItems) contains the following information:

    • entityID—the GUID of the organizational entity whose work list you want to retrieve.
    • startPosition—the position in the work list from which to start the page of results. The list is zero-based. To start at the first item, specify 0.
    • numberOfItems—the number of items from the work list to include.

      Optionally, it can contain:

    • getTotalCount—whether to include a count of the total number of work items in the list. This defaults to true. The count is returned in the totalItems value in the response.

      You should set getTotalCount to false unless you specifically need the total figure, because setting it to true is expensive in terms of database access time.

      Note that if you pass false in this attribute, and there is at least one item in the list, the totalItems value returned in the response is -1. However, if you pass false and there are no work items in the list, the totalItems value in the response is 0 (zero).

      For performance reasons, counts are not supported when requesting ALL resources. If ALL resources are requested then a non-zero list will always return a count of -1.

Whether you specify a particular resource or All resources, this request can optionally contain orderFilterCriteria—sort or filter criteria, or both, to determine how the work items are to be filtered and presented. See Sorting and Filtering Work Lists for details of the syntax and content of these criteria.

The response for this operation returns full details of all the work list items that match the criteria specified in the request.

For API reference information, see getWorkListItems.