Visual Studio Team Services (VSTS) is great for managing development and testing activities. It is easy to track the progress of the work and get notifications about any changes. However, when it comes external users, it can be a bit more complex. I typically use SharePoint project sites for most of my client communication and collaboration, such as sharing of documents, project plans, and risks logs. Thus, it would be natural to also leverage the project sites for managing any defects that clients discover in their custom solutions.
2-System Solution
I’m a firm believer of working out loud and collaborating with clients. However, there’s also a time when I want to keep the internal development workings hidden from clients on purpose as it may cause unnecessary confusion or raise false alarm bells. Without having clients access VSTS directly, how will clients track bugs? I already alluded to the fact that I use SharePoint project sites for managing all other project related artefacts. Using a Custom List in SharePoint, I track key information about a defect, including Title, Reproducible Steps, Sprint Number, Priority, Severity, Browser, and Operating System.
When a defect is created or updated in SharePoint, I used to get notified about it and would then update the corresponding information in VSTS. This solution works but is not ideal as I it requires manual transcription of information and extra time. In the remaining sections, I discuss approaches for creating defects between SharePoint and VSTS. Below is a sample of what a VSTS Bug submission looks like (NOTE: there are many fields that can be filled-in when submitting a bug in VSTS. However, I’m only interested in the fields highlighted in yellow). From the defect fields mentioned above, the Browser and Operating System values make up the System Info field.
Automating Defect Creation using Flow
Recently, Microsoft introduced connectors for Visual Studio into Flow. One of the connectors, Create a new work item, can be used to submit bugs. The fields available for the submission can be seen in the image below.
Though functional, this connector only lets you set a few fields as shown above. The most logical field to provide all the details would be in the Description field. However, this field is not shown in the Details view. To see the Description, you need to first go to the history view. Not ideal.
RESTful Solution
Luckily, VSTS has a rich REST interface that can be leveraged to submit bugs with more detailed information. Setting up this Flow requires two prerequisites:
- Create personal access tokens to authenticate access to VSTS
- Convert personal access token to Base 64
Create personal access tokens to authenticate access to VSTS
To read or write data to VSTS, the Flow must first authenticate with the service. This access can be established in a number of ways. In this example, I used the Personal Access Token. You can set up your access token by following the Authenticating with personal access tokens instructions.
Note: The maximum time span for a Personal Access Token is 1 year from creation date. Make sure to consider it in case your need for this Flow will extend beyond a year.
Convert Personal Access Token to Base 64
Before you are able to use your Personal Access Token, you have to convert it to Base 64. You can use the following PowerShell command to achieve this, as described in Jeff Bramwell’s article Calling VSTS APIs with PowerShell.
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $user,$token)))
Now that you have your Personal Access Token in it’s proper format, let’s look at setting up SharePoint and the Flow itself.
Setting Up SharePoint and Flow
As mentioned earlier in this article, I am leveraging a SharePoint Custom List for my external users to submit their bugs. In my specific scenario, I use the following fields:
|
Field Name |
Type |
Options |
Required |
|
Title |
Single line of text |
|
Yes |
|
Reproducible Steps |
Multiple lines of text |
Rich Text |
No |
|
Browser |
Choice |
IE11 Chrome Safari |
No |
|
Operating System |
Choice |
Windows 10 iOS Android |
No |
|
Priority |
Choice |
1 2 3 4 5 |
No |
|
Severity |
Choice |
1- Critical 2- High 3- Medium 4- Low |
No |
|
Acceptance Criteria |
Multiple lines of text |
Rich text |
No |
|
Sprint |
Choice |
Sprint 1 Sprint 2 Sprint 3 Sprint 4 |
No |
|
VSTS Bug ID |
Number |
|
|
Most of this information is straight forward, but I want to call out two specific points. First, you may have noticed that the values for Priority and Severity are different. This is because, although similar in categorization, I wanted to match the values that are present in VSTS to make it easier for someone looking at a bug in SharePoint and VSTS to see the relationship without needing to do any mental transformation of the values. I could have used a simple numbering scheme (or altogether different values for that matter). The second field is the VSTS Bug ID. This field is used to capture the ID of the bug that was just created by the Flow. In a later article, I’ll discuss how you can use it to update an existing Bug.
Now, let’s have a look at the Flow. It is fairly straight forward and linear, with a single path of actions.
The Flow is composed of a trigger and 4 steps.
When a new item is created
Here, I simply set up the trigger for a new item that is created in the Custom List in SharePoint. Once an item is created, the Flow kicks-in.
Initialize variable
In this step, I save my Base 64 Personal Access Token in a variable for later reference. This is good practice in case you have to alter it (and you will, at least once a year) without needing to search for the tokens inside all of your code. I called my variable VSTS Authorization.
HTTP
This is where the magic happens. Make sure to provide the correct field values (Method, Uri, Headers, Body, Authentication) to avoid errors from occurring during the submission.
In my case, I have the following mapping between the SharePoint list and VSTS:
|
SharePoint Custom List Field |
VSTS Field |
|
Sprint |
System.IterationPath |
|
Created By Email |
System.CreatedBy |
|
Title |
System.Title |
|
Reproducible Steps |
VSTS.TCM.ReproSteps |
|
Priority |
VSTS.Common.Priority |
|
Severity |
VSTS.Common.Severity |
|
Browser and Operating System (combined and formatted using HTML) |
VSTS.TCM.SystemInfo |
There are more options available to populate fields in VSTS. For a full reference, refer to the VSTS Work item field index.
The next step in the Flow captures the response from the REST PATCH message and parses out the fields of the Bug created in VSTS. To get the schema, click Use sample payload to generate schema and copy the Body of the HTTP action.
Finally, I update the original SharePoint Custom List item with the newly created VSTS Bug ID.
Considerations
As mentioned earlier, one of the limitations of this approach is using the Personal Access Token as it expires after no more than a year of its creation. One way to manage it without having to modify the Flow is by storing it in another location (e.g. SharePoint list) and referencing it in the Flow. There are other ways to authenticate, which are beyond the scope of this article.
Another interesting consideration is that if properly architected, you could use a single Flow to service multiple VSTS projects from a single SharePoint entry point by parameterizing the VSTS Uri and AreaPath and keeping the IterationPath consistent (e.g. Sprint numbers).