Deployments of SFDC and SFDX Unlocked Packages

Deployments of SFDC and SFDX Unlocked Packages

Written by Stefan Abramiuk, Technical Architect at PolSource

unlocked packagesIn January 2019, Salesforce released a functionality called Unlocked Packages. This is another functionality extending the possibilities of SFDX CLI (Command Line Interface), and its purpose is to facilitate the transfer of metadata between environments. Will it revolutionize the way applications are implemented in Salesforce environments? Let’s see what options we have and draw conclusions.

We have already learned that Salesforce is an independent organism, thus it differs considerably from environments based on Java or Node JS. Due to the lack of direct access to the operating system, the access is limited through the interface only (API), structurally, it is more similar to SaaS (Software as Service) than a typical PaaS. API limitations make operations such as deployment much more complex. Here, unfortunately, no one can promise that on Monday it will be possible to execute rollback after Friday’s deployment. The Metadata API has its own rights which cannot be worked around and the available tools have too simple functionalities to provide complete support. Obviously, there are some devotees who write their own Metadata API client applications and, sometimes, such tools appear on the GitHub; however, without any support they soon become obsolete. That also makes it impossible to use them commercially. So, are we doomed to experience that nuisance? Maybe we should start with a little theory.

Salesforce gives us a few models of application development which are based on the same ALM (Application Lifecycle Management). 

We arrange them in the following structure:

  1. Org Based
    1. Change Sets
    2. Managed/Unmanaged Packages
  2. Org-Code hybrid
  3. Source Code based
    1. SFDX/Metadata API
    2. Unlocked Packages

Each of them has their own purpose, depending on the level of complexity of our deployment. Naturally, none of those models exclude the use of the version control system (VCS).

Org Based

Change Sets

An example structure of transferring functionalities through Change Sets.

change sets

For those who are not yet familiar with Change Sets, they can be described in short as a programmer – or administrator-created package made of environment (sandbox) components. The model is by all means appropriate for small deployments, since it does not require any additional tools and it is easy in use.

Managed/Unmanaged Packages

A package is always installed from the developer environment.

managed unmanaged packages

Basically, we should separate these two types, as they usually have another purpose. However, from the perspective of software delivery, both of the processes look identical. As was the case with Change Sets, a package is made on the developer environment so that it can later be installed in another environment. Unfortunately, it requires a separate developer environment, which is our Source of Truth. The code included in Managed Package cannot be viewed, nor edited. It is possible to expose API for potential extensions and thus gain full control over what will happen after installation. Unmanaged Packages, on the other hand, leave the code open for editing and it can be changed by a programmer after installation.

Org-Code Hybrid

The Metadata API is perfect for moving metadata between environments..

org code hybrid

You may not know that this model is most commonly used at the moment. A developer has a Sandbox for creating functionality so that components can be extracted later by means of the Metadata API. Such components, in the form of files such as XML, are transferred onto the next org. Obviously, most everyone is now using the GIT as a repository of those components, but this model is difficult to manage later when there are a lot of programmers or teams that provide software to the same production environment in parallel.

Source Code Based

Now let’s turn everything we said before upside down. Our repository becomes the source of truth.

SFDX/Metadata API

An example of a model of implementation and deployment by means by SFDX and CI tool.

SFDX / Metadata API

Since SFDX came into being, the life of many programmers has become much easier. We have gained huge flexibility thanks to Scratch Orgs. Programmers may provide functionalities almost totally independently from the sheer provision of metadata. The change in the organisational structure of directories and files finally enables organisation of these metadata. It helps a lot in the management of packages to be delivered.

application life management

Source: [1]

You are likely to have seen that scheme or a similar one before. It exposes one weakness of that solution. Delivery of software to a specific environment is still similar to that which happens in the hybrid model. Admittedly, we take a package from our repository, but the very process of loading it to another environment is not always smooth. Again, we can encounter
the multicoloured process, the problem of dependencies between components and, first and foremost, dependence from the target environment. So where is our famous Monday rollback?

Unlocked Packages

A package is set up in Deb Hub environment; however, it is created from the metadata kept, for example, in CVS (GIT).

unlocked packages

