*****************
Simple Salesforce
*****************
.. image:: https://app.travis-ci.com/simple-salesforce/simple-salesforce.svg?branch=master
:target: https://travis-ci.org/simple-salesforce/simple-salesforce
.. image:: https://readthedocs.org/projects/simple-salesforce/badge/?version=latest
:target: http://simple-salesforce.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
Simple Salesforce is a basic Salesforce.com REST API client built for Python 3.8, 3.9, 3.10, 3.11, and 3.12. The goal is to provide a very low-level interface to the REST Resource and APEX API, returning a dictionary of the API JSON response.
You can find out more regarding the format of the results in the `Official Salesforce.com REST API Documentation`_
.. _Official Salesforce.com REST API Documentation: http://www.salesforce.com/us/developer/docs/api_rest/index.htm
=============
Documentation
--------------------------------
.. _Official Simple Salesforce documentation: http://simple-salesforce.readthedocs.io/en/latest/
`Official Simple Salesforce documentation`_
Examples
--------------------------
There are two ways to gain access to Salesforce
The first is to simply pass the domain of your Salesforce instance and an access token straight to ``Salesforce()``
For example:
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(instance='na1.salesforce.com', session_id='')
If you have the full URL of your instance (perhaps including the schema, as is included in the OAuth2 request process), you can pass that in instead using ``instance_url``:
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(instance_url='https://na1.salesforce.com', session_id='')
There are also four means of authentication, one that uses username, password and security token; one that uses IP filtering, username, password and organizationId, one that uses a private key to sign a JWT, and one for connected apps that uses username, password, consumer key, and consumer secret;
To login using the security token method, simply include the Salesforce method and pass in your Salesforce username, password and token (this is usually provided when you change your password):
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(username='myemail@example.com', password='password', security_token='token')
To login using IP-whitelist Organization ID method, simply use your Salesforce username, password and organizationId:
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(password='password', username='myemail@example.com', organizationId='OrgId')
To login using the JWT method, use your Salesforce username, consumer key from your app, and private key (`How To <https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_jwt_flow.htm#sfdx_dev_auth_jwt_flow>`_):
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(username='myemail@example.com', consumer_key='XYZ', privatekey_file='filename.key')
To login using a connected app, simply include the Salesforce method and pass in your Salesforce username, password, consumer_key and consumer_secret (the consumer key and consumer secret are provided when you setup your connected app):
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(username='myemail@example.com', password='password', consumer_key='consumer_key', consumer_secret='consumer_secret')
If you'd like to enter a sandbox, simply add ``domain='test'`` to your ``Salesforce()`` call.
For example:
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(username='myemail@example.com.sandbox', password='password', security_token='token', domain='test')
Note that specifying if you want to use a domain is only necessary if you are using the built-in username/password/security token authentication and is used exclusively during the authentication step.
If you'd like to keep track where your API calls are coming from, simply add ``client_id='My App'`` to your ``Salesforce()`` call.
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(username='myemail@example.com.sandbox', password='password', security_token='token', client_id='My App', domain='test')
If you view the API calls in your Salesforce instance by Client Id it will be prefixed with ``simple-salesforce/``, for example ``simple-salesforce/My App``.
When instantiating a `Salesforce` object, it's also possible to include an
instance of `requests.Session`. This is to allow for specialized
session handling not otherwise exposed by simple_salesforce.
For example:
.. code-block:: python
from simple_salesforce import Salesforce
import requests
session = requests.Session()
# manipulate the session instance (optional)
sf = Salesforce(
username='user@example.com', password='password', organizationId='OrgId',
session=session)
Record Management
--------------------------
To create a new 'Contact' in Salesforce:
.. code-block:: python
sf.Contact.create({'LastName':'Smith','Email':'example@example.com'})
This will return a dictionary such as ``{u'errors': [], u'id': u'003e0000003GuNXAA0', u'success': True}``
To get a dictionary with all the information regarding that record, use:
.. code-block:: python
contact = sf.Contact.get('003e0000003GuNXAA0')
To get a dictionary with all the information regarding that record, using a **custom** field that was defined as External ID:
.. code-block:: python
contact = sf.Contact.get_by_custom_id('My_Custom_ID__c', '22')
To change that contact's last name from 'Smith' to 'Jones' and add a first name of 'John' use:
.. code-block:: python
sf.Contact.update('003e0000003GuNXAA0',{'LastName': 'Jones', 'FirstName': 'John'})
To delete the contact:
.. code-block:: python
sf.Contact.delete('003e0000003GuNXAA0')
To retrieve a list of Contact records deleted over the past 10 days (datetimes are required to be in UTC):
.. code-block:: python
import pytz
import datetime
end = datetime.datetime.now(pytz.UTC) # we need to use UTC as salesforce API requires this!
sf.Contact.deleted(end - datetime.timedelta(days=10), end)
To retrieve a list of Contact records updated over the past 10 days (datetimes are required to be in UTC):
.. code-block:: python
import pytz
import datetime
end = datetime.datetime.now(pytz.UTC) # we need to use UTC as salesforce API requires this
sf.Contact.updated(end - datetime.timedelta(days=10), end)
Note that Update, Delete and Upsert actions return the associated `Salesforce HTTP Status Code`_
Use the same format to create any record, including 'Account', 'Opportunity', and 'Lead'.
Make sure to have all the required fields for any entry. The `Salesforce API`_ has all objects found under 'Reference -> Standard Objects' and the required fields can be found there.
.. _Salesforce HTTP Status Code: http://www.salesforce.com/us/developer/docs/api_rest/Content/errorcodes.htm
.. _Salesforce API: https://www.salesforce.com/developer/docs/api/
Queries
--------------------------
It's also possible to write select queries in Salesforce Object Query Language (SOQL) and search queries in Salesforce Object Search Language (SOSL).
All SOQL queries are supported and parent/child relationships can be queried using the standard format (Parent__r.FieldName). SOQL queries are done via:
.. code-block:: python
sf.query("SELECT Id, Email, ParentAccount.Name FROM Contact WHERE LastName = 'Jones'")
If, due to an especially large result, Salesforce adds a ``nextRecordsUrl`` to your query result, such as ``"nextRecordsUrl" : "/services/data/v26.0/query/01gD0000002HU6KIAW-2000"``, you can pull the additional results with either the ID or the full URL (if using the full URL, you must pass 'True' as your second argument)
.. code-block:: python
sf.query_more("01gD0000002HU6KIAW-2000")
sf.query_more("/services/data/v26.0/query/01gD0000002HU6KIAW-2000", True)
As a convenience, to retrieve all of the results in a single local method call use
.. code-block:: python
sf.query_all("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")
While ``query_all`` materializes the whole result into a Python list, ``query_all_iter`` returns an iterator, which allows you to lazily process each element separately
.. code-block:: python
data = sf.query_all_iter("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")
for row in data:
process(row)
Values used in SOQL queries can be quoted and escaped using ``format_soql``:
.. code-block:: python
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE LastName = {}", "Jones"))
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE LastName = {last_name}", last_name="Jones"))
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE LastName IN {names}", names=["Smith", "Jones"]))
To skip quoting and escaping for one value while still using the format string, use ``:literal``:
.. code-block:: python
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE Income > {:literal}", "USD100"))
To escape a substring used in a LIKE expression while being able to use % around it, use ``:like``:
.. code-block:: python
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE Name LIKE '{:like}%'", "Jones"))
SOSL queries are done via:
.. code-block:: python
sf.search("FIND {Jones}")
There is also 'Quick Search', which inserts your query inside the {} in the SOSL syntax. Be careful, there is no escaping!
.. code-block:: python
sf.quick_search("Jones")
Search and Quick Search return ``None`` if there are no records, otherwise they return a dictionary of search results.
More details about syntax is available on the `Salesforce Query Language Documentation Developer Website`_
.. _Salesforce Query Language Documentation Developer Website: http://www.salesforce.com/us/developer/docs/soql_sosl/index.htm
CRUD Metadata API Calls
_______________________
You can use simple_salesforce to make CRUD (Create, Read, Update and Delete) API calls to the metadata API.
First, get the metadata API object:
.. code-block:: python
mdapi = sf.mdapi
To create a new metadata component in Salesforce, define the metadata component using the metadata types reference
given in Salesforce's `metadata API documentation`_
.. _metadata API documentation: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_types_list.htm
.. code-block:: python
custom_object = mdapi.CustomObject(
fullName = "CustomObject__c",
label = "Custom Object",
pluralLabel = "Custom Objects",
nameField = mdapi.CustomField(
label = "Name",
type = mdapi.FieldType("Text")
),
deploymentStatus = mdapi.DeploymentStatus("Deployed"),
sharingModel = mdapi.SharingModel("Read")
)
This custom object metadata can then be created in Salesforce using the createMetadata API call:
.. code-block:: python
mdapi.CustomObject.create(custom_object)
Similarly, any metadata type can be created in Salesforce using the syntax :code:`mdapi.MetadataType.create()`. It is
also possible to create more than one metadata component in Salesforce with a single createMetadata API call. This can
be done by passing a list of metadata definitions to :code:`mdapi.MetadataType.create()`. Up to 10 metadata components
of the same metadata type can be created in a single API call (This limit is 200 in the case of CustomMetadata and
CustomApplication).
readMetadata, updateMetadata, upsertMetadata, deleteMetadata, renameMetadata and describeValueType API calls can be
performed with similar syntax to createMetadata:
.. code-block:: python
describe_response = mdapi.CustomObject.describe()
custom_object = mdapi.CustomObject.read("CustomObject__c")
custom_object.sharingModel = mdapi.SharingModel("ReadWrite")
mdapi.CustomObject.update(custom_object)
mdapi.CustomObject.rename("CustomObject__c", "CustomObject2__c")
mdapi.CustomObject.delete("CustomObject2__c")
The describe method returns a `DescribeValueTypeResult`_ object.
.. _DescribeValueTypeResult: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_describeValueTypeResult.htm
Just like with the createMetadata API call, multiple metadata components can be dealt with in a single API call for all
CRUD operations by passing a list to their respective methods. In the case of readMetadata, if multiple components are
read in a single API call, a list will be returned.
simple_salesforce validates the response received from Salesforce. Create, update, upsert, delete and rename
methods return :code:`None`, but raise an Exception with error message (from Salesforce) if Salesforce does not return
success. So, error handling can be done by catching the python exception.
simple_salesforce also supports describeMetadata and listMetadata API calls as follows. describeMetadata uses the API
version set for the Salesforce object and will return a DescribeMetadataResult object.
.. code-block:: python
mdapi.describe()
query = mdapi.ListMetadataQuery(type='CustomObject')
query_response = mdapi.list_metadata(query)
Up to 3 ListMetadataQuery objects can be submitted in one list_metadata API call by passing a list. The list_metadata
method returns a list of `FileProperties`_ objects.
.. _FileProperties: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_retrieveresult.htm#retrieveresult_fileproperties
File Based Metadata API Calls
-----------------------------
You can use simple_salesforce to make file-based calls to the Metadata API, to deploy a zip file to an org.
First, convert and zip the file with:
.. code-block::
sfdx force:source:convert -r src/folder_name -d dx
Then navigate into the converted folder and zip it up:
.. code-block::
zip -r -X package.zip *
Then you can use this to deploy that zipfile:
.. code-block:: python
result = sf.deploy("path/to/zip", sandbox=False, **kwargs)
asyncId = result.get('asyncId')
state = result.get('state')
Both deploy and checkDeployStatus take keyword arguments. The single package argument is not currently available to be set for deployments. More details on the deploy options can be found at https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_deploy.htm
You can check on the progress of the deploy which returns a dictionary with status, state_detail, deployment_detail, unit_test_detail:
.. code-block:: python
sf.checkDeployStatus(asyncId)
Example of a use-case:
.. code-block:: python
from simple_salesforce import Salesforce
deployment_finished = False
successful = False
sf = Salesforce(session_id="id", instance="instance")
sf.deploy("path/to/zip", sandbox=False ,**kwargs)
while not deployment_finished:
result = sf.checkDeployStatus(asyncId)
if result.get('status') in ["Succeeded", "Completed", "Error", "Failed", None]:
deployment_finished = True
if result.get('status') in ["Succeeded", "Completed"]:
successful = True
if successful:
print("✅")
else:
print("🥔")
Other Options
--------------------------
To insert or update (upsert) a record using an external ID, use:
.. code-block:: python
sf.Contact.upsert('customExtIdField__c/11999',{'LastName': 'Smith','Email': 'smith@example.com'})
To format an external ID that could contain non-URL-safe characters, use:
.. code-block:: python
external_id = format_external_id('customExtIdField__c', 'this/that & the other')
To retrieve basic metadata use:
.. code-block:: python
sf.Contact.metadata()
To retrieve a description of the object, use:
.. code-block:: python
sf.Contact.describe()
To retrieve a description of the record layout of an object by its record layout unique id, use:
.. code-block:: python
sf.Contact.describe_layout('39wmxcw9r23r492')
To retrieve a list of top level description of instance metadata, user:
.. code-block:: python
sf.describe()
for x in sf.describe()["sobjects"]:
print x["label"]
Using Bulk
--------------------------
You can use this library to access Bulk API functions. The data element can be a list of records of any size and by default batch sizes are 10,000 records and run in parallel concurrency mode. To set the batch size for insert, upsert, delete, hard_delete, and update use the batch_size argument. To set the concurrency mode for the salesforce job the use_serial argument can be set to use_serial=True.
Create new records:
.. code-block:: python
data = [
{'LastName':'Smith','Email':'example@example.com'},
{'LastName':'Jones','Email':'test@test.com'}
]
sf.bulk.Contact.insert(data,batch_size=10000,use_serial=True)
Update existing records:
.. code-block:: python
data = [
{'Id': '0000000000AAAAA', 'Email': 'examplenew@example.com'},
{'Id': '0000000000BBBBB', 'Email': 'testnew@test.com'}
]
sf.bulk.Contact.update(data,batch_size=10000,use_serial=True)
Update existing records and update lookup fields from an external id field:
.. code-block:: python
data = [
{'Id': '0000000000AAAAA', 'Custom_Object__r': {'Email__c':'examplenew@example.com'}},
{'Id': '0000000000BBBBB', 'Custom_Object__r': {'Email__c': 'testnew@test.com'}}
]
sf.bulk.Contact.update(data,batch_size=10000,use_serial=True)
Upsert records:
.. code-block:: python
data = [
{'Id': '0000000000AAAAA', 'Email': 'examplenew2@example.com'},
{'Email': 'foo@foo.com'}
]
sf.bulk.Contact.upsert(data, 'Id', batch_size=10000, use_serial=True)
Query records:
.. code-block:: python
query = 'SELECT Id, Name FROM Account LIMIT 10'
sf.bulk.Account.query(query)
To retrieve large amounts of data, use
.. code-block:: python
query = 'SELECT Id, Name FROM Account'
# generator on the results page
fetch_results = sf.bulk.Account.query(query, lazy_operation=True)
# the generator provides the list of results for every call to next()
all_results = []
for list_results in fetch_results:
all_results.extend(list_results)
Query all records:
QueryAll will return records that have been deleted because of a merge or delete. QueryAll will also return information about archived Task and Event records.
.. code-block:: python
query = 'SELECT Id, Name FROM Account LIMIT 10'
sf.bulk.Account.query_all(query)
To retrieve large amounts of data, use
.. code-block:: python
query = 'SELECT Id, Name FROM Account'
# generator on the results page
fetch_results = sf.bulk.Account.query_all(query, lazy_operation=True)
# the generator provides the list of results for every call to next()
all_results = []
for list_results in fetch_results:
all_results.extend(list_results)
Delete records (soft deletion):
.. code-block:: python
data = [{'Id': '0000000000AAAAA'}]
sf.bulk.Contact.delete(data,batch_size=10000,use_serial=True)
Hard deletion:
.. code-block:: python
data = [{'Id': '0000000000BBBBB'}]
sf.bulk.Contact.hard_delete(data,batch_size=10000,use_serial=True)
Using Bulk 2.0
--------------------------
You can use this library to access Bulk 2.0 API functions.
Create new records:
.. code-block:: text
"Custom_Id__c","AccountId","Email","FirstName","LastName"
"CustomID1","ID-13","contact1@example.com","Bob","x"
"CustomID2","ID-24","contact2@example.com","Alice","y"
...
.. code-block:: python
sf.bulk2.Contact.insert("./sample.csv", batch_size=10000)
Create new records concurrently:
.. code-block:: python
sf.bulk2.Contact.insert("./sample.csv", batch_size=10000, concurrency=10)
Update existing records:
.. code-block:: text
"Custom_Id__c","AccountId","Email","FirstName","LastName"
"CustomID1","ID-13","contact1@example.com","Bob","X"
"CustomID2","ID-24","contact2@example.com","Alice","Y"
...
.. code-block:: python
sf.bulk2.Contact.update("./sample.csv")
Upsert records:
.. code-block:: text
"Custom_Id__c","LastName"
"CustomID1","X"
"CustomID2","Y"
...
.. code-block:: python
sf.bulk2.Contact.upsert("./sample.csv", 'Custom_Id__c')
Query records:
.. code-block:: python
query = 'SELECT Id, Name FROM Account LIMIT 100000'
results = sf.bulk2.Account.query(
query, max_records=50000, column_delimiter="COMM", line_ending="LF"
)
for i, data in enumerate(results):
with open(f"results/part-{1}.csv", "w") as bos:
bos.write(data)
Download records(low memory usage):
.. code-block:: python
query = 'SELECT Id, Name FROM Account'
sf.bulk2.Account.download(
query, path="results/", max_records=200000
)
Delete records (soft deletion):
.. code-block:: text
"Id"
"0000000000AAAAA"
"0000000000BBBBB"
...
.. code-block:: python
sf.bulk2.Contact.delete("./sample.csv")
Hard deletion:
.. code-block:: python
sf.bulk2.Contact.hard_delete("./sample.csv")
Retrieve failed/successful/unprocessed records for ingest(insert,update...) job:
.. code-block:: python
results = sf.bulk2.Contact.insert("./sample.csv")
# [{"numberRecordsFailed": 123, "numberRecordsProcessed": 2000, "numberRecordsTotal": 2000, "job_id": "Job-1"}, ...]
for result in results:
job_id = result['job_id']
# also available: get_unprocessed_records, get_successful_records
data = sf.bulk2.Contact.get_failed_records(job_id)
# or save to file
sf.bulk2.Contact.get_failed_records(job_id, file=f'{job_id}.csv')
Using Apex
--------------------------
You can also use this library to call custom Apex methods:
.. code-block:: python
payload = {
"activity": [
{"user": "12345", "action": "update page", "time": "2014-04-21T13:00:15Z"}
]
}
result = sf.apexecute('User/Activity', method='POST', data=payload)
This would call the endpoint ``https://<instance>.salesforce.com/services/apexrest/User/Activity`` with ``data=`` as
the body content encoded with ``json.dumps``
You can read more about Apex on the `Force.com Apex Code Developer's Guide`_
.. _Force.com Apex Code Developer's Guide: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_dev_guide.htm
Additional Features
--------------------------
There are a few helper classes that are used internally and available to you.
Included in them are ``SalesforceLogin``, which takes in a username, password, security token, optional version and optional domain and returns a tuple of ``(session_id, sf_instance)`` where `session_id` is the session ID to use for authentication to Salesforce and ``sf_instance`` is the domain of the instance of Salesforce to use for the session.
For example, to use SalesforceLogin for a sandbox account you'd use:
.. code-block:: python
from simple_salesforce import SalesforceLogin
session_id, instance = SalesforceLogin(
username='myemail@example.com.sandbox',
password='password',
security_token='token',
domain='test')
Simply leave off the final domain if you do not wish to use a sandbox.
Also exposed is the ``SFType`` class, which is used internally by the ``__getattr__()`` method in the ``Salesforce()`` class and represents a specific SObject type. ``SFType`` requires ``object_name`` (i.e. ``Contact``), ``session_id`` (an authentication ID), ``sf_instance`` (hostname of your Salesforce instance), and an optional ``sf_version``
To add a Contact using the default version of the API you'd use:
.. code-block:: python
from simple_salesforce import SFType
contact = SFType('Contact','sesssionid','na1.salesforce.com')
contact.create({'LastName':'Smith','Email':'example@example.com'})
To use a proxy server between your client and the SalesForce endpoint, use the proxies argument when creating SalesForce object.
The proxy argument is the same as what requests uses, a map of scheme to proxy URL:
.. code-block:: python
proxies = {
"http": "http://10.10.1.10:3128",
"https": "http://10.10.1.10:1080",
}
SalesForce(instance='na1.salesforce.com', session_id='', proxies=proxies)
All results are returned as JSON converted OrderedDict to preserve order of keys from REST responses.
Helpful Datetime Resources
--------------------------
A list of helpful resources when working with datetime/dates from Salesforce
Convert SFDC Datetime to Datetime or Date object
.. code-block:: python
import datetime
# Formatting to SFDC datetime
formatted_datetime = datetime.datetime.strptime(x, "%Y-%m-%dT%H:%M:%S.%f%z")
#Formatting to SFDC date
formatted_date = datetime.strptime(x, "%Y-%m-%d")
Helpful Pandas Resources
--------------------------
A list of helpful resources when working with Pandas and simple-salesforce
Generate list for SFDC Query "IN" operations from a Pandas Dataframe
.. code-block:: python
import pandas as pd
df = pd.DataFrame([{'Id':1},{'Id':2},{'Id':3}])
def dataframe_to_sfdc_list(df,column):
df_list = df[column].unique()
df_list = [str(x) for x in df_list]
df_list = ','.join("'"+item+"'" for item in df_list)
return df_list
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE Id IN ({})", dataframe_to_sfdc_list(df,column)))
Generate Pandas Dataframe from SFDC API Query (ex.query,query_all)
.. code-block:: python
import pandas as pd
sf.query("SELECT Id, Email FROM Contact")
df = pd.DataFrame(data['records']).drop(['attributes'],axis=1)
Generate Pandas Dataframe from SFDC API Query (ex.query,query_all) and append related fields from query to data frame
.. code-block:: python
import pandas as pd
def sf_api_query(data):
df = pd.DataFrame(data['records']).drop('attributes', axis=1)
listColumns = list(df.columns)
for col in listColumns:
if any (isinstance (df[col].values[i], dict) for i in range(0, len(df[col].values))):
df = pd.concat([df.drop(columns=[col]),df[col].apply(pd.Series,dtype=df[col].dtype).drop('attributes',axis=1).add_prefix(col+'.')],axis=1)
new_columns = np.setdiff1d(df.columns, listColumns)
for i in new_columns:
listColumns.append(i)
return df
df = sf_api_query(sf.query("SELECT Id, Email,ParentAccount.Name FROM Contact"))
Generate Pandas Dataframe from SFDC Bulk API Query (ex.bulk.Account.query)
.. code-block:: python
import pandas as pd
sf.bulk.Account.query("SELECT Id, Email FROM Contact")
df = pd.DataFrame.from_dict(data,orient='columns').drop('attributes',axis=1)
YouTube Tutorial
--------------------------
Here is a helpful `YouTube tutorial`_ which shows how you can manage records in bulk using a jupyter notebook, simple-salesforce and pandas.
This can be a effective way to manage records, and perform simple operations like reassigning accounts, deleting test records, inserting new records, etc...
.. _YouTube tutorial: https://youtu.be/nPQFUgsk6Oo?t=282
Authors & License
--------------------------
This package is released under an open source Apache 2.0 license. Simple-Salesforce was originally written by `Nick Catalano`_ but most newer features and bugfixes come from `community contributors`_. Pull requests submitted to the `GitHub Repo`_ are highly encouraged!
Authentication mechanisms were adapted from Dave Wingate's `RestForce`_ and licensed under a MIT license
The latest build status can be found at `Travis CI`_
.. _Nick Catalano: https://github.com/nickcatal
.. _community contributors: https://github.com/simple-salesforce/simple-salesforce/graphs/contributors
.. _RestForce: http://pypi.python.org/pypi/RestForce/
.. _GitHub Repo: https://github.com/simple-salesforce/simple-salesforce
.. _Travis CI: https://travis-ci.com/simple-salesforce/simple-salesforce
Raw data
{
"_id": null,
"home_page": "https://github.com/simple-salesforce/simple-salesforce",
"name": "simple-salesforce",
"maintainer": "Jonathan Wobken",
"docs_url": null,
"requires_python": null,
"maintainer_email": "jonathanwobken@gmail.com",
"keywords": "python salesforce salesforce.com",
"author": "Nick Catalano",
"author_email": "nickcatal@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/13/a7/22d3992b8413cb775191a2f7af8b193cdaa9d244bf1613a2affeb26bc9f3/simple-salesforce-1.12.6.tar.gz",
"platform": null,
"description": "*****************\nSimple Salesforce\n*****************\n\n.. image:: https://app.travis-ci.com/simple-salesforce/simple-salesforce.svg?branch=master\n :target: https://travis-ci.org/simple-salesforce/simple-salesforce\n\n.. image:: https://readthedocs.org/projects/simple-salesforce/badge/?version=latest\n :target: http://simple-salesforce.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\nSimple Salesforce is a basic Salesforce.com REST API client built for Python 3.8, 3.9, 3.10, 3.11, and 3.12. The goal is to provide a very low-level interface to the REST Resource and APEX API, returning a dictionary of the API JSON response.\nYou can find out more regarding the format of the results in the `Official Salesforce.com REST API Documentation`_\n\n.. _Official Salesforce.com REST API Documentation: http://www.salesforce.com/us/developer/docs/api_rest/index.htm\n\n\n\n=============\n\nDocumentation\n--------------------------------\n\n.. _Official Simple Salesforce documentation: http://simple-salesforce.readthedocs.io/en/latest/\n\n`Official Simple Salesforce documentation`_\n\nExamples\n--------------------------\nThere are two ways to gain access to Salesforce\n\nThe first is to simply pass the domain of your Salesforce instance and an access token straight to ``Salesforce()``\n\nFor example:\n\n.. code-block:: python\n\n from simple_salesforce import Salesforce\n sf = Salesforce(instance='na1.salesforce.com', session_id='')\n\nIf you have the full URL of your instance (perhaps including the schema, as is included in the OAuth2 request process), you can pass that in instead using ``instance_url``:\n\n.. code-block:: python\n\n from simple_salesforce import Salesforce\n sf = Salesforce(instance_url='https://na1.salesforce.com', session_id='')\n\nThere are also four means of authentication, one that uses username, password and security token; one that uses IP filtering, username, password and organizationId, one that uses a private key to sign a JWT, and one for connected apps that uses username, password, consumer key, and consumer secret;\n\nTo login using the security token method, simply include the Salesforce method and pass in your Salesforce username, password and token (this is usually provided when you change your password):\n\n.. code-block:: python\n\n from simple_salesforce import Salesforce\n sf = Salesforce(username='myemail@example.com', password='password', security_token='token')\n\nTo login using IP-whitelist Organization ID method, simply use your Salesforce username, password and organizationId:\n\n.. code-block:: python\n\n from simple_salesforce import Salesforce\n sf = Salesforce(password='password', username='myemail@example.com', organizationId='OrgId')\n\nTo login using the JWT method, use your Salesforce username, consumer key from your app, and private key (`How To <https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_jwt_flow.htm#sfdx_dev_auth_jwt_flow>`_):\n\n.. code-block:: python\n\n from simple_salesforce import Salesforce\n sf = Salesforce(username='myemail@example.com', consumer_key='XYZ', privatekey_file='filename.key')\n\nTo login using a connected app, simply include the Salesforce method and pass in your Salesforce username, password, consumer_key and consumer_secret (the consumer key and consumer secret are provided when you setup your connected app):\n\n.. code-block:: python\n\n from simple_salesforce import Salesforce\n sf = Salesforce(username='myemail@example.com', password='password', consumer_key='consumer_key', consumer_secret='consumer_secret')\n\n\nIf you'd like to enter a sandbox, simply add ``domain='test'`` to your ``Salesforce()`` call.\n\nFor example:\n\n.. code-block:: python\n\n from simple_salesforce import Salesforce\n sf = Salesforce(username='myemail@example.com.sandbox', password='password', security_token='token', domain='test')\n\nNote that specifying if you want to use a domain is only necessary if you are using the built-in username/password/security token authentication and is used exclusively during the authentication step.\n\nIf you'd like to keep track where your API calls are coming from, simply add ``client_id='My App'`` to your ``Salesforce()`` call.\n\n.. code-block:: python\n\n from simple_salesforce import Salesforce\n sf = Salesforce(username='myemail@example.com.sandbox', password='password', security_token='token', client_id='My App', domain='test')\n\nIf you view the API calls in your Salesforce instance by Client Id it will be prefixed with ``simple-salesforce/``, for example ``simple-salesforce/My App``.\n\nWhen instantiating a `Salesforce` object, it's also possible to include an\ninstance of `requests.Session`. This is to allow for specialized\nsession handling not otherwise exposed by simple_salesforce.\n\nFor example:\n\n.. code-block:: python\n\n from simple_salesforce import Salesforce\n import requests\n\n session = requests.Session()\n # manipulate the session instance (optional)\n sf = Salesforce(\n username='user@example.com', password='password', organizationId='OrgId',\n session=session)\n\nRecord Management\n--------------------------\n\nTo create a new 'Contact' in Salesforce:\n\n.. code-block:: python\n\n sf.Contact.create({'LastName':'Smith','Email':'example@example.com'})\n\nThis will return a dictionary such as ``{u'errors': [], u'id': u'003e0000003GuNXAA0', u'success': True}``\n\nTo get a dictionary with all the information regarding that record, use:\n\n.. code-block:: python\n\n contact = sf.Contact.get('003e0000003GuNXAA0')\n\nTo get a dictionary with all the information regarding that record, using a **custom** field that was defined as External ID:\n\n.. code-block:: python\n\n contact = sf.Contact.get_by_custom_id('My_Custom_ID__c', '22')\n\nTo change that contact's last name from 'Smith' to 'Jones' and add a first name of 'John' use:\n\n.. code-block:: python\n\n sf.Contact.update('003e0000003GuNXAA0',{'LastName': 'Jones', 'FirstName': 'John'})\n\nTo delete the contact:\n\n.. code-block:: python\n\n sf.Contact.delete('003e0000003GuNXAA0')\n\nTo retrieve a list of Contact records deleted over the past 10 days (datetimes are required to be in UTC):\n\n.. code-block:: python\n\n import pytz\n import datetime\n end = datetime.datetime.now(pytz.UTC) # we need to use UTC as salesforce API requires this!\n sf.Contact.deleted(end - datetime.timedelta(days=10), end)\n\nTo retrieve a list of Contact records updated over the past 10 days (datetimes are required to be in UTC):\n\n.. code-block:: python\n\n import pytz\n import datetime\n end = datetime.datetime.now(pytz.UTC) # we need to use UTC as salesforce API requires this\n sf.Contact.updated(end - datetime.timedelta(days=10), end)\n\nNote that Update, Delete and Upsert actions return the associated `Salesforce HTTP Status Code`_\n\nUse the same format to create any record, including 'Account', 'Opportunity', and 'Lead'.\nMake sure to have all the required fields for any entry. The `Salesforce API`_ has all objects found under 'Reference -> Standard Objects' and the required fields can be found there.\n\n.. _Salesforce HTTP Status Code: http://www.salesforce.com/us/developer/docs/api_rest/Content/errorcodes.htm\n.. _Salesforce API: https://www.salesforce.com/developer/docs/api/\n\nQueries\n--------------------------\n\nIt's also possible to write select queries in Salesforce Object Query Language (SOQL) and search queries in Salesforce Object Search Language (SOSL).\n\nAll SOQL queries are supported and parent/child relationships can be queried using the standard format (Parent__r.FieldName). SOQL queries are done via:\n\n.. code-block:: python\n\n sf.query(\"SELECT Id, Email, ParentAccount.Name FROM Contact WHERE LastName = 'Jones'\")\n\nIf, due to an especially large result, Salesforce adds a ``nextRecordsUrl`` to your query result, such as ``\"nextRecordsUrl\" : \"/services/data/v26.0/query/01gD0000002HU6KIAW-2000\"``, you can pull the additional results with either the ID or the full URL (if using the full URL, you must pass 'True' as your second argument)\n\n.. code-block:: python\n\n sf.query_more(\"01gD0000002HU6KIAW-2000\")\n sf.query_more(\"/services/data/v26.0/query/01gD0000002HU6KIAW-2000\", True)\n\nAs a convenience, to retrieve all of the results in a single local method call use\n\n.. code-block:: python\n\n sf.query_all(\"SELECT Id, Email FROM Contact WHERE LastName = 'Jones'\")\n\nWhile ``query_all`` materializes the whole result into a Python list, ``query_all_iter`` returns an iterator, which allows you to lazily process each element separately\n\n.. code-block:: python\n\n data = sf.query_all_iter(\"SELECT Id, Email FROM Contact WHERE LastName = 'Jones'\")\n for row in data:\n process(row)\n\nValues used in SOQL queries can be quoted and escaped using ``format_soql``:\n\n.. code-block:: python\n\n sf.query(format_soql(\"SELECT Id, Email FROM Contact WHERE LastName = {}\", \"Jones\"))\n sf.query(format_soql(\"SELECT Id, Email FROM Contact WHERE LastName = {last_name}\", last_name=\"Jones\"))\n sf.query(format_soql(\"SELECT Id, Email FROM Contact WHERE LastName IN {names}\", names=[\"Smith\", \"Jones\"]))\n\nTo skip quoting and escaping for one value while still using the format string, use ``:literal``:\n\n.. code-block:: python\n\n sf.query(format_soql(\"SELECT Id, Email FROM Contact WHERE Income > {:literal}\", \"USD100\"))\n\nTo escape a substring used in a LIKE expression while being able to use % around it, use ``:like``:\n\n.. code-block:: python\n\n sf.query(format_soql(\"SELECT Id, Email FROM Contact WHERE Name LIKE '{:like}%'\", \"Jones\"))\n\nSOSL queries are done via:\n\n.. code-block:: python\n\n sf.search(\"FIND {Jones}\")\n\nThere is also 'Quick Search', which inserts your query inside the {} in the SOSL syntax. Be careful, there is no escaping!\n\n.. code-block:: python\n\n sf.quick_search(\"Jones\")\n\nSearch and Quick Search return ``None`` if there are no records, otherwise they return a dictionary of search results.\n\nMore details about syntax is available on the `Salesforce Query Language Documentation Developer Website`_\n\n.. _Salesforce Query Language Documentation Developer Website: http://www.salesforce.com/us/developer/docs/soql_sosl/index.htm\n\nCRUD Metadata API Calls\n_______________________\n\nYou can use simple_salesforce to make CRUD (Create, Read, Update and Delete) API calls to the metadata API.\n\nFirst, get the metadata API object:\n\n.. code-block:: python\n\n mdapi = sf.mdapi\n\nTo create a new metadata component in Salesforce, define the metadata component using the metadata types reference\ngiven in Salesforce's `metadata API documentation`_\n\n.. _metadata API documentation: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_types_list.htm\n\n.. code-block:: python\n\n custom_object = mdapi.CustomObject(\n fullName = \"CustomObject__c\",\n label = \"Custom Object\",\n pluralLabel = \"Custom Objects\",\n nameField = mdapi.CustomField(\n label = \"Name\",\n type = mdapi.FieldType(\"Text\")\n ),\n deploymentStatus = mdapi.DeploymentStatus(\"Deployed\"),\n sharingModel = mdapi.SharingModel(\"Read\")\n )\n\nThis custom object metadata can then be created in Salesforce using the createMetadata API call:\n\n.. code-block:: python\n\n mdapi.CustomObject.create(custom_object)\n\nSimilarly, any metadata type can be created in Salesforce using the syntax :code:`mdapi.MetadataType.create()`. It is\nalso possible to create more than one metadata component in Salesforce with a single createMetadata API call. This can\nbe done by passing a list of metadata definitions to :code:`mdapi.MetadataType.create()`. Up to 10 metadata components\nof the same metadata type can be created in a single API call (This limit is 200 in the case of CustomMetadata and\nCustomApplication).\n\nreadMetadata, updateMetadata, upsertMetadata, deleteMetadata, renameMetadata and describeValueType API calls can be\nperformed with similar syntax to createMetadata:\n\n.. code-block:: python\n\n describe_response = mdapi.CustomObject.describe()\n custom_object = mdapi.CustomObject.read(\"CustomObject__c\")\n custom_object.sharingModel = mdapi.SharingModel(\"ReadWrite\")\n mdapi.CustomObject.update(custom_object)\n mdapi.CustomObject.rename(\"CustomObject__c\", \"CustomObject2__c\")\n mdapi.CustomObject.delete(\"CustomObject2__c\")\n\nThe describe method returns a `DescribeValueTypeResult`_ object.\n\n.. _DescribeValueTypeResult: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_describeValueTypeResult.htm\n\nJust like with the createMetadata API call, multiple metadata components can be dealt with in a single API call for all\nCRUD operations by passing a list to their respective methods. In the case of readMetadata, if multiple components are\nread in a single API call, a list will be returned.\n\nsimple_salesforce validates the response received from Salesforce. Create, update, upsert, delete and rename\nmethods return :code:`None`, but raise an Exception with error message (from Salesforce) if Salesforce does not return\nsuccess. So, error handling can be done by catching the python exception.\n\nsimple_salesforce also supports describeMetadata and listMetadata API calls as follows. describeMetadata uses the API\nversion set for the Salesforce object and will return a DescribeMetadataResult object.\n\n.. code-block:: python\n\n mdapi.describe()\n query = mdapi.ListMetadataQuery(type='CustomObject')\n query_response = mdapi.list_metadata(query)\n\nUp to 3 ListMetadataQuery objects can be submitted in one list_metadata API call by passing a list. The list_metadata\nmethod returns a list of `FileProperties`_ objects.\n\n.. _FileProperties: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_retrieveresult.htm#retrieveresult_fileproperties\n\nFile Based Metadata API Calls\n-----------------------------\n\nYou can use simple_salesforce to make file-based calls to the Metadata API, to deploy a zip file to an org.\n\nFirst, convert and zip the file with:\n\n.. code-block::\n\n sfdx force:source:convert -r src/folder_name -d dx\n\nThen navigate into the converted folder and zip it up:\n\n.. code-block::\n\n zip -r -X package.zip *\n\nThen you can use this to deploy that zipfile:\n\n.. code-block:: python\n\n result = sf.deploy(\"path/to/zip\", sandbox=False, **kwargs)\n asyncId = result.get('asyncId')\n state = result.get('state')\n\nBoth deploy and checkDeployStatus take keyword arguments. The single package argument is not currently available to be set for deployments. More details on the deploy options can be found at https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_deploy.htm\n\nYou can check on the progress of the deploy which returns a dictionary with status, state_detail, deployment_detail, unit_test_detail:\n\n.. code-block:: python\n\n sf.checkDeployStatus(asyncId)\n\nExample of a use-case:\n\n.. code-block:: python\n\n from simple_salesforce import Salesforce\n\n deployment_finished = False\n successful = False\n\n sf = Salesforce(session_id=\"id\", instance=\"instance\")\n sf.deploy(\"path/to/zip\", sandbox=False ,**kwargs)\n\n while not deployment_finished:\n result = sf.checkDeployStatus(asyncId)\n if result.get('status') in [\"Succeeded\", \"Completed\", \"Error\", \"Failed\", None]:\n deployment_finished = True\n if result.get('status') in [\"Succeeded\", \"Completed\"]:\n successful = True\n\n if successful:\n print(\"\u00e2\u0153\u2026\")\n else:\n print(\"\u00f0\u0178\u00a5\u201d\")\n\nOther Options\n--------------------------\n\nTo insert or update (upsert) a record using an external ID, use:\n\n.. code-block:: python\n\n sf.Contact.upsert('customExtIdField__c/11999',{'LastName': 'Smith','Email': 'smith@example.com'})\n\nTo format an external ID that could contain non-URL-safe characters, use:\n\n.. code-block:: python\n\n external_id = format_external_id('customExtIdField__c', 'this/that & the other')\n\nTo retrieve basic metadata use:\n\n.. code-block:: python\n\n sf.Contact.metadata()\n\nTo retrieve a description of the object, use:\n\n.. code-block:: python\n\n sf.Contact.describe()\n\nTo retrieve a description of the record layout of an object by its record layout unique id, use:\n\n.. code-block:: python\n\n sf.Contact.describe_layout('39wmxcw9r23r492')\n\nTo retrieve a list of top level description of instance metadata, user:\n\n.. code-block:: python\n\n sf.describe()\n\n for x in sf.describe()[\"sobjects\"]:\n print x[\"label\"]\n\n\nUsing Bulk\n--------------------------\n\nYou can use this library to access Bulk API functions. The data element can be a list of records of any size and by default batch sizes are 10,000 records and run in parallel concurrency mode. To set the batch size for insert, upsert, delete, hard_delete, and update use the batch_size argument. To set the concurrency mode for the salesforce job the use_serial argument can be set to use_serial=True.\n\nCreate new records:\n\n.. code-block:: python\n\n data = [\n {'LastName':'Smith','Email':'example@example.com'},\n {'LastName':'Jones','Email':'test@test.com'}\n ]\n\n sf.bulk.Contact.insert(data,batch_size=10000,use_serial=True)\n\nUpdate existing records:\n\n.. code-block:: python\n\n data = [\n {'Id': '0000000000AAAAA', 'Email': 'examplenew@example.com'},\n {'Id': '0000000000BBBBB', 'Email': 'testnew@test.com'}\n ]\n\n sf.bulk.Contact.update(data,batch_size=10000,use_serial=True)\n\nUpdate existing records and update lookup fields from an external id field:\n\n.. code-block:: python\n\n data = [\n {'Id': '0000000000AAAAA', 'Custom_Object__r': {'Email__c':'examplenew@example.com'}},\n {'Id': '0000000000BBBBB', 'Custom_Object__r': {'Email__c': 'testnew@test.com'}}\n ]\n\n sf.bulk.Contact.update(data,batch_size=10000,use_serial=True)\n\nUpsert records:\n\n.. code-block:: python\n\n data = [\n {'Id': '0000000000AAAAA', 'Email': 'examplenew2@example.com'},\n {'Email': 'foo@foo.com'}\n ]\n\n sf.bulk.Contact.upsert(data, 'Id', batch_size=10000, use_serial=True)\n\n\nQuery records:\n\n.. code-block:: python\n\n query = 'SELECT Id, Name FROM Account LIMIT 10'\n\n sf.bulk.Account.query(query)\n\nTo retrieve large amounts of data, use\n\n.. code-block:: python\n\n query = 'SELECT Id, Name FROM Account'\n\n # generator on the results page\n fetch_results = sf.bulk.Account.query(query, lazy_operation=True)\n\n # the generator provides the list of results for every call to next()\n all_results = []\n for list_results in fetch_results:\n all_results.extend(list_results)\n\nQuery all records:\n\nQueryAll will return records that have been deleted because of a merge or delete. QueryAll will also return information about archived Task and Event records.\n\n.. code-block:: python\n\n query = 'SELECT Id, Name FROM Account LIMIT 10'\n\n sf.bulk.Account.query_all(query)\n\nTo retrieve large amounts of data, use\n\n.. code-block:: python\n\n query = 'SELECT Id, Name FROM Account'\n\n # generator on the results page\n fetch_results = sf.bulk.Account.query_all(query, lazy_operation=True)\n\n # the generator provides the list of results for every call to next()\n all_results = []\n for list_results in fetch_results:\n all_results.extend(list_results)\n\nDelete records (soft deletion):\n\n.. code-block:: python\n\n data = [{'Id': '0000000000AAAAA'}]\n\n sf.bulk.Contact.delete(data,batch_size=10000,use_serial=True)\n\nHard deletion:\n\n.. code-block:: python\n\n data = [{'Id': '0000000000BBBBB'}]\n\n sf.bulk.Contact.hard_delete(data,batch_size=10000,use_serial=True)\n\n\nUsing Bulk 2.0\n--------------------------\n\nYou can use this library to access Bulk 2.0 API functions.\n\nCreate new records:\n\n.. code-block:: text\n\n \"Custom_Id__c\",\"AccountId\",\"Email\",\"FirstName\",\"LastName\"\n \"CustomID1\",\"ID-13\",\"contact1@example.com\",\"Bob\",\"x\"\n \"CustomID2\",\"ID-24\",\"contact2@example.com\",\"Alice\",\"y\"\n ...\n\n.. code-block:: python\n\n sf.bulk2.Contact.insert(\"./sample.csv\", batch_size=10000)\n\n\nCreate new records concurrently:\n\n.. code-block:: python\n\n sf.bulk2.Contact.insert(\"./sample.csv\", batch_size=10000, concurrency=10)\n\n\nUpdate existing records:\n\n.. code-block:: text\n\n \"Custom_Id__c\",\"AccountId\",\"Email\",\"FirstName\",\"LastName\"\n \"CustomID1\",\"ID-13\",\"contact1@example.com\",\"Bob\",\"X\"\n \"CustomID2\",\"ID-24\",\"contact2@example.com\",\"Alice\",\"Y\"\n ...\n\n.. code-block:: python\n\n sf.bulk2.Contact.update(\"./sample.csv\")\n\n\nUpsert records:\n\n.. code-block:: text\n\n \"Custom_Id__c\",\"LastName\"\n \"CustomID1\",\"X\"\n \"CustomID2\",\"Y\"\n ...\n\n.. code-block:: python\n\n sf.bulk2.Contact.upsert(\"./sample.csv\", 'Custom_Id__c')\n\n\nQuery records:\n\n.. code-block:: python\n\n query = 'SELECT Id, Name FROM Account LIMIT 100000'\n\n results = sf.bulk2.Account.query(\n query, max_records=50000, column_delimiter=\"COMM\", line_ending=\"LF\"\n )\n for i, data in enumerate(results):\n with open(f\"results/part-{1}.csv\", \"w\") as bos:\n bos.write(data)\n\n\nDownload records(low memory usage):\n\n.. code-block:: python\n\n query = 'SELECT Id, Name FROM Account'\n\n sf.bulk2.Account.download(\n query, path=\"results/\", max_records=200000\n )\n\n\nDelete records (soft deletion):\n\n.. code-block:: text\n\n \"Id\"\n \"0000000000AAAAA\"\n \"0000000000BBBBB\"\n ...\n\n\n.. code-block:: python\n\n sf.bulk2.Contact.delete(\"./sample.csv\")\n\n\nHard deletion:\n\n.. code-block:: python\n\n sf.bulk2.Contact.hard_delete(\"./sample.csv\")\n\n\nRetrieve failed/successful/unprocessed records for ingest(insert,update...) job:\n\n.. code-block:: python\n\n results = sf.bulk2.Contact.insert(\"./sample.csv\")\n # [{\"numberRecordsFailed\": 123, \"numberRecordsProcessed\": 2000, \"numberRecordsTotal\": 2000, \"job_id\": \"Job-1\"}, ...]\n for result in results:\n job_id = result['job_id']\n # also available: get_unprocessed_records, get_successful_records\n data = sf.bulk2.Contact.get_failed_records(job_id)\n # or save to file\n sf.bulk2.Contact.get_failed_records(job_id, file=f'{job_id}.csv')\n\n\nUsing Apex\n--------------------------\n\nYou can also use this library to call custom Apex methods:\n\n.. code-block:: python\n\n payload = {\n \"activity\": [\n {\"user\": \"12345\", \"action\": \"update page\", \"time\": \"2014-04-21T13:00:15Z\"}\n ]\n }\n result = sf.apexecute('User/Activity', method='POST', data=payload)\n\nThis would call the endpoint ``https://<instance>.salesforce.com/services/apexrest/User/Activity`` with ``data=`` as\nthe body content encoded with ``json.dumps``\n\nYou can read more about Apex on the `Force.com Apex Code Developer's Guide`_\n\n.. _Force.com Apex Code Developer's Guide: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_dev_guide.htm\n\nAdditional Features\n--------------------------\n\nThere are a few helper classes that are used internally and available to you.\n\nIncluded in them are ``SalesforceLogin``, which takes in a username, password, security token, optional version and optional domain and returns a tuple of ``(session_id, sf_instance)`` where `session_id` is the session ID to use for authentication to Salesforce and ``sf_instance`` is the domain of the instance of Salesforce to use for the session.\n\nFor example, to use SalesforceLogin for a sandbox account you'd use:\n\n.. code-block:: python\n\n from simple_salesforce import SalesforceLogin\n session_id, instance = SalesforceLogin(\n username='myemail@example.com.sandbox',\n password='password',\n security_token='token',\n domain='test')\n\nSimply leave off the final domain if you do not wish to use a sandbox.\n\nAlso exposed is the ``SFType`` class, which is used internally by the ``__getattr__()`` method in the ``Salesforce()`` class and represents a specific SObject type. ``SFType`` requires ``object_name`` (i.e. ``Contact``), ``session_id`` (an authentication ID), ``sf_instance`` (hostname of your Salesforce instance), and an optional ``sf_version``\n\nTo add a Contact using the default version of the API you'd use:\n\n.. code-block:: python\n\n from simple_salesforce import SFType\n contact = SFType('Contact','sesssionid','na1.salesforce.com')\n contact.create({'LastName':'Smith','Email':'example@example.com'})\n\nTo use a proxy server between your client and the SalesForce endpoint, use the proxies argument when creating SalesForce object.\nThe proxy argument is the same as what requests uses, a map of scheme to proxy URL:\n\n.. code-block:: python\n\n proxies = {\n \"http\": \"http://10.10.1.10:3128\",\n \"https\": \"http://10.10.1.10:1080\",\n }\n SalesForce(instance='na1.salesforce.com', session_id='', proxies=proxies)\n\nAll results are returned as JSON converted OrderedDict to preserve order of keys from REST responses.\n\nHelpful Datetime Resources\n--------------------------\nA list of helpful resources when working with datetime/dates from Salesforce\n\nConvert SFDC Datetime to Datetime or Date object\n.. code-block:: python\n\n import datetime\n # Formatting to SFDC datetime\n formatted_datetime = datetime.datetime.strptime(x, \"%Y-%m-%dT%H:%M:%S.%f%z\")\n\n #Formatting to SFDC date\n formatted_date = datetime.strptime(x, \"%Y-%m-%d\")\n\nHelpful Pandas Resources\n--------------------------\nA list of helpful resources when working with Pandas and simple-salesforce\n\nGenerate list for SFDC Query \"IN\" operations from a Pandas Dataframe\n\n.. code-block:: python\n\n import pandas as pd\n\n df = pd.DataFrame([{'Id':1},{'Id':2},{'Id':3}])\n def dataframe_to_sfdc_list(df,column):\n df_list = df[column].unique()\n df_list = [str(x) for x in df_list]\n df_list = ','.join(\"'\"+item+\"'\" for item in df_list)\n return df_list\n\n sf.query(format_soql(\"SELECT Id, Email FROM Contact WHERE Id IN ({})\", dataframe_to_sfdc_list(df,column)))\n\nGenerate Pandas Dataframe from SFDC API Query (ex.query,query_all)\n\n.. code-block:: python\n\n import pandas as pd\n\n sf.query(\"SELECT Id, Email FROM Contact\")\n\n df = pd.DataFrame(data['records']).drop(['attributes'],axis=1)\n\nGenerate Pandas Dataframe from SFDC API Query (ex.query,query_all) and append related fields from query to data frame\n\n.. code-block:: python\n\n import pandas as pd\n\n def sf_api_query(data):\n df = pd.DataFrame(data['records']).drop('attributes', axis=1)\n listColumns = list(df.columns)\n for col in listColumns:\n if any (isinstance (df[col].values[i], dict) for i in range(0, len(df[col].values))):\n df = pd.concat([df.drop(columns=[col]),df[col].apply(pd.Series,dtype=df[col].dtype).drop('attributes',axis=1).add_prefix(col+'.')],axis=1)\n new_columns = np.setdiff1d(df.columns, listColumns)\n for i in new_columns:\n listColumns.append(i)\n return df\n\n df = sf_api_query(sf.query(\"SELECT Id, Email,ParentAccount.Name FROM Contact\"))\n\nGenerate Pandas Dataframe from SFDC Bulk API Query (ex.bulk.Account.query)\n\n.. code-block:: python\n\n import pandas as pd\n\n sf.bulk.Account.query(\"SELECT Id, Email FROM Contact\")\n df = pd.DataFrame.from_dict(data,orient='columns').drop('attributes',axis=1)\n\n\nYouTube Tutorial\n--------------------------\nHere is a helpful `YouTube tutorial`_ which shows how you can manage records in bulk using a jupyter notebook, simple-salesforce and pandas.\n\nThis can be a effective way to manage records, and perform simple operations like reassigning accounts, deleting test records, inserting new records, etc...\n\n.. _YouTube tutorial: https://youtu.be/nPQFUgsk6Oo?t=282\n\nAuthors & License\n--------------------------\n\nThis package is released under an open source Apache 2.0 license. Simple-Salesforce was originally written by `Nick Catalano`_ but most newer features and bugfixes come from `community contributors`_. Pull requests submitted to the `GitHub Repo`_ are highly encouraged!\n\nAuthentication mechanisms were adapted from Dave Wingate's `RestForce`_ and licensed under a MIT license\n\nThe latest build status can be found at `Travis CI`_\n\n.. _Nick Catalano: https://github.com/nickcatal\n.. _community contributors: https://github.com/simple-salesforce/simple-salesforce/graphs/contributors\n.. _RestForce: http://pypi.python.org/pypi/RestForce/\n.. _GitHub Repo: https://github.com/simple-salesforce/simple-salesforce\n.. _Travis CI: https://travis-ci.com/simple-salesforce/simple-salesforce\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A basic Salesforce.com REST API client.",
"version": "1.12.6",
"project_urls": {
"Homepage": "https://github.com/simple-salesforce/simple-salesforce"
},
"split_keywords": [
"python",
"salesforce",
"salesforce.com"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7db34c694f266760c0574159654ad1a1f7eb682584d9a3b9552ec24a38f73879",
"md5": "d18b25b3274919a3f8c0f1a79d0d6bb1",
"sha256": "66c74bee88d09ace46e4fc9c2f6b47c0d012817a764f70a5455d6dc2c7ed635c"
},
"downloads": -1,
"filename": "simple_salesforce-1.12.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d18b25b3274919a3f8c0f1a79d0d6bb1",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 132151,
"upload_time": "2024-04-15T16:20:54",
"upload_time_iso_8601": "2024-04-15T16:20:54.478535Z",
"url": "https://files.pythonhosted.org/packages/7d/b3/4c694f266760c0574159654ad1a1f7eb682584d9a3b9552ec24a38f73879/simple_salesforce-1.12.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "13a722d3992b8413cb775191a2f7af8b193cdaa9d244bf1613a2affeb26bc9f3",
"md5": "f18bb5f893bb6567d69143f9307efd05",
"sha256": "77590606c781905f6b75430562951dd2b062438da7f55fca2b61e4cde31df15b"
},
"downloads": -1,
"filename": "simple-salesforce-1.12.6.tar.gz",
"has_sig": false,
"md5_digest": "f18bb5f893bb6567d69143f9307efd05",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 140673,
"upload_time": "2024-04-15T16:20:56",
"upload_time_iso_8601": "2024-04-15T16:20:56.366605Z",
"url": "https://files.pythonhosted.org/packages/13/a7/22d3992b8413cb775191a2f7af8b193cdaa9d244bf1613a2affeb26bc9f3/simple-salesforce-1.12.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-15 16:20:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "simple-salesforce",
"github_project": "simple-salesforce",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"test_requirements": [],
"tox": true,
"lcname": "simple-salesforce"
}
JSON
