[Looking for Charlie's main web site?]

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

Note: This blog post is from 2009. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.
Often we will find API docs for a given service without any reference to a CFML example. I just experienced that, and while I offered a suggested example to the vendor, I wanted to share it here in case it never gets posted. At least if someone Googles in the future they may find this. Also, I conclude with some insights into learning more about the power of XML processing 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:

<cfhttp url="http://subdomain.harvestapp.com/account/who_am_i" username="[email protected]" password="password">
   <cfhttpparam type="header" name="Accept" value="application/xml">
   <cfhttpparam type="header" name="Content-Type" value="application/xml">
</cfhttp>

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.):

<cfhttp url="http://subdomain.harvestapp.com/account/daily/245/2009" username="[email protected]" password="password">
   <cfhttpparam type="header" name="Accept" value="application/xml">
   <cfhttpparam type="header" name="Content-Type" value="application/xml">
</cfhttp>

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:

<cfset result=xmlparse(cfhttp.filecontent)>
<cfdump var="#result.daily.day_entries#">

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

<cfoutput>Hours:#result.daily.day_entries.day_entry[1]["hours"].xmltext#</cfoutput>

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 (recovered from the archive.org site).

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.

Better file searching (on Windows) with a powerful, fast, easy tool

Note: This blog post is from 2009. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.

Update in 2019: Though this post is from 2009, I still use and recommend this tool daily, so nothing about what I said below has changed (except of course where I indicate other informational updates in 2010 and 2013). And to be clear the tool is updated constantly and sports a modern interface (unlike the favored "old tools" of other folks, which may look the same as they did 20 years ago).

Ever need to do a search for files with some given text (or files of a given name) in Windows? I realize you may use a favored file editor to do it, or (worse) may rely solely on the anemic Windows find. I'd like to point you to an awesome and free alternative.

For years I've used a great freeware tool, FileLocator Lite, and I love FLL for several reasons (as does nearly everyone I show it to). Read on for more.

[....Continue Reading....]

Copyright ©2020 Charlie Arehart
Carehart Logo
BlogCFC was created by Raymond Camden. This blog is running version 5.005.
(Want to validate the html in this page?)

Managed Hosting Services provided by
Managed Dedicated Hosting