This post serves as a guide on how to generate package.xml files natively via the SFDX CLI to help improve developer workflow. If you are interested in learning more, I am hosting a session during Salesforce Apex Hours on November 3, 2018, at 10am EST. Register here.
The package.xml is an xml file needed to retrieve the metadata source from a Salesforce instance (configuration and code) and deploy metadata (configuration and code) back to the org or to another Salesforce instance. It defines the various components of which your app consists. Hence, if you are building and deploying a Salesforce application at scale, it’s important to understand how to generate the package.xml and maintain it within your version control.
Most of the IDEs (Mavensmate, ForceCode, or Eclipse IDE) that were built and supported prior to SalesforceDX provided a UI that allowed the developer to select components and generate the package.xml automatically under the hood.
The screenshot below shows the old user interface that allowed developers to pick and choose components. The IDE had logic to build the package.xml file.
Eclipse IDE and Mavens components picker screen
Fast forward to the world of SalesforceDX. If you are using scratch orgs, the package.xml is automatically handled by the CLI under the hood so that you no longer have to worry about generating or versioning the file.
Not all companies have adopted complete source-driven development and a scratch org based development model yet.
There are multiple reasons, in my experience, that many ISVs and System Integrators have not adopted scratch orgs. Here are a few examples:
- If your application involves building an extension package on top of existing managed package applications like Health Cloud, CPQ, Financial Services Cloud, etc, some of these apps require specific permission set licenses that are not yet available in scratch orgs. Also, these apps involve so much configuration that it’s almost easier to create sandbox environments from Trialforce templates for development than scripting all of these via DX. (Safe Harbor — There are snapshots and templating features that are planned and may resolve this issue.)
- Many organizations do not have technical architects or senior developers who can script the customizations needed to set up scratch orgs using SalesforceDX.
- Not all Salesforce Administrators are comfortable with the command-line interface of SalesforceDX.
- Not all features and metadata are supported yet in SalesforceDX.
I strongly encourage the use of SalesforceDX and leveraging scratch orgs if they suit your needs. If you aren’t yet convinced, be sure to check the latest release of SalesforceDX CLI for the winter for some cool enhancements.
Salesforce recently released DX support for a VS Code extension for non-scratch orgs. The extension allows you to build apps with developer and sandbox environments and not just using the scratch-org model. The complete documentation on how to use this can be read here.
There is also documentation from Nathan Totten, the Salesforce product owner for VS Code extensions, that explains the migration from Eclipse IDE to the VS Code and leveraging VS Code.
However, you will notice that you still need to manually provide the package.xml in the manifest folder.
There are tools like package.xml builder or workbench to retrieve source files and generate a package.xml. These tools are great! However, you can do bit of shell scripting and use unmanaged packages or change sets to generate the package.xml natively via the SFDX CLI and improve your developer workflow.
Below is the shell script that can generate a package.xml from Salesforce unmanaged/managed packages or change sets.
In order to use this in your project root folder, add a scripts folder and a shell script file named generatepkgXML.sh with the script contents from the above gist.
In order to generate a package.xml from an unmanaged/managed package, run the below command from your terminal once you cd into the project folder.
./scripts/generatepkgXML.sh <org_alias> <packageName/changesetName>
<org_alias> stands for the org alias of your org that you authenticate to retrieve/deploy source
<packageName> This will be your managed package name or unmanaged package name or change set name.
The above script command will fail if you have not authenticated to the Salesforce environment via CLI or extension or you have misspelled the change set or package name.
Command Prompt Terminal that executes the script
Lets quickly summarize the Developer workflow to do org-based development using Salesforce Extension For VS Code + Package Builder In Salesforce (Unmanaged/Managed/Change set builder) + New SalesforceDX CLI v44.0
For ISV Apps
- If you are building an ISV package, create an unmanaged package (Note that an unmanaged package can be created and deleted from the package manager in Salesforce) and add all the config and code to retrieve. Any config that’s added to the org needs to go into the unmanaged package. If you already have a managed package, you can use the package name for subsequent steps.
- Create project in VS Code with the default manifest and authenticate to the org.
- Create the Scripts folder and add the generatepkgXML.sh bash script.
- Run ./scripts/generatepkgXML.sh <org_alias> <packageName> to generate the package.xml in the manifest folder to retrieve all the metadata components. Here <packageName> is the unmanaged package name. Example: If your package name is HRApp and org alias is Devorg then the script is ./scripts/generatepkgXML.sh Devorg “HRApp”
- Retrieve the source by using the retrieve from source feature as shown in the screenshot. Note that the source retrieved is now in DX format and much easier to track changes. (Keeping source in DX format is also the first step towards moving to unlocked packages).
The rule of thumb to follow is that anything you configure in the org(Objects/workflows/flows/Page Layouts, List Views, Record Types and many) or code (apex/vf/lightning components) should be added to the unmanaged package so that you can easily retrieve them.
NOTE : Unmanaged packages easily track dependencies between the components and dependencies are automatically handled.
For SI Apps Leveraging Change Sets
- Create a Change Set and add all the components that you need to move from one org to the other.
- Create a VS Code project with the default manifest and authenticate to the org where you need to extract metadata from.
- Create a Scripts folder and add the generatepkgXML.sh bash script.
- Run ./scripts/generatepkgXML.sh <org_alias> <changeset> to generate the package.xml in manifest folder to retrieve all the metadata components. Here <packageName> is the change set name. (Example: If your change set name is StackApp and org alias is mysandbox then the the script is ./scripts/generatepkgXML.sh mysandbox “StackApp”).
- Retrieve the source.
- Authorize the target org used for the deployment and alias with a name different than source org. Set it as the default org.
- Deploy the source to the target org using the deploy command as shown below.
NOTE : Change sets can have components without their dependencies, which are ideal if you want to add a few components and move to other environments.
In short, with a bit of shell script, non-scratch org support of Salesforce extension for VS Code and package builder (change sets and ability to create unmanaged package container) is possible.
I don’t miss component selection screen of Mavensmate or the Eclipse plugin for Salesforce App development.
Also, the DX source format is much more readable than the previous source format and it’s easy to transform from one format to another.
For Windows users: You will need the ability to run a bash program — this guide should help you get started.
I cannot wait for further improvements to the “Salesforce Extensions for VS Code”. I have completely shifted to the VS Code editor and “Salesforce Extensions for VS Code” for Salesforce application development and enjoy its features; running test classes, replay debugger, deploying change sets via VS Code Extension and many more.
I am doing a community talk on Apex Hours On this, so in case you are interested check the details here.
Visit www.codescience.com/services today to learn how we can help you thrive on the AppExchange.
