Python-SFDX-Toolkit 0.0.4

Python SFDX Toolkit

Python SFDX Toolkit

Python SFDX Toolkit is a CLI program built to execute both retrieve and deploy operations on Salesforce.

The CLI supports the usage of internal built in methods to retrieve and deploy as well as SFDX retrieve/deploy operations.

• Python SFDX Toolkit
  • Requirements
  • Usage
  • Installation
  • Features
    • Authenticate to Salesforce
    • Retrieve full metadata from Salesforce based on package.xml
    • Deploy full metadata to Salesforce based on package.xml
    • Apply 'standard' plugins
      • Standard Helpers
      • Standard Plugins
    • Build your own plugins
  • Changelog

Requirements

• Python3 at least 3.10
• SFDX at least 7.149.1

Usage

Python SFDX Toolkit is meant to be a CLI interface to perform retrieve and deploy operations on Salesforce.

Type pydx --help to see all the available commands. If you would like to have more information about a specific command, type pydx <command> --help to have all the available options.

Installation

To install pydx in your local environment, run the following command:

pip install Python-SFDX-Toolkit

Once installed, go to the root folder of a Salesforce project and type:

pydx init

which will create a pydx.json file in the root folder of your current workspace.

Features

Authenticate to Salesforce

To authenticate to Salesforce, in each command available you should includes the username -u and the password -p options:

pydx retrieve -u USERNAME -p PASSWORD

If you would like to authenticate to a Sandbox environment (with the url https://test.salesforce.com), you should add the 'sandbox' option -s:

pydx retrieve -s -u USERNAME -p PASSWORD

If you use the SFDX wrapper commands (i.e. retrieve-sfdx or deploy-sfdx) you should authenticate to Salesforce using the actual SFDX CLI and then use pydx to login using the org alias option:

pydx retrieve-sfdx -o MY_SFDX_ORG_ALIAS

Retrieve full metadata from Salesforce based on package.xml

To retrieve all the metadata you specified inside a "package.xml" file from Salesforce, the command to run is:

pydx retrieve

This command has the following options that you can use:

• -u --username: The username used to authenticate to Salesforce. REQUIRED
• -p --password: The password used to authenticate to Salesforce. REQUIRED
• --package: The path to the package.xml file, default is <CURRENT_FOLDER>/src/package.xml.
• -s --sandbox: Flag used to authenticate towards a Sandbox environment
• -o --output: Path to the output folder where to unpack the retrieved metadata, default is <CURRENT_FOLDER>/src.
• -se --settingFile: The path to the settings file, default is <CURRENT_FOLDER>/pydx.json.

Deploy full metadata to Salesforce based on package.xml

To deploy all your local metadatas specified inside the "package.xml" to Salesforce, you should run:

pydx deploy

The deploy command accepts the following options:

• -u --username: The username used to authenticate to Salesforce. REQUIRED
• -p --password: The password used to authenticate to Salesforce. REQUIRED
• --package: The path to the package.xml file, default is <CURRENT_FOLDER>/src/package.xml.
• -s --sandbox: Flag used to authenticate towards a Sandbox environment
• -se --settingFile: The path to the settings file, default is <CURRENT_FOLDER>/pydx.json.
• -t --testLevel: The test level used to permorm the deployment, chosen from:
  • RunAllTests: run all the tests available inside the org (both managed and unmanaged)
  • RunLocalTests: run your tests (only unmanaged tests)
  • RunSpecifiedTests: run a subset of specified tests (they should be specified inside the -runTests option)
  • NoTestRun: it doesn't run any tests to perform the deployment. ONLY FOR NON PRODUCTION ORG
• -r --runTests: comma separated test classes to be run when chosen the RunSpecifiedTests test level
• -v --validate: Flag used to perform only a validation (it executes all the operation needed to deploy the metadata but it doesn't persist any modification in the target org)

Apply 'standard' plugins

PYDX not only support retrieve and deploy operation, but also is useful when you would like to alter your metadata before the deployment or the retrieve.
This can be particularly useful when you would like to use this CLI in a CI/CD project to automate your deployment to Salesforce performing various tasks.

The Python SFDX Toolkit comes with a set of plugins we've seen useful in our projects, like delete some useless folder (such as resource-bundles), change the content of some metadatas (i.e. remove some Profile permission which usually breaks the deployment in sanboxes environment) etc...

This pre-implemented functions are divided into 2 main categories:

• helpers: function built to perform generic tasks to alter the metadatas. They are available in all your plugins under the helpers variable.
• plugins: callbacks used to perform specific tasks hardcoded inside the plugin itself. They are available in all your plugins importing the standard_plugin package.

Standard Helpers

Name	Description	Usage
editXML	Read an XML file and parse it as Dictionary to be modified by the callback function	helpers.editXML(path, callback)
filterMetadata	Remove the metadata (files) specified within the given path	helpers.filterMetadata(path)
editRawFile	Read a file and parse it as a simple string to be modified by the callback function	helpers.editRawFile(path, callback)
removeFolders	Remove all the folders (and their content) specified within the given path	helpers.removeFolders(path)
removeStandardLayouts	Remove all the layouts for the standard objects NOT specified in the given package	helpers.removeStandardLayouts(packageFile)

Standard Plugins

Name	Description	Usage
enableClassAccessLevel	Enable all class accesses to the profiles within the given path	helpers.editXML('profiles/*.profile', standard_plugins.enableClassAccessLevel)
deleteProfilePermissions	Remove all user permissions from the profile within the given path	helpers.editXML('profiles/*.profile', standard_plugins.deleteProfilePermissions)
removeOAuthConfig	Remove the Consumer Key from the Connected Apps within the given path	helpers.editXML('connectedApps/*.connectedApp', standard_plugins.removeOAuthConfig)
removeUselessListViews	Remove standard list views (inside Task and Event object) that usually mess up during the deployment	helpers.editXML('objects/Task.object', standard_plugins.removeUselessListViews)

Build your own plugins

With PYDX you can build your own plugins to permform specific tasks in your projects.
Your plugins can be run before each deployment or after each retrieving from Salesforce.

To specify when you to run your plugin, each PYDX needs to have a pydx.json file in the root of your project:

{
  "preDeploy": [],
  "postRetrieve": ["plugins.my_beautiful_plugin"]
}

in which you can specify the plugin you would like to run and when you want to run it.

Your plugins should be created inside the folder you will run the CLI (since the importing package is relative to the CLI current folder). For instance, if you run the CLI inside the root folder of a Salesforce project, a possible directory structure could be:

Your Salesforce Project/
├─ my_plugins/
│  ├─ __init__.py
│  ├─ my_beautiful_plugin.py
├─ src/
│  ├─ aura/
│  ├─ classes/
│  ├─ other metadatas.../
│  ├─ package.xml
└─ pydx.json

As you can see, your plugins are inside a Python package and, to let the CLI includes your own plugins, the CLI should be run inside "Your Salesforce Project" folder.

Your plugins should accept 2 parameters: context and helpers:

def enableClassAccesses(context, helpers):
  pass

• context contains useful information of the running environment (i.e. you can access all the environment variables of the host system)
• helpers contains useful functions to work with metadatas Standard Helpers

Changelog

• 0.0.4: First release with basic features
  • Deploy/Retrieve metadata logging in with username and password
  • Deploy/Retrieve metadata using the SFDX wrapper
  • Simple Plugin Engine to perform various tasks on metadatas