Depending on your edition, please select the guide from the below link

The following list of software is the minimum to get started using sfp. Our assumption is that you are familiar with the Salesforce CLI and are comfortable using VS Code. To keep the material simple, we will be assuming you already have access to a Salesforce Sandbox that you can build and install artifacts.

Salesforce

• Salesforce Org with sfpowerscripts-artifact Unlocked Package installed.

Workstation

sfp provides various features to alter the installation behaviour of a package. These behaviours have to be applied as an additional property of a package during build time. The following section details each of the parameters that is available.

sfp is a purpose-built CLI tool for modular Salesforce development and release management. sfp streamlines and automates the build, test, and deployment processes of Salesforce metadata, code, and data. It extends sf cli functionalities, focusing on artifact-driven development to support #flxbl Salesforce project development.

sfp is available in two editions:

• sfp (Community Edition): Open-source CLI with core build, deploy, and orchestration capabilities

• sfp-pro: Enterprise edition with additional features including a centralized server, environment management, authentication services, and team collaboration tools

Key Aspects of sfp:

• Built with codified process: sfp is derived from extensive experience in modular Salesforce implementations. By embracing the #FLXBL framework, it streamlines the process of creating a well-architected, composable Salesforce Org, eliminating time-consuming efforts usually spent on re-inventing fundamental processes.

• Artifact-Centric Approach: sfp packages Salesforce code and metadata into artifacts with deployment details, ensuring consistent deployments and simplified version management across environments.

• Best-in-Class Mono Repo Support: Offers robust support for mono repositories, facilitating streamlined development, integration, and collaboration.

Commands

sfp incorporates a suite of commands to aid in your end-to-end development cycle for Salesforce. Starting with the core commands, you can perform basic workflows to build and deploy artifacts across environments through the command line. As you get comfortable with the core commands, you can utilize more advanced commands and flags in your CI/CD platform to drive a complete release process, leveraging release definitions, changelogs, metrics, and more.

sfp is constantly evolving and driven by the passionate community that has embraced our work methods. Over the years, we have introduced utility commands to solve pain points specific to the Salesforce Platform. The commands have been successfully tested and used on large-scale enterprise implementations.

Below is a high-level snapshot of the main command categories in sfp.

sfp docker images are published from the flxbl-io Github packages registry at the link provided below

One can utilize the flxbl-io sfp images by using the

docker pull ghcr.io/flxbl-io/sfp:latest

You can also pin to a specific version of the docker image, by using the version published here To preview latest images for the docker image, visit the release candidate page and update your container image reference. For example:

default:
   image: ghcr.io/flxbl-io/sfp-rc:<version-number>

or
   image: ghcr.io/flxbl-io/sfp-rc:<sha>

sfp is a natural fit for organisations that utilize Salesforce in a large enterprise setting as its purpose built to deal with modular saleforce development. Often these organisations have teams dedicated to a particular business function, think of a team who works on features related to billing, while a team works on features related to service\

The diagram illustrates the method of organizing packages into specific categories for various business units. These categories are referred to as 'domains' within the context of sfp cli. Each domain can either contain further domains ( sub-domains) and each domain constitute of one or more packages.

sfp cli utilizes 'Release Config' to organise packages into domains. You can read more about creating a release config in the next section

Packages are containers used to group related metadata together. A package would contain components such as objects, fields, apex, flows and more allowing these elements to be easily installed, upgraded and managed as a single unit Packages in the context of sfp are not limited to second generation packaging (2GP), sfp supports various types of packages which you can read in the following sections

Salesforce CLI

The Salesforce CLI is a command-line interface that simplifies development and build automation when working with your Salesforce org. There are numerous of commands that the sf cli provides natively that is beyond the scope of this site and can be found on the official Salesforce Documentation Site.

From a build, test, and deployment perspective, the following diagram depicts the bare minimum commands necessary to get up and running in setting up your sf project, retrieving and deploying code to the target environments.

An artifact is a key concept within sfp. An artifact is a point in time snapshot of a version of a package, as mentioned in sfdx-project.json . The snapshot contains source code of a package directory , additional metadata information regarding the particular version, changelog and other details. An artifact for 2GP package would also contain details such as

Artifacts provide an abstraction over version control, as it detaches the version control from from the point of releasing into a salesforce org. Almost all commands in sfp operates on an artifact or generates an artifact. \

In the context of sfp, an artifact represents a more enhanced concept compared to a Salesforce package. While it is based on a Salesforce package or specific package types introduce by sfp, an artifact in sfp includes additional attributes and metadata that describe the package version, dependencies, installation behavior, and other context-specific information relevant to the CI/CD process. Artifacts in sfp are designed to be more than just a bundle of code and metadata; they encapsulate the package along with its CI/CD lifecycle information, making them more aligned with DevOps practices. sfp's artifacts are built to be compatible for npm package supported registries , most CI/CD providers provide a npm compatible registry to host these packages/artifacts. Here is the link to operate on Github Package Manager for instance (

All the attributes that are configured additionally to a package in your project is recorded within the artifact. When the artifact is being installed to the target org, the following steps are undertaken in sequence as seen in the below diagram. Each of the configured attributes below to one of the category in the sequence and executed

sfp cli features an intiutive command to build artifacts of all your packages in your project directory. The 'build' command automatically detects the type of package and builds an artifact individually for each package

