Work Item Versions

Operations that directly specify a particular work item do so by giving the work item ID.

The work item ID includes an optional version parameter. The version of a work item starts at 0, and increments by one whenever an operation is performed that changes the work item’s state or data. For example, the following extract shows a closeWorkItem operation increasing the version from 3 to 4:

     <api:closeWorkItem>
         <workItemID id="2" version="3"/>
     </api:closeWorkItem>

     <closeWorkItemResponse
         <workItemID id="2" version="4" xmlns=""/>
      </closeWorkItemResponse>

As the closeWorkItem extract above shows, various operations also return a version number. If no version number is specified, the latest version is assumed. However, specifying the version can be good practice because it prevents clashes when two or more users attempt to operate on the same work item. For example, two users perform an allocateAndOpenWorkItem operation on a work item. If they do not specify a version number, the second allocateAndOpenWorkItem operation to be executed will fail because the work item is no longer in a suitable state to be allocated or opened. If both users specify the version number of the work item, the second operation will still fail, but it will do so with a version number error, as shown in the following extract:

      <api:allocateAndOpenWorkItem>
         <workItemID id="2" version="1"/>
         <resource>6353AB5E-C395-409C-E706C02F22DA</resource>
      </api:allocateWorkItem>

<faultstring>The work item with id = 2 is currently at version 6, not at version 1</faultstring>
         <faultactor>PROVIDER</faultactor>

This enables your client application to know that you are attempting to use an out-of-date version of the work item, and to take appropriate action. For example, one possibility would be to use the getWorkItemHeader operation to retrieve the latest information for the work item and bring it back up to date. Another would be to use previewWorkItemFromList to obtain the current version of the work item.