Workbench logo.png

Workbench is a powerful, web-based suite of tools designed for administrators and developers to interact with Salesforce.com organizations via the Force.com APIs. Workbench includes robust support for the Force.com Partner, Bulk, Rest, Streaming, 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.

Login to Workbench Now on Developerforce


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

Demo

Try out Workbench at https://workbench.developerforce.com. Note, some of the limits and features are restricted for this demo for performance reasons.

What's New in Workbench 25.0.1

Workbench 25.0.1 introduces background processing for long running operations, which allows queries and scripts to run their full length without page timeous. See Asynchronous Background Processing section below for details. Other enhancements include more secure sessions, Force.com Canvas signed request support, OAuth CSRF protection, and partial upgrade to Force.com API 26.0.

What's New in Workbench 22.0.1

Single Record Section
Single Record Insert Page
Record Detail Page
Id Actions Hover Menu
OAuth 2.0 Login without Need to Provide Credential to Workbench

Workbench 22.0.1 brings a large number of changes to both data management and security that will fundamentally change how you use Workbench to interact with your data.

Single Record Data Actions

All items on the Data menu (i.e. Insert, Update, Upsert, Delete, Undelete, and Purge) now support working with single records directly inside Workbench. When you use the new Single Record option, you are presented with a form containing all the available fields for the operation you are performing. Just fill it out and you're done. This means you no longer have to create a CSV just to insert or modify a single record. For bulk operations, CSV operations are still available throughout Workbench.

Record Detail Page & Id Action Hover Menu

Workbench also introduces a new detail page to see all the fields of any record. Just click on id of any record in Workbench and you are brought to the detail page where you can view all the data in that record, have options to jump to data actions for that record, or even jump to related records. Mouse over hover menus were also introduced to the id links to so you can jump directly to any action for that id, including viewing the record in Salesforce.

Security: OAuth Login, CSRF, Org Id Restrictions & More

On the security front, Workbench 22.0.1 is the most secure release ever. To start, Workbench now supports OAuth 2.0 login in addition to the existing Standard and Advanced login options. In addition, an option has been added that requires end-to-end SSL is being used from the end user to Workbench and from Workbench to Salesforce. On the backend, there is now CSFRF protection, enhanced XSS protection, and optional org id whitelisting and blacklisting, which is great for administrators who want to limit to which orgs user can login from their Workbench instance.

...and a lot more

This release also adds more minor features such as manual cache clearing, syslog logging, enhanced error handling, finer tuned enablement of certain features, updates to the the Streaming API client, and fixes a few advanced login issues.

What's New in Workbench 22.0.0

In addition to updates for Salesforce Summer '11 and API 22.0, the new Workbench 22.0.0 introduces several new enhancements and bug fixes, including an new interactive tool to discover the new Streaming API, easier access to user info, better pagination of query results, and proxy support for Bulk and REST API clients.

Streaming API Utility

NOTE: This article has been updated for the Winter '12 release (API version 23.0). The Streaming API documentation contains a code sample that can be configured to work with both API version 23.0 and the previous release, 22.0.

Streaming-client-torn.png
With this new utility, in one easy-to-use interface, you can:
  • Create and modify Push Topics (i.e. streamable SOQL queries) without disrupting streaming data
  • Manage multiple subscriptions
  • View subscribed data updates in pretty-printed raw JSON
  • Monitor long polling with adjustable levels
  • Listen to other meta channels
  • Automatically connect and disconnect on page load and unload

See a live demo of using Workbench for the Streaming API in the webinar.

To be compatible with JavaScript's same-domain policy, which is commonly a problem with browser-based CometD applications, Workbench manages a completely transparent reverse proxy without the need for any additional configuration. That is, all requests from the CometD client in your browser are first sent to Workbench, authenticated, and passed along to the Salesforce CometD endpoint. Streamed data is then pushed seemlessly to your browser when changes to data qualified by your Push Topics are detected by Salesforce.

To learn more about the Streaming API and about the developer preview, see the webinar. If your organization is not included in the developer preview, this feature will not be available in Workbench.

User Info Hover

Screenshot-secondary-user-info.png
This is a such simple feature that has already received plenty of praise during the beta for its helpfulness. Instead of having to go to the Session Info page to find additional information about your user, now you can just hover over the user info on the top-right of every page to see:
  • Username
  • Instance
  • Organization Id
  • User Id

