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 its 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 you may want to 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!

The whole sequence of events looks something like this:

1. TeamHaven Mobile uploads a completed Call.
2. The TeamHaven server:
   1. Verifies the uploaded Call's Answers,
   2. Marks the Call as Completed,
   3. Saves the Answers and
   4. Adds the "Answers updated" event to the Integration Event queue.
3. The Worker Process gets the "Answers updated" message from the Integration Event queue.
4. The Worker Process downloads all the information it requires from TeamHaven.
5. The Worker Process stores this information in the database.
6. The Worker Process deletes the message from the Integration Event queue.

Steps 1 & 2 happen at TeamHaven, and steps 3 - 6 occur on your own server.

Steps 3 and 6 will be identical for every customer scenario, but the implementation of steps 4 and 5 will vary from customer to customer, depending on exactly what they want to achieve. Step 5 in particular - the storing of the information that is downloaded from TeamHaven will be very different.

Using the Integration Event queue

Access to the Integration Event queue requires an authorisation token, which can be obtained from the TeamHaven Web API. This token expires after a certain amount of time, so long running applications MUST periodically re-request authorisation before their current token expires.

Downloading information from TeamHaven

Typically some or all of the following APIs will be used:

/api/calls/:id - Get a Call

This will allow you to download basic information about the Call, including the User ID assigned to it and the Target ID it's visiting.

/api/calls/:id/answers - Get a Call's Answers

This allows you to download the Answers to the Call.

/api/calls/:id/questionnaire/manifest - Get a Call's Questionnaire Manifest

This allows you to download the Call's Questionnaire Manifest which can be used determining the Captions that relate to the FormIDs, QuestionIDs, ChoiceIDs and ItemIDs used in the Call's Questionnaire.

/api/pictures/:guid - Get a Picture

This allows you to download the JPEG representation of the answers to a Picture Question.

/api/signatures/:guid - Get a Signature

This allows you to download the JPEG representation of the answers to a Signature Question.

/api/users/:id - Get a User

This allows you to download information about a User.

/api/projects/:pid/targets/:id - Get a Target

This allows you to download information about a Target

Storing the downloaded information

We can't really tell you how to store the information as so much depends what you are trying to achieve - sorry!