Update work item relations/links in VS Team Services

Question

I am trying to use the VSTS API to remove all parent links on items, and set those parents as related items.

https://www.visualstudio.com/en-us/docs/integrate/api/wit/work-items#update-work-items

I do not fully understand how the "Path" needed to remove relations work – I am getting inconsistent results where sometimes it works, sometimes not (so, im clearly doing it wrong)

I am making an assumption that its simply the order returned by the API. So, for example:

• Index[0] item
• Index[1] item

• Index[2] item <- this is the one I want to remove, so I use index 2

      public void RemoveParentLink(int pathIndex, int itemToUpdate, string link)
  {
  
      JsonPatchDocument patchDocument = new JsonPatchDocument();
  
      patchDocument.Add(
         new JsonPatchOperation()
         {
             Operation = Operation.Remove,
             Path = $"/relations/{pathIndex}"
  
         }
      );
  
      WorkItem result = witClient.UpdateWorkItemAsync(patchDocument, itemToUpdate).Result;
  
  }
  

The documentation states that Path is:

Path to the value you want to add, replace, remove, or test. For a specific relation, use "relations/Id". For all relations, use "/relations/-".

Index is NOT the Id of course, but how do I get the relation/Id exactly?

Answer 1

Using GetWorkItemAsync or GetWorkItemsAsync with WorkItemExpand.Relations parameter to get linked work items.

Var workItem=witClient.GetWorkItemAsync(id: [work item id], expand: Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models.WorkItemExpand.Relations).Result.

Then the index is the index of relations.

Answer 2

The 'id' in the '/relation/id' path is a index in fact. You retrieve the work item definition, then the 'id' is the index of the link in the 'relations' array. Hence your assumption is right.

Evidence: given a work item with 2 links, if you try to delete/modify id >= 2 it will answer with:

{ "$id": "1", "innerException": null, "message": "Index out of range for path /relations/2.", "typeName": "Microsoft.VisualStudio.Services.WebApi.Patch.PatchOperationFailedException, Microsoft.VisualStudio.Services.WebApi, Version=14.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "typeKey": "PatchOperationFailedException", "errorCode": 0, "eventId": 3000 }

0 and 1 as id work just fine instead.

I may be wrong, but I could guess that you could get an error when using the 'replace' operation before the 'add' operation. For example you need to add a 'comment' inside the 'attributes' of a link before modifying (i.e. 'replace' operation) its value.