Imagine being able to keep an eye on your important eCommerce metrics on a large screen that auto updates!  That sounds like a perfect candidate for a Geckoboard widget!

To get the ball rolling we're starting with one of the most widely used eCommerce platforms, Magento.  The implementation is a little different to how we usually do it as Magento is self-hosted software, but it gives us the opportunity to really build what people need and it allows them to customise it to their taste.  Right now, the script outputs either the volume or total value of orders between 2 dates, and optionally also outputs the same data from a different period for the sake of comparison.  The periods can be send via URL parameters.

An example of how it would be used with Geckoboard would be to show the volume/value of sales on your Magento store over the past 30 days and compare it to the previous 30 days.   

Warning

Today we're releasing v1 of the Magento script, it's not perfect but it's a start and with your help and feedback we can make it into something special.  This script was written by me, Paul, while the developers of Geckoboard (the brains behind the whole operation) were working on some major changes to the dashboard.  My PHP skills are poor so see this as a test script and only deploy to production when you're satisfied it doesn't break anything.  You have been warned.

One final thing before we get on to explaining how this works, please do change the script and adapt it to your purpose but please also share those changes with the rest of the community here.  You've nothing to lose and you could make a lot of people very happy :)

Installation

There are two files attached to this post (response.class.php and gbwidget.php, find them at the bottom) that need to be uploaded the same directory on a publicly accessible server capable of executing php (I simply used the root of my local Magento test install).  You'll need to make some modifications to gbwidgets.php before you start:

1. Line 54:  You need to change the URL here to reflect your server.  My Magento root for testing was http://localhost:8888/magento, I don't know a lot about Magento but I reckon if you substitute your shop's home page for that string it should be OK.  So your URL might look something like http://www.yourmagentoshopname.com/api/soap/?wsdl .
2. Line 58:  Substitute your values for apiUser and apiKey.  These are the ones you set up in the admin console under System>>Web Services
3. Line 62:  This is a filter which tells the script what order statuses to ignore.  It's currently ignores order with a status of 'On Hold', 'Canceled', 'Suspected Fraud' and 'Payment Review'.  Change this if you want to.  You can also add any other filters here.
4. Line 79:  For security this file can only be accessed by a user with a security key.  At the moment it's set to '123', change this here and keep a note of it, you'll need it for the Geckoboard part.

How to use

Assuming you placed the scripts in the root of your Magento install and that's located at "http://www.yourmagentoshopname.com/" here's an example URL you would use:

http://www.yourmagentoshopname.com/gbwidget.php?ps=30&pe=1&pps=60&ppe=31&m=2

This would return 2 values; the value of sales in the 30 days to last night and the value of sales in the 30 days previous to that.  The XML that's produced (or JSON if you prefer, see line 12 of gbwidgets.php) is enough to drive the "Number and secondary stat" Geckoboard widget.  See this page for more info on the custom widget types.  This part is lifted from the documentation in the script:    

• ps - period start (days ago incl.) - default 1
• pe - period end - default 1
• pps - prior period start (for comparison purposes) - optional
• ppe - prior period end - optional
• m - metric type - 1=order volume, 2=order value (default 1)
• The default values will return sales yesterday.  To return volume of sales in past 30 days (including today) and compare against previous 30 days use ps=30&pe=1&pps=60&ppe=31

In Geckoboard

Once your scripts are modified and ready to go, fire up your Geckoboard dashboard and add a new widget.  Use Custom Widget>>"Number and secondary stat" with the following settings:

Now just hit "Add to dashboard", and you're done!

What now?

This is only the beginning - you can enhance this script to return different metrics and format the data for different widget types including the newly introduced custom charts.  Once you confirm this is working I'll open it out to others on the Help & Support forum and hopefully you guys can build on it from there.
In the meantime, let me know if anything is unclear or if you're having any difficulty and I'll do my best to help.