Friday, December 3, 2010

Force.com Workbench v20 is out! Get it working on Mac OS X

I am a big fan of Workbench, an awesome PHP app that's open source on google code, and I am even more happy now that v20 has been released! I saw on the code site that there's only been 238 downloads – if you haven't used this before, you need to take a look! Since starting to use it I now make more use of Workbench than I do of Data Loader – not that Data Loader doesn't have its place, but Workbench is a lot more flexible in its access and display of data to humans.

For the non- or only vaguely-techies among you, a PHP app requires a web server to run on, so Workbench is a little more involved than just downloading install.exe, but it's well worth the adventure. I have a Mac and I thought I'd post a step by step of how to get this working – believe me, it's worth your while (and Friday afternoon) to get this up and running. If you're on a PC then google for 'force.com workbench PC installation' and I'm sure you'll find similar posts.

1. Get yourself a web server. Apache is perfect; even better, it comes nicely set up and bundled as part of XAMPP. Download the XAMPP dmg from SourceForge and install it into /Applications

The good part about installing this packaged version of Apache is that it already takes care of a number of extensions that you would otherwise need to worry about – like the SOAP and SSL extensions. Happy days!

2. XAMPP should have installed itself under /Applications/XAMPP. Go and find this directory, and within it there should be a link to htdocs. This is your web server's root directory.

3. Download v20 of Workbench from the google code site here. I've downloaded the stable v20.0.0 but you could try the beta version also.

4. Unpack the contents to a folder called 'workbench' or similar under your htdocs directory

5. Run the XAMPP Control utility (in the base XAMPP directory) and then click on the start button for Apache. Note you'll need to be an admin user to do this; you'll likely get prompted if you're not.

6. XAMPP starts up the Apache web server on port 80 by default, so in a browser navigate to http://localhost/workbench. You should see the default login page for Workbench.

If you have a direct connection to the internet then you're good to go; you should be able to enter your username and password from here and sign in! Use the advanced mode if you want to sign into a sandbox org, or change the default login URL.

Also note that you may need to append your security token to the end of the password if you're outside your org's trusted IP range.

If you're using a proxy server then there are a few additional steps to perform, so read on...

Proxy setup

If you're on a Mac that's behind a firewall then you'll need to configure proxy settings.

1.First you need to make sure that the proxy options are enabled in the config. Go to htdocs/workbench and open config.php

2.Search for the string 'header_proxyOptions' and you should come across an array of settings. Notice that in this array, the value for the key of 'display' is 'false'. Change this to 'true'

3.You also need to ensure each of the proxy options is overrideable. Immediately below the 'header_proxyOptions' array are 5 more arrays: proxyEnabled, proxyHost, proxyPort, proxyUsername and proxyPassword. For each of these arrays, change the value for the key of 'overrideable' from 'false' to 'true'

4.Save your config.php and refresh the login page. Then hover your mouse over the Workbench image and you'll see a drop down menu. Navigate to Settings

5.Under these settings, you should have the proxy options. Check the 'proxy enabled' checkbox and add details of the host and port, and username/password if applicable.

6.Once you Apply these settings then your connection should be good to go!

General settings

Even if you don't need to enable proxy settings, you should still take a look at the Settings menu, by hovering over the Workbench image on the login page and navigating to Settings. These are the usual options for default batch sizes, assignment rules, and other options similar to the Data Loader settings.

Other PHP settings

XAMPP comes with a reasonable set of PHP initialisation parameters, for memory size etc, so for the most part your workbench should perform well even with large files for your DML operations. If you find you are hitting limits though, try increasing some of the following parameters, found in your PHP.INI file under /etc in your XAMPP base directory.

max_execution_time = 30     ; Maximum execution time of each script, in seconds
max_input_time = 60    ; Maximum amount of time each script may spend parsing request data
memory_limit = 128M      ; Maximum amount of memory a script may consume (8MB)


upload_max_filesize = 128M

Using the Bulk API

If you are keen to use the bulk API for asynchronous processing of really large datasets, then you'll need to enable cURL. Because the bulk API uses REST as opposed to SOAP for its application protocol, you need to ensure cURL extension is enabled in PHP.

To do this, go to your PHP.INI file and search for 'curl'. You should find a commented line in the extensions area of the file:

;extension=curl.so
(NB. Don't uncomment the line extension=php_curl.dll as that's for Windows only)

Remove the ; to uncomment the line, and save your PHP.INI file, then reboot Apache. That should be it! Note again that if you're using a proxy server then you'll need to play around with the proxy settings for cURL. This means playing around with the curl_init() call in the PHP script. Check out my post on the developer forums here for more details.

Have fun with Workbench!

1 comment:

  1. I just ran into this great write up. I'm glad that you are enjoying Workbench and helping people get up and running!

    The only thing I would add is that it is recommended that users use the configOverrides.php file instead of editing config.php directly. This makes it so upgrading between versions is easier since the config.php file could change version to version, but configOverrides.php will always stay the same. Also, if proxy settings should be global for all users on your network, you can leave overridable as false and put the global values directly in configOverrides.php as "default".

    Thanks again for spreading the word about Workbench!

    -Ryan (Workbench creator)

    ReplyDelete