@aurahelper/package-generator

Aura Helper Package Generator Module to create Salesforce XML Package, to deploy, retrieve or delete elements on your Org. Support to create package from JSON File, Git Diffs or Mergin other packages.

Usage no npm install needed!

<script type="module">
  import aurahelperPackageGenerator from 'https://cdn.skypack.dev/@aurahelper/package-generator';
</script>

README

Aura Helper Package Generator Module

Version Total Downloads Downloads/Month Issues Known Vulnerabilities Code Size License

Aura Helper Package Generator Module contains a powerfull class to create and merge package files to deploy, retrieve or delete metadata from your Salesforce's projects.

You can choose to merge several package xml files (including destructiveChanges.xml and destructiveChangesPost.xml files) to combine into one file of each type, combine all packages in one file and all detructives in another file or merge all files into one package or destructive file.

Also you can create packages XML files from a JSON file (See Metadata JSON Format section). Use Aura Helper Metadata Factory @aurahelper/metadata-factory to help to you to create the JSON file from a project in your computer (@aurahelper/metadata-factory) or download metadata using Aura Helper Connector @ah/connetor to download it

To handle the JSON file types better, you can use MetadataType, MetadataObject and MetadataItem classes from @aurahelper/core > Types. Also you can use this classes to create your own JSON file and use the validateJSON() method to check if the file is correct.

Other important and usefull feature is the Ignore Metadata option. You can create an .ahignore.json file (see Ignore File section) to ignore the specified metadata on the file and exclude from the package to avoid deploy, delete or retrieve the metadata files. This Feature is util in some use cases, like Custom Label values unique for every environment (like ids...), or to avoid deploy some user permissions, or when you creating autogenerated package (from git for example) and like to exclude some metadata automatically.

Table of Contents

PackageGenerator Class

Class to create and merge package files to deploy, retrieve or delete metadata from your Salesforce's projects.

Can merge several package xml files (including destructiveChanges.xml and destructiveChangesPost.xml files) to combine into one file of each type, combine all packages in one file and all detructives in another file or merge all files into one package or destructive file.

The file names must contains at least the "package" word to identify the package XML files and destructiveChanges or destrutiveChangesPost to the destructive files. For example: package1.xml, destructiveChanges_uat.xml, destructiveChangesPost-v34...

You can choose a custom API Version to create the packages, if not specified API version, the package generator get the higher API version from each file types, that is, for package XML files, get the higher API of the Package XML files passed, and the same with other file types.

The setters methods are defined like a builder pattern to make it more usefull

Class Members


Fields

The fields that start with _ are for internal use only (Does not modify this fields to a correct PackageGenerator work). To the rest of fields, setter methods are recommended instead modify fields.

apiVersion

True to remove ignored elements from the result object, false only for unselect elements

  • string | number

mergePackageFiles

true if want to merge the provided package files. If undefiend ot not has param, also set to true

  • boolean

mergeDestructives

true if want to merge the provided destructive files into one single file. If undefiend ot not has param, also set to true

  • boolean

isDestructive

true if you want to merge all files into one destructive file (valid option to merge packages full). If undefiend ot not has param, also set to true

  • boolean

beforeDeploy

true if want to merge destructive files into before deploy destructive file when select mergeDestructives. If undefiend ot not has param, also set to true

  • boolean

explicit

true if you want to put all metadata types explicit into the file, false to use wildcards when are all checked

  • boolean

ignoreFile

path to the ignore file to ignore some metadata types from the packages

  • string

typesToIgnore

List with the Metadata Type API Names to ignore. This parameter is used to ignore only the specified metadata (also must be in ignore file) and avoid ignore all metadata types specified on the file.

  • string[]

Constructors

constructor(apiVersion)

Constructor to instance a new PackageGenerator object. All parameters are optional and you can use the setters methods to set the values when you want.

Parameters:

  • apiVersion: Path to the ignore file
    • string | number

Methods

setApiVersion(apiVersion)

Method to Set the api version to create the packages

Parameters:

  • apiVersion: Api version to create the package. If not provided use the latest api version of the provided files
    • string | number

