Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
sfp provides various features to alter the installation behaviour of a package. These behaviours have to be applied as an additional property of a package during build time. The following section details each of the parameters that is available.
sfp is built on the concept of immutable artifacts, hence any properties to control the installation aspects of a package need to be applied during the build command. Installation behaviour of an package cannot be controlled dynamically. If you need to alter or add a new behaviour, please build a new version of the artifact
Attribute | Type | Description | Package Types Applicable |
---|---|---|---|
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
Attribute | Type | Description | Package Types Applicable |
---|---|---|---|
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 positional parameters.
Please note scripts are copied into the artifacts 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
Position | Value |
---|---|
Please note the script has to be completely independent and should not have dependency on a file in the version control, as scripts are executed within the context of an artifact.
Attribute | Type | Description | Package Types Applicable |
---|---|---|---|
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 here.
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:
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.
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.
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.
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?
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.
Enable Versioning: First and foremost, activate versioning in the target org to manage various versions of the Entitlement Process.
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).
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
Attribute | Type | Description | Package Types Applicable |
---|---|---|---|
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.
Package Type | Apex Test Execution during installation | Coverage Requirement |
---|---|---|
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.
This option is only applicable to source/diff packages. Disabling this option will trigger the entire local tests in the org and can lead to considerable delays
Attribute | Type | Description | Package Types Applicable |
---|
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.
Attribute | Type | Description | Package Types Applicable |
---|
sfp-pro | sfp (community) |
---|
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 default folder is deployed to any type of environment, including production unlike when only used with aliasfy mode
The table below describes the behavior of each command when merge mode is enabled/disabled.
When merge mode is enabled, it also supports push/pull commands, the default subfolder is always used during this process, make sure it is not force ignored.
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.
Attribute | Type | Description | Package Types Applicable |
---|
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
Attribute | Type | Description | Package Types Applicable |
---|
While installing a source/diff package, flows by default are deployed as 'Inactive' in the production org. One can deploy flow as 'Active' using the steps mentioned , however, this requires the flow to meet test coverage requirement.
Also making a flow inactive, is convoluted, find the detailed article provided by
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.
This feature is enabled by default, if you would like to disable the feature, set enableFlowActivation to false on your package descriptor
Attribute | Type | Description | Package Types Applicable |
---|
Attribute | Type | Description | Package Types Applicable |
---|
Aliasified packages are available only for Source 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.
Default folder are only deployed to sandboxes
Attribute | Type | Description | Package Types Applicable |
---|
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,
Merge Mode | Default available? | Build | Install | Push | Pull |
---|
Non-merge mode | Merge Mode |
---|
assignPermSetsPostDeployment can be used to assign permission sets that are introduced by the artifact to the target org for any aspects of testing or any other automation usage
preDeploymentScript
string
Run an executable script before deploying an artifact. Users need to provide a path to the script file
unlocked
org-dependent unlocked
source
diff
postDeploymentScript
string
Run an executable script after deploying an package. Users need to provide a path to the script file
unlocked
org-dependent unlocked
source
diff
1
Name of the Package
2
Username of the target org where the package is being deployed
3
Alias of the target org where the package is being deployed
4
Path to the working directory that has the contents of the package
5
Path to the package directory. One would need to combine parameter 4 and 5 to find the absolute path to the contents of the package
enablePicklist
boolean
Enable picklist upgrade for unlocked packages
unlocked
org dependent unlocked
isOptimizedDeployment
boolean
Detects test classes in a source package automatically and utilise it to deploy the provided package
source
diff
Unlocked Package
No
75% for the contents of a package validated during build
Org Dependent Unlocked Package
No
No
Source Package
Yes
Yes, either each classes need to have individual 75% coverage or use the entire org's apex test coverage
Diff Package
Yes
Yes, either each classes need to have individual 75% coverage or use the entire org's coverage
Data Package
No
No
skipDeployOnOrgs
array
Skips installation of an artifact on a target org
org-dependent unlocked
unlocked
data
source
diff
Default metadata is merged into each subfolder | Deploys subfolder that matches enviroment alias name. If there is no match, then default subfolder is deployed (Including production) | Only default is pushed | Only default is pulled |
Default merging not available | Deploys subfolder that matches enviroment alias name. If there is no match, then default subfolder is deployed (Including production) |
Default merging not available | Deploys subfolder that matches enviroment alias name. If there is no match, deploys default (Only sandboxes) | Only default is pushed | Only default is pushed |
Default merging not available | Deploys subfolder that matches enviroment alias name. If there is no match, fails | Nothing to push | Nothing to pull |
reconcileProfiles | boolean | Reconcile profiles to only apply permissions to objects, fields and features that are c |
|
assignPermSetsPreDeployment | array | Apply permsets before installing an artifact to the deployment user |
|
assignPermSetsPostDeployment | array | Apply permsets after installing an artifact to the deployment user |
|
alwaysDeploy | boolean | Deploys an artifact of the package, even if it's installed already in the org. The artifact has to be present in the artifact directory for this particular option to work |
|
enableFHT | boolean | Enable field history tracking for fields |
|
enableFT | boolean | Enable Feed Tracking for fields |
|
enableFlowActivation | boolean | Enable Flows automatically in Production |
|