Workbench
 |
The Workbench is a community-contributed, web-based application that gives administrators on-demand access to useful tools to manage salesforce.com organizations. Combining the power of both the Apex Data Loader and the Force.com Explorer, the Workbench can insert, upsert, update, query, search, delete, undelete, and purge data as well as describe any object directly in your web browser. These functions build on the strengths of both the existing products to create an even more powerful and easier-to-use on-demand application. Not only can the Workbench be used as a standalone application in your browser, but it can also be integrated within Salesforce as a single-sign-on web tab for more convenient access. Now with Version 2.0, the Workbench brings news features like SOSL Search and Smart Lookup as well as customization and performance enhancements.
Contents |
Screenshots
FAQ
General
What are the advantages of the Workbench compared to the Data Loader?
- An on-demand, web-based interface to your organization's data that combines the functions of the Data Loader and the Force.com Explorer.
- Clean, easy-to-use, user-centered interface that remembers your settings throughout your session.
- Describe function to access your organization's metadata.
- Simplified results on one easy-to-read table displayed right in your browser.
- Easier and faster SOQL query builder that dynamically updates itself.
- SOSL search function to easily build and test search strings
- The choice to view queries right in your browser or download them as a CSV file.
- Query All function to query archived items as well as items that in your Recycle Bin.
- Undelete function to restore items from your Recycle Bin by Id.
- Purge function to permanently delete items from your Recycle Bin by Id.
- Single sign on integration with the Salesforce user interface for easy access from a custom web tab.
- Smart Lookup to automatically find referenced object ids through foreign external ids, including polymorphic relationships.
- Advanced Settings that give granular-level control of configuration of the Workbench and interactions with the Force.com API
What is the Workbench not designed for?
- Being web-based, the Workbench is subject to browser and connection timeouts. As such, is it not recommended to use the Workbench for large data loads or exports. It is much better suited for quick, on-the-fly data management, which is something other API integration tools lack.
- The Workbench cannot be run from the command line, used for automated processes, or support mapping files
Is the Workbench just an extension of the Data Loader?
No, the Workbench was built completely from the ground-up using PHP and JavaScript, and binds to the Force.com Web Services API via the PHP Toolkit. It does not reference or build upon any of the Java code in the DataLoader, but was modeled after its concept.
How are the version numbers formatted?
Because the version number is appended by the version number of the Force.com API WSDL file being used, the the version numbers tend to get rather long. The version numbers follow the format below:
Major.Minor.API
If this software is Open Source, where can I get the source code?
The source code is available at the Google Code project site for download and SVN checkout and distribution under the Open Source BSD License. Please see the About page for details.
Is the Workbench created by Salesforce?
No, the Workbench is not a product of nor supported by salesforce.com, inc. However, there is great community support on the Workbench discussion board.
Features & Functions
How do I login to a non-production instance (i.e. Sandbox, Pre-Release, etc.), with a session id, or other API versions? On the Login page, click the 'Advanced' radio button for options to login to different API endpoints by using the QuickSelect menu to choose your instance and API version. To login to Sandbox with a username and password, select 'test'. To login to any instance with a session id (instead of username and password), paste in the session id and then select the specific instance that org is located. If you would like to test functionality on a previous API version, this can also be set on the QuickSelect menu, but please be aware that this setting could cause unexpected behavior in the Workbench as it is designed and tested for the latest API version.
How do I use the Workbench in a Web Tab or S-control in Salesforce for single sign on?
Introduced in v.0.5.12, the Workbench has an exposed API to allow users to be automatically logged in by providing their Server URL and Session Id in the URL arguments. This can be to integrate the Workbench into a Web Tab or S-control directly in Salesforce for single sign on into the Workbench. To integrate the Workbench into your org, follow the instructions below:
- Login to Salesforce
- Setup | Create | Tabs | Web Tabs | New
- Choose Tab Layout
- Full page width is recommended
- 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)
- Button or Link URL
- Button or Link URL (replace "<your_server>" with the web server the Workbench in installed): https://<your_server>/workbench/login.php?serverUrl={!API_Partner_Server_URL_130}&sid={!API_Session_ID}
- Encoding: Unicode UTF-8
- Save
What is Smart Lookup and how does it help me?
Smart Lookup is an optional function when using Insert, Update, or Upsert to allow you to provide foreign external ids or standard id lookup field values to automatically find their respective Salesforce ids though related objects.
For example, if you have CSV file of Contact records to insert and associate with different record types, normally you would need to first query for and replace all the plain text record types with the RecordTypeIds using a VLOOKUP function. Now, with Workbench 2.0, you can insert the Contact records directly and have the Workbench and the API do the work of looking up the RecordTypeIds by using the Smart Lookup function. To use Smart Lookup, first make sure it is enabled in Setting, upload your file using Insert, Update, or Upsert, and you will be presented with an additional Smart Lookup column on the right. There will be a dropdown selection box for each field that references another object with a relationship. For the Record Type example, simply select RecordType.Name in the Smart Lookup column on the RecordTypeId row and the column that the record type name is in your CSV file, and the Workbench will automatically associate your Contacts with the correct record type based on just their names.
The same thing can be done for any external id fields on related objects. For example, if your Contacts needed to be related to the proper Accounts, but you only knew the Accounts' external ids, Smart Lookup can automatically find the Accounts' primary Salesforce ids.
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 customize the Workbench and provide SOAP Headers to the Force.com API?
The Settings menu allows you to granularly control the Workbench right inside your web browser to configure everything from alphabetizing fields to how many records are included in batched together in API calls to whether assignment rules are fired when you insert Leads and Cases. These settings are stored in your browser's cookies folder and will remain in effect across logins to multiple orgs.
To globally change the default values on the Settings menu and toggle which ones can be overridden by end users, Workbench administrators can access the config.php file on directly from the web server (not the browser) to make these adjustments. Please see the header in the config.php file for details.
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 permentantly deletes items that are already in our organization's recycle bin. Note, some types of objects are immediately deleted from your organization when they are deleted. Be sure to check the if the record has the the Undeletable attribute before deleting records. This can be done using the Describe function and opening the Attributes folder.
Does the Workbench support queryAll()?
Yes. By default, the Query function uses the standard query() API call, which excludes archived and deleted records from your organization. To access deleted and archived records with the queryAll() API call, go to Query and choose "Include" for the "Deleted and archived records" option.
How do I call queryMore()?
The Query function does this automatically for you if the "Automatically Retrieve More Query Results" option is enabled in Setting or when exporting to a CSV file. However, if you choose to leave this setting disabled, a "More..." button will appear at the top and bottom of your query results when the more record than your default batch size is returned. Simply click one of these buttons to retrieve more results. The query batch size can be changed with the "Preferred Query Batch Size" setting on the Settings menu. Please note that large batch sizes or automatically retrieving large sets of data can cause browser timeouts and can make the Workbench hang. If this is the case, restart your browser and try again with a smaller batch size.
Why do I get the error similar to 11/9/2005 is not a valid value for the type xsd:date when trying to create, update, or upsert records?
This error is caused by the way Excel saves dates in the local format when creating CSV files. The API only accepts dates and dateTimes in the following formats:
- Date only
- YYYY-MM-DD
- Date, time, and time zone offset
- YYYY-MM-DDThh:mm:ss+hh:mm
- YYYY-MM-DDThh:mm:ss-hh:mm
- YYYY-MM-DDThh:mm:ssZ
Note, the Data Loader automatically converts the dates from your locale to the formats above, but the Workbench does not perform any manipulation to your data. To format the date properly in Excel, highlight the cells, Format | Cells | Date | Locale: ISO (International). For the dateTime values, a custom format must be created and used. The zone offset is always from UTC. For more information about these date and time formats, please see the following guides:
Installation
Download
Get the latest version of the Workbench from Google Code: http://code.google.com/p/forceworkbench/downloads/list
Instructions
The Workbench is built on PHP and connects to the Force.com API using SOAP-based web services and is designed to be installed once on a central web server and shared by the users on your network. To install and run the Workbench, you must have a working web server, such as an Apache HTTP Server, with support for PHP and optionally HTTPS. Once it is installed on your web server, any of the users on your network will have on-demand access to the Workbench via their web browser, assuming they have valid login credentials for Salesforce. Follow the instructions below to install Apache HTTP Server, PHP, and the Workbench:
- Installing LAMP/WAMP
- Easier
- Install a LAMP/WAMP bundled installation of Apache HTTP Server, MySQL, and PHP. For a list of WAMPs, please see the Comparison of WAMPs. The Workbench has been known to work with Web Developer Server Suite on Windows and MAMP on a Mac.
- Manual
- 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:
- Easier
- # 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.
Support
Please note that the Workbench is NOT a product of or supported by salesforce.com, inc. For support from the Open Source community, please visit this project's pages below:
Feedback
Have something you want to discuss about the Workbench? Have a great idea for a new feature? Looking for support from the community? Want to find out the latest news about the Workbench? Visit the Feedback & Discussion page today.
Version History
0.0.8 2007/08/05
- Blank screen
- Stripped down Apex API 8.0 Partner WSDL-based PHP Toolkit
0.1.9 2007/08/23
- Completed development of all basic functions without JavaScript flourishes
- Upgraded WSDL to Apex API 9.0
0.2.10 2007/09/04
- Partially abstracted PHP code and shared common functions for more efficient code re-use
- Added support for Query All method to query recycled and archived records
- Re-coded the Export functions to support queries of more than 2000 records by passing the Query Locater to a looping Query More calls to the Apex API
- Re-coded all basic put functions to support more than 200 records by looping multiple calls to the Apex API
- Added JavaScript functions for persistent login and SOQL builder
- Upgraded WSDL to Apex API 10.0
0.3.10 2007/09/12
- Changed branding from Apex DataLoader.PHP to Workbench
- Enhanced and streamlined the SOQL builder JavaScript function to automatically update the entire SOQL query when the user makes any changes to the criteria in the form. Also added onKeyUp event handling for realtime updating while the user types criteria in text fields.
- Added ORDER BY sorting to SOQL builder
- Added error handling if no object is selected when using SOQL builder
- Streamlined login and action-picking process with Jump To menu on login screen to avoid extra step with Select page
0.4.11 2007/11/18
- Upgraded WSDL to Force.com API Partner 11.0
- Added Purge functionality to remove items from the Recycle Bin by ID
- Expanded deleteUndelete function to allow for any simple API call that takes only IDs
- Updated Salesforce.com branding from Apex to Force.com
0.5.12 2008/02/25
- Upgraded WSDL to Force.com API Partner 12.0
- Upgraded base client to PHP Toolkit 11.1
- Added support for login with URL arguments for single sign on inside a Salesforce Web Tab. [Instructions]
- Simplified standard and advanced logins at code level
- Added support for endpoint changes when logging in with username and password under Advanced login option with auto-enabling fields
- Improved user interface on Export with more accessible and intuitive layout, auto-enabling field choices, and an additional filter selection
- Support for count() keyword in SOQL queries displaying results in browser
- Query result anchor jumping so the user does not have to scroll after running a query
- Enhanced Select page with auto-enabling field choices for more intuitive workflow
- Collapsible tree view for Describe function
- Increased maximum record size for Insert, Update, and Upsert to 2000 records, and Delete, Undelete, and Purge to 5000 records
- Added tooltip hovers to menubar
- Fixed minor bugs:
- Corrected PHP warnings for non-existent foreach() variables before field selections are made
- Corrected wording of Purge info and error messages
- Allowed API calls that do not depend on an object secion to not require selection of an object
0.6.12 2008/03/18
- Added an elapsed time clock to Query Results. Note, this is the time for the query() and queryMore() functions took to complete their requests with the Force.com API, not including the time it takes for PHP to process, transmit, and display the results to the end user.
- Added line numbers to the Query Results to match the Excel row numbers.
1.0.12 2008/03/22
- Updated documentation for general availability
- First public release on Sourceforge
1.1.12 2008/04/19
- Added auto-update reminder function if cURL is enabled
- Corrected EMEA login URL bug
- Corrected Export Query Builder bug that did not properly unquote null values
- Started to move some constants to central shared.php for version control and auto-update reminders
- Migrated SVN, downloads, and issue tracking to Google Code
- Moved Help documentation to developer.force.com
1.3.12 2008/04/29
- Corrected bug to allow for PHP Magic Quotes to be enabled and dynamically detected to strip slashes from queries
2.0.13 2008/06/16
- Upgraded WSDL to Force.com API Partner 13.0
- Added SOSL Search functionality with search builder wizard
- Added Smart Lookup for Insert, Update, and Upsert by foreign idLookup fields
- Added caching describeSObjectResults and getUserInfoResults
- Added Settings page and config.php for extensible, dual-level configuration of all aspects of the Workbench
- Added support for Force.com API SOAP Headers:
- Auto-Assignment Rules
- Default Namespace
- Client Id
- Trigger Auto-Assignment, User, and/or Other Emails
- Territory Delete Transfer User
- Query Batch Size
- Update Most Recently Used (MRU) items list on sidebar
- Manual or automatic queryMore()
- Exposed additional configuration for:
- fieldsToNull (Insert Null Values)
- File upload maximum size and row limits
- Record batch sizes
- Caching and compression
- Proxy Settings
- Alphabetizing of field names
- Auto-jump for Query and Search results
- Invalidate Salesforce session on logout
- Expanded GZIP compression to include outbound compression with the option to disable completely
- Added support for connection via proxy servers
- Enhanced base client to support nested sObjects for Smart Lookup functionality and added fieldsToNull to sObject class definition with optional supporting logic
- Added support for manual queryMore() retrieve when displaying query results in browser for increased performance and avoid browser timeouts for large queries
- Corrected bugs inserting values with non-English latin characters
- Added Requested Time performance clock to footer
- Added support for field names to be alphabetized
- Renamed Export to Query