Creating an Unlocked Package

Updated 3 months ago by Copado Solutions

Creating an Unlocked Package
  1. Open the Packages tab and click on New to create a new Package record.
  2. Select Salesforce Package as record type.

  1. Fill in the required fields:
    1. Package Name: Give your package a name. Please note that blank spaces are not allowed.
    2. Package type: Select Unlocked.
    3. Source Org Credential: The org credential from where the metadata of the package is going to be retrieved.
    4. Package Repository: This is the repository where the package will be stored:
      1. Packages can be saved in a single repository or independently in different repositories.
      2. The metadata of each package is saved in a folder labeled with the name of the package.
    5. Target Dev Hub Org: The org credential of the dev hub org which will be used to create and store the package and its versions.
    6. Source Api Version: The API version with which the source of your package is compatible. This field is important if you are using a metadata type that has changed in a recent Salesforce release.
  2. Other relevant fields in the Salesforce Package record:
    1. Package Id: Related package identifier. It is used as a package Id for package version creation and also used in the sfdx-project.json file as a package alias.
    2. Description: Add a description for the package.
    3. Package Namespace: This field is not required for unlocked packages.
    4. No Namespace: Enables the creation of a package with no namespace and is available only for unlocked packages.
    5. Sfdc Login Url: The login URL that the force:auth commands use. If this is not specified, the default will be login.salesforce.com. Override the default value if you want users to authorize to a specific Salesforce instance.
  3. Click on Save.

Loading Metadata into an Unlocked Package

Once you have created the unlocked package, you can start loading metadata:

  1. Open the Package record you have created and click on Manage Metadata::
  2. You will see a metadata grid with all the metadata included in the selected org credential. Select the metadata you want to include in the package (you can create, for instance, a Service package with classes, objects, fields, custom labels and so on related to cases):
  3. Once you have selected all the necessary components, click on Save. Copado will create a new folder in the master branch of the selected Git repository and will commit the selected metadata from the source org credential.
  4. Click on the Back button to return to the record page.

Generate a Project Definition File

A Salesforce DX Project Configuration file contains all the information needed in order to create an unlocked package.

To create a project definition file, navigate to the Package record and click on Generate Project Definition File. You will then see a summary of the file:

Versioning an Unlocked Package

A package version is a fixed snapshot of the content of the package and its related metadata. The package version lets you manage changes and track the differences each time you release or deploy a specific set of changes.

To generate a new version of a package, follow these steps:

  1. Open the Package record and click on Generate New Version:

If you are creating the first version of your package, you will see the following warning: “You need to create a package first to be able to generate beta version”:

  1. Click on Generate package to create the unlocked package.
  2. Once the package has been successfully generated, or if you had already created the package and just wanted to create a new version, click again on Generate New Version to create a new version of the package.
  3. In the Preview Details section, provide the following information:
    1. Give your version a name and provide a version number. Please note that version numbers must be in major.minor.patch.build format (e.g. 1.0.0.0).
    2. Add a description of your package (e.g. a summary of the features).
    3. Provide an installation key. This is an optional parameter for key-protected packages. If you leave it empty, the installationkeybypass parameter will be automatically set to true:

  1. Once you are done, click on Generate Beta Version to create a new version of the package that can be installed.
You can’t install beta packages in a production org. This is a safeguard to make sure the package version you release is ready for production. If you know that a version is ready to go live, you can promote the package version to Released.

 Promote Beta Version to Released Version

Prior to installing your package in a production org, you need to promote it to Released.

To do that, follow these steps:

  1. Navigate to the Package Versions related list and open the record of the version you would like to promote:

  1. On the drop-down menu, click on Promote Beta to Release:

  1. You will see a screen with a summary of the definition file:

 

  1. Click on Promote Package.
  2. Once the package has been promoted, the Package Version record will be automatically flagged as Is Released:

 

How did we do?