Return:

Return the package generator instance

  • PackageGenerator

Examples:

Set the api version

    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setApiVersion('50');
    generator.setApiVersion('50.0');
    generator.setApiVersion(50);
    generator.setApiVersion(50.0);

setMergePackagesFiles(mergePackageFiles)

Method to set if merge package files

Parameters:

  • mergePackageFiles: true if want to merge the provided package files. If undefiend ot not has param, also set to true
    • boolean

Return:

Return the package generator instance

  • PackageGenerator

Examples:

Set if merge package files

    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setMergePackagesFiles(true);
    generator.setMergePackagesFiles();  // Also set to true

setMergeDestructives(mergeDestructives)

Method to set if merge destructive files

Parameters:

  • mergeDestructives: true if want to merge the provided destructive files into one single file. If undefiend ot not has param, also set to true
    • boolean

Return:

Return the package generator instance

  • PackageGenerator

Examples:

Set if merge destructive files

    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setMergeDestructives(true);
    generator.setMergeDestructives();  // Also set to true

setIsDestructive(isDestructive)

Method to set if merge all package and XML destructive files into one destructive file

Parameters:

  • isDestructive: true if you want to merge all files into one destructive
    • boolean

Return:

Return the package generator instance

  • PackageGenerator

Examples:

Set if merge all package and destructive files into one destructive

    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setIsDestructive(true);
    generator.setIsDestructive();  // Also set to true

setBeforeDeploy(beforeDeploy)

Method to set if the destructive file to create is before deploy, in otherwise create destructive files after deploy

Parameters:

  • beforeDeploy: true if want to merge destructive files into before deploy destructive file when select mergeDestructives. If undefiend ot not has param, also set to true
    • boolean

Return:

Return the package generator instance

  • PackageGenerator

Examples:

Set if merge all package and destructive files into one destructive

    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setBeforeDeploy(true);
    generator.setBeforeDeploy();  // Also set to true

setExplicit(explicit)

Method to set if put all elements explicit on the package XML or use wildcards when apply

Parameters:

  • explicit: true if you want to put all metadata types explicit into the file, false to use wildcards when are all checked
    • boolean

Return:

Return the package generator instance

  • PackageGenerator

Examples:

Set explicit

    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setExplicit(true);
    generator.setExplicit();  // Also set to true

setIgnoreFile(ignoreFile)

Method to set the path to the ignore file

Parameters:

  • ignoreFile: path to the ignore file to ignore some metadata types from the packages
    • boolean

Return:

Return the package generator instance

  • PackageGenerator

Examples:

Set file to ignore Metadata Types

    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setIgnoreFile('path/to/the/ignore/file.json');

setTypesToIgnore(typesToIgnore)

Method to set the Metadata Types to ignore from package (Also must be exists on ignore file)

Parameters:

  • typesToIgnore: List with the Metadata Type API Names to ignore. This parameter is used to ignore only the specified metadata (also must be in ignore file) and avoid ignore all metadata types specified on the file.
    • boolean

Return:

Return the package generator instance

  • PackageGenerator

Examples:

Set Metadata Types to ignore

    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setTypesToIgnore('CustomObject');
    generator.setTypesToIgnore(['CustomObject', 'CustomField']);

mergePackages(packageOrDestructiveFiles, outputFolder)

Method to merge several package xml files (including destructiveChanges.xml and destructiveChangesPost.xml files) to combine into one file of each type, combine all packages in one file and all detructives in another file.

Parameters:

  • packageOrDestructiveFiles: File or list of files to merge (including package and destructive files in the same list)
    • string | string[]
  • outputFolder: Folder to save the created files
    • string

Return:

Object with the merge result including the paths of the merged files

  • PackageGeneratorResult

Throws:

This method can throw the next exceptions:

  • WrongDatatypeException: If api version is not a String or number (can be undefined)
  • DataNotFoundException: If not package or destructive files provided
  • WrongFilePathException: If the package or destructive files path is not a String or cant convert to absolute path
  • FileNotFoundException: If the package or destructive files path not exists or not have access to it
  • InvalidFilePathException: If the package or destructive files path is not a file
  • WrongDirectoryPathException: If the output Folder is not a String or cant convert to absolute path
  • DirectoryNotFoundException: If the directory not exists or not have access to it
  • InvalidDirectoryPathException: If the path is not a directory

Examples:

You have several options to merge package files:

Merge files by Type

Merge all package XML file into one package XML file, merge all destructive changes pre deployment into one destructiveChanges XML and merge all destructive changes post deployment into one destructiveChangesPost XML.

    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator();
    const result = generator.mergePackages(filePaths, outputFolder); // Return an object with the full path of the created files;

    console.log(result.package);                    // [pathFromRoot]/path/to/the/output/folder/package.xml
    console.log(result.destructiveChanges);         // [pathFromRoot]/path/to/the/output/folder/destructiveChanges.xml
    console.log(result.destructiveChangesPost);     // [pathFromRoot]/path/to/the/output/folder/destructiveChangesPost.xml

Merge all destructive XML files post deployment

Merge all package XML file into one package XML file and merge all destructive changes pre and post deployment into one destructiveChanges XML post deployment.

    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator();
    generator.setApiVersion('50.0').setMergeDestructives();
    const result = generator.mergePackages(filePaths, outputFolder); // Return an object with the full path of the created files;
    
    console.log(result.package);                    // [pathFromRoot]/path/to/the/output/folder/package.xml
    console.log(result.destructiveChanges);         // undefined    (By default, create destructives after deploy)
    console.log(result.destructiveChangesPost);     // [pathFromRoot]/path/to/the/output/folder/destructiveChangesPost.xml

Merge all destructive XML files pre deployment

Merge all package XML file into one package XML file and merge all destructive changes pre and post deployment into one destructiveChanges XML pre deployment.

    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setMergeDestructives().beforeDeploy();
    const result = generator.mergePackages(filePaths, outputFolder); // Return an object with the full path of the created files;
    
    console.log(result.package);                    // [pathFromRoot]/path/to/the/output/folder/package.xml
    console.log(result.destructiveChanges);         // [pathFromRoot]/path/to/the/output/folder/destructiveChanges.xml
    console.log(result.destructiveChangesPost);     // undefined

mergePackagesFull(packageOrDestructiveFiles, outputFolder)

Method to merge all provided files into only one file. You can choose if merge all into a package.xml, destructiveChanges.xml or destructiveChangesPost.xml

Parameters:

  • packageOrDestructiveFiles: File or list of files to merge (including package and destructive files in the same list)
    • string | string[]
  • outputFolder: Folder to save the created files
    • string

Return:

Object with the merge result including the paths of the merged files

  • PackageGeneratorResult

Throws:

This method can throw the next exceptions:

  • WrongDatatypeException: If api version is not a String or number (can be undefined)
  • DataNotFoundException: If not package or destructive files provided
  • WrongFilePathException: If the package or destructive files path is not a String or cant convert to absolute path
  • FileNotFoundException: If the package or destructive files path not exists or not have access to it
  • InvalidFilePathException: If the package or destructive files path is not a file
  • WrongDirectoryPathException: If the output Folder is not a String or cant convert to absolute path
  • DirectoryNotFoundException: If the directory not exists or not have access to it
  • InvalidDirectoryPathException: If the path is not a directory

Examples:

You have several options to merge full package files:

Full Merge into Package XML

Merge all package XML, all destructiveChanges XML and all destructiveChangesPost XML files into one package XML file.

    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    const result = generator.mergePackagesFull(filePaths, outputFolder); // Return an object with the full path of the created files;
    
    console.log(result.package);                    // [pathFromRoot]/path/to/the/output/folder/package.xml
    console.log(result.destructiveChanges);         // undefined
    console.log(result.destructiveChangesPost);     // undefined

Full Merge into Destructive XML post deployment

Merge all package XML, all destructiveChanges XML and all destructiveChangesPost XML files into one destructiveChangesPost XML file.

    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setIsDestructive();
    const result = generator.mergePackagesFull(filePaths, outputFolder); // Return an object with the full path of the created files;
    
    console.log(result.package);                    // undefined
    console.log(result.destructiveChanges);         // undefined        (By default, create destructives after deploy)
    console.log(result.destructiveChangesPost);     // [pathFromRoot]/path/to/the/output/folder/destructiveChangesPost.xml

Full Merge into Destructive XML pre deployment

Merge all package XML, all destructiveChanges XML and all destructiveChangesPost XML files into one destructiveChanges XML file.

    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';
    const options = {
        apiVersion: '50.0',            // Optional for merge packages
        isDestructive: true,
        beforeDeploy: true
    }
    const generator = new PackageGenerator(50);
    generator.setIsDestructive().setBeforeDeploy();
    const result = generator.mergePackagesFull(filePaths, outputFolder, apiVersion, isDestructive, beforeDeploy); // Return an object with the full path of the created files;
    
    console.log(result.package);                    // undefined
    console.log(result.destructiveChanges);         // [pathFromRoot]/path/to/the/output/folder/destructiveChanges.xml
    console.log(result.destructiveChangesPost);     // undefined

getPackageContent(metadataOrPath, useIgnoreDestructive)

Method to get the Package XML format content as String to the selected Metadata JSON file or Metadata JSON Object. See Metadata JSON Format section to understand the JSON Metadata Format

Parameters:

  • metadataOrPath: Metadata JSON file or Metadata JSON object to get the package or destructive XML content.
    • string | { [key: string]: MetadataType }
  • useIgnoreDestructive: True to use the ignore destructive file to ignore the package content.
    • boolean

Return:

Returns an String with the XML content

  • string

Throws:

This method can throw the next exceptions:

  • WrongDatatypeException: If api version is not a String or number (can be undefined)
  • WrongFilePathException: If the package or destructive files path is not a String or cant convert to absolute path
  • FileNotFoundException: If the package or destructive files path not exists or not have access to it
  • InvalidFilePathException: If the package or destructive files path is not a file
  • WrongDirectoryPathException: If the output Folder is not a String or cant convert to absolute path
  • DirectoryNotFoundException: If the directory not exists or not have access to it
  • InvalidDirectoryPathException: If the path is not a directory
  • WrongFormatException: If file is not a JSON file or not have the correct Metadata JSON format

Examples:

You have several options to get Package XML Content:

Get the package XML Content from Metadata JSON File

    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const xmlResultFromFile = generator.getPackageContent(jsonFilePath);

    console.log(xmlResultFromFile);                    // <?xml version="1.0" encoding="UTF-8"?>
                                                       // <Package xmlns="http://soap.sforce.com/2006/04/metadata">
                                                       // ...

Get the package XML Content from Metadata JSON Object

    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const jsonContent = JSON.parse(fs.readFileSync(jsonFilePath, 'utf8'));
    const xmlResultFromJSON = generator.getPackageContent(jsonContent);

    console.log(xmlResultFromJSON);                    // <?xml version="1.0" encoding="UTF-8"?>
                                                       // <Package xmlns="http://soap.sforce.com/2006/04/metadata">
                                                       // ...

createPackage(metadataOrPath, outputFolder)

Method to create a package XML file with the selected Metadata JSON file or Metadata JSON Object. See Metadata JSON Format section to understand the JSON Metadata Format

Parameters:

  • metadataOrPath: Metadata JSON file or Metadata JSON object to create the package file.
    • string | { [key: string]: MetadataType }
  • outputFolder: Folder to save the created file
    • string

Return:

Returns the path to the created file

  • string

Throws:

This method can throw the next exceptions:

  • WrongDatatypeException: If api version is not a String or number (can be undefined)
  • WrongFilePathException: If the package or destructive files path is not a String or cant convert to absolute path
  • FileNotFoundException: If the package or destructive files path not exists or not have access to it
  • InvalidFilePathException: If the package or destructive files path is not a file
  • WrongDirectoryPathException: If the output Folder is not a String or cant convert to absolute path
  • DirectoryNotFoundException: If the directory not exists or not have access to it
  • InvalidDirectoryPathException: If the path is not a directory
  • WrongFormatException: If file is not a JSON file or not have the correct Metadata JSON format

Examples:

You have several options to create the XML Package file:

Create Package XML from Metadata JSON File

    import { PackageGenerator } from '@aurahelper/package-generator';
    
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const packageFromFileResult = generator.createPackage(jsonFilePath, outputFolder);

    console.log(packageFromFileResult);            // [rootPath]/path/to/json/package.xml

Create Package XML from Metadata JSON Object

    import { PackageGenerator } from '@aurahelper/package-generator';
    
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const jsonContent = JSON.parse(fs.readFileSync('jsonFilePath', 'utf8'));
    const packageFromJSONObjectResult = generator.createPackage(jsonContent, outputFolder);

    console.log(packageFromJSONObjectResult);        // [rootPath]/path/to/json/package.xml

createBeforeDeployDestructive(metadataOrPath, outputFolder)

Method to create a before deploy destructive file with the selected Metadata JSON file or Metadata JSON Object. See Metadata JSON Format section to understand the JSON Metadata Format

Parameters:

  • metadataOrPath: Metadata JSON file or Metadata JSON object to create the destructive file.
    • string | { [key: string]: MetadataType }
  • outputFolder: Folder to save the created file
    • string

Return:

Returns the path to the created file

  • string

Throws:

This method can throw the next exceptions:

  • WrongDatatypeException: If api version is not a String or number (can be undefined)
  • WrongFilePathException: If the package or destructive files path is not a String or cant convert to absolute path
  • FileNotFoundException: If the package or destructive files path not exists or not have access to it
  • InvalidFilePathException: If the package or destructive files path is not a file
  • WrongDirectoryPathException: If the output Folder is not a String or cant convert to absolute path
  • DirectoryNotFoundException: If the directory not exists or not have access to it
  • InvalidDirectoryPathException: If the path is not a directory
  • WrongFormatException: If file is not a JSON file or not have the correct Metadata JSON format

Examples:

You have several options to create the XML before destructive file:

Create Destructive Changes XML before deploy from Metadata JSON File

    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const packageFromFileResult = generator.createBeforeDeployDestructive(jsonFilePath, outputFolder);

    console.log(packageFromFileResult);          // [rootPath]/path/to/json/destructiveChanges.xml

Create Destructive Changes XML before deploy from Metadata JSON Object

    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const jsonContent = JSON.parse(fs.readFileSync('jsonFilePath', 'utf8'));
    const packageFromJSONObjectResult = generator.createBeforeDeployDestructive(jsonContent, outputFolder);

    console.log(packageFromJSONObjectResult);          // [rootPath]/path/to/json/destructiveChanges.xml

createAfterDeployDestructive(metadataOrPath, outputFolder)

Method to create an after deploy destructive file with the selected Metadata JSON file or Metadata JSON Object. See Metadata JSON Format section to understand the JSON Metadata Format

Parameters:

  • metadataOrPath: Metadata JSON file or Metadata JSON object to create the destructive file.
    • string | { [key: string]: MetadataType }
  • outputFolder: Folder to save the created file
    • string

Return:

Returns the path to the created file

  • string

Throws:

This method can throw the next exceptions:

  • WrongDatatypeException: If api version is not a String or number (can be undefined)
  • WrongFilePathException: If the package or destructive files path is not a String or cant convert to absolute path
  • FileNotFoundException: If the package or destructive files path not exists or not have access to it
  • InvalidFilePathException: If the package or destructive files path is not a file
  • WrongDirectoryPathException: If the output Folder is not a String or cant convert to absolute path
  • DirectoryNotFoundException: If the directory not exists or not have access to it
  • InvalidDirectoryPathException: If the path is not a directory
  • WrongFormatException: If file is not a JSON file or not have the correct Metadata JSON format

Examples:

You have several options to create the XML after destructive file:

Create Destructive Changes XML after deploy from Metadata JSON File

    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const packageFromFileResult = generator.createAfterDeployDestructive(jsonFilePath, outputFolder);

    console.log(packageFromFileResult);          // [rootPath]/path/to/json/destructiveChangesPost.xml

Create Destructive Changes XML after deploy from Metadata JSON Object

    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const jsonContent = JSON.parse(fs.readFileSync('jsonFilePath', 'utf8'));
    const packageFromJSONObjectResult = generator.createAfterDeployDestructive(jsonContent, outputFolder);

    console.log(packageFromJSONObjectResult);          // [rootPath]/path/to/json/destructiveChangesPost.xml

validateJSON(metadataOrPath)

Static Method to validate a Metadata JSON file or Metadata JSON Object format. If is not valid, throw several exceptions. See Metadata JSON Format section to understand the JSON Metadata Format

Parameters:

  • metadataOrPath: Metadata JSON file or Metadata JSON object to validate.
    • string | any

Return:

Returns the Metadata Object Content validated

  • { [key: string]: MetadataType }

Throws:

This method can throw the next exceptions:

  • WrongFilePathException: If the package or destructive files path is not a String or cant convert to absolute path
  • FileNotFoundException: If the package or destructive files path not exists or not have access to it
  • InvalidFilePathException: If the package or destructive files path is not a file
  • WrongFormatException: If file is not a JSON file or not have the correct Metadata JSON format

Example:

Create and Validate your own JSON File

You can create your own JSON file to create package files and handle metadata types easy with the MetadataType, MetadataObject and MetadataItem classes from @aurahelper/core. See Metadata JSON Format section to understand the JSON Metadata Format

    import { PackageGenerator } from '@aurahelper/package-generator';
    import { MetadataType, MetadataObject, MetadataItem } = from '@aurahelper/core';

    // Instance a Metadata Type
    const customObjectType = new MetadataType('CustomObject', checkedOrNot, '.../force-app/main/default/objects', 'object');

    // Add Childs to the Metadata Type
    customObjectType.addChild('Account', new MetadataObject('Account', checkedOrNot, '.../force-app/main/default/objects/Account/Account.object-meta.xml'));
    customObjectType.addChild('Case', new MetadataObject('Case', checkedOrNot, '.../force-app/main/default/objects/Case/Case.object-meta.xml'));
    customObjectType.addChild('CustomObject__c', new MetadataObject('CustomObject__c', checkedOrNot, '.../force-app/main/default/objects/CustomObject__c/CustomObject__c.object-meta.xml'));

    // Instance other Metadata Type
    const customFieldType = new MetadataType('CustomField', checkedOrNot, '.../force-app/main/default/objects', 'field');

    // Add child to the Metadata Type
    customFieldType.addChild('Account', new MetadataObject('Account', checkedOrNot, '.../force-app/main/default/objects/Account'));
    
    // Add childs to the Metadata Object
    customFieldType.getChild('Account').addChild('Name', new MetadataItem('Name', checkedOrNot, '.../force-app/main/default/objects/Account/fields/Name.field-meta.xml'));
    customFieldType.getChild('Account').addChild('CustomField__c', new MetadataItem('CustomField__c', checkedOrNot, '.../force-app/main/default/objects/Account/fields/CustomField__c.field-meta.xml'));

    // Add child to the Metadata Type
    customFieldType.addChild('Case', new MetadataObject('Case', checkedOrNot, '.../force-app/main/default/objects/Case'));

    // Add childs to the Metadata Object
    customFieldType.getChild('Case').addChild('Subject', new MetadataItem('Subject', checkedOrNot, '.../force-app/main/default/objects/Case/fields/Subject.field-meta.xml'));
    customFieldType.getChild('Case').addChild('CustomField__c', new MetadataItem('CustomField__c', checkedOrNot, '.../force-app/main/default/objects/Case/fields/CustomField__c.field-meta.xml'));

    // Add the MetadataTypes to the main Object
    const metadataJSON = {
        CustomObject: customObjectType,
        CustomField: customFieldType
    };

    
    // Now you can create a package XML or validate the created object to ensure that is correct.
    try{
        PackageGenerator.validateJSON(metadataJSON);
    } catch(error){
        // JSON is not valid
        console.log(error.message);     // Description about the error
    }

    // Also you can validate directly a JSON file
    try{
        PackageGenerator.validateJSON('path/to/the/json/metadata');
    } catch(error){
        // JSON is not valid
        console.log(error.message);     // Description about the error
    }

