How to build a VSTS assistant - The Life and Times of a Kanban bot - Part 3

In the previous post (Part 2) we learned how to expand our bot functionality and be able to create work items using our voice.

Today, we will try to mark a work item as done or as "Closed" in VSTS.

This problem is split in two parts, which corresponds to the two APIs we will be using:

1. Searching for a specific work item by title - Fetch Work Item Search Results - /en-us/rest/api/vsts/search/work%20item%20search%20results/fetch%20work%20item%20search%20results?view=vsts-rest-4.1
2. Marking it as done - Update Work Item and change the state - /en-us/rest/api/vsts/wit/work%20items/update?view=vsts-rest-4.1

Taking a look at the ALM Search REST API documentation we will see that we'll have to build a request that looks like the one below:

 POST https://{accountName}.almsearch.visualstudio.com/_apis/search/workitemsearchresults?api-version=4.1-preview.1

Notice that for the search functionality, we have to call the almsearch endpoint and not the usual project endpoint. (API versions may differ too, so make sure you check the link above for updates to the API documentation).

The body of the request looks like below:

 
{
  "searchText": "<text to search>",
  "$skip": 0,
  "$top": 1,
  "filters": {
     "System.AssignedTo": [
          "John Doe <john@contoso.com>"
    ]
  },
  "$orderBy": [
    {
      "field": "system.id",
      "sortOrder": "ASC"
    }
  ],
  "includeFacets": true
}

and you will get a JSON back with a count of the work items found - in our sample we will only going to take the first result (nobody really has identically titled work items active at the same time - Agile wizards, feel free to jump on and start a debate on this :D ), and just grab the system.id field. Then, after we have our work item ID returned, it means that we found it, and we will call the second API in order to update it.

The second API is the Update Work Item one, and it looks like below:

 PATCH https://{accountName}.visualstudio.com/{project}/_apis/wit/workitems/{id}?api-version=4.1

with the following request body:

 
[
  {
    "op": "add",
    "path": "/fields/System.State",
    "value": "Closed"
  }
]

That's it. Check out the full code here: https://github.com/julianatanasoae/VSTSFunctionApp/blob/master/MyVSTSFunction/UpdateWorkItem.cs

Just like in part 2, we have to set up some training phrases in Dialogflow:

And the same as before, in the Action and parameters section:

That's pretty much it.

Let's take a look and see how it works.

This is how my work item board looks like right now:

In the Dialogflow test console, I will type "mark work item define user requirements as done" to close that work item. 

 

As you can see, it found my work item, and it marked it as done.

Let's refresh the VSTS dashboard and see what happened:

That particular work item doesn't show up anymore. If we change the view from Assigned to me to Recently completed we'll see the following:

It worked.

This is how you can mark work items as done by using the VSTS API. You can extend it and call more actions, assign tasks to someone else, assign tasks to a specific iteration (after finding a matching iteration), creating new iterations etc. Now, because this bot is configured to take an authorization header, I tailored it to only show work items that are assigned to the current user by using the System.AssignedTo parameter, as you don't want to screw up some other work items from your team members. :)

There are lots of improvements that can be done here, but it's shaping up as a nice prototype.

In the next post we will be talking about cross-platform stuff, as we'll shift our attention towards other assistants.

Happy Kanban-ing!

I'd love to hear your feedback on this.