By default, the behaviour of sfp's build command is to build a new version of all packages in your project directory and and creates it associated artifact.

sfp's build command is also equipped with an ability to selectively build only packages that are changed. Read more on how sfp determines a package to be built on the subsequent sections.

sfp provides mechanisms to control the aspects of the build command, the following section details how one can configure these mechanisms in your sfdx-project.json

An artifact can be build individually for a package, sfp will determine the and the corresponding api's will be invoked

In Salesforce, a package is a container that groups together metadata and code in order to facilitate the deployment and distribution of customizations and apps. Salesforce supports different types of packages, such as:

• Unlocked Packages: These are more modular and flexible than traditional managed packages, allowing developers to group and release customizations independently. They are version-controlled, upgradeable, and can include dependencies on other packages.

• Org-Dependent Unlocked Packages: Similar to unlocked packages but with a dependency on the metadata of the target org, making them less portable but useful for specific org customizations.

• Managed Packages: Managed packages are a type of Salesforce package primarily used by ISVs (Independent Software Vendors) for distributing and selling applications on the Salesforce AppExchange. They are fully encapsulated, which means the underlying code and metadata are not accessible or editable by the installing organization. Managed packages support versioning, dependency management, and can enforce licensing. They are ideal for creating applications that need to be securely distributed and updated across multiple Salesforce orgs without exposing proprietary code.

sfp auguments the above formal salesforce package types with additional package types such as below

• Source Packages: These are not formal packages in Salesforce but refer to a collection of metadata and code retrieved from a Salesforce org or version control that can be deployed to an org but aren't versioned or managed as a single entity.

• Diff Packages: These are not a formal type of Salesforce package but refer to packages created by determining the differences (diff) between two sets of metadata, often used for deploying specific changes.

In the context of sfp, an artifact represents a more enhanced concept compared to a Salesforce package. While it is based on a Salesforce package (of any type mentioned above), an artifact in sfp includes additional attributes and metadata that describe the package version, dependencies, installation behavior, and other context-specific information relevant to the CI/CD process. Artifacts in sfp are designed to be more than just a bundle of code and metadata; they encapsulate the package along with its CI/CD lifecycle information, making them more aligned with DevOps practices.

Key differences between Salesforce packages and sfp artifacts include:

• Versioning and Dependencies: While Salesforce packages support versioning, sfp artifacts enrich this with detailed dependency tracking, ensuring that the CI/CD pipeline respects the order of package installations based on dependencies.

• Installation Behavior: Artifacts in sfp carries additional metadata that defines custom installation behaviors, such as pre- and post-installation scripts or conditional installation steps, which are not inherently a part of Salesforce packages.

• CI/CD Integration: Artifacts in sfp are specifically designed to fit into a CI/CD pipeline, such as supporting storing in an artifact registory, version tracking, and release management that are essential for automated deployments but are outside the scope of Salesforce packages themselves.

To ensure that an artifact of a package is always deployed, irrespective the same version of the artifact is previously deployed to the org, you can utlize alwaysDeploy as a property added to your package,

{
  "packageDirectories": [
    {
      "path": "src-env-specific-pre",
      "package": "env-specific-pre",
      "versionDescription": "Environment related settings",
      "versionNumber": "4.7.0.NEXT",
      "alwaysDeploy":true
    },
     ...
   ]
}

sfp during validation checks the apex test coverage of a package depending on the package type. This is beneficial so that you dont run into any coverage issues while deploying into higher environments or building an unlocked package. \

However, there could be situations where the test coverage calculation is flaky , sfp provides you with an option to turn the coverage validation off.

// Demonstrating how to do use skipCoverageValidation
{
  "packageDirectories": [
    {
      "path": "core-crm",
      "package": "core-crm",
      "versionDescription": "Package containing core schema and classes",
      "versionNumber": "4.7.0.NEXT",
      "skipCoverageValidation": true
    },
     ...
   ]
}

A domain is defined by a release configuration. In order to define a domain, you need to create a new release config yaml file in your repository

A simple release config can be defined as shown below

// Sample release config <business_domain.yaml>
releaseName: <business_domain>   # --> The name of the domain
pool: <sandbox/scratch org pools>
excludeAllPackageDependencies: true
includeOnlyArtifacts:   # --> Insert packages
  - <pkg1>
releasedefinitionProperties:
  promotePackagesBeforeDeploymentToOrg: prod

The resulting file could be stored in your repository and utilized by the commands such as build, release etc.

One can utilize this attribute on a package definition is sfdx-project.json to skipTesting while a change is validated. Use this option with caution, as the package when it gets deployed (depending on the package behaviour) might trigger testing while being deployed to production

// Demonstrating how to do use skipTesting
{
  "packageDirectories": [
    {
      "path": "core-crm",
      "package": "core-crm",
      "versionDescription": "Package containing core schema and classes",
      "versionNumber": "4.7.0.NEXT",
      "skipTesting": true
    },
     ...
   ]
}

Using the ignoreOnStage:[ "build" ] property on a package, causes the particular package to be skipped by the build command. Similarly you can use ignoreOnStage:[ "quickbuild" ] to skip packages in the quickbuild stage.

{
  "packageDirectories": [
    {
      "path": "./src-env-specific-pre",
      "package": "src-env-specific-pre",
      "versionNumber": "1.0.0.NEXT",
      "ignoreOnStage": [
       "build"
      ]
    },
    {
      "path": "./src/frameworks/feature-mgmt",
      "package": "feature-mgmt",
      "versionNumber": "1.0.0.NEXT"
    }
  ]
}

