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
