mcdev 3.1.1 → 4.0.0

package/lib/metadataTypes/MobileCode.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const TYPE = require('../../types/mcdev.d');
+const MetadataType = require('./MetadataType');
+
+/**
+ * MobileCode MetadataType
+ *
+ * @augments MetadataType
+ */
+class MobileCode extends MetadataType {
+    /**
+     * Retrieves Metadata of Mobile Keywords
+     * Endpoint /legacy/v1/beta/mobile/code/ return all Mobile Codes with all details.
+     *
+     * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
+     * @param {void} [_] unused parameter
+     * @param {void} [__] unused parameter
+     * @param {void} [___] unused parameter
+     * @param {string} [key] customer key of single item to retrieve
+     * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise of metadata
+     */
+    static retrieve(retrieveDir, _, __, ___, key) {
+        return super.retrieveREST(
+            retrieveDir,
+            '/legacy/v1/beta/mobile/code/' + (key ? `?$where=keyword%20eq%20%27${key}%27%20` : ''),
+            null,
+            null,
+            key
+        );
+    }
+
+    /**
+     * Retrieves event definition metadata for caching
+     *
+     * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise of metadata
+     */
+    static retrieveForCache() {
+        return super.retrieveREST(null, '/legacy/v1/beta/mobile/code/');
+    }
+}
+
+// Assign definition to static attributes
+MobileCode.definition = require('../MetadataTypeDefinitions').mobileCode;
+
+module.exports = MobileCode;

package/lib/metadataTypes/MobileKeyword.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const TYPE = require('../../types/mcdev.d');
+const MetadataType = require('./MetadataType');
+const Util = require('../util/util');
+const File = require('../util/file');
+const cache = require('../util/cache');
+
+/**
+ * MobileKeyword MetadataType
+ *
+ * @augments MetadataType
+ */
+class MobileKeyword extends MetadataType {
+    /**
+     * Retrieves Metadata of Mobile Keywords
+     * Endpoint /legacy/v1/beta/mobile/keyword/ return all Mobile Keywords with all details.
+     *
+     * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
+     * @param {void} [_] unused parameter
+     * @param {void} [__] unused parameter
+     * @param {void} [___] unused parameter
+     * @param {string} [key] customer key of single item to retrieve
+     * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise of metadata
+     */
+    static retrieve(retrieveDir, _, __, ___, key) {
+        return super.retrieveREST(
+            retrieveDir,
+            '/legacy/v1/beta/mobile/keyword/?view=simple' +
+                (key ? `&$where=keyword%20eq%20%27${key}%27%20` : ''),
+            null,
+            null,
+            key
+        );
+    }
+
+    /**
+     * Retrieves event definition metadata for caching
+     *
+     * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise of metadata
+     */
+    static retrieveForCache() {
+        return super.retrieveREST(null, '/legacy/v1/beta/mobile/keyword/?view=simple');
+    }
+
+    /**
+     * Retrieve a specific keyword
+     *
+     * @param {string} templateDir Directory where retrieved metadata directory will be saved
+     * @param {string} name name of the metadata file
+     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @returns {Promise.<TYPE.MetadataTypeItemObj>} Promise of metadata
+     */
+    static async retrieveAsTemplate(templateDir, name, templateVariables) {
+        // TODO: Decide if we want to keep default handling (and move other types) or keep unique parsing?
+        try {
+            const res = await this.client.rest.get(
+                `/legacy/v1/beta/mobile/keyword/?view=simple&$where=keyword%20eq%20%27${name}%27%20`
+            );
+            const metadata = JSON.parse(
+                Util.replaceByObject(
+                    JSON.stringify(Util.templateSearchResult(res.entry, 'keyword', name)),
+                    templateVariables
+                )
+            );
+            if (!metadata.code.id) {
+                throw new Error(
+                    `MobileKeyword.parseMetadata:: ` +
+                        `No Mobile Code was found for ` +
+                        `event: ${metadata.name}. ` +
+                        `This cannot be templated`
+                );
+            }
+            // remove all fields listed in Definition for templating
+            this.keepTemplateFields(metadata);
+            await File.writeJSONToFile(
+                [templateDir, this.definition.type].join('/'),
+                metadata.keyword + '.' + this.definition.type + '-meta',
+                metadata
+            );
+            Util.logger.info(`- templated ${this.definition.type}: ${name}`);
+            return { metadata: metadata, type: this.definition.type };
+        } catch (ex) {
+            Util.logger.error('MobileKeyword.retrieveAsTemplate:: ' + ex);
+            return null;
+        }
+    }
+
+    /**
+     * Creates a single Event Definition
+     *
+     * @param {TYPE.MetadataTypeItem} MobileKeyword a single Event Definition
+     * @returns {Promise} Promise
+     */
+    static create(MobileKeyword) {
+        return super.createREST(MobileKeyword, '/legacy/v1/beta/mobile/keyword/');
+    }
+
+    /**
+     * prepares an event definition for deployment
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single MobileKeyword
+     * @returns {TYPE.MetadataTypeItem} Promise
+     */
+    static preDeployTasks(metadata) {
+        metadata.code.id = cache.searchForField('mobileCode', metadata.code.code, 'code', 'id');
+        return metadata;
+    }
+}
+
+// Assign definition to static attributes
+MobileKeyword.definition = require('../MetadataTypeDefinitions').mobileKeyword;
+
+module.exports = MobileKeyword;