Ignore metadata from your package

All methods to create or merge package or destructive XML files has two important options to ignore XML files. To ignore files, you need to create a .ahignore.json file (the name can be different) with the format specified on Ignore File section.

Examples:

Ignore Metadata from a Metadata JSON file when create a package

    import { PackageGenerator } from '@aurahelper/package-generator';
    
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    generator.setIgnoreFile('path/to/file' ).setTypesToIgnore(['CustomObject']);
    const packageFromFileResult = generator.createPackage(jsonFilePath, outputFolder);

    console.log(packageFromFileResult);                    // [rootPath]/path/to/json/package.xml

Ignore Metadata from a Metadata JSON Object when create a package

    import { PackageGenerator } from '@aurahelper/package-generator';
    
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    generator.setIgnoreFile('path/to/file' ).setTypesToIgnore(['CustomObject']);
    const jsonContent = JSON.parse(fs.readFileSync('jsonFilePath', 'utf8'));
    const packageFromJSONObjectResult = PackageGenerator.createPackage(jsonContent, outputFolder);

    console.log(packageFromJSONObjectResult);                    // [rootPath]/path/to/json/package.xml

Metadata JSON Format

The Metadata JSON Format used by Aura Helper Framework and modules have the next structure. Some fields are required and the datatypes checked to ensure the correct file structure.

    {
        "MetadataAPIName": {
            "name": "MetadataAPIName",                                  // Required (String). Contains the Metadata Type API Name (like object Key)
            "checked": false,                                           // Required (Boolean). Field for include this type on package or not
            "path": "path/to/the/metadata/folder",                      // Optional (String). Path to the Metadata Type folder in local project
            "suffix": "fileSuffix",                                     // Optional (String). Metadata File suffix
            "childs": {                                                 // Object with a collection of childs (Field required (JSON Object) but can be an empty object)
                "MetadataObjectName":{
                    "name": "MetadataObjectName",                       // Required (String). Contains the Metadata Object API Name (like object Key)
                    "checked": false,                                   // Required (Boolean). Field for include this object on package or not
                    "path": "path/to/the/metadata/file/or/folder",      // Optional (String). Path to the object file or folder path
                    "childs": {                                         // Object with a collection of childs (Field required (JSON Object) but can be an empty object)
                        "MetadataItemName": {
                            "name": "MetadataItemName",                 // Required (String). Contains the Metadata Item API Name (like object Key)
                            "checked": false,                           // Required (Boolean). Field for include this object on package or not
                            "path": "path/to/the/metadata/file"
                        },
                        "MetadataItemName2": {
                            ...
                        },
                        ...,
                        ...,
                        ...
                    }
                }
                "MetadataObjectName2":{
                   ...
                },
                ...,
                ...,
                ...
            }
        }
    }

Example:

    {
        "CustomObject": {
            "name": "CustomObject",
            "checked": false,
            "path":  "path/to/root/project/force-app/main/default/objects",
            "suffix": "object",
            "childs": {
                "Account": {
                    "name": "Account",
                    "checked": true,            // Add Account Object to the package
                    "path": "path/to/root/project/force-app/main/default/objects/Account/Account.object-meta.xml",
                    "childs": {}
                },
                "Case": {
                    "name": "Case",
                    "checked": true,            // Add Case Object to the package
                    "path": "path/to/root/project/force-app/main/default/objects/Case/Case.object-meta.xml",
                    "childs": {}
                },
                ...,
                ...,
                ...
            }
        },
        "CustomField": {
            "name": "CustomField",
            "checked": false,
            "path":  "path/to/root/project/force-app/main/default/objects",
            "suffix": "field",
            "childs": {
                "Account": {
                    "name": "Account",
                    "checked": false,            
                    "path": "path/to/root/project/force-app/main/default/objects/Account/fields",
                    "childs": {
                        "customField__c": {
                            "name": "customField__c",
                            "checked": true,    // Add customField__c to the package
                            "path": "path/to/root/project/force-app/main/default/objects/Account/fields/customField__c.field-meta.xml",
                        },
                        ...,
                        ...,
                        ...
                    }
                },
                "Case": {
                    "name": "Case",
                    "checked": false,           
                    "path": "path/to/root/project/force-app/main/default/objects/Case/fields",
                    "childs": {
                        "CaseNumber": {
                            "name": "CaseNumber",
                            "checked": true,    // Add CaseNumber to the package
                            "path": "path/to/root/project/force-app/main/default/objects/Account/fields/CaseNumber.field-meta.xml",
                        },
                        ...,
                        ...,
                        ...
                    }
                },
                ...,
                ...,
                ...
            }
        }
    }

