hardis:org:retrieve:sources:dx
Description
Command Behavior
Retrieves Salesforce metadata from an org and converts it into Salesforce DX (SFDX) source format.
This command provides a flexible way to pull metadata from any Salesforce org into your local SFDX project. It's particularly useful for:
- Initial Project Setup: Populating a new SFDX project with existing org metadata.
- Environment Synchronization: Bringing changes from a Salesforce org (e.g., a sandbox) into your local development environment.
- Selective Retrieval: Allows you to specify which metadata types to retrieve, or to filter out certain types.
- Org Shape Creation: Can optionally create an org shape, which is useful for defining the characteristics of scratch orgs.
Key functionalities:
- Metadata Retrieval: Connects to a target Salesforce org and retrieves metadata based on specified filters.
- MDAPI to SFDX Conversion: Converts the retrieved metadata from Metadata API format to SFDX source format.
- Org Shape Generation (Optional): If the
--shapeflag is used, it also captures the org's shape and stores installed package information. - Temporary File Management: Uses temporary folders for intermediate steps, ensuring a clean working directory.
Technical explanations
The command's technical implementation involves:
- Temporary Directory Management: It creates and manages temporary directories (
./tmp,mdapipkg,sfdx-project) to stage the retrieved metadata and the converted SFDX sources. MetadataUtils.retrieveMetadatas: This utility is used to connect to the Salesforce org and retrieve metadata in Metadata API format. It supports filtering by metadata types and excluding certain items.- SFDX Project Creation: It executes
sf project generateto create a new SFDX project structure within a temporary directory. - MDAPI to SFDX Conversion: It then uses
sf project convert mdapito convert the retrieved metadata from the MDAPI format to the SFDX source format. - File System Operations: It uses Node.js
fsto copy the converted SFDX sources to the main project folder, while preserving important project files like.gitignoreandsfdx-project.json. - Org Shape Handling: If
--shapeis enabled, it copies the generatedpackage.xmland stores information about installed packages usingsetConfig. - Error Handling: Includes robust error handling for Salesforce CLI commands and file system operations.
- WebSocket Communication: Uses
WebSocketClient.sendRefreshCommandsMessageto notify connected VS Code clients about changes to the project.
Agent Mode
Supports non-interactive execution with --agent:
sf hardis:org:retrieve:sources:dx --agent
In agent mode, all interactive prompts are skipped and default values are used.
Screenshots
Every metadata of the Helios org retrieved, managed items left out, and converted into an SFDX project
- (1) The folder where the SFDX project is written
Parameters
| Name | Type | Description | Default | Required | Options |
|---|---|---|---|---|---|
| agent | boolean | Run in non-interactive mode for agents and automation | |||
| debug -d |
boolean | Activate debug mode (more logs) | |||
| filteredmetadatas -m |
option | Comma separated list of Metadatas keys to remove from PackageXml file | |||
| flags-dir | option | Import flag values from a directory. | |||
| folder -f |
option | Folder | . | ||
| instanceurl -r |
option | URL of org instance | |||
| json | boolean | Format output as json. | |||
| keepmetadatatypes -k |
option | Comma separated list of metadatas types that will be the only ones to be retrieved | |||
| shape -s |
boolean | Updates project-scratch-def.json from org shape | |||
| skipauth | boolean | Skip authentication check when a default username is required | |||
| target-org -o |
option | Username or alias of the target org. Not required if the target-org configuration variable is already set. |
true | ||
| tempfolder -t |
option | Temporary folder | ./tmp | ||
| websocket | option | Websocket host:port for VsCode SFDX Hardis UI integration |
Examples
$ sf hardis:org:retrieve:sources:dx
$ sf hardis:org:retrieve:sources:dx --agent
