Work Item Versions
Functions that directly specify a particular work item do so by passing 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.
Various functions 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 function on a work item. If they do not specify a version number, the second allocateAndOpenWorkItem function 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 function will still fail, but it will do so with a version number error.
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 function 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.