This is very helpful for users who commonly log into multiple orgs or jump between different sandboxes. Want even more information? Just click to be brought to the complete Session Information page.

Enhanced Query Result Pagination

Incrementing query results.png
Another simple feature that goes a long way. Now, instead restarting on every page, the row numbers on SOQL query result continue from page to page.

Automatic Login with Workbench Tools Browser Extensions

After you have Workbench up and running, install Workbench Tools for Firefox or Workbench Tools for Google Chrome to get a new toolbar button in your browser to automatically log into Workbench from an active Salesforce.com session. [Google Chrome Install: 1) Download the .crx extension file. 2) Go to Settings > Extensions in Chrome. 3) Drag and drop the .crx file from your machine into the page.]

If you are logged into Salesforce, simply click the toolbar button and you will be automatically logged into Workbench. If you are not logged into Salesforce, the Firefox extension will simply direct you to the standard Workbench login screen. In Google Chrome, the extension will only be shown when logged into Salesforce.

The first time you use the extension, you will be prompted to provide your Workbench base URL. For example, if the login page for your Workbench instance is at http://localhost/workbench/login.php, just enter http://localhost/workbench. If you need to access the Options menu in the future, right-click on the toolbar button. Note, these browser extensions are not compatible with the public demo site at workbench.developerforce.com due to terms of service agreement and login CSRF requirements.

Firefox logo 64.png
Google chrome logo 64.png

Download for Firefox

Download for Google Chrome
WorkbenchToolsForFirefoxScreenshot.png
WorkbenchToolsForGoogleChromeScreenshot.png

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 is Workbench designed for? Just a like a real workbench, Workbench is designed to be an application administrators and developers can use to quickly view their organizations' data and metadata, test and troubleshoot their own applications, and be a one-stop shop for interacting with the various Force.com APIs.

It is also designed to provide just enough support to achieve these goals without getting in the way or trying to think too much for the user. This is important when using Workbench for testing and troubleshooting the APIs because Workbench will let you take control and perform operations that may otherwise not be possible through most API clients. As such, most errors messages from the APIs are returned to the user 'as is' and are not interpreted or manipulated by Workbench.


What is Workbench not designed for? Being web-based, Workbench is subject to browser and connection timeouts; however, these can be adjusted within PHP's settings, if you have access. As such, is it not recommended to use Workbench for large data loads or exports, scripting, or other performance intensive operations. It is much better suited for quick, on-the-fly interactions with the APIs.

Login

What login methods does Workbench support?

Workbench supports standard username/password login, login with a session id, and OAuth 2.0 remote access login. In addition, Workbench Tools for Firefox is a browser extension that transfers your session from the Salesforce user interface to Workbench with the click of a button. See below for details of these login methods.


What is does OAuth login and how is it configured?

OAuth allows users to log into Workbench and be authenticated directly by Salesforce without providing their username and password to Workbench. When users login with OAuth, they are redirected to Salesforce to provide their username and password, prompted to allow Workbench access their account, and then are returned to Workbench if they approve. If you have logged into a third-party application with Facebook or Linked In, it is a similar login flow, and gives users greater control of their login credentials.

To configure OAuth, an administrator needs to create a Remote Access application configuration in a Salesforce org. Note, this only needs to be done once per Workbench instance in a given environment (e.g. Production/Sandbox, Pre-Release, etc), not for every org that will log into that Workbench instance. To do this, in Salesforce, go to Setup | Develop | Remote Access and complete the form. The Callback URL should be the login URL of your Workbench instance, and is required to use HTTPS if it is not residing on localhost. Once the you save the form, a Consumer Key and Consumer Secret will be generated. Copy and paste these values into the appropriate fields in the 'oauthConfigs' section in the config/overrides.php file in Workbench. Be sure to uncomment the section by removing the leading double slashes and be sure to keep these value secret. Now, when you go to the Workbench login page, an OAuth login option should be shown.

If you want to restrict users to only be able to login with OAuth, add the following line to your config/overrides.php file in Workbench: $config["oauthRequired"]["default"] = true;


What does the error invalid_grant: ip restricted or invalid login hours mean and how do I avoid it?

