Workbench

Workbench is a powerful, web-based suite of tools designed for adminstrators and developers to interact with Salesforce.com organizations via the Force.com APIs. Workbench includes robust support for the Force.com Partner, Bulk, Metadata, and Apex APIs that allows users to describe, query, manipulate, and migrate both data and metadata in Salesforce.com organizations directly in their web browser with a simple and intuitive user interface. Workbench also provides many advanced features for testing and troubleshooting the Force.com APIs, such as customizable SOAP headers, debug logs for API traffic, backward compatibility testing with previous API versions, and single sign-on integration within the Salesforce application.

Contents

Screenshots

Advanced Login
Describing an Object
Exporting to a File
Single Sign-On Integration with Salesforce
Inserting Records with Smart Lookup
Searching for Records
Running a Query in the Browser
Metadata Retrieve
Workbench and API Settings

What's New: Version 3.0.19 for Summer '10

Metadata API Support

Rounding out support for all of the Force.com APIs, Workbench 3.0 now provides robust support for the Metadata API. Users can now describe, list, deploy, and retrieve metadata components and monitor asynchronous metadata operations via a simple yet powerful interface.

Fresh New Look and Menus

Workbench 3.0 now offers users a fresh new look and feel with a smaller header and navigation bar. This improves the user experience while giving back valuable screen real estate and providing a more extensible menu system for future growth.

Switch API Versions On The Fly

Testing and troubleshooting operations on multiple API versions no longer means tediously logging out and back in again. With Workbench 3.0, the API version of the Workbench session can be changed on the fly. In addition, a new page with the current session info has been added for quickly accessing vital information about the connection, user, and organization.

Bulk API: Hard Delete and Processing Time Reporting

Force.com Bulk API 19.0 introduced the ability to hard delete records without first going to the Recycle Bin. Workbench 3.0 fully supports this new Hard Delete operation along side the standard Delete functionality.

Persistent Named Queries & Searches

Workbench 2.5.8 introduced the ability to name and save queries and searches, but they only lasted as long as the user's session. Now with Workbench 3.0, these named queries and searches are persisted from session to session and can even be retrieved (optionality) across users and organizations.

Demo

Try out Workbench before you installing it on your own web server. Some of the file size limits are restricted for this demo. This demo is running on an unsecure connection, so it is highly recommended to not use with production organizations.

Standalone PHP Bulk API Client

The Force.com Bulk API client that is used in Workbench is also available as a standalone download for use in third-party PHP applications. For sample code and instructions, download the PHP Bulk API Client:

http://code.google.com/p/forceworkbench/downloads/list

FAQ

General

What are the advantages of the Workbench compared to the Data Loader?

  • An on-demand, web-based interface to your organization's data that combines the functions of the Data Loader and the Force.com Explorer.
  • Clean, easy-to-use, user-centered interface that remembers your settings throughout your session.
  • Describe function to access your organization's metadata.
  • Simplified results on one easy-to-read table displayed right in your browser.
  • Easier and faster SOQL query builder that dynamically updates itself.
  • SOSL search function to easily build and test search strings
  • The choice to view queries right in your browser or download them as a CSV file.
  • Query All function to query archived items as well as items that in your Recycle Bin.
  • Undelete function to restore items from your Recycle Bin by Id.
  • Purge function to permanently delete items from your Recycle Bin by Id.
  • Single sign on integration with the Salesforce user interface for easy access from a custom web tab.
  • Smart Lookup to automatically find referenced object ids through foreign external ids, including polymorphic relationships.
  • Advanced Settings that give granular-level control of configuration of the Workbench and interactions with the Force.com API
  • Ability to run Apex run anonymous blocks against dynamic API versions directly within the application
  • Metadata API support


What is the Workbench not designed for?

  • Being web-based, the Workbench is subject to browser and connection timeouts. As such, is it not recommended to use the Workbench for large data loads or exports. It is much better suited for quick, on-the-fly data management, which is something other API integration tools lack.
  • The Workbench cannot be run from the command line, used for automated processes, or support mapping files


Is the Workbench just an extension of the Data Loader?

No, the Workbench was built completely from the ground-up using PHP and JavaScript, and binds to the Force.com Web Services API via the PHP Toolkit. It does not reference or build upon any of the Java code in the DataLoader, but was modeled after its concept.


How are the version numbers formatted?

Because the version number is appended by the version number of the Force.com API WSDL file being used, the the version numbers tend to get rather long. The version numbers follow the format below:

Major.Minor.API


If this software is Open Source, where can I get the source code?

The source code is available at the Google Code project site for download and SVN checkout and distribution under the Open Source BSD License. Please see the About page for details.


Is the Workbench created by Salesforce?

No, the Workbench is not a product of nor supported by salesforce.com, inc. However, there is great community support on the Workbench discussion board.

Login

