An Easy approach to Take Metadata Backup of your Org - Using sfdx mdapi and powershell script

 Most of the time, taking metadata back up of your org involves lots of manual effort or usage of some third-party tools. So I would like to share a comparatively simple approach that involves less manual effort.  

This is using the power of sfdx metadata api commands along with PowerShell script. 

Prerequisite 

Install and set up Salesforce CLI

Follow the below link to install Salesforce CLI

https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm 

Script Logic

Script Logic involves below high-level activities

Let us see this in detail. First, we can create a file and save it as downloadcompfinal.ps1

1. Connect to your Org

You need to establish a connection to the Org from which you need to retrieve metadata. For that we can use the below command in your script file:

1. sfdx force:auth:web:login --setalias <your alias name>demoorg

This will open a login window and you can provide credentials of the org that you want to connect. This is a one-time operation and for second-time execution onwards you can avoid this.

If the login and authorization is a success, you will get a message like below:

so now onwards we will use the alias name demoorg for referring to our org always in the script.

2. Retrieve metadata types of your Org

We can use the below sfdx command to retrieve the list of available metadata components of your org. 

This approach will avoid the hardcoding of the component names.

sfdx force:mdapi:describemetadata --json -u demoorg

The above command will be downloading complete metadata details in json format, and you need additional script to just retrieve the component type name and to populate that to a text file.

Sample json file format:

Sample output file with just MetadataTypename created using the script

3.Create sfdx project to download components

Once the metadata type names are ready, we can use the below command to create an sfdx project locally where we will store the retrieved files. 

$compfolder = 'Mycompoenents'

sfdx force:project:create --projectname $compfolder

4. Retrieve components for each component type

In your script file, you can iterate over each line in the component name file and execute the retrieve command to retrieve components of that specific type.

foreach($line in Get-Content $compfilepath\<compoenentfilename>) {

    $scrpt = "sfdx force:source:retrieve -u "+$Orgname+" -m "+$line

    Invoke-Expression $scrpt

}

This command will retrieve components to the force-app folder or to the folder that you specify as default in sfdx-project.json.

5. Retrieve Profile Details

If we try to download profiles with the above approach, it will contain only userpermission details. Object, tab, field, Recordtype, App level permissions will be missing in the file. So we need a package.xml file specifically for retrieving profile details like shown below:

Some additional points to be considered while downloading profiles:

1. Using metadata command you can download only a maximum of 10,000 components. In a large org there are chances that, you have more components. In that case, you might need to split your profile list as multiple files and execute them. 

2. Each of this file content you can copy to actual package.xml using script and execute it

Copy-Item -Path $packagefolderpath\profile1package.xml -Destination package.xml

The command for retrieving components using package.xml

sfdx force:source:retrieve -u demoorg -x package.xml

6. Retrieve wildcard unsupported Components

In addition to profiles, there are other components that do not support normal retrieval using just the metadata name. For them also we need package.xml. Below are some of those:

1. Translations

2. CustomObjectTranslations

3. EmailTemplate

4. Document

5. Report

6. Dashboard

For all this, we need to have package.xml. So it is better to store all these package.xml files in one local folder and copy to actual package.xml for execution during the script processing.

Either you can manually create this or else build using script itself.

7. Download packaged components

You might also need to download components of your managed package. Even if code components are hidden, you can still get a backup of some components. For that, we can use the below command.

sfdx force:source:retrieve -u  demoorg -n <packagename>

This one also you can completely automate using the script. The below command will give you the list of packages in your org:

sfdx force:package:installed:list -u orgname --json

Once you have the list, you can iterate over each package name and execute the retrieve command to get metadata.

How to execute the script

You can open windows powershell and execute the script like shown below:

Or even you can schedule the script execution using a task scheduler to run this daily/weekly/monthly so that automatically script will take back up.

Push your changes to git repository

You can also sync your changes to your git repository using a script. Please find a sample script below:

Script Execution Time

Time taken to complete the script execution depends on the count of components that needs to be downloaded. So it can vary from minutes to hours. 

An alternate approach using the Unmanaged package

If your org component count is not huge, we have an alternate approach for retrieving components.

Follow the below steps:

1. Create an unmanaged package in your Org

2. Add all required components to this package, which needs to be downloaded

3. Then execute the retrieve package command like shown below:

sfdx force:source:retrieve -u demoorg -n <packagename>

This will help to download all components in that package with a single command. But component count should be less than 10,000.

I hope this was helpful to you to get an idea of taking back up of your metadata components easily.