This is an OAuth login error that users receive if they have Login IP Ranges configured on their profile, but the IP ranges do not include the Workbench instance. Even if the user's computer is within the allowed IP range and is successfully authenticated by Salesforce, Workbench will not be able to access the grant if it is being hosted outside the allowed IP range. This may be a common occurrence with the demo site at workbench.developerforce.com because it is hosted on a separate instance.

To resolve this issue, there are a few options below, ranging from most to least secure. Please consult with your IT and security organizations before making changes to your Login IP Ranges:

  • Host a Workbench instance inside your allowed IP range. See above for information on downloading and installing Workbench.
  • Add the IP address of the Workbench instance to your allowed IP range. The easiest way to find the IP address of Workbench requests to Salesforce is to look at your login history in Salesforce (Setup | Manage Users | Login History) and find the row with the failed login from Workbench, which should have a status of "Restricted IP." Copy the Source IP from that row and add it to your allowed range on your profile (Setup | Manage Users | Profiles | <your profile> | Login IP Ranges).
  • Remove all IP addresses from the Login IP Ranges to allow logins from any IP.


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. For example, to login to a sandbox organization, select 'Login: Sandbox (test)' and the API version you would like to use. Please be aware that using an old API version could cause unexpected behavior in Workbench as it is designed and tested for the latest API version, but offer this feature as a convenience.

To login to any instance with a session id (instead of username and password), paste in the session id into the marked field. Workbench will make a best guess for org's instance based on the pattern of the session id, but note that this will not work correctly for orgs that were previously migrated to other instances. This fuzzy lookup feature can be overridden or disabled under Settings

If you would like to do an advanced login programmatically, 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 Workbench in a Web Tab in Salesforce for single sign-on?

Authentication with this feature is not available if Login CSRF, terms agreement, or OAuth login are required. This includes the demo site at workbench.developerforce.com

Workbench has exposed an API to allow users to automatically log in to Workbench by providing their Server URL and Session Id in the URL arguments. This can be to integrate Workbench into a Web Tab directly in Salesforce for single sign-on into Workbench. To integrate 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 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, 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 syntax similar to the FAQs above:

Parameter Description Restrictions
un Username Must be used with pw and without sid
pw Password Must be used with un and without sid. 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.
sid 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 sid.
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 non-standard logins. Is there a way to set a default login type, API version, or instance

Yes, these are all configurable defaults on the Settings page.


When I provide a Session Id for login, 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 Workbench admin in the config.php file. See that file's header for details.

Data Management

Do I need to export a CSV just to edit one record?

Not any more. With Workbench 22.0.1, you can view and edit single records just by clicking on their id in query or search results. If you already know the id or it came from outside of Workbench, you can go directly to the operation you want to perform on the Data menu and paste in the id into the Single Record field.


Some data management operations also allow a ZIP file to be uploaded. What is that for and in which format should the ZIP file be? Workbench allows you upload a ZIP file for inserting, updating, upserting, or deleting binary files, such as Content, Documents, or Attachments. To use this feature, prepare a ZIP file containing the binary files and a CSV or XML-based manifest file called 'request.txt'. See the Salesforce.com Bulk API Guide for more information on creating the ZIP file. Note, you also use feature for ZIP files not containing binary files, but you will not be able to map the fields in Workbench, so make sure all field in the manifest match those in Salesforce.


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 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 (i.e. foreign alternate keys) to automatically find their respective Salesforce ids though related objects. It is available for both Single Record and CSV-based operations. Check out this video posted on the Database.com Blog that shows an example of using Smart Lookup.

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. Instead, you can insert the Contact records directly and have 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 Settings, 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 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 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, 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 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 can I know when query results have changed? Can they be streamed to me?

This is a job for the Streaming API and it is integrated right into Workbench starting with version 22.0.0. To get started, first you'll need to have the Streaming API enabled for your organization, as it is currently only available in developer preview. For more information on that, register for the Streaming API Webinar.

Once you have the Streaming API enabled, login to Workbench and go to Queries | Streaming Push Topics. First, you'll need to create a Push Topic, which is the definition of the query you want to stream. To do this, choose "Create New" from the menu, give it a name, API version, and the SOQL query and save it. Once you save your new Push Topic, click "Subscribe" to monitor any future changes to the query results. Leave the page open, and go change a record in another browser so that it now qualifies for the Push Topic and the record should be pushed to the page within a few seconds. For example, if your push topic defines a query such as SELECT Id, Name, Amount FROM Opportunity WHERE Amount > 1000, records that were less than 1000 but are now more than 1000 will be streamed to your browser.


