Skip to content

Home

Jump to bottom
Nathan Totten edited this page Oct 26, 2020 · 13 revisions

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 allowlisting and blocklisting, 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.

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

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

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.

Download for Firefox

Download for Google Chrome

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 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 | | 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 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
sid User's authenticated Session Id
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 allowlist/blocklist feature admins can configure to do just this. In your config/overrides.php file, find the "ORG ID ALLOWLIST / BLOCKLIST" 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/forceworkbench/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.

  4. 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";

  5. 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

  6. 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/forceworkbench/forceworkbench.git

  2. Go into the directory: cd forceworkbench

  3. Create a new app on Heroku: heroku create --buildpack

  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.

Clone this wiki locally