setWorkItemPriority

Use this operation to set the priority of a work item. Setting the work item priority enables a user to sort their work list by Priority.

Also, scripts and processes can check the priority value and therefore perform actions based on the work item priority.

All work items have a priority. The priority is a numeric value indicating the relative importance of the work item. By default, the work item priority is 50. The valid range for work item priority is 1 - 100.

You can change the priority of an individual work item or multiple work items. Depending on your requirements, you have a choice of one of the following:

Note: You must enter a value in the range of 1 - 100 (inclusive). If you enter a value outside this range, an exception is thrown.
  • absPriority. Enter a specific numeric value.
  • offsetPriority. Offset a work item priority by a specific numeric value. For example, an employee is away on holiday and you want to offset the priority on all their work items by 20.

The request is made up of:

  • workItemID: ID of the work item for which information is required.
  • version: (Optional) If it is omitted, the latest version is used.
  • work item priority, for example, abspriority or offsetPriority.

To use this operation:

  • A work item can be in any state except Open and Completed. If you reset the work item’s priority, its state is not changed.
  • You must have authorization for one or both of the following system actions:
    • changeAllocatedWorkItemPriority - This system action allows you to reset the priorities of work items with a status of Allocated and that are allocated to the resource performing the action.
    • changeAnyWorkItemPriority - This system action allows you to change the work item priority of any work items.

      This means if a user wants to change the priority of a work item in their work list whose status is Allocated, but it is not allocated to them, then they must also have authorization for the changeAnyWorkItemPriority system action.

For API reference information, see setWorkItemPriority.