Retrieving metadata from Salesforce using package.xml and SFDX CLI

Salesforce ecosystem provides a number of tools to retrieve metadata from connected Salesforce environment. There is an option in Salesforce extension pack for vscode to pull metdata from your connected Salesforce environment. But sometimes you still need to pull metadata from unreleated environments for purposes like committing to a git repository or deploying.

Metadata type names can be tricky and it usually difficult to create a package.xml without some googling. Please checkout article on How to create package.xml in Salesforce - With Samples

Retrieving metadata using package.xml

Once you have package.xml, you are only couple of commands away from retrieving metadata with it. Please follow below steps,

1. Make sure you have SFDX CLI tool installed. If not download and install it from SFDX CLI Downlaod
2. Make sure your CLI is connected to the environment from where you need to retrieve metadata. If not use below command to authenticate your Salesforce environment

   sfdx force:auth:web:login -r "https://yourSalesforceEnvironmentUrlHere.com" -a aliasNameHere

3. Copy package.xml to your command line location and create a folder with name "metadata" to store the metadata and run below command

   sfdx force:mdapi:retrieve -r metadata -k ./package.xml -w 5 -u aliasNameHere

You will be able to see a progress status and SFDX should retrieve code and put in your metadata folder as a zip file

Package.xml samples to retrieve Salesforce metadata

Here we will go through how we can create a package.xml to retrieve metadata from Salesforce. Common metadata type samples are also included.

Metadata type names can be tricky and it usually difficult to create a package.xml without some googling. Here we provide a sample package.xml with examples of common types.

Once you have a package.xml, it is relatively easy to retrieve metadata using it and deploy to other environments. There are multiple options for that- Force.com Migration tool/ANT (Outdated), SFDX (Recommended)- How to retrieve code using SFDX CLI.

Package.xml sample with common metadata types

When you are creating package.xml, copy below simple package.xml file as a starting point

Now copy relevant types from below xml and add to your package.xml. Then go to your org and add members tags for the elements you want to retrieve

Script to deploy source/SFDX format code to your sandbox

Salesforce has two differnt formats to store code/metadata now. Conventional Metadata format and new Source/SFDX format.

Usually you can tell the format from folder structure and file format. If code is following some folder structure like force-app/main/default usually it will be in source format. But is it not guaranteed. A better way to confirm is to check object and field metadata files. If field metadata is included inside a .object file, that means that the code is in metadata format. In source/SFDX format, field metadata will be separated into separate files

Script to deploy source format code to sandboxes

Even if we use scratch orgs for development, we still need to use sandboxes for testing, UAT, training etc. We need to convert code in source format to metadata format before can properly deploy the whole codebase to these sandboxes or production. Use below shell script to make this metadata conversion and deployment easy.

How to use

• Create a shell file with .sh extension inside your project folder and copy paste above code.
• Make the file executable with sudo chmod u+x pathToTheShellFileHere.
• Authenticate your sandboxes/production using sfdx force:auth:web:login command
• Now to deploy you can navigate to the project folder and run ./shellFileName.sh. It will ask for alias of the environment that you want to deploy to. Enter the alias and hit enter. Deployment starts.

Please note that this shell script works in Mac terminal and Linux shell only. If you are using windows, you can try to use bash shell there or write windows versions of the commands into a .bat file.

How to create a scratch org with "Non Profit Starter Pack (NPSP)"

Salesforce scratch orgs makes it very easy to track metadata changes. But if you are developing an app that involves non profit starter pack, it is usually tricky to setup a scratch org with NPSP packages. In this blog, we will go through different steps needed to setup a scratch org with NPSP packages.

NPSP is basically a combination of multiple appexchange packages. But to install these your sandbox/scratch org needs to meet certain conditions. These prerequisites are adding certain recordtypes to Account and Opprotunity and adding an Opprotunity sales process. Metdata needed for these can be found in the link - https://github.com/SalesforceFoundation/NPSP/tree/master/unpackaged/pre. If you wish to run below bash script directly, you need to copy individual metadata files from above NPSP github repo into a single npsp-dependencies folder in deployable format with a combinted package.xml file.

Use cases

• Easy development of enhancements to NPSP in scratch orgs
• Other approaches like using Cumulus CI are usually more time consuming and difficult to setup

Explanation

Above shell script will work for Mac and Linux users only. If you are a windows user, you might need to copy-paste and run individual commands separately from windows command line. As part of this script we are first creating a scratch org. Then we open the scratch org in browser. After that at line 14 we install all the prerequisites for NPSP package. Then we install 6 NPSP appexchange packages one after another. Please note that in future Salesforce might upgrade these packages and the package IDs will change. In that case find package ID corresponding to the upgraded version and change in the script.

How to use

Make sure that you are inside an sfdx project folder. If not, create a SFDX project using vscode or SFDX cli sfdx force:project:create -n projectName. As first step, make sure that you have copied all dependencies from https://github.com/SalesforceFoundation/NPSP/tree/master/unpackaged/pre to a folder with name npsp-dependencies inside your repository. Make sure you have set a devhub environment as default that you can use for spinning off scratch orgs( sfdx force:config:set defaultdevhubusername=productionUsernameHere ). Copy above code into a shell script file. *Example createScratchOrg.sh) Make sure that your shell script file has proper permissions by running chmod u+x createScratchOrg.sh. Finally run the shell script from terminal using ./createScratchOrg.sh.
Since it is installing 6 different appexchange packages as part of NPSP, the whole process might take some time. You can see the progress.

How to show a commandline/terminal menu

You might have seen a lot of command line tools offering a small menu with a number of options to choose from. Also you might have written some bash scripts that you want to make available in your terminal as a menu. Here you can find a good example to get started.

Sample

This menu sample code is organized into three main chunks. "show_menu" function takes care of styling and displaying options. option_picked function is used to show the option selected in a different color. Finally there is a while loop that is used to show the options continuously til you exit by hitting just enter.

Use cases

For an example, in Salesforce context you can use this script as a starter to get started with Salesforce DX commands. Salesforce DX commands are notoriously long and difficult to remember. You can setup a bash script with different options and user friendly labels. Then using the sample menu you can invoke necessary sfdx commands.
As final step you can alias the path to the bash script in you ".bash_profile" file. This will let you call your utility script anytime from terminal without worrying about path.

alias heydx="sh /Users/myname/Documents/Scripts/dxUtility.sh"