mcdev 3.0.0 → 3.1.0

package/lib/metadataTypes/Query.js

@@ -4,6 +4,32 @@ const MetadataType = require('./MetadataType');
 const Util = require('../util/util');
 const File = require('../util/file');
 const Mustache = require('mustache');
+
+/**
+ * @typedef {Object} QueryItem
+ * @property {string} name name
+ * @property {string} key key
+ * @property {string} description -
+ * @property {string} targetKey key of target data extension
+ * @property {string} createdDate e.g. "2020-09-14T01:42:03.017"
+ * @property {string} modifiedDate e.g. "2020-09-14T01:42:03.017"
+ * @property {'Overwrite'|'Update'|'Append'} targetUpdateTypeName defines how the query writes into the target data extension
+ * @property {0|1|2} [targetUpdateTypeId] mapped to targetUpdateTypeName via this.definition.targetUpdateTypeMapping
+ * @property {string} [targetId] Object ID of DE (removed before save)
+ * @property {string} [targetDescription] Description DE (removed before save)
+ * @property {boolean} isFrozen looks like this is always set to false
+ * @property {string} [queryText] contains SQL query with line breaks converted to '\n'. The content is extracted during retrieval and written into a separate *.sql file
+ * @property {string} [categoryId] holds folder ID, replaced with r__folder_Path during retrieve
+ * @property {string} r__folder_Path folder path in which this DE is saved
+ *
+ * @typedef {Object.<string, QueryItem>} QueryMap
+ *
+ * @typedef {Object} CodeExtractItem
+ * @property {QueryItem} json metadata of one item w/o code
+ * @property {MetadataType.CodeExtract[]} codeArr list of code snippets in this item
+ * @property {string[]} subFolder mostly set to null, otherwise list of subfolders
+ */
+
 /**
  * Query MetadataType
  * @augments MetadataType
@@ -11,8 +37,8 @@ const Mustache = require('mustache');
 class Query extends MetadataType {
     /**
      * Retrieves Metadata of queries
-     * @param {String} retrieveDir Directory where retrieved metadata directory will be saved
-     * @returns {Promise<Object>} Promise of metadata
+     * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
+     * @returns {Promise<{metadata:QueryMap,type:string}>} Promise of metadata
      */
     static async retrieve(retrieveDir) {
         return super.retrieveREST(retrieveDir, '/automation/v1/queries/', null);
@@ -20,7 +46,7 @@ class Query extends MetadataType {
 
     /**
      * Retrieves query metadata for caching
-     * @returns {Promise<Object>} Promise of metadata
+     * @returns {Promise<{metadata:QueryMap,type:string}>} Promise of metadata
      */
     static async retrieveForCache() {
         return super.retrieveREST(null, '/automation/v1/queries/', null);
@@ -28,26 +54,30 @@ class Query extends MetadataType {
 
     /**
      * Retrieve a specific Query by Name
-     * @param {String} templateDir Directory where retrieved metadata directory will be saved
-     * @param {String} name name of the metadata file
-     * @param {Object} templateVariables variables to be replaced in the metadata
-     * @returns {Promise<Object>} Promise of metadata
+     * @param {string} templateDir Directory where retrieved metadata directory will be saved
+     * @param {string} name name of the metadata file
+     * @param {Util.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @returns {Promise<{metadata:QueryMap,type:string}>} Promise of metadata
      */
     static async retrieveAsTemplate(templateDir, name, templateVariables) {
-        return super.retrieveREST(
+        const response = await super.retrieveREST(
             templateDir,
             '/automation/v1/queries/?$filter=Name%20eq%20' + name.split(' ').join('%20'),
             null,
             templateVariables
         );
+        if (response && response.metadata && !Object.keys(response.metadata).length) {
+            Util.logger.error(`${this.definition.type} '${name}' not found on server.`);
+        }
+        return response;
     }
 
     /**
      * manages post retrieve steps
-     * @param {Object} metadata a single query
-     * @param {String} _ unused
-     * @param {Boolean} isTemplating signals that we are retrieving templates
-     * @returns {Object[]} Array with one metadata object and one query string
+     * @param {QueryItem} metadata a single query
+     * @param {string} _ unused
+     * @param {boolean} isTemplating signals that we are retrieving templates
+     * @returns {CodeExtractItem} Array with one metadata object and one query string
      */
     static postRetrieveTasks(metadata, _, isTemplating) {
         // if retrieving template, replace the name with customer key if that wasn't already the case
@@ -61,7 +91,7 @@ class Query extends MetadataType {
 
     /**
      * Creates a single query
-     * @param {Object} query a single query
+     * @param {QueryItem} query a single query
      * @returns {Promise} Promise
      */
     static create(query) {
@@ -71,7 +101,7 @@ class Query extends MetadataType {
 
     /**
      * Updates a single query
-     * @param {Object} query a single query
+     * @param {QueryItem} query a single query
      * @returns {Promise} Promise
      */
     static update(query) {
@@ -81,9 +111,9 @@ class Query extends MetadataType {
 
     /**
      * prepares a Query for deployment
-     * @param {Object} metadata a single query activity definition
-     * @param {String} deployDir directory of deploy files
-     * @returns {Promise} Promise
+     * @param {QueryItem} metadata a single query activity
+     * @param {string} deployDir directory of deploy files
+     * @returns {Promise<QueryItem>} Promise
      */
     static async preDeployTasks(metadata, deployDir) {
         metadata.queryText = await File.readFile(
@@ -114,20 +144,19 @@ class Query extends MetadataType {
         } catch (ex) {
             throw new Error(`Query '${metadata.key}': ${ex.message}`);
         }
-        metadata.targetUpdateTypeId = this.definition.targetUpdateTypeMapping[
-            metadata.targetUpdateTypeName
-        ];
+        metadata.targetUpdateTypeId =
+            this.definition.targetUpdateTypeMapping[metadata.targetUpdateTypeName];
         return metadata;
     }
 
     /**
      * helper for buildDefinition
      * handles extracted code if any are found for complex types
-     * @param {String} templateDir Directory where metadata templates are stored
-     * @param {String|String[]} targetDir (List of) Directory where built definitions will be saved
+     * @param {string} templateDir Directory where metadata templates are stored
+     * @param {string|string[]} targetDir (List of) Directory where built definitions will be saved
      * @param {Object} metadata main JSON file that was read from file system
      * @param {Object} variables variables to be replaced in the metadata
-     * @param {String} templateName name of the template to be built
+     * @param {string} templateName name of the template to be built
      * @returns {Promise} Promise
      */
     static async buildDefinitionForExtracts(
@@ -180,8 +209,8 @@ class Query extends MetadataType {
 
     /**
      * parses retrieved Metadata before saving
-     * @param {Object} metadata a single query activity definition
-     * @returns {Array} Array with one metadata object and one sql string
+     * @param {QueryItem} metadata a single query activity definition
+     * @returns {CodeExtractItem} a single item with code parts extracted
      */
     static parseMetadata(metadata) {
         // folder

package/lib/metadataTypes/Role.js

@@ -107,14 +107,19 @@ class Role extends MetadataType {
             return;
         }
         if (!metadata) {
-            metadata = this.readBUMetadataForType(
-                File.normalizePath([
-                    this.properties.directories.retrieve,
-                    buObject.credential,
-                    Util.parentBuName,
-                ]),
-                true
-            ).role;
+            try {
+                metadata = this.readBUMetadataForType(
+                    File.normalizePath([
+                        this.properties.directories.retrieve,
+                        buObject.credential,
+                        Util.parentBuName,
+                    ]),
+                    true
+                ).role;
+            } catch (ex) {
+                Util.logger.error(ex.message);
+                return;
+            }
         }
         const directory = this.properties.directories.roles;
 

package/lib/metadataTypes/Script.js

@@ -5,6 +5,25 @@ const Util = require('../util/util');
 const File = require('../util/file');
 const Mustache = require('mustache');
 
+/**
+ * @typedef {Object} ScriptItem
+ * @property {string} name name
+ * @property {string} key key
+ * @property {string} description -
+ * @property {string} createdDate e.g. "2020-09-14T01:42:03.017"
+ * @property {string} modifiedDate e.g. "2020-09-14T01:42:03.017"
+ * @property {string} [script] contains script with line breaks converted to '\n'. The content is extracted during retrieval and written into a separate *.ssjs file
+ * @property {string} [categoryId] holds folder ID, replaced with r__folder_Path during retrieve
+ * @property {string} r__folder_Path folder path in which this DE is saved
+ *
+ * @typedef {Object.<string, ScriptItem>} ScriptMap
+ *
+ * @typedef {Object} CodeExtractItem
+ * @property {ScriptItem} json metadata of one item w/o code
+ * @property {MetadataType.CodeExtract[]} codeArr list of code snippets in this item
+ * @property {string[]} subFolder mostly set to null, otherwise list of subfolders
+ */
+
 /**
  * Script MetadataType
  * @augments MetadataType
@@ -13,8 +32,8 @@ class Script extends MetadataType {
     /**
      * Retrieves Metadata of Script
      * Endpoint /automation/v1/scripts/ return all Scripts with all details.
-     * @param {String} retrieveDir Directory where retrieved metadata directory will be saved
-     * @returns {Promise} Promise
+     * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
+     * @returns {Promise<{metadata:ScriptMap,type:string}>} Promise
      */
     static async retrieve(retrieveDir) {
         await File.initPrettier('ssjs');
@@ -22,7 +41,7 @@ class Script extends MetadataType {
     }
     /**
      * Retrieves script metadata for caching
-     * @returns {Promise} Promise
+     * @returns {Promise<{metadata:ScriptMap,type:string}>} Promise
      */
     static async retrieveForCache() {
         return super.retrieveREST(null, '/automation/v1/scripts/', null);
@@ -30,10 +49,10 @@ class Script extends MetadataType {
 
     /**
      * Retrieve a specific Script by Name
-     * @param {String} templateDir Directory where retrieved metadata directory will be saved
-     * @param {String} name name of the metadata file
-     * @param {Object} templateVariables variables to be replaced in the metadata
-     * @returns {Promise} Promise
+     * @param {string} templateDir Directory where retrieved metadata directory will be saved
+     * @param {string} name name of the metadata file
+     * @param {Util.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @returns {Promise<{metadata:ScriptMap,type:string}>} Promise
      */
     static async retrieveAsTemplate(templateDir, name, templateVariables) {
         await File.initPrettier('ssjs');
@@ -47,10 +66,10 @@ class Script extends MetadataType {
 
     /**
      * manages post retrieve steps
-     * @param {Object} metadata a single script
-     * @param {String} [_] unused
-     * @param {Boolean} [isTemplating] signals that we are retrieving templates
-     * @returns {Object[]} Array with one metadata object and one ssjs string
+     * @param {ScriptItem} metadata a single script
+     * @param {string} [_] unused
+     * @param {boolean} [isTemplating] signals that we are retrieving templates
+     * @returns {CodeExtractItem} Array with one metadata object and one ssjs string
      */
     static postRetrieveTasks(metadata, _, isTemplating) {
         // if retrieving template, replace the name with customer key if that wasn't already the case
@@ -82,9 +101,9 @@ class Script extends MetadataType {
 
     /**
      * helper for this.preDeployTasks() that loads extracted code content back into JSON
-     * @param {Object} metadata a single asset definition
-     * @param {String} deployDir directory of deploy files
-     * @param {String} [templateName] name of the template used to built defintion (prior applying templating)
+     * @param {ScriptItem} metadata a single asset definition
+     * @param {string} deployDir directory of deploy files
+     * @param {string} [templateName] name of the template used to built defintion (prior applying templating)
      * @returns {Promise<String>} content for metadata.script
      */
     static async _mergeCode(metadata, deployDir, templateName) {
@@ -116,9 +135,9 @@ class Script extends MetadataType {
     }
     /**
      * prepares a Script for deployment
-     * @param {Object} metadata a single script activity definition
-     * @param {String} dir directory of deploy files
-     * @returns {Promise} Promise
+     * @param {ScriptItem} metadata a single script activity definition
+     * @param {string} dir directory of deploy files
+     * @returns {ScriptItem} Promise
      */
     static async preDeployTasks(metadata, dir) {
         // folder
@@ -144,11 +163,11 @@ class Script extends MetadataType {
     /**
      * helper for buildDefinition
      * handles extracted code if any are found for complex types
-     * @param {String} templateDir Directory where metadata templates are stored
-     * @param {String|String[]} targetDir (List of) Directory where built definitions will be saved
-     * @param {Object} metadata main JSON file that was read from file system
-     * @param {Object} variables variables to be replaced in the metadata
-     * @param {String} templateName name of the template to be built
+     * @param {string} templateDir Directory where metadata templates are stored
+     * @param {string|string[]} targetDir (List of) Directory where built definitions will be saved
+     * @param {ScriptItem} metadata main JSON file that was read from file system
+     * @param {Util.TemplateMap} variables variables to be replaced in the metadata
+     * @param {string} templateName name of the template to be built
      * @returns {Promise} Promise
      */
     static async buildDefinitionForExtracts(
@@ -187,8 +206,8 @@ class Script extends MetadataType {
 
     /**
      * Splits the script metadata into two parts and parses in a standard manner
-     * @param {Object} metadata a single script activity definition
-     * @returns {Object[]} Array with one metadata object and one ssjs string
+     * @param {ScriptItem} metadata a single script activity definition
+     * @returns {CodeExtractItem} a single item with code parts extracted
      */
     static parseMetadata(metadata) {
         // folder

package/lib/metadataTypes/definitions/AccountUser.definition.js

@@ -0,0 +1,227 @@
+module.exports = {
+    bodyIteratorField: 'Results',
+    dependencies: [],
+    folderType: null,
+    hasExtended: false,
+    idField: 'ID',
+    keyField: 'CustomerKey',
+    nameField: 'Name',
+    type: 'accountUser',
+    typeDescription: 'Marketing Cloud users',
+    typeName: 'User',
+    typeRetrieveByDefault: false,
+    fields: {
+        AccountUserID: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: true,
+            template: false,
+        },
+        ActiveFlag: { isCreateable: null, isUpdateable: null, retrieving: true, template: false },
+        AssociatedBusinessUnits: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: null,
+        },
+        BusinessUnit: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: null,
+        },
+        ChallengeAnswer: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: true,
+            template: false,
+        },
+        ChallengePhrase: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: true,
+            template: false,
+        },
+        Client: { isCreateable: null, isUpdateable: null, retrieving: false, template: null },
+        CorrelationID: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: null,
+        },
+        CreatedDate: { isCreateable: null, isUpdateable: null, retrieving: true, template: false },
+        CustomerKey: { isCreateable: null, isUpdateable: null, retrieving: true, template: false },
+        DefaultApplication: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: null,
+        },
+        DefaultBusinessUnit: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: true,
+            template: false,
+        },
+        DefaultBusinessUnitObject: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: null,
+        },
+        Delete: { isCreateable: null, isUpdateable: null, retrieving: false, template: null },
+        Email: { isCreateable: null, isUpdateable: null, retrieving: true, template: false },
+        ID: { isCreateable: null, isUpdateable: null, retrieving: true, template: false },
+        IsAPIUser: { isCreateable: null, isUpdateable: null, retrieving: true, template: false },
+        IsLocked: { isCreateable: null, isUpdateable: null, retrieving: true, template: false },
+        LanguageLocale: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: null,
+        },
+        LastSuccessfulLogin: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: true,
+            template: false,
+        },
+        Locale: { isCreateable: null, isUpdateable: null, retrieving: false, template: null },
+        ModifiedDate: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: true,
+            template: false,
+        },
+        MustChangePassword: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: true,
+            template: false,
+        },
+        Name: { isCreateable: null, isUpdateable: null, retrieving: true, template: false },
+        NotificationEmailAddress: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: true,
+            template: false,
+        },
+        ObjectID: { isCreateable: null, isUpdateable: null, retrieving: false, template: null },
+        ObjectState: { isCreateable: null, isUpdateable: null, retrieving: false, template: null },
+        Owner: { isCreateable: null, isUpdateable: null, retrieving: false, template: null },
+        PartnerKey: { isCreateable: null, isUpdateable: null, retrieving: false, template: null },
+        PartnerProperties: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: null,
+        },
+        Password: { isCreateable: null, isUpdateable: null, retrieving: false, template: false },
+        Roles: { isCreateable: null, isUpdateable: null, retrieving: true, template: false },
+        'Roles.Role': {
+            skipValidation: false,
+        },
+        'Roles.Role[].Client': {
+            skipValidation: false,
+        },
+        SsoIdentities: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: null,
+        },
+        TimeZone: { isCreateable: null, isUpdateable: null, retrieving: false, template: null },
+        Unlock: { isCreateable: null, isUpdateable: null, retrieving: false, template: null },
+        UserID: { isCreateable: null, isUpdateable: null, retrieving: true, template: false },
+        UserPermissions: {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: true,
+            template: false,
+        },
+        'UserPermissions.PartnerKey': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions.ID': {
+            skipValidation: true,
+        },
+        'UserPermissions.ObjectID': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions.Name': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions.Value': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions.Description': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions.Delete': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions[].PartnerKey': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions[].ID': {
+            skipValidation: true,
+        },
+        'UserPermissions[].ObjectID': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions[].Name': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions[].Value': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions[].Description': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        'UserPermissions[].Delete': {
+            isCreateable: null,
+            isUpdateable: null,
+            retrieving: false,
+            template: false,
+        },
+        type__c: {
+            skipValidation: true,
+        },
+        AssociatedBusinessUnits__c: {
+            skipValidation: true,
+        },
+    },
+};

package/lib/metadataTypes/definitions/Asset.definition.js

@@ -677,6 +677,7 @@ module.exports = {
         ],
     },
     typeMapping: {
+        ai: 16,
         psd: 17,
         pdd: 18,
         eps: 19,

package/lib/metadataTypes/definitions/Campaign.definition.js

@@ -8,7 +8,7 @@ module.exports = {
     restPagination: true,
     type: 'campaign',
     typeDescription: 'Way of tagging/categorizing emails, journeys and alike.',
-    typeRetrieveByDefault: true,
+    typeRetrieveByDefault: false,
     typeName: 'Campaign Tag',
     fields: {},
 };

package/lib/metadataTypes/definitions/DataExtension.definition.js

@@ -167,7 +167,7 @@ module.exports = {
         ModifiedDate: {
             isCreateable: false,
             isUpdateable: false,
-            retrieving: false,
+            retrieving: true,
             template: false,
         },
         Name: {

package/lib/metadataTypes/definitions/DataExtensionField.definition.js

@@ -92,7 +92,7 @@ module.exports = {
         },
         ObjectID: {
             isCreateable: false,
-            isUpdateable: null,
+            isUpdateable: true,
             retrieving: false,
             template: false,
         },

package/lib/metadataTypes/definitions/Folder.definition.js

@@ -93,7 +93,7 @@ module.exports = {
         },
         ContentType: {
             isCreateable: true,
-            isUpdateable: true,
+            isUpdateable: false,
             retrieving: true,
             template: true,
         },

package/lib/metadataTypes/definitions/ImportFile.definition.js

@@ -1,7 +1,8 @@
 module.exports = {
     bodyIteratorField: 'items',
-    dependencies: ['ftpLocation', 'dataExtension', 'list'],
+    dependencies: ['folder', 'ftpLocation', 'dataExtension', 'list'], // folder has to be kept in here to resolve lists correctly
     destinationObjectTypeMapping: {
+        unknown: 783,
         DataExtension: 310,
         List: 13,
         SMS: 584,

package/lib/metadataTypes/definitions/Script.definition.js

@@ -21,7 +21,7 @@ module.exports = {
         createdBy: {
             isCreateable: false,
             isUpdateable: false,
-            retrieving: true,
+            retrieving: false,
             template: false,
         },
         createdDate: {
@@ -51,7 +51,7 @@ module.exports = {
         modifiedBy: {
             isCreateable: false,
             isUpdateable: false,
-            retrieving: true,
+            retrieving: false,
             template: false,
         },
         modifiedDate: {
@@ -79,9 +79,9 @@ module.exports = {
             template: false,
         },
         status: {
-            isCreateable: null,
-            isUpdateable: null,
-            retrieving: true,
+            isCreateable: false,
+            isUpdateable: false,
+            retrieving: false,
             template: false,
         },
         statusId: {