##########
Salesforce
##########

Overview
========

`Salesforce <https://www.salesforce.com>`__ 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 <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_what_is_rest_api.htm>`__
provides methods to describe objects and fields, handle records,
and submit Salesforce SOQL queries that return a Parsons :ref:`Table`.
For more information, see the `Salesforce SOQL Documentation`_.

The :class:`~parsons.salesforce.salesforce.Salesforce` class utilizes the
`Simple Salesforce <https://simple-salesforce.readthedocs.io/en/latest/>`__
client for making API calls under the hood.

.. admonition:: Authentication

   :class:`~parsons.salesforce.salesforce.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*.

Quickstart
==========

To instantiate the :class:`~parsons.salesforce.salesforce.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:

.. code-block:: python
   :caption: Pass API credentials as environmental variables

   from parsons import Salesforce
   sf = Salesforce()

.. code-block:: python
   :caption: Pass API credentials as arguments

   from parsons import Salesforce
   sf = Salesforce(username='my@email', password='my_password', security_token='123')

You can then call different endpoints:

.. code-block:: python
   :caption: Get IDs and names for all Contacts

   all_contacts = sf.query("SELECT Id, firstname, lastname FROM Contact")

.. code-block:: python
   :caption: 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'")

.. code-block:: python
   :caption: Update existing Contacts and create new records based on data in a Parsons Table

   upsert_results = sf.upsert('Contact', contacts_table, 'id')

API
====

.. autoclass:: parsons.salesforce.salesforce.Salesforce
   :inherited-members:
   :members:

.. _salesforce soql documentation: https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm