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

• git

• NPM

• VS Code

• sf CLI

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 Slack Community. If you are adventurous, contribute!

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

Head to https://source.flxbl.io/flxbl/sfp-pro/releases and download the .tgz file from the one of the releases

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

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

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

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.

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

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

Ensure you have authenticated your local development environment to your DevHub. If you are not familiar with the process, you can follow the instructions provided by Salesforce .

C. Add additional attributes to your Salesforce DX Project

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

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

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

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

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.

SFP

The diagram below depicts the basic flow of the development and test process, building artifacts, and deploying to target environments.

Once you have mastered the basic workflow, you can progress to publishing artifacts to a NPM Repository that will store immutable, versions of the metadata and code used to drive the release of your packages across Salesforce Environments.

References

The list below is a curated list of core sf cli and Salesforce DX developer guides for your reference.

• SF CLI
• sfp

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

• Package Development Model

• Unlocked Package for Customers

• Successfully Creating Unlocked Package

• Salesforce Developer Guide to Unlocked Package

• Unlocked Package FAQ

Advanced Materials

• Anti Patterns in Package Dependency Design

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

Unlocked Package and Test Coverage

Unlocked Packages, excluding Org-Dependent unlocked packages have mandatory test coverage requirements. Each package should have minimum of 75% coverage requirement. A validated build (or build command in sfp) validates the coverage of package during the build phase. To enable the feedback earlier in the process, sfp provide you functionality to validate test coverage of a package such as during the Pull Request Validation process.

Managing Version Numbers of Unlocked Package

For unlocked packages, we ask users to follow a semantic versioning of packages.

Note that an unlocked package must be promoted before it can be installed to a production org, and either the major, minor or patch (not build) version must be higher than the last version of this package which was promoted. These version number changes should be made in the sfdx-project.json file before the final package build and promotion.

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:

  • If the deployment of the unlocked package is set to mixed, and no other metadata component is dependent on the component, the component gets deleted.

  • 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

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

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

Unlocked packages have two build modes, one with skip dependency check and one without. A package being built without skipping dependency check cant be deployed into production and can usually take a long time to build. sfp cli tries to build packages in parallel understanding your dependency, however some of your packages could spend a significant time in validation.

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

• Move to org dependent package: Org-dependent unlocked packages are a variant of unlocked packages. Org-dependent packages do not validate the dependencies of a package and will be faster. However please note that all the org's where the earlier unlocked package was installed, had to be deprecated and the component locks removed, before the new org-dependent unlocked package is installed.

• Move to source-package: Use it as the least resort, source packages have a fairly loose lifecycle management.

Handling metadata that is not supported by unlocked packages

Create a source package and move the metadata and any associated dependencies over to that particular package.

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.

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.

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 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 "Release Configs"

Packages

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

Artifacts

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 a domain

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

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.

Releasing a domain

Releasing an domain involves the process of promoting, installing a collection of artifacts to a higher org such as production, generating an associated changelog for the domain. This process is driven by the release command along with a release definition.

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 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 to organise packages into domains. You can read more about creating a release config in the next section

A diff package is a variant of '' , 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 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

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.

An example of a common metadata component that typically gets overridden is which can span across multiple 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

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

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.

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

• Versioned Artifact: Aligned with sfpowerscripts principle of traceability, every deployment is traceable to a versioned artifact, which is difficult to achieve when you are using a folder to deploy

• Orchestration: Data package creation and installation can be orchestrated by sfpowerscripts, which means less scripting

Defining a Data package

Simply add an entry in the package directories, providing the package's name, path, version number and type (data). Your editor may complain that the 'type' property is not allowed, but this can be safely ignored.

Generating the contents of the data package

Options with Data Packages

Data packages support the following options, through the sfdx-project.json.

Adding Pre/Post Deployment Scripts to Data Packages

Defining a vlocity Data Package

sfpowerscripts support vlocity RBC migration using the vlocity build tool (vbt). sfpowerscripts will be automatically able to detect whether a data package need to be deployed using vlocity or using sfdmu. (Please not to enable vlocity in preparing scratchOrgs, the enableVlocity flag need to be turned on in the pool configuration file)

A vlocity data package need to have vlocityComponents.yaml file in the root of the package directory and it should have the following definition

