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.
[source:php]AddHandler application/x-httpd-php5 .php[/source]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.
Love the info you have provided here. I am interested in changing your php script to allow the return of info I need in Harvest but I have to admit I do not know where to start. Could you possibly direct me to where I can start to edit your code to allow this?
@Evan: Well, I don’t know what data you want to edit so that it returns correctly. I no longer have an Harvest account (I closed my business and no longer need it) so I can’t test it. The support guys at Harvest are a lot of help and reply quickly support@getharvest.com.
Thanks for your work on this!
Danny … cheap and effective :).
I get this error when using the plugin, using WordPress 3.3.1
Warning: SimpleXMLElement::__construct() [simplexmlelement.–construct]: Entity: line 1: parser error : Start tag expected, ‘__construct(‘Redirected to h…’) #1 [internal function]: retriveapi(”) #2 /home/art365co/public_html/wp-includes/plugin.php(405): call_user_func_array(‘retriveapi’, Array) #3 /home/art365co/public_html/wp-admin/admin.php(151): do_action(‘tools_page___FI…’) #4 /home/art365co/public_html/wp-admin/tools.php(10): require_once(‘/home/art365co/…’) #5 {main} thrown in /home/art365co/public_html/wp-content/plugins/harvest-reports/harvest-report.php on line 54
[…] PHP5, because the plugin uses SimpleXML in PHP5 to parse the XML from the API. Please visit the plugin page for instructions on enabling PHP5 via your […]