Primary Modules

This section provides details around the primary modules used in the salespyforce package, which are listed below.


Init Module (salespyforce)

The Init Module is covered on this page.


Core Module (salespyforce.core)

The Core Module is covered on this page.


API Module (salespyforce.api)

This module handles basic interactions with the Salesforce API.

Module:

salespyforce.api

Synopsis:

Defines the basic functions associated with the Salesforce API

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

17 Feb 2023

salespyforce.api.api_call_with_payload(sfdc_object, 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:

  • sfdc_object – The instantiated SalesPyForce object

  • 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

salespyforce.api.get(sfdc_object, 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:

  • sfdc_object – The instantiated SalesPyForce object

  • 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

Return to Top


Chatter Module (salespyforce.chatter)

This module handles interactions with Salesforce Chatter.

Module:

salespyforce.chatter

Synopsis:

Defines the Chatter-related functions associated with the Salesforce Connect API

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

13 Mar 2023

salespyforce.chatter.get_group_feed(sfdc_object, group_id, site_id=None)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

RuntimeError

salespyforce.chatter.get_my_news_feed(sfdc_object, site_id=None)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)

Returns:

The news feed data

Raises:

RuntimeError

salespyforce.chatter.get_user_news_feed(sfdc_object, user_id, site_id=None)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

RuntimeError

salespyforce.chatter.post_comment(sfdc_object, feed_element_id, message_text=None, message_segments=None, site_id=None, created_by_id=None)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

RuntimeError

salespyforce.chatter.post_feed_item(sfdc_object, subject_id, message_text=None, message_segments=None, site_id=None, created_by_id=None)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

RuntimeError

Return to Top


Knowledge Module (salespyforce.knowledge)

This module handles interactions with Salesforce Knowledge.

Module:

salespyforce.knowledge

Synopsis:

Defines the Knowledge-related functions associated with the Salesforce API

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

01 Sep 2023

salespyforce.knowledge.assign_data_category(sfdc_object, article_id, category_group_name, category_name)[source]

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

New in version 1.2.0.

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

RuntimeError

salespyforce.knowledge.check_for_existing_article(sfdc_object, 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:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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

salespyforce.knowledge.create_article(sfdc_object, article_data, sobject=None, full_response=False)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

ValueError, TypeError, RuntimeError

salespyforce.knowledge.create_draft_from_master_version(sfdc_object, article_id=None, knowledge_article_id=None, article_data=None, sobject=None, full_response=False)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

RuntimeError

salespyforce.knowledge.create_draft_from_online_article(sfdc_object, article_id, unpublish=False)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

RuntimeError

salespyforce.knowledge.get_article_details(sfdc_object, article_id, sobject=None)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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

salespyforce.knowledge.get_article_id_from_number(sfdc_object, 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:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

ValueError

salespyforce.knowledge.get_article_metadata(sfdc_object, article_id)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • article_id (str) – The Article ID for which to retrieve details

Returns:

The article metadata as a dictionary

Raises:

RuntimeError

salespyforce.knowledge.get_article_url(sfdc_object, article_id=None, article_number=None, sobject=None)[source]

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

Changed in version 1.2.0: Changed when lightning URLs are defined and fixed an issue with extraneous slashes.

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

ValueError

salespyforce.knowledge.get_article_version(sfdc_object, article_id)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • article_id (str) – The Article ID for which to retrieve details

Returns:

The version ID for the given master article ID

Raises:

RuntimeError

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

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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

salespyforce.knowledge.get_validation_status(sfdc_object, article_id=None, article_details=None, sobject=None)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

RuntimeError

salespyforce.knowledge.publish_article(sfdc_object, article_id, major_version=True, full_response=False)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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

salespyforce.knowledge.publish_multiple_articles(sfdc_object, article_id_list, major_version=True)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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:

RuntimeError, TypeError, ValueError

salespyforce.knowledge.update_article(sfdc_object, record_id, article_data, sobject=None, include_status_code=False)[source]

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

Parameters:

  • sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object

  • 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

Return to Top