The same package would be defined in the sfdx-project.json as follows

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

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.

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.

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

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

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.

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.

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

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

Release Definition Properties

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

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

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

// Sample sfdx project json 
{
  "packageDirectories": [
    {
      "path": "./src-env-specific-pre",
      "package": "src-env-specific-pre",
      "versionNumber": "1.0.0.0",
    },
    {
      "path": "./src/frameworks/feature-mgmt",
      "package": "feature-mgmt",
      "versionNumber": "1
    }
  ]
}

// Build a single package
sfp build -v devhub --branch=main -p feature-mgmt

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.

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 domain during a build process in sfp by utilizing specific configurations. Consider the release config example provided in

# 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

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

// Limit build by release config
sfp build -v devhub --branch=main --domain config/sales.yaml

Limiting artifacts by packages

Artifacts to be built can be limited only to certain packages. This could be very helpful, in case you want to build an artifact of only one package or a few while testing locally.

// Limit build by certain packages
sfp build -v devhub --branch=main -p sales-ui,sales-channels

Limiting artifacts by ignoring packages

Packages can be ignored from the build command by utilising an additional descriptor on the package in project manifest (sfdx-project.json)

In the above scenario, src-env-specific-pre will be ignored while build command is invoked

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\

sfp will not consider any entries in your sfdx-project.json for its operations if it is missing 'package' or 'versionNumber' attribute, By default, sfp treats all entries in sfdx-project.json as Source Packages. If you need to create an unlocked or an org depednent unlocked package, you need to proceed to create the packages using the follwing steps detailed below

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.

• Ensure your package directory is populated with an export-json and the required CSV files. Read on here to learn more about data packages

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

• Ensure your package directory is populated with an export-json and the required CSV files. Read on here to learn more about diff packages

• 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

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.

Enable Dev Hub 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.

1. Navigate to the Setup menu

2. Go to Development > Dev Hub

3. Toggle the button to on for Enable Dev Hub

4. Enable Unlocked Packages and Second-Generation Managed Packages

2. Install sfpowerscripts-artifact Unlocked Package

The sfpowerscripts-artifact package is a lightweight unlocked package consisting of a custom setting SfpowerscriptsArtifact2__c that is used to keep a record of the artifacts that have been installed in the org. This enables package installation, using sfp, to be skipped if the same artifact version already exists in the target org.

sf package install --package 04t1P000000ka9mQAA -o <your_org_alias> --security-type=AdminsOnly --wait=120

Waiting 120 minutes for package install to complete.... done
Successfully installed package [04t1P000000ka9mQAA]

Once the command completes, confirm the unlocked package has been installed.

1. Navigate to the Setup menu

2. Go to Apps > Packaging > Installed Packages

3. Confirm the package sfpowerscripts-artifact is listed in the "Installed Packages"

Ensure that you install sfpowerscripts artifact unlocked package in all your target orgs that you intend to deploy using sfp.

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 (https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_unlocked_pkg_install_pkg_upgrade.htm?q=delete+metadata)

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.

sfp utilizes mixed mode while installing unlocked packages to the target org. So any metadata that can be deleted is removed from the target org. If the component is deprecated, it has to be manually removed. Components that are hard deleted upon a version upgrade is found here.

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

// Consider a source package feature-management
// with path as src/feature-management

└── feature-management
    ├── main
    ├──── default
    ├────────  <metadata-contents>
    ├── 
    ├────────  <metadata-contents>
    ├──
    ├────────  <metadata-contents>
    └── test

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.

{
  "name": "CustomObject__c",
  "operation": "Upsert",
  "externalId": "External_Id__c",
  "query": "SELECT Id, Name, IsActive__c FROM CustomObject__c WHERE SomeCondition = true"
}

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.

{
  "name": "CustomObject__c",
  "operation": "Delete",
  "query": "SELECT Id FROM CustomObject__c WHERE IsActive__c = false"
}

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

// Use of deleteOldData
{
  "name": "CustomObject__c",
  "operation": "Upsert",
  "externalId": "External_Id__c",
  "deleteOldData": true
}

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

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

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:  # --> The name of the domain
pool: 
excludeAllPackageDependencies: true
includeOnlyArtifacts:   # --> Insert packages
  - 
