WorkItemManagementService

The WorkItemManagementService contains functions to perform actions on work items.

The table below lists the functions available from the WorkItemManagementService.

For more information about work items, see Work Lists and Work List Views.

Function Description Returns
allocateAndOpenNextWorkItem Allocates the next available work item for a specified resource to that resource and immediately opens the work item (to get the associated input and output data).

The function fails if there is no next item in the resource's work list.

This function can only be used if the work item is in a state from which it can be allocated and opened. See Work Item State Transitions.

Required system action: workItemAllocation

AllocateAndOpenNextWorkItemResponseType
allocateAndOpenWorkItem Allocates a work item to a single resource and immediately opens the work item (to get the associated input and output data).

This function can only be used if the work item is in a state from which it can be allocated and opened. See Work Item State Transitions.

Required system action: workItemAllocation

AllocateAndOpenWorkItemResponseType
allocateWorkItem Allocates a lists of work items to a resource.

This function can only be used if the work item is in a state from which it can be allocated and opened. See Work Item State Transitions.

Required system action: workItemAllocation

AllocateWorkItemResponseType
closeWorkItem Closes a work item (and updates the associated input and output data).
Note: There is a closeWorkItem function in two services:
  • WorkItemManagementService (the one described here) - Use this one if the user task did not open a form when the work item was opened. This would be used only in special use-case client applications.
  • WorkPresentationService - Use this one to close a form that was opened when the work item was opened with the openWorkItem function in the WorkPresentationService. This is typically called in response to a user clicking the Close button on a work item form. See closeWorkItem.
This function:
  • Puts the work item into a Pended state.
  • Can only be used if the work item is in a state from which it can be closed. See Work Item State Transitions.
  • Can only be used if the work item is assigned to the user with whose credentials the operation is being invoked.

Required system action: Requires closeOtherResourcesItems in order to close a work item currently allocated to another user, for example, when a manager is closing an item in a supervised work list. Otherwise, none.

CloseWorkItemResponseType
completeWorkItem Completes a work item (and updates the associated input and output data).
Note that there is a completeWorkItem function in two services:
  • WorkItemManagementService (the one described here) - Use this function if the user task was designed to not open a form nor start a pageflow. This would typically be used only in special use-case client applications -- see completeWorkItem.
  • WorkPresentationService - Use this one if a form was opened when the work item was opened with the openWorkItem function in the WorkPresentationService. This is typically called in response to a user clicking the Submit button on a work item form. See completeWorkItem.

Required system action: None

CompleteWorkItemResponseType
getOfferSet Gets the offer set for a work item (the offer set is the set of organization model entities to whom a work item is to be offered).

You can choose whether to return only the GUIDs of the organization model entities, or whether to return version and type information as well.

Required system action: None

GetOfferSetResponseType
getWorkItemHeader Gets the header information for a specific work item.

Required system action: None

GetWorkItemHeaderResponseType
openWorkItem Opens a work item (to get the associated input and output data).
Note: There is an openWorkItem function in two services:
  • WorkItemManagementService (the one described here) - Use this one if the user task was designed to not open a form nor start a pageflow. This would typically be used only in special use-case client applications.
  • WorkPresentationService - Use this one if the user task was designed to either open a form or start a pageflow, which is typical for most client applications (see openWorkItem).

Required system action: None

OpenWorkItemResponseType
pendWorkItem Pends the specified work item, which causes the work item to be hidden in the work item list until a specified date/time, or period of time has expired. The work item becomes visible again when the date/time occurs, or the period of time expires.

A hiddenPeriod of 0 cancels a hiddenPeriod set by a previous pendWorkItem function call on the same work item. See Accessing Hidden Work Items.

Required system action: pendWorkItem

PendWorkItemResponseType
reallocateWorkItem Reallocates a work item with no new data to a different resource.

Users to whom a work item can be reallocated is restricted by the system action held by the caller - see below. Also, to reallocate a work item to the original offer set, the work item can have a state of Offered, Allocated, or Pended; to reallocate a work item to the "the world", the work item can have a state of Allocated or Pended.

If there is new data to be written to the work item, use the reallocateWorkItemData function instead (see below).

Required system action:
  • reallocateToOfferSet - This system action allows you to reallocate work items to only the users in the original offer set.
  • reallocateWorkItemToWorld - This system action allows you to reallocate work items to any user in the organization model.
ReallocateWorkItemResponseType
reallocateWorkItemData Reallocates a work item to a different resource and updates the work item with new data.

Users to whom a work item can be reallocated is restricted by the system action held by the caller - see below. Also, to reallocate a work item to the original offer set, the work item can have a state of Offered, Allocated, or Pended; to reallocate a work item to the "the world", the work item can have a state of Allocated or Pended.

If the work item has no new data associated with it use the reallocateWorkItem function instead (see above).

Required system action:
  • reallocateToOfferSet - This system action allows you to reallocate work items to only the users in the original offer set.
  • reallocateWorkItemToWorld - This system action allows you to reallocate work items to any user in the organization model.
ReallocateWorkItemDataResponseType
rescheduleWorkitem Reschedules the work item and/or changes the work item data.
Depending on your requirements, the request can specify the:
  • itemSchedule - This is the work item schedule period to be associated with the work item. If no object is passed then the item schedule period will not be changed. The parameters are:
    • startDate (optional): Earliest date at which the work item can be started.

      And a choice of one of the following:

    • maxDuration (optional): Duration of the work item
    • targetDate (optional): Date by which this work item must be finished
  • itemBody - This is the work item body containing the data changes. If no object is passed, the item body will not be changed. The body is the data as a name/value pair. The parameters are:
    • Parameter: Details of the data fields associated with this work item.
    • complexValue: Value(s) of the complex object. Only one complex value or value will be specified. The value is of xs:anyType as it contains the entire complex object as XML.
    • value: Parameter value(s) - for example, 10.

This function can be used when the work item is in any state other than Completed.

Required system action: rescheduleWorkItem

RescheduleWorkItemResponseType
saveOpenWorkItem Saves a work item (and updates the associated input and output data).

Required system action: None

SaveOpenWorkItemResponseType
setWorkItemPriority Sets a work item priority, which can be used to indicate the work item's relative importance.
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 - Set a specific numeric priority.
  • offsetPriority - Offset a work item priority by specific value. For example, an employee is away on holiday and you want to offset the priority on all their work items by 20.
Required system action:
  • changeAllocatedWorkItemPriority - This system action allows you to reset the priorities of work items with a status of Allocated and that is allocated to the calling resource.
  • changeAnyWorkItemPriority - This system action allows you to change the work item priority of all work items.
SetWorkItemPriorityResponseType
skipWorkItem Skips a work item. This means that no action is carried out on the work item.

This function can only be used on work items that have default values for all required output and in/out data fields, or have values set already for such fields.

Required system action: skipWorkItem

SkipWorkItemResponseType
unallocateWorkItem Reoffers a currently allocated work item to the original offer set.

This function can only be used if the work item is in a state from which it can be unallocated. See Work Item State Transitions.

Required system action: workItemAllocation

UnallocateWorkItemResponseType