Ignore File

The ignore file is a JSON file used on ignore, create package or repair dependencies modules. On this file you can specify metadata types, objects and elements for ignore or delete from your local project or package files. You can have a main ignore file on your root project (like gitignore) named .ahignore.json for use automatically, or have different ignore files and specify it on the commands when you need tou use.

The ignore file have the next structure

    {
        // Basic structure
        "MetadataTypeAPIName": {
            "MetadataObject1",
            "MetadataObject2"
        }

        // Advance Structure
        "MetadataTypeAPIName": {
            "MetadataObject1:MetadataItem1",
            "MetadataObject1:MetadataItem2",
            "MetadataObject2:*",
            "*",
            "*:*" // Only valid on Custom Objects
        }

        // Special for Permissions
        "MetadataTypeAPIName": {
            "UserPermission:MetadataObject1:PermissionName",
            "UserPermission:MetadataObject2:*",
            "UserPermission:*:PermissionName"
        }
    }

Example:

    {
        "CustomLabels": {
            "labelName1",                   // Ignore or remove the custom label "labelName1"
            "labelName2",                   // Ignore or remove the custom label "labelName2",
            "*"                             // Ignore or remove all Custom Labels
        },
        "AssignmentRules":{
            "Case:Assign1",                 // Ignore or remove the Assignent Rule "Assign1" from the object Case
            "Lead:*",                       // Ignore or remove all Assignment Rules from Lead
            "*"                             // Ignore or remove all Assignment Rules
        },
        "CustomObject": {
            "Account",                      // Ignore or remove the Account Object
            "Case:*",                       // Ignore or remove all related objects from case, including the object (Bussines Process, Fields, Validation Rules...),
            "*",                            // Ignore or remove all custom objects (only the object not the related metadata)
            "*:*",                          // Ignore or remove all custom objects and the related metadata (Bussines Process, Fields, Validation Rules...)
        },
        "Report": {
            "ReportFolder",                 // Ignore or remove the entire folder
            "ReportFolder1:ReportName2",    // Ignore or remove the report "ReportName2" from "ReportFolder1" folder.
            "*",                            // Ignore or remove all reports.
        },
        "Workflow": {
            "Account",                      // Ignore or remove the Account worflows (Rules, Task, Alerts...)
            "*"                             // Ignore or  remove all workflows (Rules, Task, Alerts...) from all objects 
        },
        "WorkflowRule": {
            "Case:*",                       // Ignore or remove all Workflow rules from case object
            "Account:Rule1",                // Ignore or remove "Rule1" from Account workflows,
            "*"                             // Ignore or remove all Worflow rules from all objects
        },
        "Profile": {
            "UserPermission:*:Permission1", // Remove the "Permission1" User Permission from all profiles
            "UserPermission:TestProfile:*", // Remove all User permissions from TestProfile file
            "UserPermission:Admin:Perm1",   // Remove the Perm1 User Permission from Admin profile
            "TestProfile2",                 // Ignore or remove  the "TestProfile" profile 
            "*"                             // Ignore or remove all profiles
        }
    }

IMPORTANT

Some Metadata Types have singular and plural name like CustomLabels, MatchingRules, EscalationRules... For ignore or remove this types you must use the plural name, if use the singular name the ignore process not take effect with this types.