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.
This 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
- WordPress 2.3+
- A Harvest Account
- 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
- Download the plugin
- In WordPress 2.3 — 2.5 go to “Options” — “Harvest Reports”, and in 2.5 go to “Settings” — “Harvest Reports”.
- Enter your information
- Hit “Save”
- 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.
