The following has been reposted from Chris Spagnuolo's GeoScrum! (www.chrisspagnuolo.com)

As part of our move to using Rally Software as our agile management tool, we asked for a trial subscription to Rally's Web Services API.  We decided to give the API a test run by integrating a defect reporting function into our custom ESRI ArcGIS application for a large enterprise project.  Mike Juniper and Jeff Germain, two of our GIS software engineers, put the API through its paces to see what it could do.  I had the chance to discuss the API with Mike and ask him 10 questions about it.  Here are Mike's answers:

1. Can you tell us a bit about yourself and your development experience?

I started learning VBA about 9 years ago as a secondary part of my job. A few years ago, programming became a more central part of my job and I switched to VB6 because we had an unused license lying around and I wanted to learn something new. About a year ago, I took my current job as a GIS Software Engineer and switched to VB.NET.

2. What is the Rally Web Services API?

It’s an API that allows you to integrate Rally components into other software systems.

3. How long have you been using the API?

I’ve just used it for a small part of one project. I’ve really just spent a total of maybe 12-16 hours figuring it out and using it in our application. I investigated the API, figured out how it worked, and put together some sample code, which I handed off to Jeff Germain. He took it and ran with it and built a framework for using it in our application. I then built the command and the UI.

4. What made you decide to use it?

We wanted to provide a way for our customer to be able to report software defects from within our custom ESRI ArcGIS application. We wanted their defect reports to integrate right into our own Rally instance and auto-populate our defect backlog.

5. Can you describe what you did with the API?

We created a command button that opens up a form, which allows the user to provide information about the defect and submit it to Rally. Here’s some sample code showing how to log into the Rally service:

Public Shared Function GetService() As Rally.RallyServiceService

' Instantiate the service

Dim rallyService As New Rally.RallyServiceService

' ===All API calls require basic authentication===

'Set the service - not necessary if you get wsdl

'''''rallyService.Url = "https://rally1.rallydev.com/slm/webservice/1.03/RallyService"

'Login to service using http basic authentication

Dim credential As New System.Net.NetworkCredential("<username", "<password>")

Dim uri As New Uri(rallyService.Url)

Dim credentials As System.Net.ICredentials = credential.GetCredential(uri, "Basic")

rallyService.Credentials = credentials

rallyService.PreAuthenticate = True

'Configure the service to maintain an http session cookie

rallyService.CookieContainer = New System.Net.CookieContainer

'======

Return rallyService

End Function

Here’s some code showing how to get a reference to particular project:

Public Shared Function GetProject(ByVal projectName As String, ByVal rallyService As Rally.RallyServiceService) As Rally.Project

If String.IsNullOrEmpty(projectName) Then Return Nothing

Dim project As Rally.Project = Nothing

' Get the workspace from the subscription

Dim workspace As Rally.Workspace = GetWorkspace(rallyService)

' Querying for objects directly seems to be faster in most cases

Dim queryResult As Rally.QueryResult = rallyService.query(workspace, "Project", "(Name = """ & projectName & """)", "", True, 1, 20)

If HasErrors(queryResult) Then

     Throw New Exception("Error querying for project '" & projectName & "'" & FormatWarningsErrors(queryResult))

Else

     For Each projectItem As Rally.Project In queryResult.Results

          If projectItem.Name = projectName Then

               project = projectItem

               Exit For

          End If

     Next

End If

' Return value

Return project

End Function

To create a defect, you’d do something like:

Dim defect As New Rally.Defect

' Set the properties

' Create the defect on the server

Dim createResult As Rally.CreateResult = rallyService.create(defect)

Create returns a Defect on success and an OperationResult on failure so you need to examine the returned object to see what happened.

6. Had you not use the Rally API, what were the alternatives you would have considered to achieve the same results?

At the time, we were having users submit defects to a Microsoft SharePoint portal. We probably would have continued doing that and someone would have had to manually transfer or import them into Rally.

7. How would rate the ease of use of the API?

It was really easy to use. I hadn’t really used a web service before except in a class I took a while ago. But I was able to dive right in and start using it almost immediately.

8. Did you find any difficulties or problems using the API?

One thing that tripped me up is that sometimes you’ll have a ‘shell’ object and sometimes you’ll have a ‘full’ object. It’s not always clear to me which one you’re going to get ahead of time. But if you’ve got an object and the only property that is populated is the ref property, you’ve got a shell object. You can get the full object by doing something like:

      defect = DirectCast(rallyService.read(defect), Rally.Defect)

9. How has what you built helped your Scrum team and/or your customer?

We used to have a several different ways of collecting defect reports and they weren’t integrated. Now all our defects are in one place n our Rally Software as defect backlogs related to specific releases and iterations and it’s very easy for our customer to report new defects.

10. Can you envision other potential uses of the API for your current or future projects?

I haven’t given this much thought…. The web app is so good that I would think anyone who has access to it would primarily use that. However, the web services API allowed us to only expose exactly what we wanted to our customer without using another Rally login.

Thanks to Mike Juniper for all of his great answers and insights into the Rally Web Services API.  If anyone else out there has experience with the Rally Web Services API (good or bad) we'd love to hear about what your doing with it and how it has impacted your development environment and/or your customer satisfaction.

The content of this post are my own personal opinions and do not represent my employer's view in any way.

© Copyright 2007, Chris Spagnuolo
GeoScrum! by Chris Spagnuolo is licensed under a Creative Commons Attribution 3.0 United States License.