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(username=None, password=None, security_token=None, test_environment=False)[source]

Instantiate the Salesforce class

Args:
username: str
The Salesforce username (usually an email address). Not required if SALESFORCE_USERNAME env variable is passed.
password: str
The Salesforce password. Not required if SALESFORCE_PASSWORD env variable is passed.
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.
test_environment: bool
If True the client will connect to a Salesforce sandbox instance. Not required if SALESFORCE_DOMAIN env variable is passed.
Returns:
Salesforce class
describe_object(object)[source]
Args:
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]
Args:
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]
Args:
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

Args:
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:
list of dicts that have the following data: * success: boolean * created: boolean (if new record is created) * id: str (id of record created, if successful) * errors: list of dicts (with error details)
update_record(object, data_table)[source]

Update existing records of the desired object in Salesforce

Args:
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:
list of dicts that have the following data: * success: boolean * created: boolean (if new record is created) * id: str (id of record altered, if successful) * errors: list of dicts (with error details)
upsert_record(object, data_table, id_col)[source]

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

Args:
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:
list of dicts that have the following data: * 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)
delete_record(object, id_table, hard_delete=False)[source]

Delete existing records of the desired object in Salesforce

Args:
object: str
The API name of the type of record to delete. Note that custom object names end in __c
id_table: obj
A 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 of dicts that have 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)
client

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

Returns:
simple-salesforce Salesforce object