package/lib/metadataTypes/Query.js

@@ -1,97 +1,98 @@
 'use strict';
 
+const TYPE = require('../../types/mcdev.d');
 const MetadataType = require('./MetadataType');
 const Util = require('../util/util');
 const File = require('../util/file');
+const cache = require('../util/cache');
 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
  */
 class Query extends MetadataType {
     /**
      * Retrieves Metadata of queries
+     *
      * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
-     * @returns {Promise<{metadata:QueryMap,type:string}>} Promise of metadata
+     * @param {void} [_] unused parameter
+     * @param {void} [__] unused parameter
+     * @param {void} [___] unused parameter
+     * @param {string} [key] customer key of single item to retrieve
+     * @returns {Promise.<{metadata: TYPE.QueryMap, type: string}>} Promise of metadata
+     */
+    static async retrieve(retrieveDir, _, __, ___, key) {
+        await File.initPrettier('sql');
+        const objectId = key ? await this._getObjectIdForSingleRetrieve(key) : null;
+        return super.retrieveREST(
+            retrieveDir,
+            '/automation/v1/queries/' + (objectId || ''),
+            null,
+            null,
+            key
+        );
+    }
+    /**
+     * helper to allow us to select single metadata entries via REST
+     *
+     * @private
+     * @param {string} key customer key
+     * @returns {Promise.<string>} objectId or enpty string
      */
-    static async retrieve(retrieveDir) {
-        return super.retrieveREST(retrieveDir, '/automation/v1/queries/', null);
+    static async _getObjectIdForSingleRetrieve(key) {
+        const response = await this.client.soap.retrieve('QueryDefinition', ['ObjectID'], {
+            filter: {
+                leftOperand: 'CustomerKey',
+                operator: 'equals',
+                rightOperand: key,
+            },
+        });
+        return response?.Results?.length ? response.Results[0].ObjectID : null;
     }
 
     /**
      * Retrieves query metadata for caching
-     * @returns {Promise<{metadata:QueryMap,type:string}>} Promise of metadata
+     *
+     * @returns {Promise.<{metadata: TYPE.QueryMap, type: string}>} Promise of metadata
      */
     static async retrieveForCache() {
-        return super.retrieveREST(null, '/automation/v1/queries/', null);
+        return super.retrieveREST(null, '/automation/v1/queries/');
     }
 
     /**
      * 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 {Util.TemplateMap} templateVariables variables to be replaced in the metadata
-     * @returns {Promise<{metadata:QueryMap,type:string}>} Promise of metadata
+     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @returns {Promise.<{metadata: Query, type: string}>} Promise of metadata
      */
     static async retrieveAsTemplate(templateDir, name, templateVariables) {
-        const response = await super.retrieveREST(
+        await File.initPrettier('sql');
+        return super.retrieveREST(
             templateDir,
-            '/automation/v1/queries/?$filter=Name%20eq%20' + name.split(' ').join('%20'),
+            '/automation/v1/queries/?$filter=Name%20eq%20' + encodeURIComponent(name),
             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 {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
+     *
+     * @param {TYPE.QueryItem} metadata a single query
+     * @returns {TYPE.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
-        if (isTemplating) {
-            const warningMsg =
-                'Ensure that Automations using this query are updated with the new query-key before deployment.';
-            this.overrideKeyWithName(metadata, warningMsg);
-        }
+    static postRetrieveTasks(metadata) {
         return this.parseMetadata(metadata);
     }
 
     /**
      * Creates a single query
-     * @param {QueryItem} query a single query
+     *
+     * @param {TYPE.QueryItem} query a single query
      * @returns {Promise} Promise
      */
     static create(query) {
@@ -101,7 +102,8 @@ class Query extends MetadataType {
 
     /**
      * Updates a single query
-     * @param {QueryItem} query a single query
+     *
+     * @param {TYPE.QueryItem} query a single query
      * @returns {Promise} Promise
      */
     static update(query) {
@@ -111,82 +113,142 @@ class Query extends MetadataType {
 
     /**
      * prepares a Query for deployment
-     * @param {QueryItem} metadata a single query activity
+     *
+     * @param {TYPE.QueryItem} metadata a single query activity
      * @param {string} deployDir directory of deploy files
-     * @returns {Promise<QueryItem>} Promise
+     * @returns {Promise.<TYPE.QueryItem>} Promise
      */
     static async preDeployTasks(metadata, deployDir) {
-        metadata.queryText = await File.readFile(
+        metadata.queryText = await File.readFilteredFilename(
             deployDir + '/' + this.definition.type,
             metadata.key + '.' + this.definition.type + '-meta',
             'sql'
         );
-        try {
-            metadata.targetKey = Util.getFromCache(
-                this.cache,
-                'dataExtension',
-                metadata.targetKey,
-                'CustomerKey',
-                'CustomerKey'
-            );
-        } catch (ex) {
-            throw new Error(`Query '${metadata.key}': ${ex.message}`);
-        }
-        try {
-            metadata.categoryId = Util.getFromCache(
-                this.cache,
-                'folder',
-                metadata.r__folder_Path,
-                'Path',
-                'ID'
-            );
-            delete metadata.r__folder_Path;
-        } catch (ex) {
-            throw new Error(`Query '${metadata.key}': ${ex.message}`);
-        }
+        metadata.targetKey = cache.searchForField(
+            'dataExtension',
+            metadata.targetKey,
+            'CustomerKey',
+            'CustomerKey'
+        );
+        metadata.categoryId = cache.searchForField('folder', metadata.r__folder_Path, 'Path', 'ID');
+        delete metadata.r__folder_Path;
         metadata.targetUpdateTypeId =
             this.definition.targetUpdateTypeMapping[metadata.targetUpdateTypeName];
         return metadata;
     }
+    /**
+     * helper for buildDefinitionForNested
+     * searches extracted SQL file for template variables and applies the market values
+     *
+     * @param {string} code code from extracted code
+     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @returns {string} code with markets applied
+     */
+    static applyTemplateValues(code, templateVariables) {
+        // fix bad formatting applied by SQL Formatter Plus
+        code = code
+            .split(' { { { ')
+            .join('{{{')
+            .split('{ { { ')
+            .join('{{{')
+            .split(' } } } ')
+            .join('}}}')
+            .split(' } } }')
+            .join('}}}');
 
+        // replace template variables with their values
+        return Mustache.render(code, templateVariables);
+    }
     /**
      * 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 {TYPE.QueryItem} metadata main JSON file that was read from file system
+     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
      * @param {string} templateName name of the template to be built
-     * @returns {Promise} Promise
+     * @returns {Promise.<string[][]>} list of extracted files with path-parts provided as an array
+     */
+    static buildDefinitionForNested(
+        templateDir,
+        targetDir,
+        metadata,
+        templateVariables,
+        templateName
+    ) {
+        return this._buildForNested(
+            templateDir,
+            targetDir,
+            metadata,
+            templateVariables,
+            templateName,
+            'definition'
+        );
+    }
+    /**
+     * helper for buildTemplate
+     * handles extracted code if any are found for complex types
+     *
+     * @example queries are saved as 1 json and 1 sql file. both files need to be run through templating
+     * @param {string} templateDir Directory where metadata templates are stored
+     * @param {string|string[]} targetDir (List of) Directory where built definitions will be saved
+     * @param {TYPE.QueryItem} metadata main JSON file that was read from file system
+     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @param {string} templateName name of the template to be built
+     * @returns {Promise.<string[][]>} list of extracted files with path-parts provided as an array
      */
-    static async buildDefinitionForExtracts(
+    static buildTemplateForNested(
         templateDir,
         targetDir,
         metadata,
-        variables,
+        templateVariables,
         templateName
+    ) {
+        return this._buildForNested(
+            templateDir,
+            targetDir,
+            metadata,
+            templateVariables,
+            templateName,
+            'template'
+        );
+    }
+    /**
+     * helper for buildTemplateForNested / buildDefinitionForNested
+     * handles extracted code if any are found for complex types
+     *
+     * @private
+     * @param {string} templateDir Directory where metadata templates are stored
+     * @param {string|string[]} targetDir (List of) Directory where built definitions will be saved
+     * @param {TYPE.QueryItem} metadata main JSON file that was read from file system
+     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @param {string} templateName name of the template to be built
+     * @param {'definition'|'template'} mode defines what we use this helper for
+     * @returns {Promise.<string[][]>} list of extracted files with path-parts provided as an array
+     */
+    static async _buildForNested(
+        templateDir,
+        targetDir,
+        metadata,
+        templateVariables,
+        templateName,
+        mode
     ) {
         // get SQL from filesystem
-        let code = await File.readFile(
+        let code = await File.readFilteredFilename(
             [templateDir, this.definition.type],
             templateName + '.' + this.definition.type + '-meta',
             'sql'
         );
-        // fix bad formatting applied by SQL Formatter Plus
-        code = code
-            .split(' { { { ')
-            .join('{{{')
-            .split('{ { { ')
-            .join('{{{')
-            .split(' } } } ')
-            .join('}}}')
-            .split(' } } }')
-            .join('}}}');
 
-        // replace template variables with their values
         try {
-            code = Mustache.render(code, variables);
-        } catch (ex) {
+            if (mode === 'definition') {
+                code = this.applyTemplateValues(code, templateVariables);
+            } else if (mode === 'template') {
+                code = this.applyTemplateNames(code, templateVariables);
+            }
+        } catch {
             throw new Error(
                 `${this.definition.type}:: Error applying template variables on ${
                     metadata[this.definition.keyField] + '.' + this.definition.type
@@ -196,6 +258,7 @@ class Query extends MetadataType {
 
         // write to file
         const targetDirArr = Array.isArray(targetDir) ? targetDir : [targetDir];
+        const nestedFilePaths = [];
 
         for (const targetDir of targetDirArr) {
             File.writeToFile(
@@ -204,19 +267,25 @@ class Query extends MetadataType {
                 'sql',
                 code
             );
+            nestedFilePaths.push([
+                targetDir,
+                this.definition.type,
+                metadata[this.definition.keyField] + '.' + this.definition.type + '-meta.sql',
+            ]);
         }
+        return nestedFilePaths;
     }
 
     /**
      * parses retrieved Metadata before saving
-     * @param {QueryItem} metadata a single query activity definition
-     * @returns {CodeExtractItem} a single item with code parts extracted
+     *
+     * @param {TYPE.QueryItem} metadata a single query activity definition
+     * @returns {TYPE.CodeExtractItem} a single item with code parts extracted
      */
     static parseMetadata(metadata) {
         // folder
         try {
-            metadata.r__folder_Path = Util.getFromCache(
-                this.cache,
+            metadata.r__folder_Path = cache.searchForField(
                 'folder',
                 metadata.categoryId,
                 'ID',
@@ -224,7 +293,7 @@ class Query extends MetadataType {
             );
             delete metadata.categoryId;
         } catch (ex) {
-            Util.logger.warn(`Query '${metadata.key}': ${ex.message}`);
+            Util.logger.warn(` - Query '${metadata.key}': ${ex.message}`);
         }
 
         // extract SQL
@@ -240,11 +309,43 @@ class Query extends MetadataType {
 
         return { json: metadata, codeArr: codeArr, subFolder: null };
     }
+    /**
+     * should return only the json for all but asset, query and script that are saved as multiple files
+     * additionally, the documentation for dataExtension and automation should be returned
+     *
+     * @param {string[]} keyArr customerkey of the metadata
+     * @returns {string[]} list of all files that need to be committed in a flat array ['path/file1.ext', 'path/file2.ext']
+     */
+    static getFilesToCommit(keyArr) {
+        const path = File.normalizePath([
+            this.properties.directories.retrieve,
+            this.buObject.credential,
+            this.buObject.businessUnit,
+            this.definition.type,
+        ]);
+
+        const fileList = keyArr.flatMap((key) => [
+            File.normalizePath([path, `${key}.${this.definition.type}-meta.json`]),
+            File.normalizePath([path, `${key}.${this.definition.type}-meta.sql`]),
+        ]);
+        return fileList;
+    }
+
+    /**
+     *  Standardizes a check for multiple messages but adds query specific filters to error texts
+     *
+     * @param {object} ex response payload from REST API
+     * @returns {string[]} formatted Error Message
+     */
+    static checkForErrors(ex) {
+        const errors = super.checkForErrors(ex);
+        if (errors?.length > 0) {
+            return errors.map((msg) => msg.split('Error saving the Query field.').join(''));
+        }
+    }
 }
 
 // Assign definition & cache to static attributes
 Query.definition = require('../MetadataTypeDefinitions').query;
-Query.cache = {};
-Query.client = undefined;
 
 module.exports = Query;