How do I login to a non-production instance (i.e. Sandbox, Pre-Release, etc.), with a session id, or other API versions? On the Login page, click the 'Advanced' radio button for options to login to different API endpoints by using the QuickSelect menu to choose your instance and API version. To login to Sandbox with a username and password, select 'test'. To login to any instance with a session id (instead of username and password), paste in the session id and then select the specific instance that org is located. If you would like to test functionality on a previous API version, this can also be set on the QuickSelect menu, but please be aware that this setting could cause unexpected behavior in the Workbench as it is designed and tested for the latest API version. With Version 2.2.15, the Workbench can now guess your org's instance from the Session Id with the new Server Url Fuzzy Lookup feature enabled. This will not work correctly for previously migrated orgs, but can also be overridden or simply disabled under Settings.

If you would like to do an advanced login programatically, please see the FAQs below.


How can I change API versions without logging out of Workbench?

Click on the user info link in the upper-right corner below the menu bar and you will be brought to the User Session Information page with a dropdown of the available API versions. Choose the desired API version and your user session will be updated. If you choose an unsupported API version, your user session will automatically reverted to the previous version.


How do I use the Workbench in a Web Tab in Salesforce for single sign-on?

The Workbench has exposed an API to allow users to automatically log in to the Workbench by providing their Server URL and Session Id in the URL arguments. This can be to integrate the Workbench into a Web Tab directly in Salesforce for single sign-on into the Workbench. To integrate the Workbench into your org, follow the instructions below:

  1. Login to Salesforce
  2. Setup | Create | Tabs | Web Tabs | New
  3. Choose Tab Layout
    • Full page width is recommended
  4. Define Content and Display Properties
    • Tab Type: URL
    • Tab Label: Workbench
    • Tab Tab Style: Choose a style
    • Content Frame Height (pixels): Choose the maximum amount available for your screen (you may have to edit this value to find the correct value for your screen)
  5. Button or Link URL
    • Button or Link URL (replace "<your_server>" with the web server the Workbench in installed): https://<your_server>/workbench/login.php?serverUrl={!API_Partner_Server_URL_150}&sid={!API_Session_ID}
    • Encoding: Unicode UTF-8
  6. Save


Can I just pass in my username and password directly into the URL for an auto-login bookmark?

Yes, but this option is NOT recommended for production environments or any environment that needs to be secure. This should only be used for a test environment where you do not care if anyone sees your password in plain text, as it will be visible directly in the URL and not secured in any way. If you understand the security risk, this is the URL format of the link to auto-login:

https://<your_server>/workbench/login.php?un=<your_username>&pw<your_password>


Can I auto-login with advanced settings or other programmatic alternatives?

Yes, with Workbench 2.2.15 the auto-login API was greatly enhanced so you can login using query parameters that support everything that could be configured through the user interface. Below is the complete list of query parameters for login.php, with a syntax similar to the FAQs above:

Parameter Description Restrictions
un Username Must be used with pw and without sessionId
pw Password Must be used with un and without sessionId. Understand the security risks associated with this parameter -- your password will be visible in plain text in the URL. Strongly NOT recommended for production organizations.
sessionId User's authenticated Session Id Must be used without un or pw
serverUrl Full API Server URL Must be used without inst or api. Can be used with un/pw OR sessionId.
inst Organization's API instance (i.e. na1-api, eu0-api, cs0-api). This parameter overrides the Default Instance specified in Settings. Used to dynamically build the Server URL. Can be used optionally with api; otherwise default API version is used. Must not be used with serverUrl.
api API Version. This parameter overrides the Default API Version specified in Settings. Used to dynamically build the Server URL. Can be used optionally with inst; otherwise default instance is used. Must not be used with serverUrl.
startUrl First page user is brought to after login. Equivalent to "Jump to" in user interface. None
clientId Specifies a Client Id (e.g. "API Token") to use with this login for special API functionality, such as logging into Professional Edition organizations. This parameter overrides the Client Id specified in Settings. None
orgId Specifies an Organization Id for use with Customer Portal, Partner Portal, and Self-Service Portal logins. This parameter overrides the Organization Id specified in Settings. Not needed for standard, non-portal Salesforce users.
portalId Specifies the Portal Id for use with Customer Portal and Partner Portal logins. This parameter overrides the Organization's Portal Id specified in Settings. Not needed for standard, non-portal Salesforce users.


I always use Advanced Login. Is there a way to go directly to that page?

Yes, there is a 'Default Login Type' option on the Settings menu to set your preference, or just add "?adv=1" to the end of the login URL, like this:

https://<your_server>/workbench/login.php?adv=1


When I provide a Session Id for login, the Workbench always chooses the wrong instance for the Server URL. Why is this happening and how can I disable it?

The Server URL Fuzzy Lookup feature attempts to guess your organization's instance from the Session Id, but this will be incorrect if your organization was ever migrated to a new instance. To disable this feature, simply uncheck the box next to "Enable Server URL Fuzzy Lookup" in Settings. This can also be disabled for all users by the Workbench admin in the config.php file. See that file's header for details.


Instead of always going to Advanced Login, is there a way to change the default settings for the Standard Login?

Yes, you can override the default API version and instance in Settings. This setting changes both the configuration for the Standard Login and the default options in the Advanced Login.

Data Management

What does the 'Load records asynchronously via Bulk API' option do when performing an Insert, Update, Upsert, or Delete

