Tag Archives: api

Harvest Reports WordPress Plugin

When freelancing I use the Harvest application to manage all of my time tracking. It has made invoicing painless, and while I got it thinking I was over-charging my clients, it turns out then I was not charging them enough! Anyway, after being listed as a WordPress consultant by Automattic I naturally had more WordPress contracts. I then wanted to solve a business need by allowing my clients to view their impending charges inside the familiar WordPress administration interface.

Harvest Reports PluginThis was impossible until recently when Harvest published their full API. I now have the ability, through REST, to retrieve my data via XML, parse it, and put it where I choose. This lead me to creating a WordPress plugin to accomplish this, and I was encouraged by someone at Harvest to make it public domain. So I present to you the “Harvest Reports WordPress Plugin.” See the screenshot on the right for what will be accomplished with the plugin.

Remember that this was made to solve a specific business need, namely the display of pending costs incurred since the last invoice. This is not meant to be an exhaustive representation of their API as it only uses a slice of it.

Requirements

  1. WordPress 2.3+
  2. A Harvest Account
  3. PHP5

You might wonder why you need PHP5 as WordPress only needs PHP4. I use the PHP5 SimpleXML functionality to parse the XML. This is far easier then trying to do it in PHP4. Most hosts do offer PHP5, but you might have to add the following to your .htaccess file to utilize that edition.

AddHandler application/x-httpd-php5 .php

Installation

  1. Download the plugin
  2. In WordPress 2.3 — 2.5 go to “Options” — “Harvest Reports”, and in 2.5 go to “Settings” — “Harvest Reports”.
  3. Enter your information
  4. Hit “Save”
  5. Go to “Manage” — “Your Chosen Title” to see the report

To get your project ID go to your Harvest dashboard — “Manage”, and you’ll see your projects listed. When you open up one you’ll see a numerical value in the URL bar (e.g. yourname.harvestapp.com /projects/49691/). The value you want is 49691. Remember this is only meant for one project, as that was the business need I needed it to solve. Also, if you want to limit the end date on the report I have included that, but leave it blank to retrieve data up to the second.

Caveat On Hourly Rates

Since this plugin is intended to ultimately provide a monetary figure I wanted it to get the default hourly rate from the API. Unfortunately, when I first parsed the XML I saw that despite the fact that my tasks use my default hourly rate nothing was in the XML returned. I pinged their support and got the following rationale.

“When you read the Task API, you basically get back “No setting” at the second (task) level. We use the rates for reporting (and invoicing coming soon), here the defaults get cascaded. But for the API no cascading takes place to make it evident from where the value comes.”

What this means is that for every task that is used for the project you have to go in and manually set the hourly rate. Not ideal, and to me it’s not expected behavior (especially since the reporting tool inside the Harvest interface automatically uses that value), but once you set it you can forget it.

Upcoming Features

Even though I’ve worked a lot on this and need a break I still have improvements in mind.

  • JavaScript date picker
  • Exception handling from the API
  • Ajax retrieval of projects inside the options page (no need to insert a project ID manually)

I also need to double check that is handles tasks that aren’t billable by default correctly. Since I only track tasks that are billable I didn’t test this, but maybe someone can verify for me.

Props

I want to say thanks to Danny Wen of Harvest for encouraging me to do this, and Andrew Charlton of Geekly Weekly for pointing me in the way of cURL and SimpleXML.

5 Replies

jQuery: JavaScript That Doesn’t Suck

I hate JavaScript. I mean I really hate JavaScript. Dealing with different implementations of the DOM between browsers is a menace I couldn’t duplicate if I tried. I’ve tried JS libraries from Mootools, script.aculo.us, and so on until recently.

I knew jQuery existed, but I didn’t realize how powerful the language was until recently. When I realized I could select and manipulate DOM elements with CSS selectors then I was off to the races! I love how it’s tailored for designers who already understand that syntax. There is no more getElementById(“search”) or other garbage, because I can write this.

$("search").show();

Now, that is elegant! The only thing more impressive then the way it does selectors is how extensive the API is. Not only is extensive, but it is actually understandable. It’s the perfect balance between extensibility and ease of use. It’s like adding Mootools and script.aculo.us together with better DOM selectors.

Toggle Goodness

I love JavaScript toggles and its variations. It’s much more elegant that simply changing an element from display “none” to “block.” jQuery comes with an easy way to toggle elements, and I recently did something like this at work. 

$(".click").click(function() {
        $(".toggle").slideToggle("fast");
	return false;
});

Ajax With jQuery

jQuery doesn’t stop there. Doing Ajax is simpler than it seems it should be. Here’s a function that onclick will do a GET via Ajax and return a message notifying the user that the request was successful.

$(".ajax").click(function() {
	$.ajax({
    		type: "GET",
    		url: "load.html",
    		dataType: "script"
		})
	$(".successmsg").ajaxSuccess(function(evt, request, settings){
    	        $(this).append("<p>Successful Request!</p>");
	});
});

What if I want to append content into the DOM? Difficult right? Not so much.

$(".append").append("Append some text");

jQuery Plugins

The cool thing for all those effects that jQuery doesn’t provide out-of-the-box then it provides a rich API for users to develop plugins on top of jQuery. For instance, my portfolio utilizes the Coda-Slider jQuery plugin.

At work I was tasked to create some DHTML menus which I believe is a usability nightmare and an IA mistake, but alas I had to. I wanted to maximize the usability, and I found Superfish which is “Suckerfish on ‘roids.” I was able to make sexy menus that had plugins on top of the plugin including the hoverIntent jQuery plugin which is smart enough to know whether you really want the menu or if you’re just trying to move around the page.

Additional Resources

Well, that’s just scratching the surface of what jQuery can do! While learning more about it I’ve found several sites that have helped me.

Tutorials/Blogs
jQuery Plugins
API Documentation
IDE Integration

Leave a reply