SalesPyForce Core Object<a class="headerlink" href="#salespyforce-core-object" title="Permalink to this heading">¶

get_my_news_feed(site_id=None)[source]¶

This method retrieves the news feed for the user calling the function. (Reference)

Parameters:: site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
Returns:: The news feed data
Raises:: RuntimeError

get_user_news_feed(user_id, site_id=None)[source]¶

This method retrieves another user’s news feed. (Reference)

Parameters:

user_id (str) – The ID of the user whose feed you wish to return
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)

Returns:

The news feed data

Raises:

post_comment(feed_element_id, message_text=None, message_segments=None, site_id=None, created_by_id=None)[source]¶

This method publishes a comment on a Chatter feed item. (Reference)

Parameters:

feed_element_id (str) – The ID of the feed element on which to post the comment
message_text – Plaintext to be used as the message body
message_segments (list, None) – Collection of message segments to use instead of a plaintext message
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
created_by_id (str, None) – The ID of the user to impersonate (Experimental)

Returns:

The response of the POST request

Raises:

post_feed_item(subject_id, message_text=None, message_segments=None, site_id=None, created_by_id=None)[source]¶

This method publishes a new Chatter feed item. (Reference)

Parameters:

subject_id (str) – The Subject ID against which to publish the feed item (e.g. 0F9B000000000W2)
message_text – Plaintext to be used as the message body
message_segments (list, None) – Collection of message segments to use instead of a plaintext message
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
created_by_id (str, None) – The ID of the user to impersonate (Experimental)

Returns:

The response of the POST request

Raises:

class Knowledge(sfdc_object)[source]¶

This class includes methods associated with Salesforce Knowledge.

__init__(sfdc_object)[source]¶

This method initializes the salespyforce.core.Salesforce.Knowledge inner class object.

Parameters:: sfdc_object (class[salespyforce.Salesforce]) – The core salespyforce.Salesforce object

assign_data_category(article_id, category_group_name, category_name)[source]¶

This method assigns a single data category for a knowledge article. (Reference)

New in version 1.2.0.

Parameters:

article_id (str) – The ID of the article to update
category_group_name (str) – The unique Data Category Group Name
category_name (str) – The unique Data Category Name

Returns:

The API response from the POST request

Raises:

ValueError, TypeError

check_for_existing_article(title, sobject=None, return_id=False, return_id_and_number=False)[source]¶

This method checks to see if an article already exists with a given title and returns its article number. (Reference 1. Reference 2)

Parameters:

title (str) – The title of the knowledge article for which to check
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
return_id (bool) – Determines if the Article ID should be returned (False by default)
return_id_and_number (bool) – Determines if Article ID and Article Number should be returned (False by default)

Returns:

The Article Number, Article ID, or both, if found, or a blank string if not found

create_article(article_data, sobject=None, full_response=False)[source]¶

This method creates a new knowledge article draft. (Reference)

Parameters:

article_data (dict) – The article data used to populate the article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
full_response (bool) – Determines if the full API response should be returned instead of the article ID (False by default)

Returns:

The API response or the ID of the article draft

Raises:

create_draft_from_master_version(article_id=None, knowledge_article_id=None, article_data=None, sobject=None, full_response=False)[source]¶

This method creates an online version of a master article. (Reference)

Parameters:

article_id (str, None) – The Article ID from which to create the draft
knowledge_article_id (str, None) – The Knowledge Article ID (KnowledgeArticleId) from which to create the draft
article_data (dict, None) – The article data associated with the article from which to create the draft
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
full_response (bool) – Determines if the full API response should be returned instead of the article ID (False by default)

Returns:

The API response or the ID of the article draft

Raises:

create_draft_from_online_article(article_id, unpublish=False)[source]¶

This method creates a draft knowledge article from an online article. (Reference)

Parameters:

article_id (str) – The ID of the online article from which to create the draft
unpublish (bool) – Determines if the online article should be unpublished when the draft is created (False by default)

Returns:

The API response from the POST request

Raises:

get_article_details(article_id, sobject=None)[source]¶

This method retrieves details for a single knowledge article. (Reference)

Parameters:

article_id (str) – The Article ID for which to retrieve details
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The details for the knowledge article

get_article_id_from_number(article_number, sobject=None, return_uri=False)[source]¶