When performing an Insert, Update, Upsert, or Delete, a option is provided to load the records asynchronously via the Bulk API, which is available in API 17.0 and higher (18.0 and higher for Delete and 19.0 for Hard Delete). If this option is selected, the records are broken up into batches and sent to Salesforce via the REST-based Bulk API to be enqueued for processing when server resources are available. After the records have been uploaded, their progress and results can be monitored directly in Workbench or viewed in Salesforce under Setup | Monitoring | Monitor Bulk Data Load Jobs. There are also options under the Workbench Settings menu to control behavior of these asynchronous operations:

  • Asynchronous Concurrency Mode
  • Asynchronous Record Batch Size

For more information about the Bulk API, please see the Salesforce Bulk API documentation

What is Smart Lookup and how does it help me?

Smart Lookup is an optional function when using Insert, Update, or Upsert to allow you to provide foreign external ids or standard id lookup field values to automatically find their respective Salesforce ids though related objects.

For example, if you have CSV file of Contact records to insert and associate with different record types, normally you would need to first query for and replace all the plain text record types with the RecordTypeIds using a VLOOKUP function. Now, with Workbench 2.0, you can insert the Contact records directly and have the Workbench and the API do the work of looking up the RecordTypeIds by using the Smart Lookup function. To use Smart Lookup, first make sure it is enabled in Setting, upload your file using Insert, Update, or Upsert, and you will be presented with an additional Smart Lookup column on the right. There will be a dropdown selection box for each field that references another object with a relationship. For the Record Type example, simply select RecordType.Name in the Smart Lookup column on the RecordTypeId row and the column that the record type name is in your CSV file, and the Workbench will automatically associate your Contacts with the correct record type based on just their names.

The same thing can be done for any external id fields on related objects. For example, if your Contacts needed to be related to the proper Accounts, but you only knew the Accounts' external ids, Smart Lookup can automatically find the Accounts' primary Salesforce ids.


What is the difference between Delete and Purge?

Delete moves the records to your organization's recycle bin and can be undeleted if that object has the Undeletable attribute, whereas Purge permanently deletes items that are already in our organization's recycle bin. Note, some types of objects are immediately deleted from your organization when they are deleted. Be sure to check the if the record has the the Undeletable attribute before deleting records. This can be done using the Describe function and opening the Attributes folder.


How do I hard delete records from a Salesforce organization? Introduced in Force.com Bulk API 19.0, records can be permanently hard deleted from Salesforce organization skipping the Recycle Bin. To use the functionality in Workbench (3.0.19+), delete the records as normal, except check the checkbox labeled "Permanently hard delete records" in the wizard. Note, to hard delete records, users must have the "Bulk API Hard Delete" permission enabled on their profile.


Why do I get the error similar to 11/9/2005 is not a valid value for the type xsd:date when trying to create, update, or upsert records?

This error is caused by the way Excel saves dates in the local format when creating CSV files. The API only accepts dates and dateTimes in the following formats:

  • Date only
  • YYYY-MM-DD
  • Date, time, and time zone offset
  • YYYY-MM-DDThh:mm:ss+hh:mm
  • YYYY-MM-DDThh:mm:ss-hh:mm
  • YYYY-MM-DDThh:mm:ssZ

Note, the Data Loader automatically converts the dates from your locale to the formats above, but the Workbench does not perform any manipulation to your data. To format the date properly in Excel, highlight the cells, Format | Cells | Date | Locale: ISO (International). For the dateTime values, a custom format must be created and used. The zone offset is always from UTC. For more information about these date and time formats, please see the following guides:

Query & Search

How do I query records from a related parent object? Starting with Version 2.2.15, you can query parent records using relationship.field dot notation and have the query results displayed in one, simple table for browser viewing or CSV export. For example, to get your Contact’s Account Name, First Name, Last Name, and Owner’s Name, write your SOQL query like this:

SELECT Account.Name, LastName, FirstName, Owner.Name FROM Contact

Just remember to use the relationship names (“Account” and “Owner” in this case) to traverse the hierarchy up to five levels separated by dots. These names can be found under in the sub-folders of the fields on the Describe tab.


How do I query records from a related child object? Starting with Version 2.3.16, you can query child records using a nested sub-query that traverses a child relationship of the primary query and have the results displayed in one, simple nested table for browser viewing (no support for CSV export of child relationships). For example, to get all your Account records with their associated child Contact's first and last names, write your SOQL query like this:

SELECT Name, (SELECT LastName, FirstName FROM Contacts) FROM Account

Just remember to use the child relationship names (“Contacts” in this case) to traverse down the hierarchy up to one level. These names can be found under in the Child Relationship sub-folders on the Describe tab.


Does the Workbench support queryAll()?

Yes. By default, the Query function uses the standard query() API call, which excludes archived and deleted records from your organization. To access deleted and archived records with the queryAll() API call, go to Query and choose "Include" for the "Deleted and archived records" option.


How do I call queryMore()?