What is SOQL Matrix view and how do I use it?

MatrixSoql.png
SOQL Matrix view is a powerful way to group query results into rows and columns, similar to a matrix report in Salesforce, but with the power of SOQL.

For example, if you are running a query on Opportunities, you can could choose to group the records by ForecastCategory and StageName. This way all the records in the same ForecastCategory are shown in the same row and all the records in the same StageName are in the same column.

Of course, you can choose other fields to display along with each record, however, this is not required. If no other fields are chosen, the results will simply be display in the cells as dots to visualize the distribution of your data in the matrix.


How do I query records from a related parent object?

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 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 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 is the REST Explorer? The REST Explorer is a utility that gives access to the Force.com REST API to perform all the supported RESTful actions (GET, POST, PATCH, etc.) on any REST Service URL and present the JSON responses in an expandable tree complete with links to navigate to other REST Service URLs as well as optionally displaying the raw JSON responses. REST Explorer also supports custom request headers and automatically displays the raw response.


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 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 Workbench and provide SOAP Headers to the Force.com API?

The Settings menu allows you to granularly control 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.


Security

What is CSRF and how should I configure CSRF protection in Workbench?

CSRF stands for Cross-Site Request Forgery, which is an attack where hackers trick users into inserting or manipulating data on their behalf through a web site the user trusts. To protect Workbench and your data against these types of attacks, CSRF protection is integrated into Workbench and relies on a "secret" stored on your Workbench instance. It is highly recommended that you change the default secret to something that only you have access to. You can do this by going to your config/overrides.php file, finding the "CSRF SECURITY SETTINGS" section, changing the default "CHANGE ME", and uncommenting the line by removing the leading double backslashes.

In addition to the standard CSRF protection in Workbench, you can also enable Login CSRF Protection to block programmatic logins to Workbench, which could be used as an attack. Note, if Login CSRF Protection is enabled, benign programmatic logins such as those from Workbench Tools for Firefox will also be blocked. To enable Login CSRF Protection, add the following line to your config/overrides.php file:

$config["loginCsrfEnabled"]["default"]=true;


How do I require end-to-end SSL? By default, Workbench uses HTTPS (SSL) to connect to Salesforce, but the connection from your computer to Workbench is determined by your server configurations. To require Workbench to enforce end-to-end SSL, add the following line to your config/overrides.php file:

$config["requireSSL"]["default"]=true;


How do I block or only allow certain orgs to use my Workbench instance?

Workbench 22.0.1 introduced a blacklist/whitelist feature admins can configure to do just this. In your config/overrides.php file, find the "ORG ID WHITELIST / BLACKLIST" section and follow the instructions to add or remove organizations.

Keyboard Shortcuts

Currently, Workbench only has one lonely keyboard shortcut, as a sort of experiment in version 20.0.0. There are plans to add more going forward.

Shortcut Description
Ctrl+Alt+W Add an additional filter row (i.e. WHERE clause) to Query or Search.

Installation

Download

Get the latest version of the Workbench from Google Code: https://github.com/ryanbrainard/forceworkbench/tags

Installation Instructions

