Automating TICK: Using the TICK API for Reporting

I like TICK for its clean and intuitive user interface, but my organisation uses “day” as the time period for budgets whereas TICK reports everything by the hour.

So I needed my own app to take TICK report hours and convert them to days.

Fortunately the nice people at TICK helpfully provide a tool to facilitate the automation of this task …

Preliminaries

You know that TICK provides manual reporting capabilities from the homepage

But did you know you can also access this functionality for scripting via the TICK API?

There are some basics you will need to get started with the API:

1. Install cURL as the tool to provide the capability for automated access to TICK  http://curl.haxx.se/
2. Give yourself a means to run cURL in a unix environment.  Not a problem for those of you working with Linux, but for Windows users you will need a tool such as Cygwin installed  https://cygwin.com/
3. Make a note of your TICK Subscription ID and API Token.  These can be found on the Users screen.

OK, so now you are ready to build some cURL commands to access all that useful TICK data.

Main Course

To collect the data for Time Entries you need to follow the basic structure of TICK:

Clients –> Projects –> Tasks –> Time Entries

There are also the Users who enter the times linked to Time Entries

First, let’s have a look at the Clients for your Subscription.

The cURL command you need is:

curl –insecure -H “Authorization: Token token=Your API Token” –user-agent “aNameForYourApp (yourEmailAddress@wherever)” https://www.tickspot.com/Your Subscription ID/api/v2/clients.json

• –insecure stops cURL performing SSL certificate verification. You need to decide if this is appropriate for your circumstances. If not then off you go to sort out SSL certification …
• -H is the HTTP Header. TICK insists on the format shown here to recognise the API Token
• –user-agent is where you give TICK a label to identify your app and an email address to communicate with you if anything goes wrong
• Finally, there’s the address for the API. Note that these notes refer to version 2, keep an eye on https://www.tickspot.com/api to check if the version ever changes

To quote the documentation “the Tick API and has been designed around RESTful concepts with JSON for serialization” so that’s why it has clients.json

But what I hear you cry is JSON?

Well, it’s a standard way to format the returned outputs so that you can use other freely available tools to parse it into something more useful for your app. More of that shortly …

Running the cURL command for Clients in Cygwin will give you output that looks like this:

[{“id”:257764,”name”:”Client No.1″,”archive”:false,”url”:”https://www.tickspot.com/Your Subscription ID/api/v2/clients/257764.json”,”updated_at”:”2014-09-14T15:15:26.000-04:00″},{“id”:257766,”name”:”Client No.2″,”archive”:false,”url”:”https://www.tickspot.com/Your Subscription ID/api/v2/clients/257766.json”,”updated_at”:”2014-11-05T18:24:59.000-05:00″}]

JSON format puts the full output in square brackets with each dataset in braces. Elements are separated by colons and strings are in double quotes.

So you can see how it can be parsed into rows and columns or array elements.

We have already looked at the cURL command for Clients.

Now here are the other cURL commands you need for Projects, Tasks, Time Entries and Users

• curl –insecure -H “Authorization: Token token=Your API Token” –user-agent “aNameForYourApp (yourEmailAddress@wherever)” https://www.tickspot.com/Your Subscription ID/api/v2/projects.json
• curl –insecure -H “Authorization: Token token=Your API Token” –user-agent “aNameForYourApp (yourEmailAddress@wherever)” https://www.tickspot.com/Your Subscription ID/api/v2/projects/project_id/tasks.json

project_id is the numeric code taken from the output of the Projects command

• curl –insecure -H “Authorization: Token token=Your API Token” –user-agent “aNameForYourApp (yourEmailAddress@wherever)” “https://www.tickspot.com/Your Subscription ID/api/v2/entries?project_id=project_id&start_date=yyyy-mm-dd&end_date= yyyy-mm-dd.json”

start_date and end_date gives a restricted range for the Time Entries. You must specify values for them.

• curl –insecure -H “Authorization: Token token=Your API Token” –user-agent ” aNameForYourApp (yourEmailAddress@wherever)” https://www.tickspot.com/Your Subscription ID/api/v2/users.json

The output of the Time Entries command looks like this:

[{“id“:44400081,”date”:”2015-03-06″,”hours”:7.5,”notes”:””,”task_id“:6470920,”user_id“:222443,”url”:”https://www.tickspot.com/Your Subscription ID/api/v2/entries/44400081.json”,”created_at”:”2015-03-09T04:28:05.000-04:00″,”updated_at”:”2015-03-09T04:28:05.000-04:00″}]

• id is the unique identifier of that Time Entry
• task_id links back to the list of Tasks. From Task you can link back to Project. From Project you can link back to Client
• user_id links to the User

That’s everything you need to collect all the TICK Time Entry data and feed the rest of your app to construct your own reports.

Good luck!