Feature/984: bulk update notification email addresses

docs/dist/documentation.md

@@ -195,6 +195,8 @@ Provides default functionality that can be overwritten by child metadata type cl
 <dt><a href="#Mcdev.">Mcdev.(selectedType, buObject)</a> ⇒ <code>Array.&lt;string&gt;</code></dt>
 <dd><p>helper for <a href="Mcdev.#runOnBU">Mcdev.#runOnBU</a></p>
 </dd>
+<dt><a href="#Mcdev.">Mcdev.(cred, bu, type, [keys])</a> ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code></dt>
+<dd></dd>
 <dt><a href="#Automation.">Automation.(metadata)</a> ⇒ <code>boolean</code></dt>
 <dd><p>helper for <a href="#Automation.postRetrieveTasks">postRetrieveTasks</a> and <a href="#Automation.execute">execute</a></p>
 </dd>
@@ -216,6 +218,9 @@ Provides default functionality that can be overwritten by child metadata type cl
 <dt><a href="#Automation.">Automation.(metadataMap, originalMetadataMap, key)</a> ⇒ <code>Promise.&lt;{key:string, response:object}&gt;</code></dt>
 <dd><p>helper for <a href="#Automation.postDeployTasks">postDeployTasks</a></p>
 </dd>
+<dt><a href="#Automation.">Automation.()</a> ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code></dt>
+<dd><p>helper function to retrieve data about all automations in the BU</p>
+</dd>
 <dt><a href="#getUserName">getUserName(userList, item, fieldname)</a> ⇒ <code>string</code></dt>
 <dd></dd>
 <dt><a href="#setupSDK">setupSDK(sessionKey, authObject)</a> ⇒ <code><a href="#SDK">SDK</a></code></dt>