This method returns the Article ID when an article number is provided. (Reference 1, Reference 2)

Parameters:

article_number (str, int) – The Article Number to query
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
return_uri (bool) – Determines if the URI of the article should be returned rather than the ID (False by default)

Returns:

The Article ID or Article URI, or a blank string if no article is found

Raises:

get_article_metadata(article_id)[source]¶

This method retrieves metadata for a specific knowledge article. (Reference)

Parameters:: article_id (str) – The Article ID for which to retrieve details
Returns:: The article metadata as a dictionary
Raises:: RuntimeError

get_article_url(article_id=None, article_number=None, sobject=None)[source]¶

This function constructs the URL to view a knowledge article in Lightning or Classic.

Parameters:

article_id (str, None) – The Article ID for which to retrieve details
article_number (str, int, None) – The article number for which to retrieve details
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The article URL as a string

Raises:

get_article_version(article_id)[source]¶

This method retrieves the version ID for a given master article ID. (Reference)

Parameters:: article_id (str) – The Article ID for which to retrieve details
Returns:: The version ID for the given master article ID
Raises:: RuntimeError

get_articles_list(query=None, sort=None, order=None, page_size=20, page_num=1)[source]¶

This method retrieves a list of knowledge articles. (Reference)

Parameters:

query (str, None) – A SOQL query with which to filter the results (optional)
sort (str, None) – One of the following optional values: LastPublishedDate, CreatedDate, Title, or ViewScore
order (str, None) – Optionally define the ORDER BY as ASC or DESC
page_size (int) – The number of results per page (20 by default)
page_num (int) – The starting page number (1 by default)

Returns:

The list of retrieved knowledge articles

get_validation_status(article_id=None, article_details=None, sobject=None)[source]¶

This method retrieves the Validation Status for a given Article ID. (Reference)

Parameters:

article_id (str, None) – The Article ID for which to retrieve details
article_details (dict, None) – The dictionary of article details for the given article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The validation status as a text string

Raises:

publish_article(article_id, major_version=True, full_response=False)[source]¶

This method publishes a draft knowledge article as a major or minor version. (Reference)

Parameters:

article_id (str) – The Article ID to publish
major_version (bool) – Determines if the published article should be a major version (True by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value indicating the success of the action or the API response from the PATCH request

Raises:

RuntimeError, TypeError, ValueError

publish_multiple_articles(article_id_list, major_version=True)[source]¶

This method publishes multiple knowledge article drafts at one time. (Reference)

Parameters:

article_id_list (list) – A list of Article IDs to be published
major_version (bool) – Determines if the published article should be a major version (True by default)

Returns:

The API response from the POST request

Raises:

update_article(record_id, article_data, sobject=None, include_status_code=False)[source]¶

This method updates an existing knowledge article draft. (Reference)

Parameters:

record_id (str) – The ID of the article draft record to be updated
article_data (dict) – The article data used to update the article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
include_status_code (bool) – Determines if the API response status code should be returned (False by default)

Returns:

A Boolean indicating if the update operation was successful, and optionally the API response status code

Raises:

ValueError, TypeError, RuntimeError

__init__(connection_info=None, version='58.0', base_url=None, org_id=None, username=None, password=None, endpoint_url=None, client_id=None, client_secret=None, security_token=None, helper=None)[source]¶

This method instantiates the core Salesforce object.

Parameters:

connection_info (dict, None) – The information for connecting to the Salesforce instance
version (str) – The Salesforce API version to utilize (Default: 57.0)
base_url (str, None) – The base URL of the Salesforce instance
org_id (str, None) – The Org ID of the Salesforce instance
username (str, None) – The username of the API user
password (str, None) – The password of the API user
endpoint_url (str, None) – The endpoint URL for the Salesforce instance
client_id (str, None) – The Client ID for the Salesforce instance
client_secret (str, None) – The Client Secret for the Salesforce instance
security_token (str, None) – The Security Token for the Salesforce instance
helper (str, None) – The file path of a helper file

Returns:

The instantiated object

Raises:

TypeError

api_call_with_payload(method, endpoint, payload, params=None, headers=None, timeout=30, show_full_error=True, return_json=True)[source]¶

This method performs a POST call against the Salesforce instance. (Reference)

Parameters:

method (str) – The API method (post, put, or patch)
endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, str, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

connect()[source]¶

This method connects to the Salesforce instance to obtain the access token. (Reference)

Returns:: The API call response with the authorization information

create_sobject_record(sobject, payload)[source]¶

This method creates a new record for a specific sObject. (Reference)

Parameters:

sobject (str) – The sObject under which to create the new record
payload (dict) – The JSON payload with the record details

Returns:

The API response from the POST request

Raises:

describe_object(object_name)[source]¶

This method returns the full (describe) information for a specific sObject. (Reference)

Parameters:: object_name (str) – The name of the Salesforce object
Returns:: The Salesforce object data

download_image(image_url, record_id, field_name, file_path=None, sobject=None)[source]¶

This method downloads an image using the sObject Rich Text Image Retrieve functionality. (Reference 1, Reference 2)

Parameters:

image_url (str) – The URL for the image to be downloaded
record_id (str) – The Record ID where the image is found
field_name (str) – The field name within the record where the image is found
file_path (str, None) – The path to the directory where the image should be saved (current directory if not defined)
sobject (str) – The sObject for the record where the image is found (Knowledge__kav by default)

Returns:

The full path to the downloaded image

Raises:

get(endpoint, params=None, headers=None, timeout=30, show_full_error=True, return_json=True)[source]¶

This method performs a GET request against the Salesforce instance. (Reference)

Parameters:

endpoint (str) – The API endpoint to query
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, str, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

get_all_sobjects()[source]¶: This method returns a list of all Salesforce objects. (i.e. sObjects) (Reference)

get_api_versions()[source]¶: This method returns the API versions for the Salesforce releases. (Reference)

get_org_limits()[source]¶: This method returns a list of all org limits.

New in version 1.1.0.

get_rest_resources()[source]¶: This method returns a list of all available REST resources. (Reference)

get_sobject(object_name, describe=False)[source]¶

This method returns basic information or the full (describe) information for a specific sObject. (Reference 1, Reference 2)

Parameters:

object_name (str) – The name of the Salesforce object
describe (bool) – Determines if the full (i.e. describe) data should be returned (defaults to False)

Returns:

The Salesforce object data

patch(endpoint, payload, params=None, headers=None, timeout=30, show_full_error=True, return_json=False)[source]¶

This method performs a PATCH call against the Salesforce instance. (Reference)

Parameters:

endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, str, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

post(endpoint, payload, params=None, headers=None, timeout=30, show_full_error=True, return_json=True)[source]¶

This method performs a POST call against the Salesforce instance. (Reference)

Parameters:

endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, str, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

put(endpoint, payload, params=None, headers=None, timeout=30, show_full_error=True, return_json=True)[source]¶

This method performs a PUT call against the Salesforce instance. (Reference)

Parameters:

endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, str, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

search_string(string_to_search)[source]¶

This method performs a SOSL query to search for a given string. (Reference)

New in version 1.1.0.

Parameters:: string_to_search (str) – The string for which to search
Returns:: The SOSL response data in JSON format

soql_query(query, replace_quotes=True)[source]¶

This method performs a SOQL query and returns the results in JSON format. (Reference 1, Reference 2)

Parameters:

query (str) – The SOQL query to perform
replace_quotes (bool) – Determines if double-quotes should be replaced with single-quotes (True by default)

Returns:

The result of the SOQL query

update_sobject_record(sobject, record_id, payload)[source]¶

This method updates an existing sObject record. (Reference)

Parameters:

sobject (str) – The sObject under which to update the record
record_id (str) – The ID of the record to be updated
payload (dict) – The JSON payload with the record details to be updated

Returns:

The API response from the PATCH request

Raises:

Core Module (salespyforce.core)¶

This module contains the core object and functions to establish the connection to the API and leverage it to perform various actions.

Module:: salespyforce.core
Synopsis:: This module performs the core Salesforce-related operations
Usage:: from salespyforce import Salesforce
Example:: sfdc = Salesforce()
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 01 Sep 2023

class salespyforce.core.Salesforce(connection_info=None, version='58.0', base_url=None, org_id=None, username=None, password=None, endpoint_url=None, client_id=None, client_secret=None, security_token=None, helper=None)[source]¶

This is the class for the core object leveraged in this module.

class Chatter(sfdc_object)[source]¶

This class includes methods associated with Salesforce Chatter.

__init__(sfdc_object)[source]¶

This method initializes the salespyforce.core.Salesforce.Chatter inner class object.

Parameters:: sfdc_object (class[salespyforce.Salesforce]) – The core salespyforce.Salesforce object

get_group_feed(group_id, site_id=None)[source]¶

This method retrieves a group’s news feed. (Reference)

Parameters:

group_id (str) – The ID of the group whose feed you wish to return
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)