releasedefinitionProperties:
  promotePackagesBeforeDeploymentToOrg: prod

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

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": {
               
                "validate": ".forceignore"
            }
   }
 }

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

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,
      "": [
        "core-package",
        "featureA-package",
        "featureB-package"
      ]
    },
    {
      "path": "features/featureA",
      "package": "featureA-package",
      "versionName": "Feature A 1.0",
      "versionNumber": "1.0.0.NEXT"
       "": [
        "core-package",
        "featureA-package",
        "featureB-package"
      ]
    },
    {
      "path": "features/featureB",
      "package": "featureB-package",
      "versionName": "Feature B 1.0",
      "versionNumber": "1.0.0.NEXT",
      
        "core-package",
        "featureA-package",
        "featureB-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": {
    "sfpowerscripts":{
      "":{
        "enableMultiDefinitionFiles": true,
        "packages": {
          "package1":"scratchOrgDef/package1-def.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.

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

The scripts are called with the following parameters. In your script you can refer to the parameters using

Please note scripts are copied into the and are not executed from version control. sfpowerscripts only copies the script mentioned by this parameter and do not copy any additional files or dependencies. Please ensure pre/post deployment scripts are independent or should be able to download its dependencies

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:

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

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

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

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

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.

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.

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.

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,

Skip artifacts if they are already installed

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.

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

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

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

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

sfp artifacts fetch -p Sprint2-13-11.yaml --npm --scope flxbl 

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

In a high velocity project operating on a trunk such as a #flxbl project and with substantial number of packages, manually generating release definition can be a chore. This can eased by using generating the release definition file automatically after every publish command. One can utilise release config along with release definition generate command to automate the process of generating release definitions.

 sfp releasedefinition:generate -b releasedefns  \
                                -c  main  \
                                -d releasedefns_directory \
                                -f  ${{inputs.releaseconfig}} \
                                -n ${{env.RELEASE_NAME}}
                                

The above command will generate a release definition file based on the head of the branch 'main', one can also provide a commit ref ( by providing a commit id to the -c or --gitref flag ) to utilize the latest artifacts on the particular commit. The generated release definition is then written to a directory called releasedefns_directory and pushed to a branch called releasedefns

One can utlilze the --nopush flag, if the intent is only to create a releasedefinition locally and do not push the same to the git repository

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

GitHub Packages acts as a hosting service for npm packages, allowing for seamless integration with existing GitHub workflows. For configuration details, visit GitHub's guide on configuring NPM for use with GitHub Packages.

GitLab NPM Registry

GitLab offers a fully integrated npm registry within its continuous integration/continuous deployment (CI/CD) pipelines. To configure NPM to interact with GitLab’s registry, refer to GitLab's NPM registry documentation.

Azure Artifacts

Azure Artifacts provides a npm feed that's compatible with NPM, enabling package hosting, sharing, and version control. Note: The link provided previously was incorrect. Azure Artifacts information can be found here: Azure Artifacts documentation.

JFrog Artifactory

JFrog Artifactory offers a robust solution for managing npm packages, with features supporting binary repository management. For setting up Artifactory to work with NPM, refer to JFrog’s npm Registry documentation.

MyGet

MyGet provides package management support for npm, among other package managers, facilitating the hosting and management of private npm packages. For specifics on utilizing NPM with MyGet, check out MyGet’s NPM support documentation.

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.

• Follow the instructions on your npm registry to generate .npmrc file with the correct URL and access token (which has the permission to publish into your registry.

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

  --npm                             Upload artifacts to a pre-authenticated private npm registry
  --npmrcpath=<value>               Path to .npmrc file used for authentication to registry. If left blank, defaults to home
                                    directory
  --npmtag=<value>                  Add an optional distribution tag to NPM packages. If not provided, the 'latest' tag is set
                                    to the published version.
  --scope=<value>                   (required for NPM) User or Organisation scope of the NPM package

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

  --gittag                          Tag the current commit ID with an annotated tag containing the package name and version -
                                    does not push tag
  --gittagage=<value>               Specifies the number of days,for a tag to be retained,any tags older the provided number
                                    will be deleted
  --gittaglimit=<value>             Specifies the minimum number of  tags to be retained for a package
  --pushgittag                      Pushes the git tags created by this command to the repo, ensure you have access to the repo

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

validate command helps you to validate 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 prepare command or one could use the a target org for its purpose

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