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)

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)

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)

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)

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)

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)

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)

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)

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)

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