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