sfp is a purpose-built cli-based tool for modular Salesforce development and release management. sfp aims to streamline and automate 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

Key Aspects of sfp:

• Built with codified process: sfp cli is derived from extensive experience in modular Salesforce implementations. By embracing the #FLXBL framework, it aims to streamline the process of creating a well-architected, composable Salesforce Org. sfp cli eliminates the need for time-consuming efforts usually spent on re-inventing fundamental processes, helping you achieve your objectives faster

• Artifact-Centric Approach: sfp packages Salesforce code and metadata into artifacts and 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.

• Support for Multiple Package Types: sfp accommodates various Salesforce package types with streamlined commands, enabling modular development, independent versioning, and flexible deployment strategies.

• Orchestrate Across Entire Lifecycle: sfp provides an extensive set of functionality across the entire lifecycle of your Salesforce development.

• End-to-End Observability: sfp is built with comprehensive metrics emitted on every command, providing unparalleled visibility into your ALM process.

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 (locally to start and to a NPM artifact repository after) 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, change logs, 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. As we continue to grow the toolset, we hope to introduce more commands to address the future wave of challenges.

Below is a high-level snapshot of the main topics and commands of sfp.

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.

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:

sfp build -v <DevHubAlias/DevHubUsername>

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

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

sfp install -o <TargetOrgAlias/TargetOrgUsername>

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.

Install sfp community edition

A. Install sfp in your local machine

npm i -g @flxbl-io/sfp

B. Check sfp version

sfp --version
@flxbl-io/sfp/37.0.0 darwin-arm64 node-v20.3.1

C. Validate Installation

sfp commands

Command                         Summary
 ─────────────────────────────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 apextests trigger               Triggers Apex unit test in an org. Supports test level RunAllTestsInPackage, which optionally allows validation of individual class code coverage
 artifacts fetch                 Fetch sfp artifacts from a NPM compatible registry using a release definition file
 artifacts promote               Promotes artifacts predominantly for unlocked packages with code coverage greater than 75%
 artifacts query                 Fetch details about artifacts installed in a target org
 build                           Build artifact(s) of your packages in the current project
 ...

Install sfp - pro

A. Download the latest release from source.flxbl.io

B. Install the version in your local machine

npm i -g <path-to-downloaded-file>

C. Check sfp version

sfp --version
@flxbl-io/sfp/43.1..0 darwin-arm64 node-v20.3.1

D. Validate Installation

sfp commands

Command                         Summary
 ─────────────────────────────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 apextests trigger               Triggers Apex unit test in an org. Supports test level RunAllTestsInPackage, which optionally allows validation of individual class code coverage
 artifacts fetch                 Fetch sfp artifacts from a NPM compatible registry using a release definition file
 artifacts promote               Promotes artifacts predominantly for unlocked packages with code coverage greater than 75%
 artifacts query                 Fetch details about artifacts installed in a target org
 build                           Build artifact(s) of your packages in the current project
 ...

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

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

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

A. Ensure you have enabled and authenticated to DevHub

B. Authenticate your Salesforce CLI to DevHub

C. Add additional attributes to your Salesforce DX Project

1. Navigate to your sfdx-project.json file and locate the packageDirectories property.

{ 
"packageDirectories" : [ 
    { "path": "force-app", "default": true}, 
    { "path" : "unpackaged" }, 
    { "path" : "utils" } 
  ],
"namespace": "", 
"sfdcLoginUrl" : "https://login.salesforce.com", 
"sourceApiVersion": "60.0"
}

In the above example, the package directories are

• force-app

• unpackaged

• utils

1. Add the following additional attributes to the sfdx-project.json and save.

• package

• versionNumber

{
   "packageDirectories" : [ 
    {
       "package": "force-app",
       "versionNumber": "1.0.0.NEXT",
       "path": "force-app",
       "default": true
     }, 
    { "path" : "unpackaged" },  // You can repeat the same for additonal directories
    { "path" : "utils" }  // You can repeat the same for additonal directories
   ],
"namespace": "", 
"sfdcLoginUrl" : "https://login.salesforce.com", 
"sourceApiVersion": "60.0"
}

Thats the minimal configuration required to run sfp on a project.

Move on to the next chapter to execute sfp commands in this directory.

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

A project utilizing sfp implements the following concepts.

Domains

A package (synonymous with modules) is a container that groups 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. A package is defined as a directory in your project repository and is defined by an entry in sfdx-project.json

An artifact represents a versioned snapshot of a package at a specific point in time. It includes the source code from the package directory (as specified in sfdx-project.json), along with metadata about the version, change logs, and other relevant details. Artifacts are the deployable units in the sfp framework, ensuring consistency and traceability across the development lifecycle. When sfp is integrated into a Salesforce project, it centralizes around the following key essential process

Building' refers to the creation of an artifact from a package. Utilizing the build command, sfp facilitates the generation of artifacts for each package in your repository. This process encapsulates the package's source code and metadata into a versioned artifact ready for installation.

Publishing a domain involves the process of publishing the artifacts generated by the build command into an artifact repository. This is the storage area where the artifacts are fetched for releases, rollback, etc.

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

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

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)

2. Docker installed on your machine

3. Registry credentials from your welcome email

Accessing the Images

1. Login to the Gitea registry:

1. Pull the desired image:

The version numbers can be found at https://source.flxbl.io/flxbl/-/packages/container/sfp-pro/

1. (Optional) Tag for your registry:

Best Practices

1. Use specific version tags in production

2. Cache images in your private registry for better performance

3. Implement proper access controls in your registry

4. Document image versions used in your pipelines

Building Docker Images

If you need to build the images yourself, you can access the source code from source.flxbl.io and follow these instructions:

Prerequisites

• Docker with BuildKit support

• GitHub Personal Access Token with packages:read permissions

• Node.js (for local development)

Building the Main Image

Building the SF CLI Image

Build Arguments

The following build arguments are supported:

• NODE_MAJOR: Node.js major version (default: 22)

• SFP_VERSION: Version of SFP Pro to build

• GIT_COMMIT: Git commit hash for versioning

• SF_COMMIT_ID: Salesforce commit ID

Support

For issues or questions about Docker images, please contact flxbl support through your designated support channels.

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.

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.

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.

Artifacts built by sfp follow a naming convention that starts with the <name_of_the_package>sfpowerscripts_artifact_<Major>.<Minor>.<Patch>-<BuildNumber>. One can use any of the npm commands to interact with sfp artifacts.

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, sfpowerscripts incorporates a default test coverage validation 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.

// Org dependent unlocked package with additonal attributes

  "packageDirectories": [
    {
      "path": "src/core/core-crm",
      "package": "core-crm",
      "versionNumber": "4.7.0.NEXT",
      "skipTesting": true,
      "skipCoverageValidation": true
    },
     ...
   ]
}

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

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.

// sfdx-project.json

{
  "packageDirectories": [
    {
      "path": "util",
      "default": false,
      "package": "Expense-Manager-Util",
      "versionName": "Winter ‘24",
      "versionDescription": "Welcome to Winter 2024 Release of Expense Manager Util Package",
      "versionNumber": "4.7.0.NEXT"
    },
     {
      "path": "unpackaged",
      "default": true,
      "package": "unpackaged",
      "versionName": "v3.2",
      "type":"diff"
    }
  ],
  "sourceApiVersion": "58.0",
  "packageAliases": {
    "TriggerFramework": "0HoB00000004RFpLAM",
    "Expense Manager - Util": "0HoB00000004CFpKAM",
    "External Apex Library@1.0.0.4": "04tB0000000IB1EIAW",
    "Expense Manager": "0HoB00000004CFuKAM"
  }
}

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

Source Packages is an sfp cli feature that mimics the behaviour of native unlocked packages.

Source Packages are metadata deployments from a Salesforce perspective, it is a group of components that are deployed to an org. Unlocked packages are a First Class Salesforce deployment construct, where the lifecycle is governed by the org, such as deleting/deprecating metadata and validating versions.

We always recommend using unlocked packages over source packages whenever you can. As a matter of preference, this is our priority of package types

3. Source Packages

Source Packages are typically used for application-config (configuring an application delivered by a managed package such as changes to help text/description of fields ) or when you come across these constraints

• Facing bugs while deploying the metadata using unlocked packages

• Unlocked Package validation takes too long (still we recommend go org-dependent)

