Aura Helper Dependencies Manager Module
Module to check and repair Metadata Dependencies on Salesforce's project files. You can repair your dependencies with one simple method or check if have errors. Also you can use a .ahignore.json file (see Ignore File section) to exclude the specified metadata types when check dependencies error and compress or not the affected XML files.
Table of Contents
Class to check dependencies errors on files or repair it automatically. This class analize all metadata types and files to check if any file or type does not exists on the local project to repair it from the files where exists.
All Dependecies Manager methods return a Promise with the associated data to the processes.
Class Members
The fields that start with _ are for internal use only (Does not modify this fields to a correct connection work). To the rest of fields, setter methods are recommended instead modify fields.
Path to the project root folder
List of metadata details to repair dependencies.
Path to the ignore file
JSON Metadata Object or JSON Metadata File path with the objects to repair (if you don't want to repair all Metadata Types)
string
| { [key: string]: MetadataType }
True to compress the XML Files, false in otherwise. If undefined or not pass parameter, also set to true.
Sort order to order the XML elements. Values: simpleFirst, complexFirst, alphabetAsc or alphabetDesc. (alphabetDesc by default)
The Connection class has only one constructor to create a connection
Constructor to create a new connection object. All parameters are optional and you can use the setters methods to set the values when you want.
Parameters:
- projectFolder: Path to the project root folder
- metadataDetails: List of metadata details
Method to handle the event when preparing execution of repair or check dependencies
Parameters:
- callback: Callback function to call when manager is on prepare
Return:
Returns the DependenciesManager object
Examples:
Handling progress on prepare stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onPrepare((status) => {
console.log('Handling progress on prepare');
}));
Method to handle the event before start process Metadata Type
Parameters:
- callback: Callback function to handle progress before start process Metadata Type
Return:
Returns the DependenciesManager object
Examples:
Handling progress on start type stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onStartType((status) => {
console.log('Handling progress on start type');
console.log('MetadataType => ' + status.entityType);
}));
Method to handle the event before start process Metadata Object
Parameters:
- callback: Callback function to handle progress before start process Metadata Object
Return:
Returns the DependenciesManager object
Examples:
Handling progress on start object stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onStartObject((status) => {
console.log('Handling progress on start object');
console.log('MetadataType => ' + status.entityType);
console.log('MetadataObject => ' + status.entityObject);
}));
Method to handle the event before start process Metadata Item
Parameters:
- callback: Callback function to handle progress before start process Metadata Item
Return:
Returns the DependenciesManager object
Examples:
Handling progress on start item stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onStartItem((status) => {
console.log('Handling progress on start item');
console.log('MetadataType => ' + status.entityType);
console.log('MetadataObject => ' + status.entityObject);
console.log('MetadataItem => ' + status.entityItem);
}));
Method to handle the event before after process Metadata Type
Parameters:
- callback: Callback function to handle progress after process Metadata Type
Return:
Returns the DependenciesManager object
Examples:
Handling progress on end type stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onEndType((status) => {
console.log('Handling progress on end type');
console.log('MetadataType => ' + status.entityType);
}));
Method to handle the event before after process Metadata Object
Parameters:
- callback: Callback function to handle progress after process Metadata Object
Return:
Returns the DependenciesManager object
Examples:
Handling progress on end object stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onEndObject((status) => {
console.log('Handling progress on end object');
console.log('MetadataType => ' + status.entityType);
console.log('MetadataObject => ' + status.entityObject);
}));
Method to handle the event before after process Metadata Item
Parameters:
- callback: Callback function to handle progress after process Metadata Item
Return:
Returns the DependenciesManager object
Examples:
Handling progress on end item stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onEndObject((status) => {
console.log('Handling progress on end item');
console.log('MetadataType => ' + status.entityType);
console.log('MetadataObject => ' + status.entityObject);
console.log('MetadataItem => ' + status.entityItem);
}));
Method to handle the event before start processing results on some processes
Parameters:
- callback: Callback function to handle progress when manager is processing results
Return:
Returns the DependenciesManager object
Examples:
Handling progress on process stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onProcess((status) => {
console.log('Handling progress on process');
}));
Method to handle the event before start process errors on metadata type
Parameters:
- callback: Callback function to handle progress before start process errors
Return:
Returns the DependenciesManager object
Examples:
Handling progress on start errors on Metadata Type stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onStartErrors((status) => {
console.log('Handling progress on start errors');
console.log('MetadataType => ' + status.entityType);
}));
Method to handle the event after process errors on metadata type
Parameters:
- callback: Callback function to handle progress after process errors
Return:
Returns the DependenciesManager object
Examples:
Handling progress on end errors on Metadata Type stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onEndErrors((status) => {
console.log('Handling progress on end errors');
console.log('MetadataType => ' + status.entityType);
}));
Method to handle the event before start processing the errors encuntered on file
Parameters:
- callback: Callback function to handle progress before start processing the errors encuntered on file
Return:
Returns the DependenciesManager object
Examples:
Handling progress on start file error stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onEndErrors((status) => {
console.log('Handling progress on end errors');
console.log('MetadataType => ' + status.entityType);
console.log('MetadataObject => ' + status.entityObject);
console.log('MetadataItem => ' + status.entityItem);
console.log('File => ' + status.data);
}));
Method to handle the event before start compress XML File on some processes
Parameters:
- callback: Callback function to handle progress when start compress
Return:
Returns the DependenciesManager object
Examples:
Handling progress on compress file stage
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.onCompressFile((status) => {
console.log('Handling progress on end errors');
console.log('MetadataType => ' + status.entityType);
console.log('MetadataObject => ' + status.entityObject);
console.log('MetadataItem => ' + status.entityItem);
console.log('File => ' + status.data);
}));
Method to set the ignore file to ignore the metadata types
Parameters:
- ignorefile: Path to the ignore file
Return:
Return the DependenciesManager object instance
Examples:
Set the ignore file
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.setIgnoreFile('path/to/the/ignore/file.json');
Method to set the Metadata Name or Names to ignore
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.
string
| { [key: string]: MetadataType }
Return:
Return the DependenciesManager object instance
Examples:
Set the types to repair
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.setTypesToRepair({
CustomObject: {
checked: true,
childs: {},
name: 'CustomObject'
}
});
True to compress the XML Files, false in otherwise. If undefined or not pass parameter, also set to true.
Parameters:
- compress: True to compress the XML Files, false in otherwise
Return:
Return the DependenciesManager object instance
Examples:
Set compress affected XML Files
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.setCompress(true);
Method to set the sort order value to sort the XML Elements when compress
Parameters:
- sortOrder: Sort order to order the XML elements. Values: simpleFirst, complexFirst, alphabetAsc or alphabetDesc. (alphabetDesc by default).
Return:
Return the DependenciesManager object instance
Examples:
Set Sort order to order XML Elements
import { DependenciesManager } from '@aurahelper/xml-definitions';
import { SORT_ORDER } from '@aurahelper/xml-compressor';
const dependenciesManager = new DependenciesManager();
dependenciesManager.setSortOrder(SORT_ORDER.SIMPLE_FIRST);
Method to set Simple XML Elements first as sort order (simpleFirst)
Return:
Return the DependenciesManager object instance
Examples:
Set Simple first sort order to order XML Elements
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.setIgnoreFile('path/to/the/ignore/file.json').sortSimpleFirst();
Method to set Complex XML Elements first as sort order (complexFirst)
Return:
Return the DependenciesManager object instance
Examples:
Set Complex first sort order to order XML Elements
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.setIgnoreFile('path/to/the/ignore/file.json').sortComplexFirst();
Method to set Alphabet Asc as sort order (alphabetAsc)
Return:
Return the DependenciesManager object instance
Examples:
Set Alphabet asc sort order to order XML Elements
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.setIgnoreFile('path/to/the/ignore/file.json').sortAlphabetAsc();
Method to set Alphabet Desc as sort order (alphabetDesc)
Return:
Return the DependenciesManager object instance
Examples:
Set Alphabet desc sort order to order XML Elements
import { DependenciesManager } from '@aurahelper/xml-definitions';
const dependenciesManager = new DependenciesManager();
dependenciesManager.setIgnoreFile('path/to/the/ignore/file.json').sortAlphabetDesc();
Method to get a list with all supported types to repair or check dependencies
Return:
Return a list with the supported Metadata Type API Names
Examples:
import { DependenciesManager } from '@aurahelper/xml-definitions';
const supportedTypes = DependenciesManager.getSupportedTypes();
console.log(supportedTypes);
Method to repair any Salesforce project dependencies to fix possible deploy errors.
Return:
Return an object with the repaired errors data. See Repair Response section to understand the response.
{ [key: string]: DependenciesRepairResponse }
| undefined
Throws:
This method can throw the next exceptions:
WrongDirectoryPathException
: If the project path is not a String or can't convert to absolute pathDirectoryNotFoundException
: If the project path not exists or not have access to itInvalidDirectoryPathException
: If the project path is not a directoryWrongFilePathException
: If the ignore file or types file is not a String or can't convert to absolute pathFileNotFoundException
: If the ignore file or types file not exists or not have access to itInvalidFilePathException
: If the ignore file or types file is not a fileWrongFormatException
: If types is not a Metadata JSON file or Metadata JSON Object or ignore file is not a JSON file
Examples:
Repair all Dependencies
import { DependenciesManager } from '@aurahelper/xml-definitions';
import { Connection } from '@aurahelper/connector';
const connection = new Connection('MyOrg', '50');
connection.setUsernameOrAlias('MyOrg');
connection.setSingleThread();
connection.listMetadataTypes().then((metadataDetails) => {
const projectRoot = 'path/to/your/project';
const manager = new DependenciesManager(projectRoot, metadataDetails);
const errors = manager.repairDependencies();
if(errors != undefinded){
}
}).catch((error) => {
});
Repair all Dependencies and compress
import { DependenciesManager } from '@aurahelper/xml-definitions';
import { Connection } from '@aurahelper/connector';
import { SORT_ORDER } from '@aurahelper/xml-compressor';
const connection = new Connection('MyOrg', '50');
connection.setUsernameOrAlias('MyOrg');
connection.setSingleThread();
connection.listMetadataTypes().then((metadataDetails) => {
const projectRoot = 'path/to/your/project';
const manager = new DependenciesManager(projectRoot, metadataDetails);
manager.setCompress();
manager.sortSimpleFirst();
const errors = manager.repairDependencies();
if(errors != undefinded){
}
}).catch((error) => {
});
Repair specified types
You can choose specified Metadata Types (and childs) to repair. See Metadata JSON Format section to understand the JSON Metadata Format
import { MetadataTypes, MetadataType, MetadataObject, MetadataItem } = from '@aurahelper/core';
import { DependenciesManager } from '@aurahelper/xml-definitions';
import { Connection } from '@aurahelper/connector';
const connection = new Connection('MyOrg', '50');
connection.setUsernameOrAlias('MyOrg');
connection.setSingleThread();
connection.listMetadataTypes().then((metadataDetails) => {
const projectRoot = 'path/to/your/project';
const types: {};
types[MetadataTypes.CUSTOM_APPLICATION] = new MetadataType(MetadataTypes.CUSTOM_APPLICATION, true);
types[MetadataTypes.PERMISSION_SET] = new MetadataType(MetadataTypes.PERMISSION_SET, false);
types[MetadataTypes.PERMISSION_SET].addChild(new MetadataObject('PermissionSet1', true));
types[MetadataTypes.PERMISSION_SET].addChild(new MetadataObject('PermissionSet2', true));
types[MetadataTypes.PERMISSION_SET].addChild(new MetadataObject('PermissionSet3', false));
const manager = new DependenciesManager(projectRoot, metadataDetails);
manager.setTypesToRepair(types);
const errors = manager.repairDependencies();
if(errors != undefinded){
}
}).catch((error) => {
});
Monitorize Progress
You can monitorize the progress for every file and metadata type with the progress calback. The progress callback return a ProgressStatus object with the progress data and some util methods to handle the progress
import { DependenciesManager } from '@aurahelper/xml-definitions';
import { Connection } from '@aurahelper/connector';
import { SORT_ORDER } from '@aurahelper/xml-compressor';
const connection = new Connection('MyOrg', '50');
connection.setUsernameOrAlias('MyOrg');
connection.setSingleThread();
connection.listMetadataTypes().then((metadataDetails) => {
const projectRoot = 'path/to/your/project';
const options = {
ignoreFile: 'path/to/the/ignore/file',
compress: true,
sortOrder: SORT_ORDER.SIMPLE_FIRST
};
const manager = new DependenciesManager(projectRoot, metadataDetails);
manager.setIgnoreFile('path/to/the/ignore/file').setCompress().sortSimpleFirst();
manager.onPrepare(() => {
console.log('Handle progress on prepare');
});
manager.onStartType(() => {
console.log('Handle progress on start type');
});
manager.onStartObject(() => {
console.log('Handle progress on start object');
});
...
const errors = manager.repairDependencies();
if(errors != undefinded){
}
}).catch((error) => {
});
Method to check errors on any Salesforce project dependencies to fix possible deploy errors.
Return:
Return an object with the errors data. See Only Check Response section to understand the response.
{ [key: string]: DependenciesCheckResponse[] }
| undefined
Throws:
This method can throw the next exceptions:
WrongDirectoryPathException
: If the project path is not a String or can't convert to absolute pathDirectoryNotFoundException
: If the project path not exists or not have access to itInvalidDirectoryPathException
: If the project path is not a directoryWrongFilePathException
: If the ignore file or types file is not a String or can't convert to absolute pathFileNotFoundException
: If the ignore file or types file not exists or not have access to itInvalidFilePathException
: If the ignore file or types file is not a fileWrongFormatException
: If types is not a Metadata JSON file or Metadata JSON Object or ignore file is not a JSON file
Examples:
Check errors only
import { DependenciesManager } from '@aurahelper/xml-definitions';
import { Connection } from '@aurahelper/connector';
const connection = new Connection('MyOrg', '50');
connection.setUsernameOrAlias('MyOrg');
connection.setSingleThread();
connection.listMetadataTypes().then((metadataDetails) => {
const projectRoot = 'path/to/your/project';
const manager = new DependenciesManager(projectRoot, metadataDetails);
manager.onPrepare(() => {
console.log('Handle progress on prepare');
});
manager.onStartType(() => {
console.log('Handle progress on start type');
});
manager.onStartObject(() => {
console.log('Handle progress on start object');
});
...
const errors = manager.checkErrors();
if(errors != undefinded){
}
}).catch((error) => {
});
When you repair dependencies with any option (compress or not, repair specified types...) the response error has the next structure:
{
"MetadataTypeName": {
"metadataType": "MetadataTypeName"
"errors": [
{
"file": "path/to/file"
"errors": [
{
"elementPath": "xmlSuperParentTag>xmlParentTag>xmlTag",
"value": "error value",
"metadataType": "error Metadata Type",
"metadataObject": "error Metadata Object",
"metadataItem": "error Metadata Item",
"xmlElement": {
}
},
{
...
},
{
...
}
]
},
{
...
},
{
...
}
]
}
}
Example:
{
"CustomApplication": {
"metadataType": "CustomApplication"
"errors": [
{
"file": "..../force-app/main/default/applications/customApplicationExample.app-meta.xml"
"errors": [
{
"elementPath": "actionOverrides>content",
"value": "FlexiPageExample",
"metadataType": "FlexiPage",
"metadataObject": "FlexiPageExample",
"xmlElement": {
"actionName": "View",
"comment": "Action override description",
"content": "FlexiPageExample",
"formFactor": "Large",
"pageOrSobjectType": "Account",
"skipRecordTypeSelect": false,
"type": "Flexipage"
}
},
{
...
},
{
...
}
]
},
{
...
},
{
...
}
]
},
"PermissionSet": {
"metadataType": "PermissionSet"
"errors": [
{
"file": "..../force-app/main/default/permissionsets/permissionSetExample.app-meta.xml"
"errors": [
{
"elementPath": "fieldPermissions>field",
"value": "Account.custom_field__c",
"metadataType": "CustomField",
"metadataObject": "Account",
"metadataItem": "custom_field__c",
"xmlElement": {
"editable": false,
"field": "Account.custom_field__c",
"readable": false
}
},
{
...
},
{
...
}
]
},
{
...
},
{
...
}
]
}
}
When you only check dependencies errors the response error has the next structure:
{
"MetadataTypeName": [
{
"object": "MetadataObject",
"item": "MetadataItem",
"line": 16,
"startColumn": 146,
"endColumn": 166,
"message": "MetadataTypeName named MetadataObject.MetadataItem does not exists",
"severity": "Warning",
"file": "/path/to/file"
},
{
"object": "MetadataObject",
"item": "MetadataItem",
"line": 17,
"startColumn": 146,
"endColumn": 166,
"message": "MetadataTypeName named MetadataObject.MetadataItem does not exists",
"severity": "Warning",
"file": "/path/to/file"
},
],
"MetadataTypeName": [
{
...
},
{
...
}
]
}
Example:
{
"CustomApplication": [
{
"object": "FlexiPageExample",
"line": 16,
"startColumn": 146,
"endColumn": 166,
"message": "FlexiPage named FlexiPageExample does not exists",
"severity": "Warning",
"file": "..../force-app/main/default/applications/customApplicationExample.app-meta.xml"
},
{
"object": "FlexiPageExample",
"line": 17,
"startColumn": 146,
"endColumn": 166,
"message": "FlexiPage named FlexiPageExample does not exists",
"severity": "Warning",
"file": "..../force-app/main/default/applications/customApplicationExample.app-meta.xml"
},
],
"PermissionSet": [
{
"object": "Account",
"item": "custom_field__c",
"line": 1771,
"startColumn": 56,
"endColumn": 85,
"message": "CustomField named Account.custom_field__c does not exists",
"severity": "Warning",
"file": "..../force-app/main/default/permissionsets/permissionSetExample.permissionset-meta.xml"
},
{
"object": "Account",
"item": "custom_field2__c",
"line": 1772,
"startColumn": 56,
"endColumn": 85,
"message": "CustomField named Account.custom_field2__c does not exists",
"severity": "Warning",
"file": "..../force-app/main/default/permissionsets/permissionSetExample.permissionset-meta.xml"
},
]
}
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",
"checked": false,
"path": "path/to/the/metadata/folder",
"suffix": "fileSuffix",
"childs": {
"MetadataObjectName":{
"name": "MetadataObjectName",
"checked": false,
"path": "path/to/the/metadata/file/or/folder",
"childs": {
"MetadataItemName": {
"name": "MetadataItemName",
"checked": false,
"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,
"path": "path/to/root/project/force-app/main/default/objects/Account/Account.object-meta.xml",
"childs": {}
},
"Case": {
"name": "Case",
"checked": true,
"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,
"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,
"path": "path/to/root/project/force-app/main/default/objects/Account/fields/CaseNumber.field-meta.xml",
},
...,
...,
...
}
},
...,
...,
...
}
}
}
The ignore file is a JSON file used on ignore, create package or dependencies manager modules. On this file you can specify metadata types, objects and elements for ignore or delete from your local project, package files or ignore when check dependencies.
The ignore file have the next structure
{
"MetadataTypeAPIName": {
"MetadataObject1",
"MetadataObject2"
}
"MetadataTypeAPIName": {
"MetadataObject1:MetadataItem1",
"MetadataObject1:MetadataItem2",
"MetadataObject2:*",
"*",
"*:*"
}
"MetadataTypeAPIName": {
"UserPermission:MetadataObject1:PermissionName",
"UserPermission:MetadataObject2:*",
"UserPermission:*:PermissionName"
}
}
Example:
{
"CustomLabels": {
"labelName1",
"labelName2",
"*"
},
"AssignmentRules":{
"Case:Assign1",
"Lead:*",
"*"
},
"CustomObject": {
"Account",
"Case:*",
"*",
"*:*",
},
"Report": {
"ReportFolder",
"ReportFolder1:ReportName2",
"*",
},
"Workflow": {
"Account",
"*"
},
"WorkflowRule": {
"Case:*",
"Account:Rule1",
"*"
},
"Profile": {
"UserPermission:*:Permission1",
"UserPermission:TestProfile:*",
"UserPermission:Admin:Perm1",
"TestProfile2",
"*"
}
}
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.