Sometimes, due to certain platform errors, some metadata components need to be ignored during build (especially for unlocked packages) while the same being required for other commands like validate . sfp offer you an easy mechanism which allows to switch .forceignore files depending on the operation.

Add this entry to your sfdx-project.json and as in the example below, mention the path to different files that need to be used for different stages

 {
  "packageDirectories": [
    {
      "path": "core",
      "package": "core-package",
      "versionName": "Core 1.0",
      "versionNumber": "1.0.0.NEXT",
      "default": true,
    }
  ],
  "plugins": {
        "sfp": {
            "ignoreFiles": {
                "build": "forceignores/.buildignore"
                "validate": ".forceignore"
            }
   }
 }

Given a directory of artifacts and a target org, the deploy command will deploy the artifacts to the target org according to the sequence defined in the project configuration file.

// Command to install set of artifacts to devhub
sfp install -u devhub --artifactdir artifacts

Sequence of Activities

The install command runs through the following steps

• Reads all the sfp artifacts provided through the artifact directory

• Unzips the artifacts and finds the latest sfdx-project.json.ori to determine the deployment order, if this particular file is not found, it utilizes sfdx-project.json on the repo

• Read the installed packages in the target org utilizing the records in SfpowerscriptsArtifacts2__c

• Install each artifact from the provided artifact directory to the target org based on the deployment order respecting the attributes configured for each package

Assume you have a domain 'sales' as defined by release config sales.yaml provided as shown in this example here.

# release-config for sales
releaseName: sales
pool: sales-pool
excludeAllPackageDependencies: true 
includeOnlyArtifacts:
  - sales-ui
  - sales-channels
releasedefinitionProperties:
  skipIfAlreadyInstalled: true
  usePackageDiffDeploymentMode: true
  promotePackagesBeforeDeploymentToOrg: prod
  changelog:
    workItemFilters:
      -  (AKG|GIK)-[0-9]{2,5}
    workItemUrl: https://example.atlassian.net/browse
    limit: 30

In order to build the artifact of the packages defined by the above release config, you would use the the build command with the flags as described here.

sfp build --releaseconfig sales.yaml -v devhub --branch main 

If you require only to build packages that's changed form the last published packages, you would add an additional diffcheck flag.

sfp build --releaseconfig sales.yaml -v devhub --branch main  --diffcheck

A. Install sfp in your local machine

npm i -g @flxbl-io/sfp

B. Check sfp version

C. Validate Installation

In the earlier section, we looked at how we configured the project directory for sfp, Now lets walk through some core commands.

A. Build an artifact for a package

The build command will generate a zipped artifact file for each package you have defined in the sfdx-project.json file. The artifact file will contain metadata and the source code at the point build creation for you to use to install.

1. Open up a terminal within your Salesforce project directory and enter the following command:

You will see the logs with details of your package creation, for instance here is a sample output

1. A new "artifacts" folder will be generated within your source project containing a zipped artifact file for each package defined in your sfdx-project.json file. For example, the artifact files will contain the following naming convention with the "_sfpowerscript_artifact_" in between the package name and version number. package-name_sfpowerscripts_artifact_1.0.0-1.zip \

B. Install the artifact to a target org

Ensure you have authenticated your salesforce cli to a org first. If you haven't, please find the instructions .

1. Once you have the authenticated to the sandbox, you could execute the installation command as below

1. Navigate to your target org and confirm that the package is now installed with the expected changes from your artifact. In this example above, a new custom field has been added to the Account Standard Object.

Org-dependent unlocked packages, a variation of unlocked packages, allow you to create packages that depend on unpackaged metadata in the target org. Org dependent package is very useful in the context of orgs that have lots of metadata and is struggling with understanding the dependency while building a 'unlocked package'

Org dependent packages significantly enhance the efficiency of #flxbl projects who are already on scratch org based development. By allowing installation on a clean slate, these packages validate dependencies upfront, thereby reducing the additional validation time often required by unlocked packages.

Org-Dependent Unlocked Package and Test Coverage

Org-dependent unlocked packages bypass the test coverage requirements, enabling installation in production without standard validation. This differs significantly from metadata deployments, where each Apex class deployed must meet a 75% coverage threshold or rely on the org's overall test coverage. While beneficial for large, established orgs, this approach should be used cautiously.

To address this, sfp incorporates a default test coverage for org-dependent unlocked packages during the validation process. To disable this test coverage check during validation, additional attributes must be added to the package directory in the sfdx-project.json file.

\

Good Work! If you made it past the getting started guide with minimal errors and questions, you are well on your way to introduce sfp into your Salesforce Delivery workflow.

Let's summarize what you have done:

1. Setup pre-requisite software on your workstation and have access to a Salesforce Org.

2. Installed the latest sfp cli.

3. Configured your source project and added additional properties required for sfp cli to generate artifacts.

4. Build artifact(s) locally to be used to deploy.

5. Installed artifact(s) to target org.

This is just the tip of the iceberg for the full features sfp can provide for you and your team. Please continue to read further and experiment.

For any comments/recommendations to sfp so please join our . If you are adventurous, contribute!

Occasionally you might need to assign a permission set for the deployment user to successfully install the package, run apex tests or functional tests, sfp provides you an easy mechanism to assign permission set either before installation or after installation of an artifact. assignPermSetsPreDeployment assumes the permission sets are already deployed on the target org and proceed to assign these permission sets to the user

assignPermSetsPostDeployment can be used to assign permission sets that are introduced by the artifact to the target org for any aspects of testing or any other automation usage

Have you ever encountered this error when deploying an updated Entitlement Process to your org?

Deployment Issue with Entitlement Process in Salesforce

It's important to note that Salesforce prevents the deployment of an Entitlement Process that is currently in use, irrespective of its activation status in the org. This limitation holds true even for inactive processes, potentially impacting deployment strategies.

To create a new version of an Entitlement Process, navigate to the Entitlement Process Detail page in Salesforce and perform the creation. If you then use sf cli to retrieve this new version and attempt to deploy it into another org, you're likely to encounter errors. Deploying it as a new version can bypass these issues, but this requires enabling versioning in the target org first.

The culprit behind this is an attribute in the Entitlement Process metadata file: versionMaster.

According to the Salesforce documentation, versionMaster ‘identifies the sequence of versions to which this entitlement process belongs and it can be any value as long as it is identical among all versions of the entitlement process.’ An important factor here about versionMaster is: versionMaster is org specific. When you deploy a completely new Entitlement Process to an org with a randomly defined versionMaster, Salesforce will generate an ID for the Entitlement Process and map it to this specific versionMaster.

Deploying updated Entitlement Processes from one Salesforce org to another can often lead to deployment errors due to discrepancies in the versionMaster attribute, sfp's enitlement helper enables you to automatically align the versionMaster by pulling its value from the target org and updating the deploying metadata file accordingly. This ensures that your deployment process is consistent and error-free.

1. Enable Versioning: First and foremost, activate versioning in the target org to manage various versions of the Entitlement Process.

2. Create or Retrieve Metadata File:

   • Create a new version of the Entitlement Process as a metadata file, which can be done via the Salesforce UI and retrieved with the Salesforce CLI (sf cli).

3. Ensure Metadata Accuracy

Automation around entitlement filter can be disabled globally by using these attributes in your sfdx-project.json

sfp by default attempts to trigger all the apex tests in a package in asynchronous mode during validation. This is to ensure that you have a highly performant apex test classes which provide you fast feedback.

If you have inherited an existing code base or your unit tests have lot of DML statemements, you will encounter test failuers when a tests in package is triggered asynchronously. You can instruct sfp to trigger the tests of the package in a synchronous mode by setting 'testSynchnronous as true \

Skip artifacts if they are already installed

// Command to deploy set of artifacts to devhub
sfp install -u devhub --artifactdir artifacts --skipifalreadyinstalled          

By using the skipifalreadyinstalled option with the deploy command, you can prevent the reinstallation of an artifact that is already present in the target organization.

Install artifacts to an org baselined on an another org

The --baselineorg parameter allows you to specify the alias or username of an org against which to check whether the incoming package versions have already been installed and form a deployment plan.This overrides the default behaviour which is to compare against the deployment target org. This is an optional feature which allows to ensure each org's are updated with the same installation across every org's in the path to production.

sfp cli when encounters the attribute skipDeployOnOrgs on a package, the generated artifact during installation is checked against the alias or the username passed onto the installation command. If the username or the alias is matched, the artifact installation is skipped

// Demonstrating how to do use skipDeployOnOrgs
{
  "packageDirectories": [
    {
      "path": "core-crm",
      "package": "core-crm",
      "versionDescription": "Package containing core schema and classes",
      "versionNumber": "4.7.0.NEXT",
      "skipDeployOnOrgs":[
       "qa",
       "[email protected]
      ]
    },
     ...
   ]
}

In the above example, if the alias to installation command is qa, the artifact for core-crm will get skipped during intallation. The same can also be applied for username of an org as well

In order to prevent deployment errors to target Salesforce Orgs, enabling reconcileProfiles totrue ensures and extra steps are taken to ensure the profile metadata is cleansed of any missing attributes prior to deployment.

During the reconcilement process, you can provide the follow flags to the command:

• Folder - path to the folder which contains the profiles to be reconciled, if project contain multiple package directories, please provide a comma separated list, if

• Profile List - list of profiles to be reconciled. If omitted, all the profiles components will be reconciled.

• Source Only - set this flag to reconcile profiles only against component available in the project only. Configure ignored permissions in sfdx-project.json file in the array

• Destination Folder - the destination folder for reconciled profiles, if omitted existing profiles will be reconciled and will be rewritten in the current location

For more details on thesfp profile reconcile command, .

While installing a source/diff package, flows by default are deployed as 'Inactive' in the production org. One can deploy flow as 'Active' using the steps mentioned here, however, this requires the flow to meet test coverage requirement.

Also making a flow inactive, is convoluted, find the detailed article provided by Gearset

sfp has automation built in that attempts to align the status of a particular flow version as kept inside the package. It automatically activates the latest version of a Flow in the target org (assuming the package has the latest version). If an earlier version of package is deployed, it skips the activation.

At the same time, if the package contains a Flow with status Obsolete/InvalidDraft/Draft, all the versions of the flow would be rendered inactive.\

To ensure a package is always included during validation when its domain is impacted, add alwaysSync as a property to your package descriptor:

When framework-core is changed and validation is triggered, framework-config will automatically be included because it belongs to the same domain and has alwaysSync: true.

This also works across domains when using dependencyOn in release configs. If Domain B has a dependencyOn referencing a package from Domain A, and that package changes, all alwaysSync packages in Domain A will be included.

Step 1: Download the Installer

1. Go to

2. Select the latest release (or a specific version you need)

A. Ensure you have enabled and authenticated to DevHub

Ensure you have in your production org or created a developer org.

B. Authenticate your Salesforce CLI to DevHub

SFP-Pro provides Docker images through our self-hosted Gitea registry at source.flxbl.io. These pre-built images are maintained and updated regularly with the latest features and security patches.

Prerequisites

1. Access to source.flxbl.io (Gitea server)

sfp is a purpose-built cli tool used predominantly in a modular salesforce project. \

A project utilizing sfp implements the following concepts.

Domains

In an sfp-powered Salesforce project, "Domains" represent distinct business capabilities. A project can encompass multiple domains, and each domain may include various sub-domains. Domains are not explicitly declared within sfp but are conceptually organized through ""

sfp cli supports operations on various types of packages within your repository. A short summary on the comparison between different package types is provided below\

This section details identifies on how sfp analyzes and classifies different package types by using the information in sfdx-project.json

• Unlocked Packages are identified if a matching alias with a package version ID is found and verified through the DevHub. For example, the package named "Expense-Manager-Util" is found to be an Unlocked package upon correlation with its alias "Expense Manager - Util" and subsequent verification.

• Source Packages are assumed if no matching alias is found in packageAliases. These packages are typically used for source code that is not meant to be packaged and released as a managed or unlocked package.

To fully leverage the capabilities of sfp, a few addition steps need to be configured in your Salesforce Orgs. Please follow the following steps.

1. Enable Dev Hub

To enable modular package development, the following configurations need to be turned on in order to create Scratch Orgs and Unlock Packages.

in your Salesforce org so you can create and manage scratch orgs and second-generation packages. Scratch orgs are disposable Salesforce orgs to support development and testing.

validate command helps you to test ((deployability, apex tests, coverage) a change made to your configuration / code against a target org. This command is typically triggered as part of your Pull Request (PR) or Merge process, to ensure the correctness of configuration/code, before being merged into your main branch.

validate can either utilise a scratch org from a tagged pool prepared earlier using the command or one could use the a target org for its purpose

validate pool / validate org command runs the following checks with the options to enable additional features such as dependency and impact analysis:

sfp's build commands process the packages in the order as mentioned in your sfdx-project.json. The commands also read your dependencies property, and then when triggered, will wait till all its dependencies are resolved, before triggering the equivalent package creation command depending on the type of the package and generating an artifact in the due process

sfp's build command is equipped with a diffcheck functionality, which is enabled when one utilizes diffcheck flag, A comparison (using git diff) is made between the latest source code and the previous version of the package published by the '' command. If any difference is detected in the package directory, package version or scratch org definition file (applies to unlocked packages only), then the package will be created - otherwise, it is skipped. For eg: provided the followings packages in sfdx-project.json along with its dependencies

Scenario 1 : Build All

1. Trigger creation of artifact for package A

Artifacts to be built can be limited by various mechanisms. This section deals with various techniques to limit artifacts being built

Limiting artifacts by domain

Artifacts to be built can be restricted by during a build process in sfp by utilizing specific configurations. Consider the example provided in

You can use the path to the config file to the build command to limit the artifacts being built as in the sample below

Projects that utilise sfp predominantly follow a mono-repo structure similar to the picture shown above. Each repository has a "src" folder that holds one or more packages that map to your sfdx-project.json file.

Different folders in each of the structure are explained as below:

1. core-crm: A folder to house all the core model of your org which is shared with all other domains.

2. frameworks: This folder houses multiple packages which are basically utilities/technical frameworks such as Triggers, Logging and Error Handling, Dependency Injection etc.

The Publish command pushes artifacts created by the build command to a npm registry and also provides you functionality to tag a version of the artifact in your git repository.

Publishing to an NPM-Compatible Private Registry

To publish packages to your private registry, you'll need to configure your credentials accordingly. Follow the guidelines provided by your registry's service to ensure a smooth setup.

1. Locate Documentation: Jump into your private registry provider's documentation or help center.

Salesforce inherently does not support the deployment of picklist values as part of unlocked package upgrades. This limitation has led to the need for workarounds, traditionally solved by either replicating the picklist in the source package or manually adding the changes in the target organization. Both approaches add a burden of extra maintenance work. This issue has been documented and recognised as a known problem, which can be reviewed in detail .

To ensure picklist consistency between local environments and the target Salesforce org, the following pre-deployment steps outline the process for managing picklists within unlocked packages:

sfp cli optimally deploys artifacts to the target organisation by reducing the time spent on running Apex tests where possible. This section explains how this optimisation works for different package types.

sfp features commands and functionality that helps in dealing with complexity of defining dependency of unlocked packages. These functionalities are designed considering aspects of a #flxbl project, such as the predominant use of mono repositories in the context of a non-ISV scenarios.

Package dependencies are defined in the sfdx-project.json (Project Manifest). More information on defining package dependencies can be found in the Salesforce docs.

Let's unpack the concepts utilizing the above example:

• There are two unlocked packages and one source package

  • Expense Manager - Util is an unlocked package in your DevHub, identifiable by 0H in the packageAlias

  • Expense Manager - another unlocked package which is dependent on ' Expense Manager - Util', 'TriggerFramework' and 'External Apex Library - 1.0.0.4'

  • Expense Manager Org Config - a source package, lets assume has some reports and dashboards

• External Apex Library is an external dependency, it could be a managed package or any unlocked package released on a different Dev Hub. All external package dependencies must be defined with a 04t ID, which can be determined from the installation URL from AppExchange or by contacting your vendor.

• Source Packages/Org Dependent Unlocked / Data packages have an implied dependency as defined by the order of installation, as in it assumes any depedent metadata is already available in the target org before the installation of components within the package

The configFile flag in the build command is used for features and settings of the scratch org used to validate your unlocked package. It is optional and if not passed in, it will assume the default one which is none.

Typically, all packages in the same repo share the same scratch org definition. Therefore, you pass in the definition that you are using to build your scratch org pool and use the same to build your unlocked package.

sfp build --configFile <path-to-config-file> -v <devhub>

However, there is an option to use multiple definitions.

For example, if you have two packages, package 1 is dependent on SharedActivities, and package 2 is not. You would pass a scratch org definition file to package 1 via scratchOrgDefFilePaths in sfdx-project. Package 2 would be using. the default definitionFile.

{
  "packageDirectories": [
    {
      "path": "package1",
      "default": true,
    },
    {
      "path": "package2",
      "default": false
    }
  ],
  "plugins": {
    "sfp":{
      "scratchOrgDefFilePaths":{
        "enableMultiDefinitionFiles": true,
        "packages": {
          "package1":"scratchOrgDef/package1-def.json"
        }
      }
    }
  }
}

Breaking Changes: sfp community edition to sfp-pro

Critical: Update Your Pipelines

Most orchestrator: command aliases have been removed in sfp-pro. You must update your pipelines:

New/Changed in sfp-pro:

Exception: sfp orchestrator:publish still works in sfp-pro.

• --commit flag added to build command for specifying commit hash

• Server flags added to most commands (--server-url, --api-key)

• Additional commands in pro: server:*

✅ What Stays the Same

• Core command functionality is unchanged

• All flags from sfp-comm still work

• Command outputs remain compatible

Migration Notes:

🆕 New in sfp-pro

• All core orchestrator commands (build, install, publish, release) work identically

• Existing pipelines using these commands will continue to work

• New flags are optional and backward compatible

This feature is by default activated whenever build/quickbuild even in implicit scenarios such as validate, prepare etc, which might result in building packages.

Let's consider the following sfdx-project.json to explain how this feature works.

The above project manifest (sfdx-project.json) describes three packages, sfdc-logging, feature-mgmt., core-crm . Each package are defined with dependencies as described below

As you might have noticed, this is an incorrect representation, as per the definitions of unlocked package, the package 'core-crm' should be explicitly defining all its dependencies. This means it should be as described below.

To successfully create a version of core-crm , both sfdc-logging and feature-mgmt. should be defined as an explicit dependency in the sfdx-project.json

As the number of packages grow in your project, it is often seen developers might accidentally miss declaring dependencies or the sfdx-project.json has become so large due to large amount of repetition of dependencies between packages. This condition would result in build stage often failing with missing dependencies.

sfp features a transitive dependency resolution which can autofill the dependencies of the package by inferring the dependencies from sfdx-project.json, so the above package descriptor of core-crm will be resolved correctly to \

Please note, in the current iteration, it will autofill dependency information from the current sfdx-project.json and doesn't consider variations among previous versions.

For dependencies outside of the sfdx-project.json, one could define an externalDependencyMap as shown below

If you need to disable this feature and have stringent dependency management rules, utilize the following in your sfdx-project.json

In a Flxbl project powered by sfp, development follows a structured, iterative workflow designed for team collaboration and continuous delivery. This section guides you through the complete development lifecycle - from setting up your environment to submitting code for review.

Prerequisites

DevHub Access is Required for sfp development:

• Building any type of package (source, unlocked, data)

• Creating and managing scratch orgs

• Resolving package dependencies

Ensure your Salesforce user has DevHub access by following .

The Development Flow

Development in an sfp project follows these key principles:

1. Isolated Environments: Each developer works in their own sandbox or scratch org

2. Source-Driven Development: All changes are tracked in version control

3. Iterative Cycles: Developers continuously pull, modify, and push changes

4. Automated Validation: Pull requests trigger comprehensive validation

How Developers Work

Developers in an sfp project typically follow this pattern:

Starting a Sprint or Feature

• Fetch a fresh environment from a pre-prepared pool

  • Scratch orgs: Can be fetched per story for maximum isolation

  • Sandboxes: Usually fetched at sprint start for longer-running work

• Pull the latest metadata to sync with the org

Daily Development Cycle

• Pull changes from the org to stay synchronized

• Make modifications to metadata and code

• Push changes back to the org for testing

• Run tests locally to validate functionality

Completing Work

• Create a pull request with your changes

• Automated validation runs via CI/CD pipeline

• Review environment is created for acceptance testing

• Merge after approval and successful validation

Environment Management

sfp provides powerful commands for environment management through pools:

Local Scratch Org Pools (Community Edition)

Pre-prepared scratch orgs managed locally via DevHub:

Server-Managed Pools (sfp-pro)

Centralized pool management for both scratch orgs and sandboxes:

This pooling approach means developers spend less time waiting for environment creation and more time coding.

Source Synchronization

The foundation of sfp development is bidirectional source synchronization:

Pull Command

Retrieves changes from your org to local source:

• Automatically handles text replacement reversals

• Detects conflicts and provides resolution options

• Suggests new replacements for hardcoded values

Push Command

Deploys local changes to your org:

• Applies environment-specific text replacements

• Handles destructive changes automatically

• Supports various test execution levels

What's Next?

For a complete walkthrough of the development workflow with detailed commands and examples:

For specific development tasks:

For managing environments:

sfp provides powerful commands to manage and understand package dependencies in your Salesforce projects. These tools help you maintain clean dependency declarations, troubleshoot dependency issues, and optimize your build processes.

Available Commands

Understanding Dependencies

In Salesforce DX projects, packages can depend on other packages. These dependencies come in two forms:

• Direct Dependencies: Dependencies explicitly declared in a package's configuration

• Transitive Dependencies: Dependencies of your dependencies (indirect dependencies)

For example, if Package A depends on Package B, and Package B depends on Package C, then:

• Package A has a direct dependency on Package B

• Package A has a transitive dependency on Package C

Dependency Management Workflow

A typical dependency management workflow involves:

1. Development Phase: Use sfp dependency:expand to make all dependencies explicit during development, helping identify potential issues early

2. Analysis: Use sfp dependency:explain to understand dependency relationships and identify unnecessary dependencies

3. Cleanup: Use sfp dependency:shrink before committing to maintain minimal, clean dependency declarations

External Dependencies

External dependencies are packages from outside your project, typically:

• Managed packages from AppExchange

• Packages from other Dev Hub organizations

• Third-party components

These are configured in your sfdx-project.json under plugins.sfp.externalDependencyMap:

Best Practices

1. Keep dependencies minimal: Only declare direct dependencies in your source control

2. Use expand for analysis: Temporarily expand dependencies to understand the full graph

3. Validate regularly: Run dependency commands in CI/CD to catch issues early

4. Document external dependencies: Clearly document why each external dependency is needed

Common Issues and Solutions

Circular Dependencies

If packages depend on each other in a circular manner, the dependency commands will report an error. Refactor your packages to break the circular dependency.

Missing Dependencies

If a package references components from another package without declaring the dependency, add the missing dependency to the package's configuration.

Version Conflicts

When different packages require different versions of the same dependency, sfp will use the highest compatible version. Consider standardizing versions across your project.

See Also

• - Conceptual overview of dependencies

• - How sfp resolves dependencies

sfp provides intelligent AI-assisted error analysis to help developers quickly understand and resolve validation failures. When enabled through the errorAnalysis configuration in ai-assist.yaml, the system automatically analyzes error patterns and provides actionable insights.

Quick Setup

1. Create config/ai-assist.yaml in your project root:

2. Add the minimal configuration:

3. Set your LLM provider credentials (e.g., in CI/CD secrets)

That's it! AI error analysis will automatically activate during validation failures.

How It Works

1. Change Significance Analysis

Before triggering AI analysis, sfp evaluates if changes are significant enough to warrant review:

• Metadata Type Detection: Uses Salesforce ComponentSet for accurate identification

• Smart Thresholds: Different thresholds per file type (Apex: 3 lines, Flows: 1 line, LWC: 10 lines)

• Automatic Exclusions: Skips non-critical metadata (CustomLabels, StaticResources, Translations)

2. Error Analysis

When validation fails and changes are significant, AI provides:

• Root Cause Analysis: Understanding why the error occurred

• Quick Fix Suggestions: Immediate actions to resolve issues

• Related Components: Other files that might be involved

• Documentation Links: References to relevant Salesforce docs

Configuration

Configure AI assistance through config/ai-assist.yaml:

Usage

AI error analysis is automatically enabled when:

1. A config/ai-assist.yaml file exists in your project

2. The errorAnalysis.enabled flag is set to true

3. Valid LLM provider credentials are available

No additional CLI flags are required - sfp automatically detects and uses the configuration.

Validation processes often need to synchronize the provided organization by installing packages that differ from those already installed. This task can become particularly time-consuming for large projects with hundreds of packages, especially in monorepo setups with multiple independent domains.

Using Release Configurations

To streamline the validation process and focus it on specific domains, you can use release configurations with the --releaseconfig flag. This approach limits the scope of validation to only the packages defined in your release configuration, significantly enhancing efficiency and reducing validation time.

Basic Usage

In this example, validation is limited to packages defined in the release-domain-sales.yml configuration file. Only packages that:

1. Are listed in the release configuration AND

2. Have changes compared to what's installed in the org

will be validated.

Multiple Domain Configurations

For projects with multiple independent domains, you can specify multiple release configurations:

Benefits of Domain-Limited Validation

1. Faster Feedback: Validate only the relevant packages for your team's domain

2. Reduced Dependencies: Avoid failures from unrelated packages in other domains

3. Parallel Development: Multiple teams can work independently without blocking each other

4. Optimized CI/CD: Shorter validation times mean more efficient pipeline execution

Example Release Configuration

Combining with Other Options

With Diff Check

With Individual Mode

With Branch References

Best Practices

1. Organize by Domain: Create separate release configurations for each logical domain

2. Keep Configurations Updated: Regularly review and update package lists in release configs

3. Use in CI/CD: Automate domain-specific validation in your pipeline

4. Document Dependencies: Clearly document cross-domain dependencies in your configurations

Note: The deprecated --mode=thorough-release-config and --mode=ff-release-config have been replaced by using the standard modes with the --releaseconfig flag. This provides the same functionality with a simpler, more consistent interface.

A diff package is a variant of 'source package' , where the contents of the package only contain the components that are changed. This package is generated by sfpowerscripts by computing a git diff of the current commit id against a baseline set in the Dev Hub Org

A diff package mimics a Change Set model, where only changes are contained in the artifact. As such, this package is always an incremental package. It only deploys the changes incrementally compared to baseline and applied to the target org. Unless both previous version and the current version have the exact same components, a diff package can never be rolled back, as the impact on the org is unpredictable. It is always recommended to roll forward a diff package by fixing or creating a necessary change that counters the impact that you want on the target orgs.

The below example demonstrates a sfdx-project.json where the package unpackaged is a diff package. You can mark a diff package with the type 'diff'. All other attributes applicable to source packages are applicable for diff packages.

A manual entry in sfpowerscripts_Artifact2__c custom object should be made with the name of the package and the baseline commit id and version. Subsequent deployments will automatically reset the baseline when the package gets deployed to Dev Hub

In certain scenarios, it's necessary to build a new version of a package when any package in the collection undergoes changes. This can be accomplished by utilizing the buildCollection attribute in the sfdx-project.json file.

To ensure that a new version of a package is built whenever any package in a specified collection undergoes a change, you can use the buildCollection attribute in the sfdx-project.json file. Below is an example illustrating how to define a collection of packages that should be built together.

Salesforce has a strict limit on the number of fields that can be tracked. Of course, this limit can be increased by raising it to the Salesforce Account Executive (AE). However, it would be problematic if an unlocked package is deployed to orgs that do not have the limit increased. So don’t be surprised when you are working on a flxbl project and happen to find that the deployment of field history tracking from unlocked packages is disabled by Salesforce.

One workaround is to keep a copy of all the fields that need to be tracked in a separate source package (field-history-tracking or similar) and deploy it as one of the last packages with the ‘alwaysDeploy’ option.

However, this specific package has to be carefully aligned with the original source/unlocked packages, to which the fields originally belong. As the number of tracked fields increases in large projects, this package becomes larger and more difficult to maintain. In addition, since it’s often the case that the project does not own the metadata definition of fields from managed packages, it doesn’t make much sense to carry the metadata only for field history tracking purposes.

To resolve this, sfp features the ability to automate the deployment of field history tracking for both unlocked packaged and managed packages without having to maintain additional packages.

Two mechanisms are implemented to ensure that all the fields that need to be field history tracking enabled are properly deployed. Specifically, a YAML file that contains all the tracked fields is added to the package directory.

During deployment, the YAML file is examined and the fields to be set are stored in an internal representation inside the deployment artifact. Meanwhile, the components to be deployed are analyzed and the ones with ‘trackHistory’ on are added to the same artifact. This acts as a double assurance that any field that is missed in the YAML files due to human error will also be picked up. After the package installation, all the fields in the artifact are retrieved from the target org and, for those fields, the trackHistory is turned on before they are redeployed to the org.

In this way, the deployment of field history tracking is completely automated. One now has a declarative way of defining field history tracking (as well as feed tracking) without having to store the metadata in the repo. The only maintenance effort left for developers is to manage the YAML file.

Data packages are a sfpowerscripts construct that utilise the to create a versioned artifact of Salesforce object records in csv format, which can be deployed to the a Salesforce org using the sfpowerscripts package installation command.

The Data Package offers a seamless method of integrating Salesforce data into your CICD pipelines , and is primarily intended for record-based configuration of managed package such as CPQ, Vlocity (Salesforce Industries), and nCino.

Data packages are a wrapper around SFDMU that provide a few key benefits:

• Ability to skip the package if already installed: By keeping a record of the version of the package installed in the target org with the support of an unlocked package, sfpowerscripts can skip installation of data packages if it is already installed in the org

sfp handles destructive changes according to the type of package. Here is a rundown on how the behaviour is according to various package types and modes

Unlocked Packages

Salesforce handles destructive changes in unlocked packages / org dependent unlocked packages as part of the package upgrade process. From the Salesforce documentation ()

Metadata that was removed in the new package version is also removed from the target org as part of the upgrade. Removed metadata is metadata not included in the current package version install, but present in the previous package version installed in the target org. If metadata is removed before the upgrade occurs, the upgrade proceeds normally. Some examples where metadata is deprecated and not deleted are:

The sfp dependency:shrink command optimizes your project's dependency declarations by removing redundant transitive dependencies from your sfdx-project.json. This results in a cleaner project configuration with only the necessary direct dependencies declared for each package.

The sfp dependency:explain command helps you understand the dependencies between packages in your project. It can analyze either a specific package's dependencies or all package dependencies in the project, showing both direct and transitive dependencies.

In some situations, you might need to execute a pre/post deployment script to do manipulate the data before or after being deployed to the org.

The AI-powered report functionality generates comprehensive analysis reports for your Salesforce projects using advanced language models. This feature provides deep insights into code quality, architecture, and best practices specific to the Flxbl framework.