Introduction
============
This is a distutils-packaged and updated version of the beatbox module
by Simon Fell, which is a Python implementation of a client for the
Salesforce.com Partner Web Services API.
`beatbox module <http://www.pocketsoap.com/beatbox>`_
This module contains 2 versions of the Salesforce.com client:
* XMLClient
The original beatbox version of the client which returns xmltramp objects.
* PythonClient
Marshalls the returned objects into proper Python data types. e.g. integer fields return integers.
Compatibility
=============
Beatbox supports versions 16.0 through 20.0 of the Salesforce Partner Web
Services API. However, the following API calls have not been implemented at
this time:
* convertLead
* emptyRecycleBin
* invalidateSessions
* logout
* merge
* process
* queryAll
* undelete
* describeSObject
* sendEmail
* describeDataCategoryGroups
* describeDataCategoryGroupStructures
Beatbox has been tested with Python 2.4 and Python 2.6.
Basic Usage Examples
====================
Instantiate a Python Salesforce.com client:
::
svc = beatbox.PythonClient()
svc.login('username', 'passwordTOKEN')
(Note that interacting with Salesforce.com via the API requires the use of a
'security token' which must be appended to the password.)
Query for contacts with last name 'Doe':
::
res = svc.query("SELECT Id, FirstName, LastName FROM Contact WHERE LastName='Doe'")
res[0]
# {'LastName': 'Doe', 'type': 'Contact', 'Id': '0037000000eRf6vAAC', 'FirstName': 'John'}
res[0].Id
# '0037000000eRf6vAAC'
Add a new Lead and get the ID of the newly created Lead:
::
contact = {'type': 'Lead', 'LastName': 'Glick', 'FirstName': 'David', 'Company': 'Individual'}
res = svc.create(contact)
res[0]['id']
# '00Q7000000RVyiHEAT'
More Examples
=============
The examples folder contains the examples for the original beatbox. For
examples on how to use the PythonClient see
src/beatbox/tests/test_pythonClient.py.
Some of these other products that have been built on top of beatbox can also
provide example of use:
* `Salesforce Base Connector <http://plone.org/products/salesforcebaseconnector>`_
* `Salesforce PFG Adapter <http://plone.org/products/salesforcepfgadapter>`_
* `Salesforce Auth Plugin <http://plone.org/products/salesforceauthplugin>`_
* `RSVP for Salesforce <http://plone.org/products/collective.salesforce.rsvp>`_
Alternatives
============
David Lanstein has created a `Python Salesforce Toolkit <http://code.google.com/p/salesforce-python-toolkit/>`_ that is based on the
`suds <https://fedorahosted.org/suds/>`_ SOAP library. Based on limited tests it appears to be somewhat slower
than beatbox for operations that return a lot of data; however, it may be a
better option if you want to be able to automatically generate a service proxy
for a new WSDL (such as for the Enterprise web services API).
Ron Hess from Salesforce.com has adapted beatbox for use with Google App
Engine. See `<http://code.google.com/p/force-app-engine/>`
Running Tests
=============
First, we need to add some custom fields to the Contacts object in your Salesforce instance:
* Login to your Salesforce.com instance
* Browse to Setup --> Customize --> Contacts --> Fields --> "New" button
* Add a Picklist (multi-select) labeled "Favorite Fruit", then add: Apple, Orange, Pear
* Leave default of 3 lines and field name should default to "Favorite_Fruit"
* Add a Number labeled "Favorite Integer", with 18 places, 0 decimal places
* Add a Number labeled "Favorite Float", with 13 places, 5 decimal places
Create a sfconfig file in your python path with the following format:
::
USERNAME='your salesforce username'
PASSWORD='your salesforce passwordTOKEN'
where TOKEN is your Salesforce API login token.
Add './src' to your PYTHONPATH
Run the tests:
::
python src/beatbox/tests/test_beatbox.py
python src/beatbox/tests/test_pythonClient.py