Integrating ColdFusion and the REST API for Harvest (TimeSheet Service); Accessing XML in CF

I'll demonstrate here calling the REST API for the Harvest online timesheet application. (If you would want to point me to another alternative timesheet app, no need as I'm happy. I realize there are many. Indeed, I list many of them on my CF411 site section for time tracking tools and services.)

Anyway, the Harvest API docs pages do show a Ruby example. While I didn't take the time replicate that exactly (it has a few more touches like error-handling, extensibility, etc), I did want to at least show how one could call the REST-based API using CFHTTP.

Some Simple CFHTTP Examples

Here are two simple examples, first, showing calling the who_am_i method:

Note that I'm using the same nomenclature they do in their docs, in that you would need to change the "subdomain" value to be whatever your own it. Also, like them I've just left the placeholders above for your Harvest username/password. And the API docs show needing to pass in those two headers, which I do in the CFHTTPPARAM.

Getting TimeSheet Entries

The next, more interesting example calls the method to get the timesheet data for a given day (and yes, since the REST API has no state you do need to pass in the username/password on each call. In a more complete app, you might prompt the user for those and store it in a session for reuse, etc.):

Note also that the date is in Julian format (the number of the day in the year). I'm showing Dec 10. Again, I could elaborate this to take in URL variables to change the date. I'll leave that to the reader.

So how do you calculate the date in Julian format? Well, you could of course modify the code to use CF's date/time functions to do a conversion, but if you just want to look up a given day for manually, here's a trick. If you've never noticed it (as a Harvest user), the real web-based Harvest timesheet always also shows the julian date in the URL for a timesheet entry.

Getting Real Data from the Returned XML

The result of both calls is some XML. In the first example, I ignored it. In the second, of course, you need to get the data.

So I pass it to the XMLParse function (new in CF6) and still missed by many. That converts the XML into an internal CF XML object, which represents the XML as a series of nested structures, arrays, and attributes. If you do a CFDUMP of the result, you'll see what I mean:

And to output the hours for the first entry, one could do this:

How did I figure out that nested set of arrays and structures, you ask?...

Learning More about XML processing in CFML

I won't elaborate here about how to go about accessing the various parts of the (sometimes complex) internal XML object. But you can learn it really quickly. Most CFers are blithely unaware of the power of this feature set (or they get confused and give up). There are two (well, three) places you can learn more.

First, the best resource on CF/XML processing (in my opinion) is a great extended Adobe Devnet article by Nate Weiss. Though from 2002, it's an all-time classic.

He introduces the topic assuming you know nothing about XML, and steps quickly into processing it in CFML (reading and writing it), including understanding all those structures, arrays, and attributes. Within just a few pages, you'll be amazed at how much more productive you can be with XML processing in CFML.

Nate even introduced the valuable concepts of using XPath/XMLSearch to make accessing XML even easier and XSLT to do conversions from XML to other formats. He does all this very gently and in a compelling way. I still refer people to it often, to this day (and return to it myself when I'm stumped).

That said, there are of course a few ways that XML processing in CFML has evolved since CF6, so you will want to check out the CF docs as well. Besides the CFML Reference on XMLParse, note that there is also a chapter on the topic in the oft-missed ColdFusion Developer's Guide.

Many only know of the CFML Reference, but they miss out on this 1,000+ page free online book (from Adobe). The CF8 version of this is here and the chapter here. The CF9 version of the manual is here and the chapter is here.

Hope any of that may help someone.