Tutorial: Downloading completed Calls

The first thing to understand is that TeamHaven does not offer a way to bulk download all of the data from all of the completed Calls in a Project. Instead, the data must be downloaded one Call at a time. While initially this might seem an onerous restriction, when used in the proper overall solution, this works perfectly well.

The trick is to know when a Call has been completed so that you can download it, and this is where we meet our first piece of the TeamHaven Web API - Integration Events.

In a nutshell, Integration Events are TeamHaven's way of informing you when something interesting has happened. There are several different event types, but for this scenario we only need to focus on the "Answers updated" event, which is raised when a Call is completed for the first time and it's answers are uploaded to the TeamHaven server, or when somebody updates the answers at a later date.

TeamHaven makes these Integration Events available via a Windows Azure Message Queue. If you don't know what a message queue is, then read up on them, but basically TeamHaven pushes messages (Integration Events) into the queue and you can pull them out of the other end whenever you choose. Using a queue provides two important benefits. Firstly it scales well, allowing you to use multiple worker processes if your processing is quite slow. Secondly it provides several layers of fault tolerance to ensure you don't miss messages, even if your workers crash while processing them.

So, the core of our downloading solution will be a loop which repeatedly pulls messages from the Integration Event queue until it receives a signal to stop. If a message couldn't be fetched, then we will wait a little while before checking again, otherwise it will examine the message to see if it is an "Answers Updated" event and if it is, it will download the data from TeamHaven. Finally it will delete the message from the queue, regardless of whether it was an "Answers Updated" event or another type. It is safe to do this, because nobody else cares about these messages and if you don't want them, nobody does. Messages expire after 7 days anyway, but if you don't delete them you will end up repeatedly fetching them many times each day, wasting time, bandwidth, CPU cycles and electricity!