Skip to content

hardis:project:clean:filter-xml-content

Description

Command Behavior

Filters the content of Salesforce metadata XML files to remove specific elements, enabling more granular deployments.

This command addresses a common challenge in Salesforce development: deploying only a subset of metadata from XML files when the target org might not support all elements or when certain elements are not desired. It allows you to define rules in a JSON configuration file to remove unwanted XML nodes.

Key functionalities:

  • Configurable Filtering: Uses a JSON configuration file (e.g., filter-config.json) to define which XML elements to remove. Each filter can target folders (folders) or specific files (files), and defines XML tags and values to exclude.
  • Wildcard Support: Supports wildcard patterns in exclude_list[].values using * (any sequence) and ? (single character), allowing flexible matching (for example SBQQ__*).
  • Targeted File Processing: Processes matching XML files from a specified input folder (defaults to current directory) and writes the filtered content to an output folder.
  • Example Use Cases: Useful for scenarios like:
    • Removing references to features not enabled in the target org.
    • Stripping out specific profile permissions or field-level security settings.
    • Filtering targeted files only (for example one permissionset) while keeping other files untouched.
    • Cleaning up metadata that is not relevant to a particular deployment.
Technical explanations

The command's technical implementation involves:

  • Configuration Loading: Reads the filter-config.json file, which contains an array of filters. Each filter defines a name, description, either folders or files (where to apply the filter), file_extensions, and an exclude_list.
  • File System Operations: Copies the input folder to an output folder (if different) to avoid modifying original files directly. It then iterates through either explicitly listed files or files found in configured folders, and applies extension checks before filtering.
  • XML Parsing and Manipulation: For each matching XML file:
    • It uses xml2js.Parser to parse the XML content into a JavaScript object.
    • It recursively traverses the JavaScript object, applying the filterElement function.
    • The filterElement function checks for type_tag and identifier_tag defined in the exclude_list. If a match is found and the identifier matches one of the excludeDef.values entries (exact or wildcard), the element is removed from the XML structure.
    • After filtering, it uses writeXmlFile to write the modified JavaScript object back to the XML file.
  • Logging: Provides detailed logs about the filtering process, including which files are being processed and which elements are being filtered.
  • Summary Reporting: Tracks and reports on the files that have been updated due to filtering.

Parameters

Name Type Description Default Required Options
configfile
-c		 option Config JSON file path
debug boolean debug
flags-dir option undefined
inputfolder
-i		 option Input folder (default: "." )
json boolean Format output as json.
outputfolder
-f		 option Output folder (default: parentFolder + _xml_content_filtered)
websocket option websocket

Examples

sf hardis:project:clean:filter-xml-content -i "./mdapi_output"

sf hardis:project:clean:filter-xml-content -i "retrieveUnpackaged"