Rather that have me run through examples, I recommend you visit GitHub at http://github.com/almsports/VSORestSample for a selection of presented code samples for your convenience. All you need to do is enter your account name and you’re all set.

Getting Work Item Information

Once you have familiarised yourself with the basics of the API, you will also be able to tackle more complex components, such as Work Item Tracking. I want to mention this in particular because, whereas simple Get requests are sufficient to request projection information, Work Item Tracking requires the entire bandwidth of the API to allow you to create or edit work items, read out attachments and histories, and assign tags.

Figure 3: Work item units within Rest API

Work item information can be requested in two different ways: Either you use a predefined query from a team project, or you create your own query using the Work Item Query Language (WIQL). Regardless of the method you ultimately opt for, both query types initially only return a list of work item IDs. Send a second request to obtain more detailed work item information, using one of the work item IDs as an additional identifier:

In this query, the returned work item IDs are listed with the requested data fields. In this process, it is important to make sure not to state a project name in the URL otherwise the service is unable to find the requested resource and it returns a “404 not found” error message.

Secure authentication and authorisation with OAuth 2.0

As mentioned above, the authentication type selected for VSORestSample is not secure and must not be used in productive applications. Thankfully, REST API supports the OAuth 2.0 authentication protocol, which means the requesting application must no longer provide the user credentials and transfer them upon opening interfaces. OAuth 2.0 is not a standard used exclusively by Visual Studio Online, but is rather a well-adopted protocol relied upon by many companies (e.g. Dropbox, Foursquare, GitHub and Google). In terms of general characteristics, OAuth 2.0:

• is a standard for secure data transfers
• requires user registration for authorisation
• provides users with unique authentication

The underlying mechanism of OAuth is actually relatively simple:

• First, an application must register for the requested service. This registration process usually requests data, such as the application name, website, logo, etc.
• You then receive a Client ID and a Client Secret. The Client ID features public information and is used within the application to open the service. In contrast, the Client Secret must be treated with absolute confidentiality to safeguard secure authentication.

OAuth 2.0 for Visual Studio Online

The authentication process for Visual Studio Online follows a similar pattern, although Figure 4 (below) illustrates that Visual Studio Online must also register the requesting application to open the API to it. During registration it is particularly important to list the correct API units, called “scopes”, to which the application is granted access. If incorrect scopes are selected, the application will later be unable to query these units and an error message is returned instead of data.

At this point it is also important to note that the scope cannot be changed after registration (as at April 2015). Consequently, selecting an incorrect API unit means the application must re-register to change its permission scope.

Figure 4: Visual Studio Online OAuth mechanism

When a user wants to connect to their Visual Studio Online system with an external application, an authorisation request is sent to Visual Studio Online upon starting the application. Visual Studio Online then prompts the user to enter their credentials into the conventional Microsoft authentication dialogue, and then to authorise the application (i.e. enable the application to access and edit data on behalf of the user.) Visual Studio Online then transfers an authorisation code to the application which then uses said code to request an access token. This token enables the application to access data for the rest of the session without users having to authenticate themselves again.

Securely requesting data

To keep everything secure, each query the application makes must feature the access token to safeguard the functionality of the authentication mechanism. For this purpose, the http request from the VSORestSample is changed and amended by the token information:

Compared with the first example, notice that the authentication header now no longer features “Basic”, but rather “Authorization” as the scheme, and that the parameter has changed from “Username/Password” to the “bearer {Access Token}” token.

Always up to date with Service Hooks

We’ve had a whirlwind tour through the new REST API and updated authentication system. So far, so good. An additional, important element in your journey towards a customised ALM platform is the so-called Service Hooks feature. Service Hooks enable notification of external services and applications for specific events within a team project. This allows the establishment of a workflow between Visual Studio Online or Team Foundation Server 2015 and external services, and completes the process started with the new API and Authentication. Here is the Service Hooks mechanism in an overview:

Figure 5: Event model for Service Hooks

The Service Hook publisher defines events, which can be consumed by a Service Hook Consumer via subscriptions. These consumers, in turn, trigger actions. Nowadays there are more than a dozen services that can be integrated using Service Hooks, including Jenkins, HipChat, Slack, UserVoice, Trello, and so on. Let’s see an example of that.

Integrating Trello and TFS 2015 CTP

I’ll demonstrate the Service Hook principle with an example that is already working very smoothly – the Trello online collaboration tool. The Service Hook for Trello can be configured so that events from the Build, Version control, Team room or Work items units trigger an action in Trello. In the following example a new card is created in Trello for each newly created work item in a certain TFS team project.

Figure 6: Service Hooks for TFS 2015 CTP

I was positively surprised by how easy the integration with Trello was – I was able to integrate the tool into TFS 2015 in seconds. I merely created a new Service Hook in the TFS administrator user interface in the Service Hooks section, and select Trello as the service. I needed to grant TFS access to Trello data and boards to be able to create new cards in Trello, as you can see below.

Figure 7: Creating a Service Hook for Trello

It looks like, at time of writing, Trello engineers are not quite prepared for the fact that the TFS on-prem can now also create a service hook because the dialogue continues to read “Let Visual Studio Online use your account?”. However, this is no reason for concern. After completing configuration of the Service Hook, newly created product backlog items are seamlessly transferred from the TFS 2015 to a Trello board and shown there as new cards.

Figure 8: Trello card created by TFS

TFS Evolution – an open source demo project

Finally, to give you a sense of how this all fits together, I’ll introduce an open source project which I’ve worked on, together with my colleagues Marco Richardson and Ulli Stirnweiß (ullibility.net). The TFS Evolution Windows app uses the three improvements and integration options we’ve discussed, (Rest API, OAuth 2.0 and Service Hooks) to visualise data from Visual Studio Online.

TFS Evolution shows Team Foundation Server data in a previously unseen way. The app was designed for scrum teams who demand a concise visualisation of the most important data as part of daily meetings, so TFS Evolution provides a detailed overview of the team performance and current tasks.

The app is split into two sections: a dashboard, providing teams with a burndown chart, sprint progress chart and an event ticker as well as a touch-optimised task board:

Figure 9: “Team Performance & Health State” dashboard

And a task board, allowing for fast and simple adaptations to the information with touch gestures.

Figure 10: Task board

TFS Evolution is open source and available to download from GitHub, and we invite you to modify and enhance it, or even just take a look to get some inspiration for your own projects!

Adding Value and Fostering Creativity

Thanks to an integration of external services, applications and tools, the Visual Studio ALM platform can now be customised to suit any company’s processes. System restrictions are either removed or easy to work around, and manual tasks can be automated more than ever before. The added value to users now not only lies in the use of individual tools, but on the information these tools share amongst each other.

The REST API and Service Hooks also mean that the platform is becoming increasingly accessible for other technologies. Coupled with the existing Git version control and support for cross-platform development tools (Cordova and Xamarin), Microsoft’s ALM platform has the potential to be the product development foundation for any company.

Finally, the TFS Evolution showcase I mentioned should help you see what’s possible on this new platform, and let you think outside the usual process constraints you might traditionally associate with a Microsoft tool. These new integration options enable countless possibilities, and will hopefully lead to some more streamlined ways to support everything from daily stand-ups to actual coding. Be creative, and craft an ALM platform to suit your process.