setWorkItemPriority

Use this function to set the priority of a work item.

Setting the work item priority with the setWorkItemPriority function (which is in the WorkItemManagementService) allows 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 must specify a value in the range of 1 - 100 (inclusive). If you enter a value outside this range, an exception is thrown.)

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:

  • absPriority. A numeric value from 1 to 100.
  • 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 of the employee's 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 function:

  • 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.