• Dealing with metadata that is global or org-specific in nature (such as queues, profiles, etc or composite UI layouts, which doesn't make sense to be packaged using unlocked package)

• Development teams who are starting to adopt package-based development and want to organize their metadata

A Salesforce Org composed only of source packages

A Salesforce Org can be composed only with source packages, however the lack of dependency validation as in unlocked packages, lack of automated destruction of changes can make it a bit challenging. As salesforce org is not aware of the source package, there is no component lock , so another source package with same metadata component can alwasy overwrite a metadata component deployed by another package. For these, reasons, we always recommend you prefer unlocked package or its variant org dependent unlocked packages.

Dependency Management for source packages

Source packages can depend on other unlocked packages or managed packages, however dependencies of source packages are validated during deployment time, ie., source packages assume that dependent metadata is already there in your org before the metadata in the source package is being deployed. That being said, for purposes of development in scratch org, you could add 'unlocked/managed package' dependencies to a source package, so sfp cli commands like prepare and validate (in sfpowerscripts:orchestrator) will install the dependencies to the target org before proceedint to install source package

There is a huge amount of documentation on unlocked packages. Here are list of curated links that can help you get started on learning more about unlocked package

The Basics

Advanced Materials

The following sections deals with more of the operational aspects when dealing with unlocked packages

Unlocked Package and Test Coverage

Managing Version Numbers of Unlocked Package

Deprecating Components from an Unlocked Package

Unlocked packages provide traceability in the org by locking down the metadata components to the package that introduces it. This feature which is the main benefit of unlocked package can also create issues when you want to refactor components from one package to another. Let's look at some scenarios and common strategies that need to be applied

For a project that has two packages.

• Package A and Package B

• Package B is dependent on Package A.

Scenario 1:

• Remove a component from Package A, provided the component has no dependency

• Solution: Create a new version of Package A with the metadata component being removed and install the package.

Scenario 2:

• Move a metadata component from Package A to Package B

• Solution: This scenario is pretty straight forward, one can remove the metadata component from Package A and move that to Package B. When a new version of Package A gets installed, the following things happen:

  • On the subsequent install of Package B, Package B restores the field and takes ownership of the component.

Scenario 3:

• Move a metadata component from Package B to Package A, where the component currently has other dependencies in Package B

• Solution: In this scenario, one can move the component to Package A and get the packages built. However during deployment to an org, Package A will fail with an error this component exists in Package B. To mitigate this one should do the following:

  • Deploy a version of Package B which removes the lock on the metadata component using deprecate mode. Some times this needs extensive refactoring to other components to break the dependencies. So evaluate whether the approach will work.

  • If not, you can go to the UI (Setup > Packaging > Installed Packages > <Name of Package> > View Components and Remove) and remove the lock for a package.

Managing Package Dependencies

{
  "packageDirectories": [
    {
      "path": "util",
      "default": true,
      "package": "Expense-Manager-Util",
      "versionName": "Winter ‘20",
      "versionDescription": "Welcome to Winter 2020 Release of Expense Manager Util Package",
      "versionNumber": "4.7.0.NEXT"
    },
    {
      "path": "exp-core",
      "default": false,
      "package": "ExpenseManager",
      "versionName": "v 3.2",
      "versionDescription": "Winter 2020 Release",
      "versionNumber": "3.2.0.NEXT",
      "dependencies": [
        {
          "package": "ExpenseManager-Util",
          "versionNumber": "4.7.0.LATEST"
        },
          {
          "package": "TriggerFramework",
          "versionNumber": "1.7.0.LATEST"
        },
        {
          "package": "External Apex Library - 1.0.0.4"
        }
      ]
    }
  ],
  "sourceApiVersion": "47.0",
  "packageAliases": {
    "TriggerFramework": "0HoB00000004RFpLAM",
    "Expense Manager - Util": "0HoB00000004CFpKAM",
    "External Apex Library@1.0.0.4": "04tB0000000IB1EIAW",
    "Expense Manager": "0HoB00000004CFuKAM"
  }
}

Let's unpack the concepts utilizing the above example:

• There are two unlocked packages

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

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

Build Options with Unlocked Packages

During these situations, we ask you to consider whether the time taken to build all validated packages on an average is within your build budget, If not, here are your options

Handling metadata that is not supported by unlocked packages

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

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:

• User-entered data in custom objects and fields are deprecated and not deleted. Admins can export such data if necessary.

• An object such as an Apex class is deprecated and not deleted if it’s referenced in a Lightning component that is part of the package.

Source Packages

Source packages support destructive changes using folder structure to demarcate components that need to be deleted. One can make use of pre-destructive and `post-destructive folders to mark components that need to be deleted

The package installation is a single deployment transaction with components that are part of pre/post deployed along with destructive operation as specified in the folder structure. This would allow one to refactor the current code to facilitate refactoring for the destructive changes to succeed, as often deletion is only allowed if there are no existing components in the org that have a reference to the component that is being deleted

Data Packages

Data packages utilize sfdmu under the hood, and one can utilize any of the below approaches to remove data records.

Approach 1: Combined Upsert and Delete Operations

One effective method involves configuring SFDMU to perform both upsert and delete operations in sequence for the same object. This approach ensures comprehensive data management—updating and inserting relevant records first, followed by removing outdated entries based on specific conditions.

Upsert Operation: Updates or inserts records based on a defined external ID, aligning the Salesforce org with new or updated data from a source file.

Delete Operation: Deletes specific records that meet certain criteria, such as being marked as inactive, to ensure the org only contains relevant and active data.

Approach 2: Utilizing deleteOldData

Another approach involves using the deleteOldData parameter. This parameter is particularly useful when needing to clean up old data that no longer matches the current dataset in the source before inserting or updating new records.

• Delete Old Data: Before performing data insertion or updates, SFDMU can be configured to remove all existing records that no longer match the new dataset criteria, thus simplifying the maintenance of data freshness and relevance in the target org

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

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.

• The presence of an additional type attribute within a package directory will further inform sfp of the specific nature of the package. For instance, types such as "data" for data packages or "diff" for diff packages

The sfdx-project.json file outlines various specifications for Salesforce DX projects, including the definition and management of different types of Salesforce packages. From the sample provided, sfp (Salesforce Package Builder) analyzes the "package" attribute within each packageDirectories entry, correlating with packageAliases to identify package IDs, thereby determining the package's type as 2GP (Second Generation Packaging).

Consider the following sfdx-project.json

Understanding Package Type Determination using the samplesfdx-project.json

The sfdx-project.json sample can be used to determine how sfp processes and categorizes packages within a Salesforce DX project. The determination process for each package type, based on the attributes defined in the packageDirectories, unfolds as follows:

• Unlocked Packages: For a package to be identified as an Unlocked package, sfp looks for a correlation between the package name defined in packageDirectories and an alias within packageAliases. In the provided example, the "Expense-Manager-Util" under the util path is matched with its alias "Expense Manager - Util", subsequently confirmed through the DevHub with its package version ID, categorizing it as an Unlocked package.

• Source Packages: If a package does not have a corresponding alias in packageAliases, it is treated as a Source package. These packages are typically utilized for organizing source code not intended for release. For instance, packages specified in paths like "exp-core-config" and "expense-manager-test-data" would default to Source packages if no matching aliases are found.

• Specialized Package Types: The explicit declaration of a type attribute within a package directory allows for the differentiation into more specialized package types. For example, the specification of "type": "data" explicitly marks a package as a Data package, targeting specific use cases different from typical code packages.

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.

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

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

sfp build -v <devhub_name> --branch <value> 

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 build -v <devhub_name> --branch <value>  --diffcheck

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.

A package is a collection of metadata grouped together in a directory, and defined by an entry in your sfdx-project.json ( Project Manifest).

// A sample sfdx-project.json with a packag
{
  "packageDirectories": [
    {
      "path": "src-env-specific-pre",
      "package": "env-specific-pre",
      "versionNumber": "4.7.0.NEXT",
    },
     ...
   ]
}

Each package in the context of sfp need to have the following attributes as the absolute minimum\

Creating an Unlocked Package

Creating an Unlocked Package with SF CLI

To create an unlocked package using the Salesforce CLI, follow the steps below:

1. Identify the Package Directory: Ensure that your sfdx-project.json contains an entry for the package you wish to turn into an unlocked package. The entry must include path, package, and versionNumber.

2. Create a Package: If the package does not already exist, create it with the command:

   Copy

   sf package:create --name <package_name> --packagetype Unlocked  --nonamespace -o <alias_for_org>

   Replace <package_name> with the name of your unlocked package, with the package directory specified in your sfdx-project.json, and <alias_for_org> with the alias for your Salesforce org.

3. Ensure that an entry for your package is created in your packageAliases section. Please commit the updated sfdx-project.json to your version control, before proceeding with sfp commands

Creating an Org Dependent Unlocked Package

Creating an Org Dependent Unlocked Package with SF CLI

To create an unlocked package using the Salesforce CLI, follow the steps below:

1. Identify the Package Directory: Ensure that your sfdx-project.json contains an entry for the package you wish to turn into an unlocked package. The entry must include path, package, and versionNumber.

2. Create a Package: If the package does not already exist, create it with the command:

   Copy

   sf package:create --name <package_name> --packagetype Unlocked  --org-dependent      --nonamespace -o <alias_for_org>

   Replace <package_name> with the name of your unlocked package, with the package directory specified in your sfdx-project.json, and <alias_for_org> with the alias for your Salesforce org.

3. Ensure that an entry for your package is created in your packageAliases section. Please commit the updated sfdx-project.json to your version control, before proceeding with sfp commands

Creating a data package

• Identify the Package Directory: Ensure that your sfdx-project.json contains an entry for the package you wish to turn into an unlocked package. The entry must include path, package, and versionNumber.

• Add an additional attribute of "type":"data" \

  Copy

      {
      "path": "path--to--package",
      "package": "name--of-the-package", 
      "versionNumber": "X.Y.Z.[NEXT/BUILDNUMBER]",
      "type": "data", // required for data packages
      }

Creating a diff package

• Identify the Package Directory: Ensure that your sfdx-project.json contains an entry for the package you wish to turn into an unlocked package. The entry must include path, package, and versionNumber.

• Add an additional attribute of "type":"diff" \

  Copy

      {
      "path": "path--to--package",
      "package": "name--of-the-package", 
      "versionNumber": "X.Y.Z.[NEXT/BUILDNUMBER]",
      "type": "diff", // required for data packages
      }

• Ensure a new record is created in SfpowerscriptsArtifact2__c object in your devhub, with the details such as the name of the package, the initial version number, the baseline commit id

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.

3. sales: An example of a domain in your org. Under this particular domain, multiple packages that belong to the domain are included.

4. src-access-mgmt: This package is typically one of the packages that is deployed second to last in the deployment order and used to store profiles, permission sets, and permission set groups that are applied across the org. Permission Sets and Permission Set Groups particular to a domain should be in their respective package directory.

5. src-env-specific: An aliasified package which carries metadata for each particular stage (environment) of your path to production. Some examples include named credentials, remote site settings, web links, custom metadata, custom settings, etc.

6. src-temp: This folder is marked as the default folder in sfdx-project.json. This is the landing folder for all metadata and this particular folder doesn't get deployed anywhere other than a developers scratch org. This place is utilized to decide where the new metadata should be placed into.

7. src-ui: Should include page layouts, flexipages and Lightning/Classic apps unless we are sure these will only reference the components of a single domain package and its dependencies. In general, custom UI components such as LWC, Aura and Visualforce should be included in a relevant domain package.

8. runbooks: This folder stores markdown files required for each release and or sandbox refresh to ensure all manual steps are accounted for and versioned control. As releases are completed to production, each release run book can be archived as the manual steps should typically no longer be required. Sandbox refresh run books should be managed accordingly to the type of sandbox depending if they have data or only contain metadata.

9. scripts: This optional folder is to store commonly used APEX or SOQL scripts that need to be version controlled and reference by multiple team members.

Release configuration is a fundamental setup that outlines the organisation of packages within a project, streamlining across different lifecycle of your project, such as validating, building, deploying/release of artifacts. In flxbl projects, a release config is used to define the concept of a domain/subdomains. This configuration is instrumental when using sfp commands, as it allows for selective operations on specified packages defined by a configuration. By employing a release configuration, teams can efficiently manage a mono repository of packages across various teams.

---
​releaseName: core
pool: core_pool
includeOnlyArtifacts:
  - src-env-specific-pre
  - src-env-specific-alias-pre
  - core-crm
  - telephony-service
excludePackageDependencies:
  - Genesys Cloud for Salesforce
  - Marketing Cloud
releasedefinitionProperties:
  changelog:
    workItemFilters:
      -  BRO-[0-9]{3,4}
    workItemUrl: https://bro.atlassian.net/browse
    limit: 30

The below table list the options that are currently available for release configuration

Release Definition Properties

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

Scenario 1 : Build All

1. Trigger creation of artifact for package A

2. Once A is completed, trigger creation of artifacts for packages B & C **,**using the version of A, created in step 1

3. Once C is completed, trigger creation of package D

Scenario 2 : Build with diffCheck enabled on a package with no dependencies

In this scenario, where only a single package has changed and diffCheck is enabled, the build command will only trigger the creation of Package B

Scenario 3 : Build with diffCheck enabled on changes in multiple packages

In this scenario, where there are changes in multiple packages, say B & C, the build command will trigger the creation of artifacts for these packages in parallel, as their dependent package A has not changed (hence fulfilled). Please note even though there is a change in C, package D will not be triggered, unless there is an explicit version change of version number (major.minor.patch) of package D

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

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.

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": {
    "sfpowerscripts":{
      "scratchOrgDefFilePaths":{
        "enableMultiDefinitionFiles": true,
        "packages": {
          "package1":"scratchOrgDef/package1-def.json"
        }
      }
    }
  }
}

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 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",
       "user@colaorg.com.au.sit
      ]
    },
     ...
   ]
}

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 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.

{
  "packageDirectories": [
    {
      "path": "core",
      "package": "core-package",
      "versionName": "Core 1.0",
      "versionNumber": "1.0.0.NEXT",
      "default": true,
      "buildCollection": [
        "core-package",
        "featureA-package",
        "featureB-package"
      ]
    },
    {
      "path": "features/featureA",
      "package": "featureA-package",
      "versionName": "Feature A 1.0",
      "versionNumber": "1.0.0.NEXT"
       "buildCollection": [
        "core-package",
        "featureA-package",
        "featureB-package"
      ]
    },
    {
      "path": "features/featureB",
      "package": "featureB-package",
      "versionName": "Feature B 1.0",
      "versionNumber": "1.0.0.NEXT",
      "buildCollection": [
        "core-package",
        "featureA-package",
        "featureB-package"
      ]
    }
  ],
}

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.

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"
            }
   }
 }

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.

To ensure salesforce deployment requirements for source packages, each Apex class within the source package must achieve a minimum of 75% test coverage. This coverage must be verified individually for each class. It's imperative that the test classes responsible for this coverage are included within the same package.

During the artifact preparation phase, sfp cli will automatically identify Apex test classes included within the package. These identified test classes will then be utilised at the time of installation to verify that the test coverage requirement is met for each Apex class, ensuring compliance with Salesforce's deployment standards. When there are circumstances, where individual coverage cannot be achieved by the apex classes within a package, one can disable 'optimized deployment' feature by using the attribute mentioned below.

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

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

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:

   • API Name: Validate that the API name within the metadata file accurately reflects the new version.

   • Version Number: Update the versionNumber in your metadata file to represent the new version clearly.

   • Default Version: Confirm that only one version of the Entitlement Process is set as Default to avoid deployment conflicts.

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

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:

1. Retrieval and Comparison: Initially, picklists defined within the packages marked for deployment will be retrieved from the target org. These retrieved values are then compared with the local versions of the picklists.

2. Update on Change Detection: Should any discrepancies be identified between the local and retrieved picklists, the differing values will be updated in the target org using the Salesforce Tooling API.

3. Handling New Picklists: During the retrieval phase, picklists that are present locally but absent in the target org are identified as newly created. These new picklists are deployed using the standard deployment process, as Salesforce permits the deployment of new picklists from unlocked packages.

4. Picklist Enabled Package Identification: Throughout the build process, the sfp cli examines the contents of each unlocked package artifact. A package is marked as 'picklist enabled' if it contains one or more picklist(s).

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. sfp allow you to provide a path to a shell script (Mac/Unix) / batch script (on Windows).

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

// Command to deploy with baseline
sfp install -u qa \
           --artifactdir artifacts \
           --skipifalreadyinstalled --baselineorg devhub

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.

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 deploy 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

Aliasify enables deployment of a subfolder in a source package that matches the target org. For example, you have a source package as listed below.

During Installation, only the metadata contents of the folder that matches the alias gets deployed. If the alias is not found, sfp will fallback to the 'default' folder. If the default folder is not found, an error will be displayed saying default folder or alias is missing.

// Demonstrating package directory with aliasfy
{
  "packageDirectories": [
      {    
      "path": "src/src-env-specific-alias-post",
      "package": "src-env-specific-alias-post",
      "versionNumber": "2.0.10.NEXT",
      "aliasfy" : true
    }

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.

// Sample package 

{
  "packageDirectories": [
      {    
      "path": "src/core-crm",
      "package": "core-crm",
      "versionNumber": "2.0.10.NEXT",
      "enableFHT" : true,
      "enableFT" : true
    }

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.

// Demonstrating package by disabling flow activation
{
  "packageDirectories": [
      {    
      "path": "src/order-management",
      "package": "order-management",
      "versionNumber": "2.0.10.NEXT",
      "enableFlowActivation" : false
    }

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.

2. Credentials Setup: Find the section dedicated to setting up publishing credentials or authentication.

3. Follow Steps: Adhere to the detailed steps provided by your registry to configure your system for publishing.

When working with sfp and managing artifacts, it’s required to use a private NPM registry. This allows for more control over package distribution, increased security, and custom package management. Here are some popular NPM compatible private registries, including instructions on how to configure NPM to use them:

GitHub Packages

GitLab NPM Registry

Azure Artifacts

JFrog Artifactory

MyGet

Utilising publish command

• Each of these registries offers its own advantages, and the choice between them should be based on your project’s needs and existing infrastructure.

• Utilize the parameters in sfp publish and provide the npmrc file along with activating npm

Tagging an artifact

sfp's publish command provides you with various options to tag the published artifacts in version control. Please note that these tags are utilized by sfp's build command to determine which packages are to be built when used with diffcheckflag

The fetch command provides you with the ability to fetch artifacts from your artifact registry to your local file system. Artifacts once fetched from your registry can the be used for installation or for further analysis The fetch command requires a release definition file as the input. Let's assume you have the following release definition file with the name of the file as Sprint2-13-11.yaml

One can use the fetch command to fetch all the artifacts by issuing the command as shown below

Please note the scope flag, the scope flag should match exactly the scope that was provided during publish command

mergeMode adds an additional mode for deploying aliasified packages with content inheritance. During package build, the default folder's content is merged with subfolders that matches the org with alias name, along with subfolders able to override inherited content. This reduces metadata duplication while using aliasifed packages.

Note in the image above that the AccountNumberDefault__c field is replicated in each deployment directory that matches the alias.

The table below describes the behavior of each command when merge mode is enabled/disabled.

Before merge mode, the whole package was "force ignored." With merge mode, you have the option to allow push/pull from aliasfy packages by not ignoring the default subfolder.

sfp provides two commands to install artifacts into a target org, sfp install and sfp release. While sfp install installs a set of artifacts from a provided directory into a target org, sfp release allows you to install a defined collection of artifacts from an artifact registry directly into a target org, providing you with the consistency required in a pipeline. sfp release is a combination of predominantly fetch and install commands, and the sequence can be explained with the below image

The release command is invoked by using the command sfp release with the inputs as shown below

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

A release definition is a YAML file that carries attributes of artifacts and other details. A release definition is the main input for a release command.

release: Sprint-2-13-11-6844956242
skipIfAlreadyInstalled: true
artifacts:
  feature-management: 1.0.19-6844956242
  apex-logger: 1.0.20-89
promotePackagesBeforeDeploymentToOrg: prod
changelog:
  workItemFilters:
    - (FGK|FFK)-[0-9]{3,4}
  workItemUrl: https://flxbl.atlassian.net/browse
  limit: 30

Lets examine closely the above release defintion file and understand the various attributes and it purposes

release: Sprint-2-13-11-6844956242

This defines the name of the release. this value will be utilised to generate changelogs or as an identification for other systems to understand what release went into an org

skipIfAlreadyInstalled: true

This attribute determines whether artifacts should be skipped from installing if the same version number is already installed in the target org

artifacts:
  feature-management: 1.0.19-6844956242
  apex-logger: 1.0.20-89

This attribute determines which artifacts constitute the provided release.

promotePackagesBeforeDeploymentToOrg: <targetOrgAlias>

The above attribute determines whether an artifact of type unlocked package should be promoted before installing into the target org as provided by the alias. If the alias of the requested org and the targeOrgAlias matches, the unlocked packages are promoted before installing into the org

changelog:
  workItemFilters:
    - (FGK|FFK)-[0-9]{3,4}
  workItemUrl: https://flxbl.atlassian.net/browse
  limit: 30

Here is a run down of all attributes that make up a release definition

// An example where validate is utilized against a pool 
// of earlier prepared scratch orgs with label review
 
sfp validate pool  -p review \
                   -v devhub  \
                   --diffcheck

// An example where validate is utilized against a target org 
sfp validate org -u  ci \
                 -v devhub  \
                 --installdeps  \

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

• Checks accuracy of metadata by deploying the metadata to a org

• Triggers Apex Tests

• Validate Apex Test Coverage of each package (default: 75%)

• Toggle between different modes for validation

  • Individual

  • Fast Feedback

  • Thorough (Default)

  • Fast Feedback Release Config

  • Thorough Release Config

• [optional] - Validate dependencies between packages for changed component

• [optional] - Disable diff check while validating, this will validate all the packages in the repository

• [optional] - Disable parallel testing of apex tests, this will validate apex tests of each package in synchronous mode

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
    },
     ...
   ]
}

sfp has a comprehensive collection of validation techniques one can adopt according to requirements of your projects. Read on more about various validation modes to achieve your objective

Validate Modes

Sequence of Activities

The following are the list of steps that are orchestrated by the validate command If used with pools

• Fetch a scratch org from the provided pools in a sequential manner or

If used against a provided org

• Authenticate to to the provided target org

• Build packages that are changed by comparing the tags in your repo against the packages installed in the target

• For each of the packages (internally calls the Install Command) Thorough Mode (Default)

  • Trigger Apex Tests if there are any apex test in the package

  • Validate test coverage of the package depending on the type of the package (source packages: each class needs to have 75% or more, unlocked packages: packages as whole need to have 75% or more)

  Fast Feedback Mode

  • Trigger selective Apex Tests based on impact analysis of the changes in the package

  • Skip coverage calculations

  • Skip deployment of package if the descriptor is changed

  • Skip deployment of top level packages direct dependency on the package containing changed components

  Individual Mode

  • Ignore packages that are installed in the scratch org (basically eliminate the requirement of using a pooled org)

  • Compute changed packages by observing the diff of Pull/Merge Request

  • Validate each of the changed packages (install any dependencies) using Thorough Mode

  Fast Feedback Release Config Mode

  • Inherit Fast Feedback Mode Features but filtered using a release configuration file containing list of packages to focus validation on

  • Deploy only change packages in the list by comparing against what is installed in the org

  Thorough Release Config Mode

  • Inherit Thorough Mode Features but filtered using a release configuration file containing list of packages to focus validation on

  • Deploy only change packages in the list by comparing against what is installed in the org

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

The project analysis command helps you analyze your Salesforce project for potential issues and provides detailed reports in various formats. This command is particularly useful for identifying issues such as duplicate components, hardcoding of environment configuration metadata and so fort the

Usage

sfp project:analyze [flags]

Common Use Cases

The analyze command serves several key purposes:

1. Runs various available linters across the project

2. Generating comprehensive analysis reports

3. Integration with CI/CD pipelines for automated checks

Available Flags

Scoping Analysis

The command provides three mutually exclusive ways to scope your analysis:

1. By Package: Analyze specific packages

   Copy

   sfp project:analyze -p core,utils

2. By Domain: Analyze all packages in a domain

   Copy

   sfp project:analyze -d sales

3. By Source Path: Analyze a specific directory

   Copy

   sfp project:analyze -s ./force-app/main/default

Output Formats

The command supports multiple output formats:

• Markdown: Human-readable documentation format

• JSON: Machine-readable format for integration with other tools

• GitHub: Special format for GitHub Checks API integration

GitHub Integration

When running in GitHub Actions, the command automatically:

1. Creates GitHub Check runs for each analysis

2. Adds annotations to the code for identified issues

3. Provides detailed summaries in the GitHub UI

Examples

1. Basic analysis of all packages:

   Copy

   sfp project:analyze

2. Analyze specific packages with JSON output:

   Copy

   sfp project:analyze -p core,utils --output-format json

3. Analyze with strict validation:

   Copy

   sfp project:analyze --fail-on duplicates --fail-on-unclaimed

4. Generate reports in a specific directory:

   Copy

   sfp project:analyze --report-dir ./analysis-reports

Validation processes often aim 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.

To streamline the validation process and focus it on specific domains, employing release config based modes is highly recommended. This approach limits the scope of validation, enhancing efficiency and reducing time.

 sfp validate org        -u ci 
                         -v devhub \
                         --diffcheck \
                         --mode=thorough-release-config \
                         --releaseconfig=<path-to-release-config>

In the above example the changes are only validated against the packages as mentioned in the provided release config

Pools are defined by creating a pool definition file. The file can be placed in a directory within your repository.

The below configuration details a pool with tag 'DEV-POOL' allocated with 20 scratch orgs. Read on below to understand other configurations that are available

{
    "tag": "DEV-POOL",
    "maxAllocation": 20,
    "expiry": 10,
    "batchSize": 10,
    "configFilePath": "config/project-scratch-def.json",
    "relaxAllIPRanges": true,
    "installAll": true,
    "enableSourceTracking": true,
    "retryOnFailure": true,
    "succeedOnDeploymentErrors": true,
    "fetchArtifacts": {
        "npm": {
            "scope": "myproject",
    }
}