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.
Try out Workbench at https://workbench.developerforce.com. Note, some of the limits and features are restricted for this demo for performance reasons.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 Google Chrome|
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:
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.
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:
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:
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:
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:
|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.
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:
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:
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:
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?
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.
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:
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.
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:
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.
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:
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:
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.
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.
|Ctrl+Alt+W||Add an additional filter row (i.e. WHERE clause) to Query or Search.|
Get the latest version of the Workbench from Google Code: https://github.com/ryanbrainard/forceworkbench/tags
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:
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.
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.
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.
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.
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.
4. Restart your app server.
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.
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
The instructions above work for most people, but in case you are having problems, here is a more verbose set of instructions and notes:
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.
So, the best option is to upgrade to Snow Leopard.
Note, PHP soapclient is pre-installed with MAMP (just drop Workbench and you are good to go):
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.
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
sudo apachectl restart
You should be good to go. Check with php -m | grep soap.
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:
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.
24.0.1 Beta 2012/04/29 - 2012/06/25