Returns:

The news feed data

Raises:

get_my_news_feed(site_id=None)[source]¶

This method retrieves the news feed for the user calling the function. (Reference)

Parameters:: site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
Returns:: The news feed data
Raises:: RuntimeError

get_user_news_feed(user_id, site_id=None)[source]¶

This method retrieves another user’s news feed. (Reference)

Parameters:

user_id (str) – The ID of the user whose feed you wish to return
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)

Returns:

The news feed data

Raises:

post_comment(feed_element_id, message_text=None, message_segments=None, site_id=None, created_by_id=None)[source]¶

This method publishes a comment on a Chatter feed item. (Reference)

Parameters:

feed_element_id (str) – The ID of the feed element on which to post the comment
message_text – Plaintext to be used as the message body
message_segments (list, None) – Collection of message segments to use instead of a plaintext message
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
created_by_id (str, None) – The ID of the user to impersonate (Experimental)

Returns:

The response of the POST request

Raises:

post_feed_item(subject_id, message_text=None, message_segments=None, site_id=None, created_by_id=None)[source]¶

This method publishes a new Chatter feed item. (Reference)

Parameters:

subject_id (str) – The Subject ID against which to publish the feed item (e.g. 0F9B000000000W2)
message_text – Plaintext to be used as the message body
message_segments (list, None) – Collection of message segments to use instead of a plaintext message
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
created_by_id (str, None) – The ID of the user to impersonate (Experimental)

Returns:

The response of the POST request

Raises:

class Knowledge(sfdc_object)[source]¶

This class includes methods associated with Salesforce Knowledge.

__init__(sfdc_object)[source]¶

This method initializes the salespyforce.core.Salesforce.Knowledge inner class object.

Parameters:: sfdc_object (class[salespyforce.Salesforce]) – The core salespyforce.Salesforce object

assign_data_category(article_id, category_group_name, category_name)[source]¶

This method assigns a single data category for a knowledge article. (Reference)

New in version 1.2.0.

Parameters:

article_id (str) – The ID of the article to update
category_group_name (str) – The unique Data Category Group Name
category_name (str) – The unique Data Category Name

Returns:

The API response from the POST request

Raises:

ValueError, TypeError

check_for_existing_article(title, sobject=None, return_id=False, return_id_and_number=False)[source]¶

This method checks to see if an article already exists with a given title and returns its article number. (Reference 1. Reference 2)

Parameters:

title (str) – The title of the knowledge article for which to check
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
return_id (bool) – Determines if the Article ID should be returned (False by default)
return_id_and_number (bool) – Determines if Article ID and Article Number should be returned (False by default)

Returns:

The Article Number, Article ID, or both, if found, or a blank string if not found

create_article(article_data, sobject=None, full_response=False)[source]¶

This method creates a new knowledge article draft. (Reference)

Parameters:

article_data (dict) – The article data used to populate the article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
full_response (bool) – Determines if the full API response should be returned instead of the article ID (False by default)

Returns:

The API response or the ID of the article draft

Raises:

create_draft_from_master_version(article_id=None, knowledge_article_id=None, article_data=None, sobject=None, full_response=False)[source]¶

This method creates an online version of a master article. (Reference)

Parameters:

article_id (str, None) – The Article ID from which to create the draft
knowledge_article_id (str, None) – The Knowledge Article ID (KnowledgeArticleId) from which to create the draft
article_data (dict, None) – The article data associated with the article from which to create the draft
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
full_response (bool) – Determines if the full API response should be returned instead of the article ID (False by default)

Returns:

The API response or the ID of the article draft

Raises:

create_draft_from_online_article(article_id, unpublish=False)[source]¶

This method creates a draft knowledge article from an online article. (Reference)

Parameters:

article_id (str) – The ID of the online article from which to create the draft
unpublish (bool) – Determines if the online article should be unpublished when the draft is created (False by default)

Returns:

The API response from the POST request

Raises:

get_article_details(article_id, sobject=None)[source]¶

This method retrieves details for a single knowledge article. (Reference)

Parameters:

article_id (str) – The Article ID for which to retrieve details
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The details for the knowledge article

get_article_id_from_number(article_number, sobject=None, return_uri=False)[source]¶

This method returns the Article ID when an article number is provided. (Reference 1, Reference 2)

Parameters:

article_number (str, int) – The Article Number to query
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
return_uri (bool) – Determines if the URI of the article should be returned rather than the ID (False by default)

Returns:

The Article ID or Article URI, or a blank string if no article is found

Raises:

get_article_metadata(article_id)[source]¶

This method retrieves metadata for a specific knowledge article. (Reference)

Parameters:: article_id (str) – The Article ID for which to retrieve details
Returns:: The article metadata as a dictionary
Raises:: RuntimeError

get_article_url(article_id=None, article_number=None, sobject=None)[source]¶

This function constructs the URL to view a knowledge article in Lightning or Classic.

Parameters:

article_id (str, None) – The Article ID for which to retrieve details
article_number (str, int, None) – The article number for which to retrieve details
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The article URL as a string

Raises:

get_article_version(article_id)[source]¶

This method retrieves the version ID for a given master article ID. (Reference)

Parameters:: article_id (str) – The Article ID for which to retrieve details
Returns:: The version ID for the given master article ID
Raises:: RuntimeError

get_articles_list(query=None, sort=None, order=None, page_size=20, page_num=1)[source]¶

This method retrieves a list of knowledge articles. (Reference)

Parameters:

query (str, None) – A SOQL query with which to filter the results (optional)
sort (str, None) – One of the following optional values: LastPublishedDate, CreatedDate, Title, or ViewScore
order (str, None) – Optionally define the ORDER BY as ASC or DESC
page_size (int) – The number of results per page (20 by default)
page_num (int) – The starting page number (1 by default)

Returns:

The list of retrieved knowledge articles

get_validation_status(article_id=None, article_details=None, sobject=None)[source]¶

This method retrieves the Validation Status for a given Article ID. (Reference)

Parameters:

article_id (str, None) – The Article ID for which to retrieve details
article_details (dict, None) – The dictionary of article details for the given article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The validation status as a text string

Raises:

publish_article(article_id, major_version=True, full_response=False)[source]¶

This method publishes a draft knowledge article as a major or minor version. (Reference)

Parameters:

article_id (str) – The Article ID to publish
major_version (bool) – Determines if the published article should be a major version (True by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value indicating the success of the action or the API response from the PATCH request

Raises:

RuntimeError, TypeError, ValueError

publish_multiple_articles(article_id_list, major_version=True)[source]¶

This method publishes multiple knowledge article drafts at one time. (Reference)

Parameters:

article_id_list (list) – A list of Article IDs to be published
major_version (bool) – Determines if the published article should be a major version (True by default)

Returns:

The API response from the POST request

Raises:

update_article(record_id, article_data, sobject=None, include_status_code=False)[source]¶

This method updates an existing knowledge article draft. (Reference)

Parameters:

record_id (str) – The ID of the article draft record to be updated
article_data (dict) – The article data used to update the article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
include_status_code (bool) – Determines if the API response status code should be returned (False by default)

Returns:

A Boolean indicating if the update operation was successful, and optionally the API response status code

Raises:

ValueError, TypeError, RuntimeError

__init__(connection_info=None, version='58.0', base_url=None, org_id=None, username=None, password=None, endpoint_url=None, client_id=None, client_secret=None, security_token=None, helper=None)[source]¶

This method instantiates the core Salesforce object.

Parameters:

connection_info (dict, None) – The information for connecting to the Salesforce instance
version (str) – The Salesforce API version to utilize (Default: 57.0)
base_url (str, None) – The base URL of the Salesforce instance
org_id (str, None) – The Org ID of the Salesforce instance
username (str, None) – The username of the API user
password (str, None) – The password of the API user
endpoint_url (str, None) – The endpoint URL for the Salesforce instance
client_id (str, None) – The Client ID for the Salesforce instance
client_secret (str, None) – The Client Secret for the Salesforce instance
security_token (str, None) – The Security Token for the Salesforce instance
helper (str, None) – The file path of a helper file

Returns:

The instantiated object

Raises:

TypeError

api_call_with_payload(method, endpoint, payload, params=None, headers=None, timeout=30, show_full_error=True, return_json=True)[source]¶

This method performs a POST call against the Salesforce instance. (Reference)

Parameters:

method (str) – The API method (post, put, or patch)
endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, str, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

connect()[source]¶

This method connects to the Salesforce instance to obtain the access token. (Reference)

Returns:: The API call response with the authorization information

create_sobject_record(sobject, payload)[source]¶

This method creates a new record for a specific sObject. (Reference)

Parameters:

sobject (str) – The sObject under which to create the new record
payload (dict) – The JSON payload with the record details

Returns:

The API response from the POST request

Raises:

describe_object(object_name)[source]¶

This method returns the full (describe) information for a specific sObject. (Reference)

Parameters:: object_name (str) – The name of the Salesforce object
Returns:: The Salesforce object data

download_image(image_url, record_id, field_name, file_path=None, sobject=None)[source]¶

This method downloads an image using the sObject Rich Text Image Retrieve functionality. (Reference 1, Reference 2)

Parameters:

image_url (str) – The URL for the image to be downloaded
record_id (str) – The Record ID where the image is found
field_name (str) – The field name within the record where the image is found
file_path (str, None) – The path to the directory where the image should be saved (current directory if not defined)
sobject (str) – The sObject for the record where the image is found (Knowledge__kav by default)

Returns:

The full path to the downloaded image

Raises:

get(endpoint, params=None, headers=None, timeout=30, show_full_error=True, return_json=True)[source]¶

This method performs a GET request against the Salesforce instance. (Reference)

Parameters:

endpoint (str) – The API endpoint to query
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, str, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

get_all_sobjects()[source]¶: This method returns a list of all Salesforce objects. (i.e. sObjects) (Reference)

get_api_versions()[source]¶: This method returns the API versions for the Salesforce releases. (Reference)

get_org_limits()[source]¶: This method returns a list of all org limits.

New in version 1.1.0.

get_rest_resources()[source]¶: This method returns a list of all available REST resources. (Reference)

get_sobject(object_name, describe=False)[source]¶

This method returns basic information or the full (describe) information for a specific sObject. (Reference 1, Reference 2)

Parameters:

object_name (str) – The name of the Salesforce object
describe (bool) – Determines if the full (i.e. describe) data should be returned (defaults to False)

Returns:

The Salesforce object data

patch(endpoint, payload, params=None, headers=None, timeout=30, show_full_error=True, return_json=False)[source]¶

This method performs a PATCH call against the Salesforce instance. (Reference)

Parameters:

endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, str, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

post(endpoint, payload, params=None, headers=None, timeout=30, show_full_error=True, return_json=True)[source]¶

This method performs a POST call against the Salesforce instance. (Reference)

Parameters:

endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, str, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

put(endpoint, payload, params=None, headers=None, timeout=30, show_full_error=True, return_json=True)[source]¶

This method performs a PUT call against the Salesforce instance. (Reference)

Parameters:

endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, str, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

search_string(string_to_search)[source]¶

This method performs a SOSL query to search for a given string. (Reference)

New in version 1.1.0.

Parameters:: string_to_search (str) – The string for which to search
Returns:: The SOSL response data in JSON format

soql_query(query, replace_quotes=True)[source]¶

This method performs a SOQL query and returns the results in JSON format. (Reference 1, Reference 2)

Parameters:

query (str) – The SOQL query to perform
replace_quotes (bool) – Determines if double-quotes should be replaced with single-quotes (True by default)

Returns:

The result of the SOQL query

update_sobject_record(sobject, record_id, payload)[source]¶

This method updates an existing sObject record. (Reference)

Parameters:

sobject (str) – The sObject under which to update the record
record_id (str) – The ID of the record to be updated
payload (dict) – The JSON payload with the record details to be updated

Returns:

The API response from the PATCH request

Raises:

salespyforce.core.compile_connection_info(base_url, org_id, username, password, endpoint_url, client_id, client_secret, security_token)[source]¶

This function compiles the connection info into a dictionary that can be consumed by the core object.

Parameters:

base_url (str) – The base URL of the Salesforce instance
org_id (str) – The Org ID of the Salesforce instance
username (str) – The username of the API user
password (str) – The password of the API user
endpoint_url (str) – The endpoint URL for the Salesforce instance
client_id (str) – The Client ID for the Salesforce instance
client_secret (str) – The Client Secret for the Salesforce instance
security_token (str) – The Security Token for the Salesforce instance

Returns:

The connection info in a dictionary

salespyforce.core.define_connection_info()[source]¶

This function prompts the user for the connection information.

Returns:: The connection info in a dictionary

Core Functionality Subclasses (salespyforce.core.Salesforce)¶

These classes below are inner/nested classes within the core salespyforce.core.Salesforce class.

Note

The classes themselves are PascalCase format and singular (e.g. Knowledge, etc.) whereas the names used to call the inner class methods are all lowercase (or snake_case) and plural. (e.g. core_object.knowledge.check_for_existing_article(), etc.)

Chatter Subclass (salespyforce.core.Salesforce.Chatter)¶

class Salesforce.Chatter(sfdc_object)[source]

This class includes methods associated with Salesforce Chatter.

get_group_feed(group_id, site_id=None)[source]

This method retrieves a group’s news feed. (Reference)

Parameters:

group_id (str) – The ID of the group whose feed you wish to return
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)