@@ -520,6 +525,7 @@ main class
     * [.execute(businessUnit, [selectedType], [keys])](#Mcdev.execute) ⇒ <code>Promise.&lt;Object.&lt;string, Array.&lt;string&gt;&gt;&gt;</code>
     * [.pause(businessUnit, [selectedType], [keys])](#Mcdev.pause) ⇒ <code>Promise.&lt;Object.&lt;string, Array.&lt;string&gt;&gt;&gt;</code>
     * [.fixKeys(businessUnit, type, [keys])](#Mcdev.fixKeys) ⇒ <code>Promise.&lt;Object.&lt;string, Array.&lt;string&gt;&gt;&gt;</code>
+    * [.updateNotifications(businessUnit, type, [keys])](#Mcdev.updateNotifications) ⇒ <code>Promise.&lt;Object.&lt;string, Array.&lt;string&gt;&gt;&gt;</code>
 
 <a name="Mcdev.setSkipInteraction"></a>
 
@@ -827,6 +833,20 @@ Updates the key to match the name field
 | type | <code>TYPE.SupportedMetadataTypes</code> | limit execution to given metadata type |
 | [keys] | <code>Array.&lt;string&gt;</code> | customerkey of the metadata |
 
+<a name="Mcdev.updateNotifications"></a>
+
+### Mcdev.updateNotifications(businessUnit, type, [keys]) ⇒ <code>Promise.&lt;Object.&lt;string, Array.&lt;string&gt;&gt;&gt;</code>
+Updates notification email address field
+
+**Kind**: static method of [<code>Mcdev</code>](#Mcdev)  
+**Returns**: <code>Promise.&lt;Object.&lt;string, Array.&lt;string&gt;&gt;&gt;</code> - key: business unit name, value: list of affected item keys  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| businessUnit | <code>string</code> | name of BU |
+| type | <code>TYPE.SupportedMetadataTypes</code> | limit execution to given metadata type |
+| [keys] | <code>Array.&lt;string&gt;</code> | customerkey of the metadata |
+
 <a name="Asset"></a>
 
 ## Asset ⇐ [<code>MetadataType</code>](#MetadataType)
@@ -1384,6 +1404,7 @@ Automation MetadataType
     * [.getFilesToCommit(keyArr)](#Automation.getFilesToCommit) ⇒ <code>Array.&lt;string&gt;</code>
     * [.deleteByKey(customerKey)](#Automation.deleteByKey) ⇒ <code>boolean</code>
     * [.postDeleteTasks(customerKey)](#Automation.postDeleteTasks) ⇒ <code>void</code>
+    * [.updateNotifications(keys)](#Automation.updateNotifications) ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code>
 
 <a name="Automation.retrieve"></a>
 
@@ -1650,6 +1671,18 @@ clean up after deleting a metadata item
 | --- | --- | --- |
 | customerKey | <code>string</code> | Identifier of metadata item |
 
+<a name="Automation.updateNotifications"></a>
+
+### Automation.updateNotifications(keys) ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code>
+A function to update automation email notifications
+
+**Kind**: static method of [<code>Automation</code>](#Automation)  
+**Returns**: <code>Promise.&lt;Array.&lt;string&gt;&gt;</code> - keys of the automations where notifications were updated  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| keys | <code>string</code> | metadata keys |
+
 <a name="Campaign"></a>
 
 ## Campaign ⇐ [<code>MetadataType</code>](#MetadataType)
@@ -3380,6 +3413,7 @@ Provides default functionality that can be overwritten by child metadata type cl
     * [.readBUMetadataForType(readDir, [listBadKeys], [buMetadata])](#MetadataType.readBUMetadataForType) ⇒ <code>object</code>
     * [.getFilesToCommit(keyArr)](#MetadataType.getFilesToCommit) ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code>
     * [.getKeysForFixing(metadataMap)](#MetadataType.getKeysForFixing) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.setNotifEmailAddr()](#MetadataType.setNotifEmailAddr) ⇒ <code>Array.&lt;string&gt;</code>
 
 <a name="MetadataType.client"></a>
 
@@ -4207,6 +4241,13 @@ additionally, the documentation for dataExtension and automation should be retur
 | --- | --- | --- |
 | metadataMap | <code>TYPE.MetadataTypeMap</code> | metadata mapped by their keyField |
 
+<a name="MetadataType.setNotifEmailAddr"></a>
+
+### MetadataType.setNotifEmailAddr() ⇒ <code>Array.&lt;string&gt;</code>
+Abstract setNotifEmailAddr method that needs to be implemented in child metadata type
+
+**Kind**: static method of [<code>MetadataType</code>](#MetadataType)  
+**Returns**: <code>Array.&lt;string&gt;</code> - returns keys of items where notification email address was set  
 <a name="MobileCode"></a>
 
 ## MobileCode ⇐ [<code>MetadataType</code>](#MetadataType)
@@ -8469,6 +8510,19 @@ helper for [Mcdev.#runOnBU](Mcdev.#runOnBU)
 | selectedType | <code>TYPE.SupportedMetadataTypes</code> | limit execution to given metadata type |
 | buObject | <code>TYPE.BuObject</code> | properties for auth |
 
+<a name="Mcdev."></a>
+
+## Mcdev.(cred, bu, type, [keys]) ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code>
+**Kind**: global function  
+**Returns**: <code>Promise.&lt;Array.&lt;string&gt;&gt;</code> - keys of the automations where notifications were updated  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| cred | <code>string</code> | name of Credential |
+| bu | <code>string</code> | name of BU |
+| type | <code>string</code> | metadata type |
+| [keys] | <code>Array.&lt;string&gt;</code> | limit retrieval to given metadata keys |
+
 <a name="Automation."></a>
 
 ## Automation.(metadata) ⇒ <code>boolean</code>
@@ -8556,6 +8610,13 @@ helper for [postDeployTasks](#Automation.postDeployTasks)
 | originalMetadataMap | <code>TYPE.AutomationMap</code> | metadata to be updated (contains additioanl fields) |
 | key | <code>string</code> | current customer key |
 
+<a name="Automation."></a>
+
+## Automation.() ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code>
+helper function to retrieve data about all automations in the BU
+
+**Kind**: global function  
+**Returns**: <code>Promise.&lt;Array.&lt;string&gt;&gt;</code> - returns data about automations with the legacy key  
 <a name="getUserName"></a>
 
 ## getUserName(userList, item, fieldname) ⇒ <code>string</code>

lib/cli.js

@@ -543,6 +543,53 @@ yargs
             Mcdev.fixKeys(argv.BU, argv.TYPE, csvToArray(argv.KEY));
         },
     })
+    .command({
+        command: 'updateNotifications <BU> <TYPE> [KEY]',
+        aliases: ['updNotif'],
+        desc: 'bulk updates notification email addresses',
+        builder: (yargs) => {
+            yargs
+                .positional('BU', {
+                    type: 'string',
+                    describe: 'the business unit where to update notification email address',
+                })
+                .positional('TYPE', {
+                    type: 'string',
+                    describe: 'metadata type',
+                })
+                .positional('KEY', {
+                    type: 'string',
+                    describe: 'key(s) of the metadata component(s)',
+                })
+                .positional('emailError', {
+                    type: 'string',
+                    describe: 'email to notify that an error occured during execution',
+                })
+                .positional('emailComplete', {
+                    type: 'string',
+                    describe: 'email to notify about successfull completion',
+                })
+                .positional('errorNote', {
+                    type: 'string',
+                    describe: 'run error note',
+                })
+                .positional('completionNote', {
+                    type: 'string',
+                    describe: 'run completion note',
+                })
+                .option('like', {
+                    type: 'string',
+                    group: 'Options for update notification email address:',
+                    describe:
+                        'filter metadata components (can include % as wildcard or _ for a single character)',
+                });
+        },
+        handler: (argv) => {
+            Mcdev.setOptions(argv);
+            // ! do not allow multiple types to be passed in here via csvToArray
+            Mcdev.updateNotifications(argv.BU, argv.TYPE, csvToArray(argv.KEY));
+        },
+    })
     .command({
         command: 'upgrade',
         aliases: ['up'],

lib/index.js

@@ -64,6 +64,10 @@ class Mcdev {
             'refresh',
             'schedule',
             'skipInteraction',
+            'emailError',
+            'emailComplete',
+            'errorNote',
+            'completionNote',
         ];
         for (const option of knownOptions) {
             if (argv[option] !== undefined) {
@@ -1126,6 +1130,85 @@ class Mcdev {
         Util.logger.info(`:: Done\n`);
         return result;
     }
+    /**
+     * Updates notification email address field
+     *
+     * @param {string} businessUnit name of BU
+     * @param {TYPE.SupportedMetadataTypes} type limit execution to given metadata type
+     * @param {string[]} [keys] customerkey of the metadata
+     * @returns {Promise.<Object.<string, string[]>>} key: business unit name, value: list of affected item keys
+     */
+    static async updateNotifications(businessUnit, type, keys) {
+        const [cred, bu] = businessUnit ? businessUnit.split('/') : [null, null];
+        if (Util.OPTIONS.emailComplete == null && Util.OPTIONS.emailError == null) {
+            Util.logger.error(`No email addresses were provided`);
+            return null;
+        }
+        const properties = await config.getProperties();
+        const resultsObj = {};
+        if (bu === '*') {
+            Util.logger.info(':: Updating notifications on all BUs for all credentials');
+            let counter_credTotal = 0;
+            for (const cred in properties.credentials) {
+                Util.logger.info(`:: Updating notifications on BUs for ${cred}`);
+                let counter_credBu = 0;
+                for (const bu in properties.credentials[cred].businessUnits) {
+                    resultsObj[`${cred}/${bu}`] = await this.#updateNotificationsBU(
+                        cred,
+                        bu,
+                        type,
+                        keys
+                    );
+                    counter_credBu++;
+                    Util.startLogger(true);
+                }
+                counter_credTotal += counter_credBu;
+                Util.logger.info(`:: ${counter_credBu} BUs of ${cred}\n`);
+            }
+            Util.logger.info(`:: Updated notifications on ${counter_credTotal} BUs of ${cred}\n`);
+        } else {
+            resultsObj[`${cred}/${bu}`] = await this.#updateNotificationsBU(cred, bu, type, keys);
+        }
+
+        return resultsObj;
+    }
+    /**
+     *
+     * @param {string} cred name of Credential
+     * @param {string} bu name of BU
+     * @param {string} type metadata type
+     * @param {string[]} [keys] limit retrieval to given metadata keys
+     * @returns {Promise.<string[]>} keys of the automations where notifications were updated
+     */
+    static async #updateNotificationsBU(cred, bu, type, keys) {
+        const properties = await config.getProperties();
+        if (!(await config.checkProperties(properties))) {
+            return null;
+        }
+        const buObject = await Cli.getCredentialObject(
+            properties,
+            cred === null ? null : cred + '/' + bu,
+            null,
+            true
+        );
+        if (buObject !== null) {
+            cache.initCache(buObject);
+            cred = buObject.credential;
+            bu = buObject.businessUnit;
+        }
+        try {
+            MetadataTypeInfo[type].client = auth.getSDK(buObject);
+        } catch (ex) {
+            Util.logger.error(ex.message);
+            return null;
+        }
+        Util.logger.info(
+            `Setting notification email address of type ${type} on ${cred}/${bu}` +
+                (keys ? Util.getKeysString(keys) : '') +
+                `\n`
+        );
+        return await MetadataTypeInfo[type].updateNotifications(keys);
+    }
 }
 
 module.exports = Mcdev;

lib/metadataTypes/Automation.js

@@ -1558,6 +1558,116 @@ class Automation extends MetadataType {
         // delete local copy: retrieve/cred/bu/.../...-doc.md
         await super.postDeleteTasks(customerKey, [`${this.definition.type}-doc.md`]);
     }
+    /**
+     * helper function to retrieve data about all automations in the BU
+     *
+     * @returns {Promise.<string[]>} returns data about automations with the legacy key
+     */
+    static async #getEncodedAutomationIDs() {
+        const keyBackup = this.definition.keyField;
+        const iteratorBackup = this.definition.bodyIteratorField;
+        this.definition.keyField = 'key';
+        this.definition.bodyIteratorField = 'entry';
+        const automationLegacyKeys = await super.retrieveREST(
+            undefined,
+            `/legacy/v1/beta/bulk/automations/automation/definition/`
+        );
+        this.definition.keyField = keyBackup;
+        this.definition.bodyIteratorField = iteratorBackup;
+        return automationLegacyKeys;
+    }
+    /**
+     * A function to update automation email notifications
+     *
+     * @param {string} keys metadata keys
+     * @returns {Promise.<string[]>} keys of the automations where notifications were updated
+     */
+    static async updateNotifications(keys) {
+        const emailComplete = Array.isArray(Util.OPTIONS.emailComplete)
+            ? Util.OPTIONS.emailComplete.join(',')
+            : Util.OPTIONS.emailComplete;
+        const emailError = Array.isArray(Util.OPTIONS.emailError)
+            ? Util.OPTIONS.emailError.join(',')
+            : Util.OPTIONS.emailError;
+        const updatedKeys = [];
+        let notificationsResult;
+        const automationLegacyMapObj = await this.#getEncodedAutomationIDs(); // retrieve automation legacy keys to update notifications
+        for (const key of Object.keys(automationLegacyMapObj.metadata)) {
+            if (Array.isArray(keys) && keys.includes(key)) {
+                try {
+                    notificationsResult = await this.client.rest.get(
+                        '/legacy/v1/beta/automations/notifications/' +
+                            automationLegacyMapObj.metadata[key].id
+                    );
+                } catch (ex) {
+                    Util.logger.error(
+                        `Error retrieving notifications for automation '${key}': ${ex.message} (${ex.code}))`
+                    );
+                }
+                // if the parameters provided are the same as the email addresses/notes already in the notifications - skip this automation
+                if (
+                    notificationsResult.workers.find(
+                        (notification) =>
+                            (notification.notificationType === 'Complete' &&
+                                (emailComplete !== notification.definition ||
+                                    Util.OPTIONS.completionNote !== notification.body)) ||
+                            notificationsResult.workers.find(
+                                (notification) =>
+                                    notification.notificationType === 'Error' &&
+                                    (emailError !== notification.definition ||
+                                        Util.OPTIONS.errorNote !== notification.body)
+                            )
+                    )
+                ) {
+                    // create payload
+                    const notificationBody = {
+                        programId: automationLegacyMapObj.metadata[key].id,
+                        workers: [
+                            {
+                                programId: automationLegacyMapObj.metadata[key].id,
+                                notificationType: 'Complete',
+                                definition: emailComplete,
+                                body: Util.OPTIONS.completionNote,
+                                channelType: 'Account',
+                            },
+                            {
+                                programId: automationLegacyMapObj.metadata[key].id,
+                                notificationType: 'Error',
+                                definition: emailError,
+                                body: Util.OPTIONS.errorNote,
+                                channelType: 'Account',
+                            },
+                        ],
+                    };
+                    try {
+                        const result = await this.client.rest.post(
+                            '/legacy/v1/beta/automations/notifications/' +
+                                automationLegacyMapObj.metadata[key].id,
+                            notificationBody
+                        );
+                        if (result) {
+                            // should be empty if all OK
+                            throw new Error(result);
+                        }
+                        updatedKeys.push(key);
+                    } catch (ex) {
+                        Util.logger.error(
+                            `Error updating notifications for automation '${key}': ${ex.message} (${ex.code}))`
+                        );
+                    }
+                    Util.logger.info(
+                        Util.getGrayMsg(` - updated notifications for automation '${key}'`)
+                    );
+                } else {
+                    Util.logger.info(
+                        ` ☇ skipping automation '${key}' - email addresses provided and run notes are the same`
+                    );
+                    return;
+                }
+            }
+        }
+        return updatedKeys;
+    }
 }
 
 // Assign definition to static attributes