sfq 0.0.9

Python wrapper for the Salesforce's Query API.

sfq (Salesforce Query)

sfq is a lightweight Python wrapper library designed to simplify querying Salesforce, reducing repetitive code for accessing Salesforce data.

For more varied workflows, consider using an alternative like Simple Salesforce. This library was even referenced on the Salesforce Developers Blog.

Features

• Simplified query execution for Salesforce instances.
• Integration with Salesforce authentication via refresh tokens.
• Option to interact with Salesforce Tooling API for more advanced queries.

Installation

You can install the sfq library using pip:

pip install sfq

Usage

Library Querying

from sfq import SFAuth

# Initialize the SFAuth class with authentication details
sf = SFAuth(
    instance_url="https://example-dev-ed.trailblaze.my.salesforce.com",
    client_id="PlatformCLI",
    refresh_token="your-refresh-token-here"
)

# Execute a query to fetch account records
print(sf.query("SELECT Id FROM Account LIMIT 5"))

# Execute a query to fetch Tooling API data
print(sf.query("SELECT Id, FullName, Metadata FROM SandboxSettings LIMIT 5", tooling=True))

Bash Querying

You can easily incorporate this into ad-hoc bash scripts or commands:

python -c "from sfq import SFAuth; sf = SFAuth(instance_url='$instance_url', client_id='$client_id', refresh_token='$refresh_token'); print(sf.query('$query'))" | jq -r '.records[].Id'

How to Obtain Salesforce Tokens

To use the sfq library, you'll need a client ID and refresh token. The easiest way to obtain these is by using the Salesforce CLI:

Steps to Get Tokens

1. Install the Salesforce CLI:
   Follow the instructions on the Salesforce CLI installation page.

2. Authenticate with Salesforce:
   Login to your Salesforce org using the following command:

   sf org login web --alias int --instance-url https://corpa--int.sandbox.my.salesforce.com
   

3. Display Org Details:
   To get the client ID, refresh token, and instance URL, run:

   sf org display --target-org int --verbose --json
   

   The output will look like this:

   {
     "status": 0,
     "result": {
       "id": "00Daa0000000000000",
       "apiVersion": "63.0",
       "accessToken": "your-access-token-here",
       "instanceUrl": "https://example-dev-ed.trailblaze.my.salesforce.com",
       "username": "[e-mail]",
       "clientId": "PlatformCLI",
       "connectedStatus": "Connected",
       "sfdxAuthUrl": "force://PlatformCLI::your-refresh-token-here::https://example-dev-ed.trailblaze.my.salesforce.com",
       "alias": "int"
     }
   }
   

4. Extract and Use the Tokens:
   The sfdxAuthUrl is structured as:

   force://<client_id>::<refresh_token>::<instance_url>
   

   You can extract and use the tokens in a bash script like this:

   query="SELECT Id FROM User WHERE IsActive = true AND Profile.Name = 'System Administrator'"
   
   sfdxAuthUrl=$(sf org display --target-org int --verbose --json | jq -r '.result.sfdxAuthUrl' | sed 's/force:\/\///')
   clientId=$(echo "$sfdxAuthUrl" | sed 's/::/\n/g' | sed -n '1p')
   refreshToken=$(echo "$sfdxAuthUrl" | sed 's/::/\n/g' | sed -n '2p')
   instanceUrl=$(echo "$sfdxAuthUrl" | sed 's/::/\n/g' | sed -n '3p')
   
   pip install sfq && python -c "from sfq import SFAuth; sf = SFAuth(instance_url='$instanceUrl', client_id='$clientId', refresh_token='$refreshToken'); print(sf.query('$query'))" | jq -r '.records[].Id'
   

Important Considerations

• Security: Safeguard your refresh token diligently, as it provides access to your Salesforce environment. Avoid sharing or exposing it in unsecured locations.
• Efficient Data Retrieval: The query function automatically handles pagination, simplifying record retrieval across large datasets. It's recommended to use the LIMIT clause in queries to control the volume of data returned.
• Advanced Metadata Queries: Utilize the tooling=True option within the query function to access the Salesforce Tooling API. This option is designed for performing complex metadata operations, enhancing your data management capabilities.