Salesforce¶

Overview¶

Salesforce is a cloud-based CRM (customer relationship management) tool with a huge share of the for-profit and apolitical non-profit markets. This Parsons integration with the Salesforce REST API provides methods to describe objects and fields, handle records, and submit Salesforce SOQL queries that return a Parsons Table.

The Salesforce class utilizes the Simple Salesforce client for making API calls under the hood.

Note

Authentication: Salesforce requires your Salesforce username and password, as well as a security token which can be acquired or reset by logging in to your Salesforce account and navigating to Settings > My Personal Information > Reset My Security Token.

Quick Start¶

To instantiate the Salesforce class, you can store your Salesforce username, password, and security token as environmental variables (SALESFORCE_USERNAME, SALESFORCE_PASSWORD, and SALESFORCE_SECURITY_TOKEN, respectively) or pass them in as arguments:

from parsons import Salesforce, Table

# First approach: Pass API credentials as environmental variables
sf = Salesforce()

# Second approach: Pass API credentials as arguments
sf = Salesforce(username='my@email', password='my_password', security_token='123')

You can then call different endpoints:

# Get IDs and names for all Contacts
all_contacts = sf.query("SELECT Id, firstname, lastname FROM Contact")

# Get IDs, names, and email addresses from Contacts with a specific value for a custom field
ak_contacts = sf.query("SELECT Id, firstname, lastname, email FROM Contact WHERE digital_source__c == 'AK'")

# Update existing Contacts and create new records based on data in a Parsons Table
upsert_results = sf.upsert('Contact', contacts_table, 'id')

API¶

class parsons.salesforce.salesforce.Salesforce(username=None, password=None, security_token=None, test_environment=False, consumer_key=None, consumer_secret=None, domain=None, authentication_method=None)[source]¶

Instantiate the Salesforce class

Supports the password and client_credentials authentication methods.

Parameters:

username – str The Salesforce username (usually an email address). Not required if SALESFORCE_USERNAME env variable is passed. Used in the ‘password’ auth method.
password – str The Salesforce password. Not required if SALESFORCE_PASSWORD env variable is passed. Used in the ‘password’ auth method.
security_token – str The Salesforce security token that can be acquired or reset in Settings > My Personal Information > Reset My Security Token. Not required if SALESFORCE_SECURITY_TOKEN env variable is passed. Used in the ‘password’ auth method.
test_environment – bool If True the client will connect to a Salesforce sandbox instance. Not required if SALESFORCE_DOMAIN env variable is passed.
consumer_key – str consumer key for a connected app. Used in the ‘client_credentials’ auth method.
consumer_secret – str consumer secret for a connected app. Used in the ‘client_credentials’ auth method.
domain – str url for the salesforce instance. Used in the ‘client_credentials’ auth method
authentication_method – str the method to use for authentication. defaults to “password”. Not required if SALESFORCE_AUTHENTICATION_METHOD env variable is passed.

Returns:

Salesforce class

describe_object(object)[source]¶

Parameters:: object – str The API name of the type of record to describe. Note that custom object names end in __c
Returns:: Ordered Dict of all the object’s meta data in Salesforce

describe_fields(object)[source]¶

Parameters:: object – str The API name of the type of record on whose fields you want data. Note that custom object names end in __c
Returns:: Dict of all the object’s field meta data in Salesforce

query(soql)[source]¶

Parameters:: soql – str The desired query in Salesforce SOQL language (SQL with additional limitations). For reference, see the Salesforce SOQL documentation.
Returns:: list of dicts with Salesforce data

insert_record(object, data_table)[source]¶

Insert new records of the desired object into Salesforce

Parameters:

object – str The API name of the type of record to insert. Note that custom object names end in __c
data_table – obj A Parsons Table with data for inserting records. Column names must match object field API names, though case and order need not match. Note that custom field names end in __c.

Returns:

success: boolean
created: boolean (if new record is created)
id: str (id of record created, if successful)
errors: list of dicts (with error details)

Return type:

list of dicts that have the following data

update_record(object, data_table)[source]¶

Update existing records of the desired object in Salesforce

Parameters:

object – str The API name of the type of record to update. Note that custom object names end in __c
data_table – obj A Parsons Table with data for updating records. Must contain one column named id. Column names must match object field API names, though case and order need not match. Note that custom field names end in __c.

Returns:

success: boolean
created: boolean (if new record is created)
id: str (id of record altered, if successful)
errors: list of dicts (with error details)

Return type:

list of dicts that have the following data

upsert_record(object, data_table, id_col)[source]¶

Insert new records and update existing ones of the desired object in Salesforce

Parameters:

object – str The API name of the type of record to upsert. Note that custom object names end in __c
data_table – obj A Parsons Table with data for upserting records. Column names must match object field API names, though case and order need not match. Note that custom field names end in __c.
id_col – str The column name in data_table that stores the record ID. Required even if all records are new/inserted.

Returns:

success: boolean
created: boolean (if new record is created)
id: str (id of record created or altered, if successful)
errors: list of dicts (with error details)

Return type:

list of dicts that have the following data

delete_record(object, id_table, hard_delete=False)[source]¶

Delete existing records of the desired object in Salesforce

Parameters:

object – str The API name of the type of record to delete. Note that custom object names end in __c
id_table – obj Parsons Table of record IDs to delete. Note that ‘Id’ is the default Salesforce record ID field name.
hard_delete – boolean If true, will permanently delete record instead of moving it to trash

Returns:

list[dict]: Each list has the following data: * success: boolean * created: boolean (if new record is created) * id: str (id of record deleted, if successful) * errors: list of dicts (with error details)

property client¶

Get the Salesforce client to use for making all calls. For more information, check the Simple Salesforce Documentation

Returns:: simple-salesforce Salesforce object