The Query function does this automatically for you if the "Automatically Retrieve More Query Results" option is enabled in Setting or when exporting to a CSV file. However, if you choose to leave this setting disabled, a "More..." button will appear at the top and bottom of your query results when the more record than your default batch size is returned. Simply click one of these buttons to retrieve more results. The query batch size can be changed with the "Preferred Query Batch Size" setting on the Settings menu. Please note that large batch sizes or automatically retrieving large sets of data can cause browser timeouts and can make the Workbench hang. If this is the case, restart your browser and try again with a smaller batch size.


How does Search work and how do I use it effectively?

The Search function allows you to use the Salesforce Object Search Language (SOSL) to construct simple but powerful text searches for the search() call. Unlike SOQL, which can only query one base object at a time, SOSL allows you to efficiently search text, email, and phone fields for multiple objects at a time with a single query.

First, you must provide a search string and then you can optionally provide specific objects which limit your search. Then you can list which fields you would like returned by providing a comma-separated list of API names for the fields. If you would like to narrow down your results within each object, you can add WHERE and LIMIT clauses in the 'including fields' boxes. For example, you could write Name, CloseDate, My_Custom_Field__c WHERE CloseDate > LAST_YEAR LIMIT 5 for the Opportunity object to return the Name, Close Date, and your custom field for the first five records where the Close Date is greater than last year. For more examples, see the SOSL guide in the API Documentation.

Metadata

How do I describe and list metadata types and components with Workbench? Combining the power of the describeMetadata() and listMetadata() Metadata API operations, the Metadata Types & Components page describes and lists the metadata types and components of the logged organization. To navigate between parent and child metadata types, click the INFO links within the Type Description folder.


How do I retrieve metadata components from a Salesforce organization with Workbench? Workbench supports both retrieving packaged and unpackaged metadata components by sending a retrieve request to the Force.com Metadata API, which processes the request asynchronously on the Salesforce servers. You can track the progress of the retrieval in Workbench and download the results when the server-side processing is complete.

To retrieve packaged metadata, go to the Retrieve page and simply provide a comma-separated list of package names. To retrieve unpackaged metadata, you will need to upload an unpackaged manifest file (i.e. 'package.xml'). For samples of the manifest files, please see:

http://www.salesforce.com/us/developer/docs/api_meta/index_Left.htm#StartTopic=Content/manifest_samples.htm

Once the retrieve request has been created and sent to Salesforce, you will be brought to the Metadata API Process Status page to track the asynchronous processing on the server. Simply click "Refresh" to see the latest status. Once the processing is complete and the ZIP file is available, the refresh button will disappear and a download link will be available. Note, once navigating away from the page or downloading the ZIP, it will be deleted from both the Salesforce and Workbench servers.