At long last, we have got to the bottom – that is the newest functionality, also known as the Second Generation Packages (2GP). What makes it different from that previously described? It is another hybrid, but this time between SFDX/Metadata API and Unmanaged Packages. In this model the functionality is created on scratch orgs and its code is delivered to the repository, as in the previous point. Only subsequently does the difference become visible. On the basis of the metadata gathered in files we can create a package with the name and number of the version. We can install such a package in any environment or any scratch org. The model is ideal for implementations within a single organisation; it is rather unsuitable to be sold to clients, because the code is open for view and edition, as in the case of Unmanaged Packages.

Unlocked Packages – What is happening under the bonnet?

A few commands to start with

Both Managed and Unmanaged Package components are added to the package via UI. If someone has already had an opportunity to do it, they know how tedious this task is, and how many mistakes can be made throughout that process. In the case of Unlocked Packages we indicate a folder(s) which we want to include and the whole thing is done.

So now that we have got our “code”, what comes next?

We create a package, name it and indicate its source:

sfdx force:package:create -n HelloWrold -d “<my description>” -r force-app -t Unlocked -v DevHubOrg

Our file sfdx-project.json looks more or less like this:

“packageDirectories”: [
“path”: “force-app”,
“default”: true,
“package”: “HelloWrold”,
“versionName”: “ver 0.1”,
“versionNumber”: “0.1.0.NEXT”
“namespace”: “”,
“sfdcLoginUrl”: “”,
“sourceApiVersion”: “43.0”,
“packageAliases”: {
HelloWrold“: “0Hoxxx”

The next step is to create the version of our package. We can set up a password/key which will protect it from unauthorised use.

sfdx force:package:version:create -p HelloWrold -d force-app -k test1234 —wait 10 -v DevHubOrg

If everything is ok, we will get the package version number, and from now on we can install it on our sandboxes and scratch orgs. Depending on the model adopted in the project, we can create a lot of versions which together comprise the release, and finally, we can label the one which is accepted for installation on the production.

This operation is carried out with the command promote in the following way:

sfdx force:package:version:promote -p 04t…

What should be included in the package?

As already mentioned, a package should be prepared, and the flexible structure of SFDX directories is ideally suited here. Create a separate directory for each package inside the directory force-app. Thanks to that, in the process of package creation you indicate only one directory, e.g. force-app/packageB. Obviously, you may want to put everything in one package, which is not bad in some cases. But, if you have a few teams providing a solution to the same production environment, you need to think of giving some structure to packages.

It is worth creating a basic package, i.e. a package which contains elements common to the other solutions on the one hand, and at least one package for each team, on the other hand. The basic package should not be dependent on any other; while team-specific or project-specific packages may (but not necessarily) be dependent on the basic package.

If we arrange it properly in directories, the creation of a package will be a breeze.

force app

When should you create a package?

A package is created in order to deliver software to other environments. What this means is that it needs to have some finite and tested elements which make a coherent whole. It is not often that we want to deliver a single task on the UAT (User Acceptance Test) immediately after its completion. That is why the suggestion presented in the diagram below is based on two deployment methods.

  1. Metadata API – for DEV and QA, Scratch Org
  2. Unlocked Packages – for all the other environments

unlock package

As always, programmers work on scratch orgs or developer sandboxes. QA teams work on a QA sandbox. When a sprint is about to close, the delivered functionalities are collected
in one place in the repository (it can be a branch or a tag) so that a package version may be created out of them. Please note that thanks to that we do not need branches in a repository for environments such as the UAT or PreProd. We have 100% certainty that the code which we are installing on the SIT will get to the Production.

Where is the catch?

Most likely, everyone will immediately set out to look for licence restrictions or similar problems typical of cloud-based solutions. Fortunately, the solution is totally free. When it comes to restrictions, you can try to find them only in the types of metadata which are supported. All the differences are clearly shown in the Metadata Coverage Report. One thing which stands out at the very beginning is the lack of Community support.  However, we need to remember that it is quite a new solution and some work on it will be necessary to make it fully functional.

To sum up

We hope that we have encouraged you to, or at least picked your interest in, Unlocked Packages. Judging from our own experience, we see that clients are more and more in need of modular solutions, quick deployments and rollback options. Will Unlocked Packages manage to satisfy these needs? We think that they will soon. They are worth writing about, testing and investigating. Salesforce quite actively follows the activity on their forums; therefore, seeing that the topic raises interest and earns feedback, Salesforce can put a stronger emphasis on this functionality. We recommend you browse through the trailhead in the context of Unlocked Packages and try them out yourselves.

Have more questions about Unlocked Packages? Contact us today!

Sources and materials

[1] –