Workbench is built on PHP and is designed to be installed once on a central web server and shared by the users on your network; however, if you are the only user or just want to try it out, you can also just install a web server on your local computer (it's really not as scary as it sounds). 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. Alternatively, you can deploy Workbench to Heroku to create a publicly accessible instance of Workbench; see the section titled "Deploying Workbench to Heroku" below for details. For local installation, follow these instructions to install Apache HTTP Server, PHP, and Workbench:

  1. Install an xAMP (LAMP/WAMP/MAMP) package. An xAMP package is a pre-configured bundle of a Apache HTTP Server, MySQL, and PHP to make installation simple. To find an xAMP package, Windows users can see the Comparison of WAMPs and Mac users can use MAMP. Note, MySQL is not used by Workbench, so you can exclude installation of MySQL if the bundle you are installing allows it. Alternatively, you can also just install Apache and PHP separately instead of using a pre-configured xAMP package.
  2. Download, unzip, drop the unzipped "workbench" folder into your server's web document root.
  3. Try going to http://localhost/workbench (adjust for different base URLs and/or port numbers). 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. Also, be sure to look at the Security FAQs for information on securing your instance.

Once you get Workbench all setup, make sure you install one of the Workbench Tools browser extensions to get one-click login from Salesforce to Workbench, and join the Workbench Google Group for updates and discussion.

Advanced Installation Instructions

Distributed Session Support

By default PHP stores sessions on the local disk of the app server. This works fine when you only have one app server, but if you have a large instance that requires multiple app servers, the sessions on the app servers will get out of sync as requests are load balanced between the servers. To solve this problem, Workbench supports distributed sessions with Redis. With this setup, instead of storing sessions locally, all the app servers remain stateless and read and write session data to a common Redis cluster. This allows for simple (non-sticky) load balancing to any app server and scaling the pool size up or down without any loss of session data. To enable this setup on your own instance, follow the instructions below. For doing the same on Heroku (hint, it's easier), see the section titled Deploying Workbench to Heroku.

1. Setup a Redis instance. This can either be done yourself or as a service. This may or may not be the same Redis instance used for other operations in Workbench.

2. Install the PhpRedis extension in PHP.

3. Configure Workbench to use Redis as a session store. Add this line to your config/overrides.php file and change the Redis URL as needed:

$config["sessionStore"]["default"] = "redis://localhost:6379";

4. Restart your app server.

Asynchronous Background Processing

Certain operations in Workbench can take a long time to complete because of long-running requests to the Salesforce APIs. For example, SOQL queries against very large data sets can take upwards of 30 minutes to complete. Because browsers, load balancers, PHP, and app servers generally have much shorter timeouts, pages in Workbench can timeout waiting for such operations to complete. To solve this problem, Workbench has an asynchronous background processing framework that allows long-running operations to be run in the background while the user sees a "Loading..." indicator and then the results returned to the user when completed. This setup requires one or more background workers to be running in addition to the app server(s). The queuing and communication between the app server(s) and the background worker(s) requires Redis. The app server(s), background worker(s), and Redis can be on the same physical hardware or distributed across multiple machines -- the only requirement is that both the app server(s) and background worker(s) have network access to Redis, but not necessarily to each other. Async background processing is currently used for SOQL Queries, Apex Execute, and REST Explorer queries. To enable this setup on your own instance, follow the instructions below. For doing the same on Heroku (hint, it's easier), see the section titled Deploying Workbench to Heroku.

1. Setup a Redis instance. This can either be done yourself or as a service. This may or may not be the same Redis instance used for session management in Workbench.

2. Install the PhpRedis extension in PHP.

3. Enable command line usage in PHP.

3. Configure Workbench to use Redis. Add this line to your config/overrides.php file and change the Redis URL as needed:

$config["redisUrl"]["default"] = "redis://localhost:6379";

4. Start the background workers by running this script (only been tested on Ubuntu Linux). Note, the max number of workers can be set with the MAX_WORKERS environment variable.

async_workers.sh

4. Restart your app server.

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. If you made changes to the config/overrides.php file (or legacy configOverrides.php), be sure to backup this file from the old version and replace it in the new version. If you still have a configOverrides.php, migrate the contents of this file to config/overrides.php.

Deploying Workbench to Heroku

Another option for running Workbench is to deploy to the Heroku cloud application platform, which can be great way to get a public instance up and running quickly. This will automatically download and install Apache, PHP, and Phing on Heroku and publish your instance of Workbench to the world. By adding a Redis add-on, multiple dynos are supported with distributed session management and async background processing.

To get started, first follow the Heroku Quickstart. For "Step 4: Deploy An Application," follow these steps:

1. Clone the Workbench repo: git clone https://github.com/ryanbrainard/forceworkbench.git

2. Go into the directory: cd forceworkbench

3. Create a new app on Heroku with the Phing buildpack: heroku create --buildpack https://github.com/ryanbrainard/heroku-buildpack-phing.git

4. Push to Heroku: git push heroku master

5. View in your browser: heroku open

6 [Optional]. To configure Workbench, instead of using the config/overrides.php file to override settings, which would require a source code commit and push to Heroku, it is recommended to use environment variables. Workbench 24.0.0 supports environment variable based configuration in a flattened version of the config/overrides.php format. For example:

$config['configKey]['default'] = 'configValue'

would be set on Heroku with:

heroku config:add "forceworkbench__configKey__default=configValue"

Workbench includes a script that can be used to convert an existing config/overrides.php format into local export or heroku config:add commands. The script is located at build/ConvertConfigFileToEnvVars.php when you clone the repo.

7 [Optional]. If you plan to enable scale Workbench to more than one web dyno, a distributed session store must be used so that the app servers remain stateless and can balance requests. Currently, the only distributed session store is Redis, which can be easily added as an add-on to Heroku, like this:

heroku addons:add redistogo

This will inject a REDISTOGO_URL config var in your app. Workbench does not read this configuration directly, so needs to be copied over to Workbench configuration to enable Redis as the session store:

heroku config:add "forceworkbench__sessionStore__default=$(heroku config:get REDISTOGO_URL)"

Now the web dynos can be safely scaled out:

heroku scale web=2

8 [Optional]. Similarly, if you plan to use the async background processing feature in Workbench, a Redis instance must be available for queuing and message passing between web and worker dynos. This can be the same Redis instance as the one used for session management, but does not need to be. As such, a second Workbench configuration must be set. Assuming you already added the Redis add-on as shown above, copy the configuration for async processing like this:

heroku config:add "forceworkbench__redisUrl__default=$(heroku config:get REDISTOGO_URL)"

Now a worker dyno can be started:

heroku scale worker=1

By default, only one worker process is run per worker dyno, but Workbench supports scaling more to than one worker process per dyno with the MAX_WORKERS config var. To more efficiently use resources, It is recommended to set this to as high as 4 before scaling to more worker dynos:

heroku config:add MAX_WORKERS=4

Installation Help

The instructions above work for most people, but in case you are having problems, here is a more verbose set of instructions and notes:

  • 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.
  • Workbench includes .htaccess files to properly control the caching of static files that do not need to be downloaded on every page load and compress the text-based files for transport. If you install Workbench on an Apache Web Server, these should work as-is as long as your Apache configuration will allow htaccess overrides like this. Some hosted providers will not allow this, so in that case, it is will not harm anything to just delete them (you just won't have the performance improvements). If you are installing Workbench on a non-Apache server (e.g. Microsoft IIS), the .htaccess file will not work. Instead, you can manually enable GZIP or Deflate compression and set the cache expiration sometime long in the future for the 'static' folder in Workbench.

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 supported 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

26.0.0 2013/01/12

  • Upgraded Partner, Metadata, Apex, and Streaming clients to Force.com API 26.0
  • Bug Fix: Eliminated double escaping of HTML entities for Bulk API DML operations
  • Bug Fix: Corrected handling of cookie Path component in CometD reverse proxy
  • Bug Fix: Require REST Explorer resource paths to begin with a slash
  • Bug Fix: Temporarily block DML operations on objects with more than 10000 chars

25.0.2~4 2012/09/16

  • Enable async processing for all REST Explorer operations
  • Remove full WorkbenchContext from RestExplorerController to optimize serialization used for async processing
  • Fix error handling for REST Explorer async operations

25.0.1 2012/09/09

  • Redis-based queueing and async processing framework
  • Async processing for SOQL Query, Apex Execute, and REST Explorer pages
  • Added support for signed request-based logins with the pilot Canvas Framework in Winter '13
  • Encryption of Salesforce session id in the PHP session
  • Set default timezone to UTF if not already set in php.ini.
  • Partial upgrade of Partner, Metadata, and Apex clients to Force.com API 26.0
  • Added favicon.ico in web root
  • OAuth login uses state parameter instead of PHP session with added CSRF protection
  • Reenabled logging of unknown exceptions with greater number of known exceptions
  • Check user agreed to terms of service on every request
  • Bug Fix: Block DML requests with different number of rows per column
  • Bug Fix: Corrected HTML escaping in debug mode
  • Bug Fix: DML results with batch size + 1 rows display correctly
  • Bug Fix: Handle objects with only one field

25.0.0 2012/08/10

  • Upgraded Partner, Metadata, Apex, Bulk, REST, and Streaming clients to Force.com API 25.0
  • Added new Salesforce instances to instance picklist
  • Bug Fix: Allow more than one error per row to displayed on DML operation failures (e.g two triggered validation rules)
  • Bug Fix: Scrub additional headers of REST Explorer to be compatible with CURL versions that do not already do this
  • Bug Fix: Block invalid CSV files if all rows do not have same number of columns
  • Bug Fix: Handle DML operations for sobjects with unknown key prefixes

24.0.1 Beta 2012/04/29 - 2012/06/25

  • Support for saving session data to Redis to allow for multiple, horizontally scalable, stateless app servers
  • Encapulation of configuration into a single point of access
  • Removal of Workbench configuration from PHP session
  • Option to auto-forward unsecure requests to HTTPS endpoint
  • Support for remote term files
  • Changed static resource versioning to query parameters instead of file paths to simplify build process
  • Changed logging to JSON format for machine readability
  • Support for multiple log handlers with syslog and file-based handlers
  • Complete support for HTTP_X_FORWARD_* headers
  • Add BAYEUX_BROWSER cookie support to Streaming API client

24.0.0 2012/02/27

  • Upgraded Partner, Metadata, Apex, Bulk, REST, and Streaming clients to Force.com API 24.0
  • Added partial support for Phing-based builds
  • Added support for environment variable based configuration
  • Added script for converting file-based configuration to environment variable-based configuration
  • Removed hand cursor from async result processing times pseudo link
  • Disabled parent relationship queries by default with user option to enable
  • Show warning pop-up when clearing saved queries
  • Added support for SSL detection with HTTP_X_FORWARDED_PROTO
  • Bug Fix: Special case for EmailTemplate metadata component listing
  • Bug Fix: Improve query table copy and pasting

23.0.0 2011/10/26

  • Upgraded Partner, Metadata, Apex, Bulk, REST, and Streaming clients to Force.com API 23.0
  • Removed streaming 22.0/23.0 stagger support for Streaming API GA in API 23.0
  • Bug Fix: Treat various expected API errors as WorkbenchHandledExceptions
  • Bug Fix: Logout OAuth users without API access

22.0.1 2011/08/29

  • Single record detail pages with id link integration
  • Single record DML actions with detail page and id link integration
  • OAuth 2.0 login support
  • Optional Login CSRF protection
  • CSRF protection for all writable POSTs
  • Organization id blacklist/whitelist
  • Clear cache after a metadata deployment
  • Add buttons to explictly clear Workbench cache
  • Change PHPSESSION to be HTTPOnly
  • Add top-level PHP error handler
  • Request and top-level error/exception logging to syslog
  • Better protection for non-overrideable settings
  • Support parsing of Enterprie API server URLs on login
  • Show login errors on login page with non-secret fields pre-populated
  • Send user to logout page on authentication errors
  • Allow latest version checks to be disabled
  • Added ability to configure terms of service to which users must agree to login
  • Replace expected Exceptions with HandledExceptions
  • Support /id URLs in REST Explorer
  • Add configuration to disable parent relationship queries
  • Add configuration to disable CSV export
  • Add configuration for end-to-end SSL requiredness
  • Disable pilot Streaming API client when connected to Winter '12 instance
  • Clear cache when using 70% of memory
  • Add licensing and copyright details
  • Deny access to config files via .htaccess
  • Bug Fix: Field alphabetizing fails if no fields exist for an object
  • Bug Fix: Stop describing objects DML actions that do not require objects
  • Bug Fix: Re-allow logins to instances with port numbers
  • Bug Fix: Allow programmic portal id login to work
  • Bug Fix: Reviewed and added XSS protection to various areas of the app
  • Bug Fix: XSS protection for PHP_SELF and disallow URIs with PATH_INFO
  • Bug Fix: Allow Streaming API client to work with proxies that add additional headers
  • Bug Fix: Trim cookies in streaming client
  • Bug Fix: Use SSL on non-IIS servers in streaming client
  • Bug Fix: Content-Type Header Not Being Set in PhpReverseProxy if !function_exists('getallheaders')

22.0.0 2011/06/26

  • Upgraded Partner, Metadata, Apex, Bulk, REST, and Streaming clients to Force.com API 22.0
  • Added Streaming API (pilot) support. Manage Push Topics, subscriptions, and monitor meta channels. Includes reverse proxy to handle cross-domain traffic
  • Revamped API connection and cache management with new Workbench Context. Additional items will be folded into this in the coming releases to allow for a common way for accessing connections, caching values, and other application-wide coordination.
  • Added proxy support for Bulk and REST API clients and tools
  • Continue incrementing query results rows for paginated results
  • Added support for login startUrl parameters with additional query parameters
  • Show waiting indicator for REST Explorer
  • Added a tool tip with secondary user info
  • Show number of sub-items in more folder trees
  • Warn when memory usage is too high on querying to CSV
  • Bug Fix: Allow deletes, undeletes, and purges to read CSVs with Id column in non-first column
  • Bug Fix: Make best attempt to find older WSDL for Metadata and Apex
  • Bug Fix: Warn when memory usage is too high on querying to CSV
  • Bug Fix: Single-quoted data in SOQL filters not appearing on page reload

21.0.1 2011/03/15

  • Stream Bulk API results and REST Explorer binary downloads directly to end user without loading into Workbench memory.
  • Allow Bulk API Client to take any Salesforce SOAP API endpoint, instead of just Partner API. Pre-constructed Bulk API are also allowed now.
  • Allow Bulk API Client to export results to local files.
  • Check memory usage on CSV uploads and recommend using Bulk API if memory is almost exhausted.
  • Only recommend Bulk API for DML is cURL extension is installed.
  • Remove dependency on PECL library for hashing footer scripts.
  • Ping Salesforce on page loads after five minutes of inactivity to check if session is still alive.
  • Bug Fix: Use object in FROM clause for Bulk Queries instead of object specified in query form.
  • Bug Fix: Download ZIP-based Bulk API requests as ZIP files.
  • Bug Fix: Allow REST Explorer to download binaries from Chatter feeds.
  • Bug Fix: Auto-execute REST-based queryMore requests in REST Explorer.

21.0.0 2011/02/23

  • Upgraded Partner, Metadata, Apex, Bulk, and Rest clients to Force.com API 21.0
  • Added Rest API discovery with REST Explorer integrated into Workbench and added support for custom request headers, support for PUT verb, and automatic display of raw non-JSON responses (JSON responses are shown in expandable tree).
  • Added Bulk API Query support for running SOQL queries asynchronously and returning results in either CSV or XML format.
  • Enhanced links from Workbench to Salesforce to only pass sessions where needed.
  • Default to using Bulk API for large data loads with customizable threshold.
  • Bug Fix: CSV file formats supported in all browsers.
  • Bug Fix: Localization of dates works correctly even if timezone is unset
  • Bug Fix: Metadata Deploy with Perform Retrieve option allows ZIP to be downloaded


20.0.0 2010/10/10

  • Upgraded Partner, Metadata, Apex, and Bulk clients to Force.com API 20.0
  • SOQL Matrix View to view SOQL query results on a matrix grid with arbitrary columns and rows
  • Support for binary file DML operations with new Bulk API ZIP_CSV and ZIP_XML content types
  • Timezone conversion for date times
  • Localization formatting for date times
  • All-Or-None transactional DML processing
  • Auto-refresh on async status pages
  • Display object and fields labels in any language
  • Support for AllOrNoneHeader, DisableFeedTrackingHeader, LocaleOptions, PackageVersionHeader SOAP headers
  • Keyboard shortcut (Crtl+Alt+W) for adding filter/object rows in SOQL/SOSL builders
  • Show warning for unsupported settings for current API version or Bulk API operation
  • Removed Jump To menu by default. Can be re-added with new setting.
  • Added escaping for package names in Metadata Retrieve
  • Allow Bulk API to be used down to API 16.0
  • Read-only Mode for kiosk support
  • Performance: New .htaccess files for enabling caching of static content and GZIP compression if Workbench is installed on a Apache Web Server
  • Performance: Delayed loading of some UI elements during download and rendering
  • Performance: Limited cookie traffic to only overridden configs
  • Performance: Moved all external JavaScript to footer
  • Performance: Achieved YSlow A rating
  • Bug Fix: string-based configs not clearing to defaults
  • Bug Fix: invalid Async Ids in Metadata API operations
  • Bug Fix: Bulk API operations with polymorphic foreign key lookups
  • Bug Fix: Session Info not displaying for users without Metadata API access
  • Changed version numbering scheme to align with Salesforce.com API versions and clients


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 unhanded 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 preferred 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