How do I deploy metadata components to a Salesforce organization with Workbench? Workbench fully supports file-based metadata deployments with complete control over deploy options. To prepare to deploy, create a deployment ZIP file (see: http://www.salesforce.com/us/developer/docs/api_meta/Content/file_based.htm#using_deploy_retrieve). It may be easier to create the ZIP file using the Retrieve function (usually from the source organization). To stage for deployment, choose the prepared ZIP file along with any applicable deployment options on the Deploy page in Workbench. Note, if you get a "No package.xml found" error and you do in fact have a package.xml in the deployment ZIP, try toggling the "Single Package" option.

Once the deployment request has been staged and sent to Salesforce, you will be brought to the Metadata API Process Status page to track the asynchronous processing on the server. Simply click "Refresh" to see the latest status. Once the processing is complete, the deployment results will be shown.


How do I view the status and results of an asynchronous metadata operation not initiated with Workbench? If you started an asynchronous metadata operation (i.e. deploy(), retrieve()) using some other Metadata API client (e.g. Force.com Migration Tool for ANT) and know the asyncProcessId, you can use Workbench to view the status and results. Simply go to the Metadata API Process Status page (ensure there are no query parameters on the URL) and provide the asyncProcessId to view the status and results.

Utilities

What does the Execute function for and what do I type in the box?

The Execute function allows users to execute Apex scripts directly from the Workbench as an anonymous block against a dynamic set of API versions and debug levels. This is similar to the System Log in the Salesforce application. For more information about Apex code, please see the documentation:

http://www.salesforce.com/us/developer/docs/apexcode/index.htm

Settings

How do I customize the Workbench and provide SOAP Headers to the Force.com API?

The Settings menu allows you to granularly control the Workbench right inside your web browser to configure everything from alphabetizing fields to how many records are included in batched together in API calls to whether assignment rules are fired when you insert Leads and Cases. These settings are stored in your browser's cookies folder and will remain in effect across logins to multiple orgs.

To globally change the default values on the Settings menu and toggle which ones can be overridden by end users, Workbench administrators can access the config.php file on directly from the web server (not the browser) to make these adjustments. Please see the header in the config.php file for details.


How do I view the disable the security warning, the requested time, or show the SOAP Messages?

These three settings are configured to not be changed by end users by default, but if you would like to either make global changes or allow individual users to be able to make changes, locate the checkSSL, displayRequestTime, debug properties in the config.php file to make adjustments. Please see the header in the config.php file for details.

Installation

Download

Get the latest version of the Workbench from Google Code: http://code.google.com/p/forceworkbench/downloads/list

Upgrade Instructions

If you are upgrading the Workbench from a previous version, simply replace your old Workbench folder on your web server with the new one. You can also run them side by side if you would like to have a transition period to test new features before releasing to your users.


Starting with 2.4.17, it is recommended to make admin-controlled configuration overrides in the new condigOverrides.php file instead of directly in the config.php file, as these changes might be affected by upgrades. If you have made changes in config.php, move these to the new configOverrides.php file (there is an example in the file) and restore the config.php to its original state. At runtime, any changes in the configOverrides.php file will automatically be applied to override the defaults in config.php. Next time you upgrade, just retain your configOverrides.php and the settings will be applied to the new config.php.

When you update from 2.4.17, you must backup the file configOverrides.php, and copy again after install.

As of 2.4.17, the PHP cURL module is required for Bulk API operations.

Installation Instructions

Workbench is built on PHP and connects to the Force.com APIs and is designed to be installed once on a central web server and shared by the users on your network. To install and run Workbench, you must have a working web server, such as an Apache HTTP Server, with support for PHP and optionally HTTPS. Once it is installed on your web server, any of the users on your network will have on-demand access to the Workbench via their web browser, assuming they have valid login credentials for Salesforce. Follow the instructions below to install Apache HTTP Server, PHP, and Workbench:

Easier

  • Install an xAMP (LAMP/WAMP/MAMP) bundled installation of Apache HTTP Server, MySQL, and PHP. For a list of WAMPs, please see the Comparison of WAMPs. Workbench has been known to work with Web Developer Server Suite on Windows and MAMP on a Mac. Note, MySQL is not used by Workbench, so you can exclude installation of MySQL if the bundle you are installing allows it.
  • At this point, Workbench will work out of the box with many LAMP/WAMP/MAMP packages. Just download, drop the unzipped "workbench" folder into your server's web document root, and try going to http://localhost/workbench. If this does not work, go through the advanced instructions below to make sure you've got everything setup correctly. If you are still having problems, post a message on the Workbench discussion group.

Advanced

  • Install Apache HTTP Server from http://httpd.apache.org/
  • Install PHP 5.x+ from http://www.php.net
  • Ensure that PHP is registered with your Apache HTTP Server to handle .php files. The following lines should be in <your_apache_dir>\conf\httpd.conf file:
# Dynamic Shared Object (DSO) Support
LoadModule php5_module "<your_apache_dir>/php5apache2.dll"
# AddType
AddType application/x-httpd-php .php
# Anywhere
PHPIniDir "<your_apache_dir>/php5"
  • Ensure that PHP works on a basic level:
  • Create a file called phpinfo.php in your web server's document root directory and paste the following into the file:
<?php phpinfo(); ?>
  • Access the in your web browser by navigating to http://localhost/phpinfo.php. You should be presented with a page of PHP information about the current stage of PHP. If you did not, there is a problem with configuration of either your web server or PHP.
  • PHP 5 includes two .ini files to be used as templates for configuration. Rename php.ini-recommended to php.ini
  • Search for the string "extension_dir" in php.ini. Uncomment it and set it equal to "/ext/". PHP requires an explicit path to find your extensions under Windows.
  • In order to use the HTTPS protocol and other features of Workbench, you need to edit some of the configurations in your php.ini file:
  • Search for "extension=php_curl.dll". There should be a semi-colon in front of that line - remove it to enable the extension.
  • Scroll down and find "extension=php_openssl.dll" and do the same.
  • Now scroll down a bit further and find "extension=php_sockets.dll". Leave this line alone, but insert a new line below it and type "extension=php_soap.dll" on that line.
  • Search for "magic_quotes_gpc" and ensure that it is "Off" (no longer necessary in Version 1.2.12 [2008-04-29] and higher)
  • Search for "file_uploads" and ensure that it is "On"
  • (optional, but recommended) Now you need to copy the SSL library files from the PHP installation directory to your Windows system directory. The two files are libeay32.dll and ssleay32.dll. They need to be copied into the system directory, usually c:\windows\system32 on an XP system. If you happen to have OpenSSL already installed on your computer you may find that these files are already installed. If they are, you should only replace them if the ones from the PHP directory are more recent. Change the extensions on the existing ones by adding '.bak' just to be safe. Note: these files must be readable by the Apache process, which may not run with the same permissions that you have when you copy the file into system32, please check that these are read and executable by world/all users
  • Next, you'll need to add the PHP installation directory to your system path. Note, this step may have already been done by your PHP/WAMP installation. Right-click on My Computer on your desktop (or in the Start menu) and select 'Properties'. Click on the Advanced tab and then the 'Environment Variables' button. Scroll down in the System variables list until you find 'Path'. Select it and click the 'Edit' button. Click at the end of the string and make sure that the rest of the string is not highlighted. Type ";c:\php" at the end of the existing string and click OK until all of the windows are closed.
  • Restart your web server and re-load your phpinfo.php file to ensure it is still working.
  • Download and unzip the Workbench zip file into your web server's document root.
  • Point your web browser to https://localhost/workbench and you should be redirected to the Workbench login page, where you can login using your salesforce.com username and password.
  • If you wish to set Workbench settings for all of your users or choose which settings they have access to override on the Settings menu, open the config.php file and follow the instructions within. Starting with Version 2.2.15, this also includes proxy server settings. If you wish to remove the "Unsecure Connection Detected" message from the bottom (and don't feel like hosting the Workbench using HTTPS), you can disable this as well in the config.php file.

Installing PHP Soap Extension on Mac OS X

Before OSX 10.6, Apple shipped php without the soap extension. As of 10.6, the stock php supports workbench just fine. You just need to enable php by editing httpd.conf and restarting apache.

Option 1: Upgrade to 10.6

So, the best option is to upgrade to Snow Leopard.


Option 2: Install MAMP

Note, PHP soapclient is pre-installed with MAMP (just drop Workbench and you are good to go):

Option 3: Install Marc Liyanage's PHP

This is the simplest route. Just visit Marc Liyanage's site and follow the directions. Marc has provided an OSX package that installs an alternate version, with soap, so the installation is a snap. Don't forget to uncomment "LoadModule php5_module" in /private/etc/apache2/httpd.conf. This has the advantage that you won't be modifying the "stock" php that ships with OSX.


Option 4: Compile and install soap module

This took a while to figure out, so I'm posting the formula here. This worked for me on OSX 10.5.6 on a MacBook Pro Core Duo (intel 32 bit), with apple's php 5.26 and with Apache/2.2.9. However, on another machine, it resulted in soap module being available from the php command line, but not in php under apache. I was unable to figure out what the problem was, so resorted to using Marc Liyanage's php (which is a simpler solution). 

curl -O http://de3.php.net/distributions/php-5.2.6.tar.bz2

tar xjf php-5.2.6.tar.bz2

cd php-5.2.6/ext/soap

./configure --enable-layout=Darwin --enable-mods-shared=all --prefix=/usr --mandir=/usr/share/man --localstatedir=/var --infodir=/usr/share/info --disable-dependency-tracking --with-apxs2=/usr/sbin/apxs --with-kerberos=/usr --enable-cli

make

sudo cp modules/soap.so /usr/lib/php/extensions/php_soap.so

In /private/etc/php.ini:

  • change the ‘extension_dir’ to ‘/usr/lib/php/extensions’
  • enable the extension by uncommenting the line ‘extension=php_soap.so’

sudo apachectl restart

You should be good to go. Check with php -m | grep soap.

Support

Please note that the Workbench is NOT a product of or supported by salesforce.com, inc. For support from the Open Source community, please visit this project's pages below:

Feedback

Have something you want to discuss about the Workbench? Have a great idea for a new feature? Looking for support from the community? Want to find out the latest news about the Workbench? Visit the Feedback & Discussion page today.

Version History

3.0.19 2010/06/17

  • Upgraded Partner, Apex, and Bulk clients to Force.com API 19.0.
  • Added client and user interface support for Metadata API operations describeMetadata(), listMetadata(), deploy(), retrieve(), checkStatus(), deployCheckStatus(), and retrieveCheckStatus(). Users can describe and list metadata types and components, retrieve and deploy packaged and unpackaged metadata components, and monitor asynchronous operations with tree-based visualizations.
  • Revamped user interface to use drop-down menus, new logo, and lighter color scheme with a smaller header footprint giving back more real estate.
  • Added Bulk API support for new hardDelete() operation.
  • Added ability to download Bulk API batch requests.
  • Added Apex/API/Total Processing Time and Failed Records values to Bulk API Status page.
  • Add ability to change API versions without re-login.
  • Added new page for viewing user session information.
  • Extended saved queries and searches to persist user sessions with ability widen scope to outside given user or organization.
  • Added picklist field statistics to describe results.
  • Added convenience command to jump to Run All Tests page in Salesforce.
  • Added warning to Settings page if user attempts to navigate with changes and confirmation dialogue when settings are saved.
  • Added ability to set server port number on auto login.
  • Added unhandled exception handler.
  • Fixed various bugs, including describe.php not auto-submitting on Google Chrome and intermittent logouts when changing settings.



2.5.18 2010/02/21

  • Upgraded Partner, Apex, and Bulk clients to Force.com API 18.0.
  • Added ability to save named queries and searches and recall them at a later time during the Workbench session.
  • Enhanced query and search builders to support an unlimited number of filters (SOQL) and object selections (SOSL).
  • Allow SOQL query results using constructs introduced in API 18.0, such as aggregate function, date functions, GROUP BY, HAVING, and WITH (DATA CATEGORY) keywords. Note, the SOQL query builder in Workbench does not yet support assist with building these queries, but will now display their results.
  • Added support for bulk Delete operations with Bulk API 18.0.
  • Client-side sorting of data tables, including query and search results.
  • Display of stateInfo in batches and jobs for Bulk API and allow failed results to be downloaded.
  • Pretty printing of SOAP messages in debug mode.
  • Added support for Mac-style CSVs.
  • Various minor bug fixes, including: corrected display issues with queries of history entities, added missing attributes in describe results, fixed minor JavaScript events for better keyboard support.

2.4.17 2009/10/10

  • Upgraded Partner and Apex clients to Force.com API 17.0.
  • Added REST client for asynchronous Bulk API data loading operations and fully integrated with existing Workbench functions.
  • Support for new 17.0+ describe object results and object operation filtering.
  • Compatibility with new prefered login.salesforce.com production login endpoint.
  • Added setting for Default Login Type (Standard or Advanced)
  • Expanded multiple functions for compatibility in non-production Salesforce environments
  • Enforce stricter adherence to Partner WSDL versions.
  • Dynamically choose latest Apex API WSDL.
  • Add option to disable HTTPS for testing purposes.
  • Auto-redirect to Login page after logout.
  • Added 'Text Area Rows' option to change the number of rows in text boxes for Query, Search, and Execute functions.
  • Cleaned up PHP errors for users displaying notices to end users.
  • Added AJAX-based API Call Afterburner for testing purposes.
  • Removed "OwnerId" and "RecordTypeId" syntax highlighting in Describe results.
  • Corrected multiple IE cosmetic bugs.
  • Fixed field name alphabetizing to be natural, case-insensitive (A, a, B, b; instead of (A, B, a, b).
  • Added CSS typefaces and fallbacks for Linux users.
  • Refactoring of duplicated page info, error messaging, endpoint construction, API versioning.

2.3.16 2009/06/21

  • Upgraded Partner and Apex clients to Force.com API 16.0
  • Added support for parent-to-child SOQL relationship queries to display nested sObjects For example, [SELECT Id, Name, (SELECT Id, LastName, FirstName FROM Contacts) FROM Account] will display Accounts with their child Contacts.
  • Added the ability to download full results history from file-based API operations. Similar to the success and error files produced by the Data Loader, but in one convenient file that can be downloaded on demand.
  • Introduced optional Describe Results Highlighting for custom fields, system fields, and boolean values.
  • Extended "Link Ids to Record Detail" feature across the entire application. Now, if a Salesforce Id appears anywhere from a query result to a Apex debug log to an upsert, it is automatically hyperlinked to the record detail in the Salesforce user interface. This feature can optionally be disabled.
  • Added advanced login support for new Salesforce instances.
  • Added additional set of buttons at top of Setting page for easier access.
  • Corrected error if more than one Document or Attachment body was queried
  • Made Search results consistent with the rest of the application to start results incrementing at 1.
  • Minor bug fixes to CSV preview.

2.2.15 2009/02/15

  • Upgraded Partner and Apex clients to Force.com API 15.0
  • Added support for child-to-parent SOQL relationship queries to unwrap nested sObjects and display inline in the browser and for CSV exports. For example, [SELECT Id, Opportunity.Account.Name, ContactId FROM OpportunityContactRole] will unwrap the Opportunity.Account.Name value and display inline with Id and Contact. Parent-to-child relationship queries are not yet supported, and a error message will be displayed as such.
  • Added support for AllowFieldTruncation SOAP header and accessible under Settings | Data Management.
  • Fixed bug to allow Client Id to be set before login for access to PE and GE organizations
  • Shows new version notifications on select.php if auto-login is used
  • Query results incremented with continuously across queryMore() batches.
  • Added caps lock warning feature if user has caps lock on when typing password on either standard or advanced login.
  • Ids in query results are hyperlinked to their corresponding record in the Salesforce user interface, with setting to disable if desired.
  • Added Server URL Fuzzy Lookup to guess the instance from the session id on advanced logins, with setting to disable if desired
  • Exposed new auto-login query parameters: inst, api, clientId, orgId, portalId, startUrl
  • Improved logout behavior when a bad sessions is detected
  • Data table row numbering no longer starts at 2, and numbers continue for queryMore results
  • Implemented Login Scope Header both in Settings and for orgId and portalId auto-login parameters
  • Removed proxy configurations from Settings overrides by default. Admins can still make changes in config.php

2.1.14 2008/10/21

  • Upgraded WSDL to Force.com API Partner 14.0
  • Added Execute function to run Apex scripts in the Workbench
  • Added support for semi-joins and anti-joins in API 14.0
  • Added support for IN, NOT IN, INCLUDES, and EXCLUDES to query builder
  • Exposed 'un' and 'pw' URL query parameters for quick standard login with username and password directly in the URL, which can be helpful for bookmarking the login to a test environment. Note, this option is NOT recommended for a production environment, as your password is sent in plain text.
  • Exposed 'login.php?adv=1' URL query parameter to automatically choose the Advanced default login screen.
  • Added settings for default API version and server URL, and the ability to disable unsecure connection detection and request timer.
  • Created collapsible sections for debug logs
  • Corrected minor bugs, including:
  • CSV-exported queries now automatically calls queryMore()
  • Customized settings now loaded before login to allow so client id and proxy settings are not lost after logout
  • Standardized use of ap0-api and eu0-api endpoints in QuickSelect
  • Select screen no longer is blank if no choice is provided
  • 'Use Default Assignment Rule' can be saved successfully
  • Enhanced XSS security
  • Fatal errors on blank CSV output and describe on PE orgs

2.0.13 2008/06/16

  • Upgraded WSDL to Force.com API Partner 13.0
  • Added SOSL Search functionality with search builder wizard
  • Added Smart Lookup for Insert, Update, and Upsert by foreign idLookup fields
  • Added caching describeSObjectResults and getUserInfoResults
  • Added Settings page and config.php for extensible, dual-level configuration of all aspects of the Workbench
  • Added support for Force.com API SOAP Headers:
  • Auto-Assignment Rules
  • Default Namespace
  • Client Id
  • Trigger Auto-Assignment, User, and/or Other Emails
  • Territory Delete Transfer User
  • Query Batch Size
  • Update Most Recently Used (MRU) items list on sidebar
  • Manual or automatic queryMore()
  • Exposed additional configuration for:
  • fieldsToNull (Insert Null Values)
  • File upload maximum size and row limits
  • Record batch sizes
  • Caching and compression
  • Proxy Settings
  • Alphabetizing of field names
  • Auto-jump for Query and Search results
  • Invalidate Salesforce session on logout
  • Expanded GZIP compression to include outbound compression with the option to disable completely
  • Added support for connection via proxy servers
  • Enhanced base client to support nested sObjects for Smart Lookup functionality and added fieldsToNull to sObject class definition with optional supporting logic
  • Added support for manual queryMore() retrieve when displaying query results in browser for increased performance and avoid browser timeouts for large queries
  • Corrected bugs inserting values with non-English latin characters
  • Added Requested Time performance clock to footer
  • Added support for field names to be alphabetized
  • Renamed Export to Query

1.3.12 2008/04/29

  • Corrected bug to allow for PHP Magic Quotes to be enabled and dynamically detected to strip slashes from queries

1.1.12 2008/04/19

  • Added auto-update reminder function if cURL is enabled
  • Corrected EMEA login URL bug
  • Corrected Export Query Builder bug that did not properly unquote null values
  • Started to move some constants to central shared.php for version control and auto-update reminders
  • Migrated SVN, downloads, and issue tracking to Google Code
  • Moved Help documentation to developer.force.com

1.0.12 2008/03/22

  • Updated documentation for general availability
  • First public release on Sourceforge

0.6.12 2008/03/18

  • Added an elapsed time clock to Query Results. Note, this is the time for the query() and queryMore() functions took to complete their requests with the Force.com API, not including the time it takes for PHP to process, transmit, and display the results to the end user.
  • Added line numbers to the Query Results to match the Excel row numbers.

0.5.12 2008/02/25

  • Upgraded WSDL to Force.com API Partner 12.0
  • Upgraded base client to PHP Toolkit 11.1
  • Added support for login with URL arguments for single sign on inside a Salesforce Web Tab. [Instructions]
  • Simplified standard and advanced logins at code level
  • Added support for endpoint changes when logging in with username and password under Advanced login option with auto-enabling fields
  • Improved user interface on Export with more accessible and intuitive layout, auto-enabling field choices, and an additional filter selection
  • Support for count() keyword in SOQL queries displaying results in browser
  • Query result anchor jumping so the user does not have to scroll after running a query
  • Enhanced Select page with auto-enabling field choices for more intuitive workflow
  • Collapsible tree view for Describe function
  • Increased maximum record size for Insert, Update, and Upsert to 2000 records, and Delete, Undelete, and Purge to 5000 records
  • Added tooltip hovers to menubar
  • Fixed minor bugs:
  • Corrected PHP warnings for non-existent foreach() variables before field selections are made
  • Corrected wording of Purge info and error messages
  • Allowed API calls that do not depend on an object secion to not require selection of an object

0.4.11 2007/11/18

  • Upgraded WSDL to Force.com API Partner 11.0
  • Added Purge functionality to remove items from the Recycle Bin by ID
  • Expanded deleteUndelete function to allow for any simple API call that takes only IDs
  • Updated Salesforce.com branding from Apex to Force.com

0.3.10 2007/09/12

  • Changed branding from Apex DataLoader.PHP to Workbench
  • Enhanced and streamlined the SOQL builder JavaScript function to automatically update the entire SOQL query when the user makes any changes to the criteria in the form. Also added onKeyUp event handling for realtime updating while the user types criteria in text fields.
  • Added ORDER BY sorting to SOQL builder
  • Added error handling if no object is selected when using SOQL builder
  • Streamlined login and action-picking process with Jump To menu on login screen to avoid extra step with Select page

0.2.10 2007/09/04

  • Partially abstracted PHP code and shared common functions for more efficient code re-use
  • Added support for Query All method to query recycled and archived records
  • Re-coded the Export functions to support queries of more than 2000 records by passing the Query Locater to a looping Query More calls to the Apex API
  • Re-coded all basic put functions to support more than 200 records by looping multiple calls to the Apex API
  • Added JavaScript functions for persistent login and SOQL builder
  • Upgraded WSDL to Apex API 10.0

0.1.9 2007/08/23

  • Completed development of all basic functions without JavaScript flourishes
  • Upgraded WSDL to Apex API 9.0

0.0.8 2007/08/05

  • Blank screen
  • Stripped down Apex API 8.0 Partner WSDL-based PHP Toolkit
Retrieved from "http://wiki.developerforce.com/index.php/Workbench"