Returns:

The news feed data

Raises:

get_my_news_feed(site_id=None)[source]

This method retrieves the news feed for the user calling the function. (Reference)

Parameters:: site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
Returns:: The news feed data
Raises:: RuntimeError

get_user_news_feed(user_id, site_id=None)[source]

This method retrieves another user’s news feed. (Reference)

Parameters:

user_id (str) – The ID of the user whose feed you wish to return
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)

Returns:

The news feed data

Raises:

post_comment(feed_element_id, message_text=None, message_segments=None, site_id=None, created_by_id=None)[source]

This method publishes a comment on a Chatter feed item. (Reference)

Parameters:

feed_element_id (str) – The ID of the feed element on which to post the comment
message_text – Plaintext to be used as the message body
message_segments (list, None) – Collection of message segments to use instead of a plaintext message
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
created_by_id (str, None) – The ID of the user to impersonate (Experimental)

Returns:

The response of the POST request

Raises:

post_feed_item(subject_id, message_text=None, message_segments=None, site_id=None, created_by_id=None)[source]

This method publishes a new Chatter feed item. (Reference)

Parameters:

subject_id (str) – The Subject ID against which to publish the feed item (e.g. 0F9B000000000W2)
message_text – Plaintext to be used as the message body
message_segments (list, None) – Collection of message segments to use instead of a plaintext message
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
created_by_id (str, None) – The ID of the user to impersonate (Experimental)

Returns:

The response of the POST request

Raises:

Knowledge Subclass (salespyforce.core.Salesforce.Knowledge)¶

class Salesforce.Knowledge(sfdc_object)[source]

This class includes methods associated with Salesforce Knowledge.

assign_data_category(article_id, category_group_name, category_name)[source]

This method assigns a single data category for a knowledge article. (Reference)

New in version 1.2.0.

Parameters:

article_id (str) – The ID of the article to update
category_group_name (str) – The unique Data Category Group Name
category_name (str) – The unique Data Category Name

Returns:

The API response from the POST request

Raises:

ValueError, TypeError

check_for_existing_article(title, sobject=None, return_id=False, return_id_and_number=False)[source]

This method checks to see if an article already exists with a given title and returns its article number. (Reference 1. Reference 2)

Parameters:

title (str) – The title of the knowledge article for which to check
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
return_id (bool) – Determines if the Article ID should be returned (False by default)
return_id_and_number (bool) – Determines if Article ID and Article Number should be returned (False by default)

Returns:

The Article Number, Article ID, or both, if found, or a blank string if not found

create_article(article_data, sobject=None, full_response=False)[source]

This method creates a new knowledge article draft. (Reference)

Parameters:

article_data (dict) – The article data used to populate the article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
full_response (bool) – Determines if the full API response should be returned instead of the article ID (False by default)

Returns:

The API response or the ID of the article draft

