Force CLI Part 2 - Extracting Metadata
In Part 1 of this series, Getting Started, I covered downloading and installing the Force CLI, and logging in to Salesforce. This post covers extracting metadata from your Salesforce org.
Why do I need the Metadata?
This is a very good question - a lot of the time the answer is that you don’t. If you do, its highly likely that your IDE of choice will handle this for you - pulling down the metadata components that you are working on and uploading the changes when you save or deploy. The classic use case for this is to make a backup of your implementation, typically on a regular schedule in an unattended fashion.
EXTRACT ALL THE METADATA
At first glance, this looks about as straightforward as it could be. Executing force help shows there is a command that looks tailor made:
export Export metadata to a local directory
By default, this command dumps the metadata to a subdirectory of your current directory named (fittingly enough) metadata, although you can supply a different location for the output as an additional parameter.
After logging in, I can export the metadata by executing the following command:
However, at the time of writing this doesn’t quite bring everything back. Here’s the contents of my metadata directory- spot the deliberate mistake:
analyticSnapshots homePageComponents quickActions applications homePageLayouts remoteSiteSettings approvalProcesses labels reportTypes assignmentRules layouts roles autoResponseRules networks samlssoconfigs callCenters objectTranslations scontrols classes objects sharingRules communities package.xml sites components pages staticresources connectedApps permissionsets tabs dataSources portals translations flows profiles triggers groups queues workflows
Spotters Badge for those eagle-eyed readers that wondered where the Lightning Components metadata directory(aka aura) is.
There’s currently no way to influence the metadata elements that are included by the export command, but luckily there is a mechanism to extract individual metadata component types.
Fetch! Good boy!
The fetch subcommand provides granularity around metadata extraction, not just down to a single type of metadata, but as far as a single metadata component. I’m not going down to that level, but if you are interested then execute force help fetch which gives full details of the options.
The fetch command takes a -t switch to identify which metadata type you want to extract. For all types you can specify the name of the metadata type as detailed in the Metadata API Developer’s Guide, so to extract the Force.com Sites metadata, for example, you would execute:
force fetch -t CustomSite
The metadata name for Lightning Components is AuraDefinitionBundle, but you can also specify Aura as the type, which will extract the Lightning Component metadata via the REST API - I tend to use the latter version as I find it is slightly faster than the metadata route.
force fetch -t Aura
extracts the Lightning Components to the metadata directory, and the entire Salesforce configuration is now in one place:
analyticSnapshots homePageComponents remoteSiteSettings applications homePageLayouts reportTypes approvalProcesses labels roles assignmentRules layouts samlssoconfigs aura networks scontrols autoResponseRules objectTranslations sharingRules callCenters objects sites classes package.xml staticresources communities pages tabs components permissionsets translations connectedApps portals triggers dataSources profiles workflows flows queues groups quickActions
Putting these commands together in a bash script, with a dash of compression, gives me a handy backup file containing my metadata:
#/bin/bash force login force export force fetch -t Aura zip -r metadata > backup.zip
Note - if you run the above commands directly from the command line, ignore the first one. That tells the OS which command to use to execute the script, which makes no sense for individual commands.
Version Control to Major Tom
Where this can be particularly powerful is if you integrate with version control. You can use a script to periodically extract the latest metadata and merge into your Git repository for example.