Raises:

create_draft_from_master_version(article_id=None, knowledge_article_id=None, article_data=None, sobject=None, full_response=False)[source]

This method creates an online version of a master article. (Reference)

Parameters:

article_id (str, None) – The Article ID from which to create the draft
knowledge_article_id (str, None) – The Knowledge Article ID (KnowledgeArticleId) from which to create the draft
article_data (dict, None) – The article data associated with the article from which to create the draft
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
full_response (bool) – Determines if the full API response should be returned instead of the article ID (False by default)

Returns:

The API response or the ID of the article draft

Raises:

create_draft_from_online_article(article_id, unpublish=False)[source]

This method creates a draft knowledge article from an online article. (Reference)

Parameters:

article_id (str) – The ID of the online article from which to create the draft
unpublish (bool) – Determines if the online article should be unpublished when the draft is created (False by default)

Returns:

The API response from the POST request

Raises:

get_article_details(article_id, sobject=None)[source]

This method retrieves details for a single knowledge article. (Reference)

Parameters:

article_id (str) – The Article ID for which to retrieve details
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The details for the knowledge article

get_article_id_from_number(article_number, sobject=None, return_uri=False)[source]

This method returns the Article ID when an article number is provided. (Reference 1, Reference 2)

Parameters:

article_number (str, int) – The Article Number to query
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
return_uri (bool) – Determines if the URI of the article should be returned rather than the ID (False by default)

Returns:

The Article ID or Article URI, or a blank string if no article is found

Raises:

get_article_metadata(article_id)[source]

This method retrieves metadata for a specific knowledge article. (Reference)

Parameters:: article_id (str) – The Article ID for which to retrieve details
Returns:: The article metadata as a dictionary
Raises:: RuntimeError

get_article_url(article_id=None, article_number=None, sobject=None)[source]

This function constructs the URL to view a knowledge article in Lightning or Classic.

Parameters:

article_id (str, None) – The Article ID for which to retrieve details
article_number (str, int, None) – The article number for which to retrieve details
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The article URL as a string

Raises:

get_article_version(article_id)[source]

This method retrieves the version ID for a given master article ID. (Reference)

Parameters:: article_id (str) – The Article ID for which to retrieve details
Returns:: The version ID for the given master article ID
Raises:: RuntimeError

get_articles_list(query=None, sort=None, order=None, page_size=20, page_num=1)[source]

This method retrieves a list of knowledge articles. (Reference)

Parameters:

query (str, None) – A SOQL query with which to filter the results (optional)
sort (str, None) – One of the following optional values: LastPublishedDate, CreatedDate, Title, or ViewScore
order (str, None) – Optionally define the ORDER BY as ASC or DESC
page_size (int) – The number of results per page (20 by default)
page_num (int) – The starting page number (1 by default)

Returns:

The list of retrieved knowledge articles

get_validation_status(article_id=None, article_details=None, sobject=None)[source]

This method retrieves the Validation Status for a given Article ID. (Reference)

Parameters:

article_id (str, None) – The Article ID for which to retrieve details
article_details (dict, None) – The dictionary of article details for the given article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The validation status as a text string

Raises:

publish_article(article_id, major_version=True, full_response=False)[source]

This method publishes a draft knowledge article as a major or minor version. (Reference)

Parameters:

article_id (str) – The Article ID to publish
major_version (bool) – Determines if the published article should be a major version (True by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value indicating the success of the action or the API response from the PATCH request

Raises:

RuntimeError, TypeError, ValueError

publish_multiple_articles(article_id_list, major_version=True)[source]

This method publishes multiple knowledge article drafts at one time. (Reference)

Parameters:

article_id_list (list) – A list of Article IDs to be published
major_version (bool) – Determines if the published article should be a major version (True by default)

Returns:

The API response from the POST request

Raises:

update_article(record_id, article_data, sobject=None, include_status_code=False)[source]

This method updates an existing knowledge article draft. (Reference)

Parameters:

record_id (str) – The ID of the article draft record to be updated
article_data (dict) – The article data used to update the article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
include_status_code (bool) – Determines if the API response status code should be returned (False by default)

Returns:

A Boolean indicating if the update operation was successful, and optionally the API response status code

Raises:

ValueError, TypeError, RuntimeError