mcdev 5.0.2 → 5.2.0

package/lib/metadataTypes/Automation.js

@@ -6,6 +6,7 @@ const Util = require('../util/util');
 const File = require('../util/file');
 const Definitions = require('../MetadataTypeDefinitions');
 const cache = require('../util/cache');
+const pLimit = require('p-limit');
 
 /**
  * Automation MetadataType
@@ -13,6 +14,7 @@ const cache = require('../util/cache');
  * @augments MetadataType
  */
 class Automation extends MetadataType {
+    static notificationUpdates = {};
     /**
      * Retrieves Metadata of Automation
      *
@@ -35,42 +37,57 @@ class Automation extends MetadataType {
             };
         }
         const results = await this.client.soap.retrieveBulk('Program', ['ObjectID'], requestParams);
-        if (results.Results?.length) {
+        if (results.Results?.length && !key) {
             // empty results will come back without "Results" defined
             Util.logger.info(
                 Util.getGrayMsg(
-                    ` - ${results.Results?.length} Automations found. Retrieving details...`
+                    ` - ${results.Results?.length} automation${
+                        results.Results?.length === 1 ? '' : 's'
+                    } found. Retrieving details...`
                 )
             );
         }
+        // the API seems to handle 50 concurrent requests nicely
+        const rateLimit = pLimit(50);
+
         const details = results.Results
             ? await Promise.all(
-                  results.Results.map(async (a) => {
-                      try {
-                          return await this.client.rest.get(
-                              '/automation/v1/automations/' + a.ObjectID
-                          );
-                      } catch (ex) {
+                  results.Results.map(async (item) =>
+                      rateLimit(async () => {
                           try {
-                              if (ex.message == 'socket hang up') {
-                                  // one more retry; it's a rare case but retrying again should solve the issue gracefully
-                                  return await this.client.rest.get(
-                                      '/automation/v1/automations/' + a.ObjectID
-                                  );
+                              return await this.client.rest.get(
+                                  '/automation/v1/automations/' + item.ObjectID
+                              );
+                          } catch (ex) {
+                              try {
+                                  if (ex.message == 'socket hang up') {
+                                      // one more retry; it's a rare case but retrying again should solve the issue gracefully
+                                      return await this.client.rest.get(
+                                          '/automation/v1/automations/' + item.ObjectID
+                                      );
+                                  }
+                              } catch {
+                                  // no extra action needed, handled below
                               }
-                          } catch {
-                              // no extra action needed, handled below
+                              // if we do get here, we should log the error and continue instead of failing to download all automations
+                              Util.logger.error(
+                                  ` ☇ skipping Automation ${item.ObjectID}: ${ex.message} ${ex.code}`
+                              );
+                              return null;
                           }
-                          // if we do get here, we should log the error and continue instead of failing to download all automations
-                          Util.logger.error(
-                              ` ☇ skipping Automation ${a.ObjectID}: ${ex.message} ${ex.code}`
-                          );
-                          return null;
-                      }
-                  })
+                      })
+                  )
               )
             : [];
-        let metadataMap = this.parseResponseBody({ items: details });
+
+        // * if retrieving some automations fails, a null element would remain in the details-array for each of them that needs to be filtered to prevent it from causing issues elsewhere
+        let metadataMap = this.parseResponseBody({ items: details.filter(Boolean) });
+
+        if (Object.keys(metadataMap).length) {
+            // attach notification information to each automation that has any
+            await this.#getAutomationNotificationsREST(metadataMap);
+        }
+
         // * retrieveDir can be empty when we use it in the context of postDeployTasks
         if (retrieveDir) {
             metadataMap = await this.saveResults(metadataMap, retrieveDir, null, null);
@@ -83,6 +100,85 @@ class Automation extends MetadataType {
         }
         return { metadata: metadataMap, type: this.definition.type };
     }
+
+    /**
+     * helper for {@link Automation.retrieve} to get Automation Notifications
+     *
+     * @private
+     * @param {TYPE.MetadataTypeMap} metadataMap keyField => metadata map
+     * @returns {Promise.<void>} Promise of nothing
+     */
+    static async #getAutomationNotificationsREST(metadataMap) {
+        Util.logger.info(Util.getGrayMsg(` Retrieving Automation Notification information...`));
+
+        // get list of keys that we retrieved so far
+        const foundKeys = Object.keys(metadataMap);
+
+        // get encodedAutomationID to retrieve notification information
+        const iteratorBackup = this.definition.bodyIteratorField;
+        this.definition.bodyIteratorField = 'entry';
+        const automationLegacyMapObj = await super.retrieveREST(
+            undefined,
+            `/legacy/v1/beta/bulk/automations/automation/definition/`
+        );
+        this.definition.bodyIteratorField = iteratorBackup;
+        const automationLegacyMap = Object.keys(automationLegacyMapObj.metadata)
+            .filter((key) => foundKeys.includes(key))
+            // ! using the `id` field to retrieve notifications does not work. instead one needs to use the URL in the `notifications` field
+            .map((key) => ({
+                id: automationLegacyMapObj.metadata[key].id,
+                key,
+            }));
+
+        // get notifications for each automation
+        const rateLimit = pLimit(5);
+        let found = 0;
+        let skipped = 0;
+        const promiseMap = await Promise.all(
+            automationLegacyMap.map((automationLegacy) =>
+                rateLimit(async () => {
+                    // this is a file so extended is at another endpoint
+                    try {
+                        const notificationsResult = await this.client.rest.get(
+                            '/legacy/v1/beta/automations/notifications/' + automationLegacy.id
+                        );
+                        if (Array.isArray(notificationsResult?.workers)) {
+                            metadataMap[automationLegacy.key].notifications =
+                                notificationsResult.workers.map((n) => ({
+                                    email: n.definition.split(',').map((item) => item.trim()),
+                                    message: n.body,
+                                    type: n.notificationType,
+                                }));
+                            found++;
+                        } else {
+                            if (
+                                !notificationsResult ||
+                                typeof notificationsResult !== 'object' ||
+                                Object.keys(notificationsResult).length !== 1 ||
+                                !notificationsResult?.programId
+                            ) {
+                                throw new TypeError(JSON.stringify(notificationsResult));
+                            }
+                            // * if there are no automation notifications, the API returns a single object with the programId
+                        }
+                    } catch (ex) {
+                        Util.logger.debug(
+                            ` ☇ issue retrieving Notifications for automation ${automationLegacy.key}: ${ex.message} ${ex.code}`
+                        );
+                        skipped++;
+                    }
+                })
+            )
+        );
+        Util.logger.info(
+            Util.getGrayMsg(` Notifications found for ${found} automation${found === 1 ? '' : 's'}`)
+        );
+        Util.logger.debug(
+            `Notifications not found for ${skipped} automation${skipped === 1 ? '' : 's'}`
+        );
+        return promiseMap;
+    }
+
     /**
      * Retrieves Metadata of Automation
      *
@@ -134,6 +230,7 @@ class Automation extends MetadataType {
      * @returns {Promise.<TYPE.AutomationMapObj>} Promise of metadata
      */
     static async retrieveForCache() {
+        // get automations for cache
         const results = await this.client.soap.retrieveBulk('Program', [
             'ObjectID',
             'CustomerKey',
@@ -141,14 +238,30 @@ class Automation extends MetadataType {
         ]);
         const resultsConverted = {};
         if (Array.isArray(results?.Results)) {
+            // get encodedAutomationID to retrieve notification information
+            const keyBackup = this.definition.keyField;
+            const iteratorBackup = this.definition.bodyIteratorField;
+            this.definition.keyField = 'key';
+            this.definition.bodyIteratorField = 'entry';
+            const automationsLegacy = await super.retrieveREST(
+                undefined,
+                `/legacy/v1/beta/bulk/automations/automation/definition/`
+            );
+            this.definition.keyField = keyBackup;
+            this.definition.bodyIteratorField = iteratorBackup;
+
+            // merge encodedAutomationID into results
             for (const m of results.Results) {
                 resultsConverted[m.CustomerKey] = {
                     id: m.ObjectID,
                     key: m.CustomerKey,
                     name: m.Name,
+                    programId: automationsLegacy.metadata[m.CustomerKey]?.id,
+                    status: automationsLegacy.metadata[m.CustomerKey]?.status,
                 };
             }
         }
+
         return { metadata: resultsConverted, type: this.definition.type };
     }
 
@@ -175,14 +288,21 @@ class Automation extends MetadataType {
                 Util.logger.error(`${this.definition.type} '${name}' not found on server.`);
                 return;
             }
-            const details = await this.client.rest.get(
+            let details = await this.client.rest.get(
                 '/automation/v1/automations/' + metadata.ObjectID
             );
+            const metadataMap = this.parseResponseBody({ items: [details] });
+            if (Object.keys(metadataMap).length) {
+                // attach notification information to each automation that has any
+                await this.#getAutomationNotificationsREST(metadataMap);
+                details = Object.values(metadataMap)[0];
+            }
+
             let val = null;
             let originalKey;
             // if parsing fails, we should just save what we get
             try {
-                const parsedDetails = this.parseMetadata(details);
+                const parsedDetails = this.postRetrieveTasks(details);
                 originalKey = parsedDetails[this.definition.keyField];
                 if (parsedDetails !== null) {
                     val = JSON.parse(
@@ -214,14 +334,344 @@ class Automation extends MetadataType {
             throw new Error(JSON.stringify(results));
         }
     }
+    /**
+     * helper for {@link Automation.postRetrieveTasks} and {@link Automation.execute}
+     *
+     * @param {TYPE.AutomationItem} metadata a single automation
+     * @returns {boolean} true if the automation schedule is valid
+     */
+    static #isValidSchedule(metadata) {
+        if (metadata.type === 'scheduled' && metadata.schedule?.startDate) {
+            try {
+                if (this.definition.timeZoneMapping[metadata.schedule.timezoneName]) {
+                    // if we found the id in our list, remove the redundant data
+                    delete metadata.schedule.timezoneId;
+                }
+            } catch {
+                Util.logger.debug(
+                    `- Schedule name '${metadata.schedule.timezoneName}' not found in definition.timeZoneMapping`
+                );
+            }
+            return true;
+        } else {
+            return false;
+        }
+    }
     /**
      * manages post retrieve steps
      *
      * @param {TYPE.AutomationItem} metadata a single automation
-     * @returns {TYPE.AutomationItem} metadata
+     * @returns {TYPE.AutomationItem | void} parsed item
      */
     static postRetrieveTasks(metadata) {
-        return this.parseMetadata(metadata);
+        // folder
+        this.setFolderPath(metadata);
+        // automations are often skipped due to lack of support.
+        try {
+            if (metadata.type === 'scheduled' && metadata.schedule?.startDate) {
+                // Starting Source == 'Schedule'
+
+                if (!this.#isValidSchedule(metadata)) {
+                    return;
+                }
+                // type 'Running' is temporary status only, overwrite with Scheduled for storage.
+                if (metadata.type === 'scheduled' && metadata.status === 'Running') {
+                    metadata.status = 'Scheduled';
+                }
+            } else if (metadata.type === 'triggered' && metadata.fileTrigger) {
+                // Starting Source == 'File Drop'
+                // Do nothing for now
+            }
+            if (metadata.steps) {
+                let i = 0;
+
+                for (const step of metadata.steps) {
+                    i++;
+
+                    const stepNumber = step.stepNumber || step.step || i;
+                    delete step.stepNumber;
+                    delete step.step;
+
+                    for (const activity of step.activities) {
+                        try {
+                            // get metadata type of activity
+                            activity.r__type = Util.inverseGet(
+                                this.definition.activityTypeMapping,
+                                activity.objectTypeId
+                            );
+                            delete activity.objectTypeId;
+                        } catch {
+                            Util.logger.warn(
+                                ` - Unknown activity type '${activity.objectTypeId}'` +
+                                    ` in step ${stepNumber}.${activity.displayOrder}` +
+                                    ` of Automation '${metadata.name}'`
+                            );
+                            continue;
+                        }
+
+                        // if no activityObjectId then either serialized activity
+                        // (config in Automation ) or unconfigured so no further action to be taken
+                        if (
+                            activity.activityObjectId === '00000000-0000-0000-0000-000000000000' ||
+                            activity.activityObjectId == null
+                        ) {
+                            Util.logger.debug(
+                                ` - skipping ${
+                                    metadata[this.definition.keyField]
+                                } activity ${stepNumber}.${
+                                    activity.displayOrder
+                                } due to missing activityObjectId: ${JSON.stringify(activity)}`
+                            );
+                            // empty if block
+                        } else if (!this.definition.dependencies.includes(activity.r__type)) {
+                            Util.logger.debug(
+                                ` - skipping ${
+                                    metadata[this.definition.keyField]
+                                } activity ${stepNumber}.${
+                                    activity.displayOrder
+                                } because the type ${
+                                    activity.r__type
+                                } is not set up as a dependency for ${this.definition.type}`
+                            );
+                        }
+                        // / if managed by cache we can update references to support deployment
+                        else if (
+                            Definitions[activity.r__type]?.['idField'] &&
+                            cache.getCache(this.buObject.mid)[activity.r__type]
+                        ) {
+                            try {
+                                // this will override the name returned by the API in case this activity's name was changed since the automation was last updated, keeping things nicely in sync for mcdev
+                                const name = cache.searchForField(
+                                    activity.r__type,
+                                    activity.activityObjectId,
+                                    Definitions[activity.r__type].idField,
+                                    Definitions[activity.r__type].nameField
+                                );
+                                if (name !== activity.name) {
+                                    Util.logger.debug(
+                                        ` - updated name of step ${stepNumber}.${activity.displayOrder}` +
+                                            ` in Automation '${metadata.name}' from ${activity.name} to ${name}`
+                                    );
+                                    activity.name = name;
+                                }
+                            } catch (ex) {
+                                // getFromCache throws error where the dependent metadata is not found
+                                Util.logger.warn(
+                                    ` - Missing ${activity.r__type} activity '${activity.name}'` +
+                                        ` in step ${stepNumber}.${activity.displayOrder}` +
+                                        ` of Automation '${metadata.name}' (${ex.message})`
+                                );
+                            }
+                        } else {
+                            Util.logger.warn(
+                                ` - Missing ${activity.r__type} activity '${activity.name}'` +
+                                    ` in step ${stepNumber}.${activity.displayOrder}` +
+                                    ` of Automation '${metadata.name}' (Not Found in Cache)`
+                            );
+                        }
+                    }
+                }
+            }
+            return JSON.parse(JSON.stringify(metadata));
+        } catch (ex) {
+            Util.logger.warn(
+                ` - ${this.definition.typeName} '${metadata[this.definition.nameField]}': ${
+                    ex.message
+                }`
+            );
+            return null;
+        }
+    }
+    /**
+     * a function to start query execution via API
+     *
+     * @param {string[]} keyArr customerkey of the metadata
+     * @returns {Promise.<string[]>} Returns list of keys that were executed
+     */
+    static async execute(keyArr) {
+        const metadataMap = {};
+        for (const key of keyArr) {
+            if (Util.OPTIONS.schedule) {
+                // schedule
+                const results = await this.retrieve(undefined, undefined, undefined, key);
+                if (Object.keys(results.metadata).length) {
+                    for (const resultKey of Object.keys(results.metadata)) {
+                        if (this.#isValidSchedule(results.metadata[resultKey])) {
+                            metadataMap[resultKey] = results.metadata[resultKey];
+                        } else {
+                            Util.logger.error(
+                                ` - skipping ${this.definition.type} ${results.metadata[resultKey].name}: no valid schedule settings found.`
+                            );
+                        }
+                    }
+                }
+            } else {
+                // runOnce
+                const objectId = await this.#getObjectIdForSingleRetrieve(key);
+                metadataMap[key] = {};
+                metadataMap[key][this.definition.idField] = objectId;
+                metadataMap[key][this.definition.keyField] = key;
+            }
+        }
+        if (!Object.keys(metadataMap).length) {
+            Util.logger.error(`No ${this.definition.type} to execute`);
+            return false;
+        }
+        Util.logger.info(
+            `Starting automations ${
+                Util.OPTIONS.schedule
+                    ? 'according to schedule'
+                    : 'to run once (use --schedule or --execute=schedule to schedule instead)'
+            }: ${Object.keys(metadataMap).length}`
+        );
+        const promiseResults = [];
+        for (const key of Object.keys(metadataMap)) {
+            if (Util.OPTIONS.schedule && metadataMap[key].status === 'Scheduled') {
+                // schedule
+                Util.logger.info(
+                    ` - skipping ${this.definition.type} ${metadataMap[key].name}: already scheduled.`
+                );
+            } else {
+                // schedule + runOnce
+                promiseResults.push(this.#executeItem(metadataMap, key));
+            }
+        }
+        const results = await Promise.all(promiseResults);
+        const executedKeyArr = results
+            .filter(Boolean)
+            .filter((r) => r.response.OverallStatus === 'OK')
+            .map((r) => r.key);
+        Util.logger.info(`Executed ${executedKeyArr.length} of ${keyArr.length} items`);
+        return executedKeyArr;
+    }
+    /**
+     * helper for {@link Automation.execute}
+     *
+     * @param {TYPE.AutomationMap} metadataMap map of metadata
+     * @param {string} key key of the metadata
+     * @returns {Promise.<{key:string, response:object}>} metadata key and API response
+     */
+    static async #executeItem(metadataMap, key) {
+        if (Util.OPTIONS.schedule) {
+            this.#preDeploySchedule(metadataMap[key]);
+            metadataMap[key].status = 'Scheduled';
+            return this.#scheduleAutomation(metadataMap, metadataMap, key);
+        } else {
+            return this.#runOnce(metadataMap[key]);
+        }
+    }
+
+    /**
+     * helper for {@link Automation.execute}
+     *
+     * @param {TYPE.AutomationItem} metadataEntry metadata object
+     * @returns {Promise.<{key:string, response:object}>} metadata key and API response
+     */
+    static async #runOnce(metadataEntry) {
+        return super.executeSOAP(metadataEntry);
+    }
+
+    /**
+     *  Standardizes a check for multiple messages but adds query specific filters to error texts
+     *
+     * @param {object} ex response payload from REST API
+     * @returns {string[] | void} formatted Error Message
+     */
+    static getErrorsREST(ex) {
+        const errors = super.getErrorsREST(ex);
+        if (errors?.length > 0) {
+            return errors.map((msg) =>
+                msg
+                    .split('403 Forbidden')
+                    .join('403 Forbidden: Please check if the automation is currently running.')
+            );
+        }
+        return errors;
+    }
+
+    /**
+     * a function to start query execution via API
+     *
+     * @param {string[]} keyArr customerkey of the metadata
+     * @returns {Promise.<string[]>} Returns list of keys that were paused
+     */
+    static async pause(keyArr) {
+        const metadataMap = {};
+        for (const key of keyArr) {
+            if (key) {
+                const results = await this.retrieve(undefined, undefined, undefined, key);
+                if (Object.keys(results.metadata).length) {
+                    for (const key of Object.keys(results.metadata)) {
+                        if (this.#isValidSchedule(results.metadata[key])) {
+                            metadataMap[key] = results.metadata[key];
+                        } else {
+                            Util.logger.error(
+                                ` - skipping ${this.definition.type} ${results.metadata[key].name}: no valid schedule settings found.`
+                            );
+                        }
+                    }
+                }
+            }
+        }
+
+        Util.logger.info(`Pausing automations: ${Object.keys(metadataMap).length}`);
+        const promiseResults = [];
+        for (const key of Object.keys(metadataMap)) {
+            if (metadataMap[key].status === 'Scheduled') {
+                promiseResults.push(this.#pauseItem(metadataMap[key]));
+            } else if (metadataMap[key].status === 'PausedSchedule') {
+                Util.logger.info(
+                    ` - skipping ${this.definition.type} ${metadataMap[key].name}: already paused.`
+                );
+            } else {
+                Util.logger.error(
+                    ` - skipping ${this.definition.type} ${
+                        metadataMap[key].name
+                    }: currently ${metadataMap[
+                        key
+                    ].status.toLowerCase()}. Please try again in a few minutes.`
+                );
+            }
+        }
+        const pausedKeyArr = (await Promise.all(promiseResults))
+            .filter(Boolean)
+            .filter((r) => r.response.OverallStatus === 'OK')
+            .map((r) => r.key);
+
+        Util.logger.info(`Paused ${pausedKeyArr.length} of ${keyArr.length} items`);
+        return pausedKeyArr;
+    }
+
+    /**
+     * helper for {@link Automation.pause}
+     *
+     * @param {TYPE.AutomationItem} metadata automation metadata
+     * @returns {Promise.<{key:string, response:object}>} metadata key and API response
+     */
+    static async #pauseItem(metadata) {
+        const schedule = {};
+        try {
+            const response = await this.client.soap.schedule(
+                'Automation',
+                schedule,
+                {
+                    Interaction: {
+                        ObjectID: metadata[this.definition.idField],
+                    },
+                },
+                'pause',
+                {}
+            );
+            Util.logger.info(
+                ` - paused ${this.definition.type}: ${metadata[this.definition.keyField]} / ${
+                    metadata[this.definition.nameField]
+                }`
+            );
+            return { key: metadata[this.definition.keyField], response };
+        } catch (ex) {
+            this._handleSOAPErrors(ex, 'pausing', metadata, false);
+            return null;
+        }
     }
 
     /**
@@ -230,12 +680,19 @@ class Automation extends MetadataType {
      * @param {TYPE.AutomationMap} metadata metadata mapped by their keyField
      * @param {string} targetBU name/shorthand of target businessUnit for mapping
      * @param {string} retrieveDir directory where metadata after deploy should be saved
-     * @param {boolean} [isRefresh] optional flag - so far not used by automation
      * @returns {Promise.<TYPE.AutomationMap>} Promise
      */
-    static async deploy(metadata, targetBU, retrieveDir, isRefresh) {
-        const upsertResults = await this.upsert(metadata, targetBU, isRefresh);
-        await this.saveResults(upsertResults, retrieveDir, null);
+    static async deploy(metadata, targetBU, retrieveDir) {
+        const upsertResults = await this.upsert(metadata, targetBU);
+        const savedMetadata = await this.saveResults(upsertResults, retrieveDir, null);
+        if (
+            this.properties.metaDataTypes.documentOnRetrieve.includes(this.definition.type) &&
+            !this.definition.documentInOneFile
+        ) {
+            const count = Object.keys(savedMetadata).length;
+            Util.logger.debug(` - Running document for ${count} record${count === 1 ? '' : 's'}`);
+            await this.document(savedMetadata);
+        }
         return upsertResults;
     }
 
@@ -258,11 +715,47 @@ class Automation extends MetadataType {
      * @returns {Promise} Promise
      */
     static update(metadata, metadataBefore) {
-        metadata.id = metadataBefore.id;
+        if (metadataBefore.status === 'Running') {
+            Util.logger.error(
+                ` ☇ error updating ${this.definition.type} ${
+                    metadata[this.definition.keyField] || metadata[this.definition.nameField]
+                } / ${
+                    metadata[this.definition.nameField]
+                }: You cannot update an automation that's currently running. Please wait a bit and retry.`
+            );
+            return null;
+        }
         const uri = '/automation/v1/automations/' + metadata.id;
         return super.updateREST(metadata, uri);
     }
 
+    /**
+     * helper for {@link Automation.preDeployTasks} and {@link Automation.execute}
+     *
+     * @param {TYPE.AutomationItem} metadata metadata mapped by their keyField
+     */
+    static #preDeploySchedule(metadata) {
+        delete metadata.schedule.rangeTypeId;
+        delete metadata.schedule.pattern;
+        delete metadata.schedule.scheduledTime;
+        delete metadata.schedule.scheduledStatus;
+        if (this.definition.timeZoneMapping[metadata.schedule.timezoneName]) {
+            metadata.schedule.timezoneId =
+                this.definition.timeZoneMapping[metadata.schedule.timezoneName];
+        } else {
+            Util.logger.error(
+                `Could not find timezone ${metadata.schedule.timezoneName} in definition.timeZoneMapping`
+            );
+        }
+
+        // the upsert API needs this to be named scheduleTypeId; the retrieve API returns it as typeId
+        metadata.schedule.scheduleTypeId = metadata.schedule.typeId;
+        delete metadata.schedule.typeId;
+
+        // prep startSource
+        metadata.startSource = { schedule: metadata.schedule, typeId: 1 };
+    }
+
     /**
      * Gets executed before deploying metadata
      *
@@ -270,6 +763,15 @@ class Automation extends MetadataType {
      * @returns {Promise.<TYPE.AutomationItem>} Promise
      */
     static async preDeployTasks(metadata) {
+        if (metadata.notifications) {
+            this.notificationUpdates[metadata.key] = metadata.notifications;
+        } else {
+            const cached = cache.getByKey(metadata.key);
+            if (cached?.notifications) {
+                // if notifications existed but are no longer present in the deployment package, we need to run an empty update call to remove them
+                this.notificationUpdates[metadata.key] = [];
+            }
+        }
         if (this.validateDeployMetadata(metadata)) {
             // folder
             this.setFolderId(metadata);
@@ -277,25 +779,12 @@ class Automation extends MetadataType {
             if (metadata.type === 'scheduled' && metadata?.schedule?.startDate) {
                 // Starting Source == 'Schedule'
 
-                delete metadata.schedule.rangeTypeId;
-                delete metadata.schedule.pattern;
-                delete metadata.schedule.scheduledTime;
-                delete metadata.schedule.scheduledStatus;
-                if (this.definition.timeZoneMapping[metadata.schedule.timezoneName]) {
-                    metadata.schedule.timezoneId =
-                        this.definition.timeZoneMapping[metadata.schedule.timezoneName];
-                } else {
-                    Util.logger.error(
-                        `Could not find timezone ${metadata.schedule.timezoneName} in definition.timeZoneMapping`
-                    );
-                }
-                delete metadata.schedule.timezoneName;
-                // the upsert API needs this to be named scheduleTypeId; the retrieve API returns it as typeId
-                metadata.schedule.scheduleTypeId = metadata.schedule.typeId;
-                delete metadata.schedule.typeId;
+                this.#preDeploySchedule(metadata);
+                // * run _buildSchedule here but only to check if things look ok - do not use the returned schedule object for deploy
+                this._buildSchedule(metadata.schedule);
 
-                // prep startSource
-                metadata.startSource = { schedule: metadata.schedule, typeId: 1 };
+                delete metadata.schedule.timezoneName;
+                delete metadata.startSource.schedule.timezoneName;
             } else if (metadata.type === 'triggered' && metadata.fileTrigger) {
                 // Starting Source == 'File Drop'
 
@@ -393,6 +882,16 @@ class Automation extends MetadataType {
         }
         return deployable;
     }
+    /**
+     * helper for {@link MetadataType.updateREST} and {@link MetadataType.updateSOAP} that removes old files after the key was changed
+     *
+     * @private
+     * @param {TYPE.MetadataTypeItem} metadataEntry a single metadata Entry
+     * @returns {void}
+     */
+    static async _postChangeKeyTasks(metadataEntry) {
+        super._postChangeKeyTasks(metadataEntry, true);
+    }
 
     /**
      * Gets executed after deployment of metadata type
@@ -403,87 +902,185 @@ class Automation extends MetadataType {
      */
     static async postDeployTasks(metadataMap, originalMetadataMap) {
         for (const key in metadataMap) {
-            // need to put schedule on here if status is scheduled
+            const item = metadataMap[key];
 
-            if (originalMetadataMap[key]?.type === 'scheduled') {
-                // Starting Source == 'Schedule': Try starting the automation
-                if (originalMetadataMap[key].status === 'Scheduled') {
-                    let schedule = null;
-                    try {
-                        schedule = this._buildSchedule(originalMetadataMap[key].schedule);
-                    } catch (ex) {
-                        Util.logger.error(
-                            `- Could not create schedule for automation ${originalMetadataMap[key].name} to start it: ${ex.message}`
-                        );
-                    }
-                    if (schedule !== null) {
-                        try {
-                            // remove the fields that are not needed for the schedule but only for CLI output
-                            const schedule_StartDateTime = schedule._StartDateTime;
-                            delete schedule._StartDateTime;
-                            const schedule_interval = schedule._interval;
-                            delete schedule._interval;
-                            const schedule_timezoneString = schedule._timezoneString;
-                            delete schedule._timezoneString;
-                            // start the automation
-                            await this.client.soap.schedule(
-                                'Automation',
-                                schedule,
-                                {
-                                    Interaction: {
-                                        ObjectID: metadataMap[key].id,
-                                    },
-                                },
-                                'start',
-                                {}
-                            );
-                            const intervalString =
-                                (schedule_interval > 1 ? `${schedule_interval} ` : '') +
-                                (schedule.RecurrenceType === 'Daily'
-                                    ? 'Day'
-                                    : schedule.RecurrenceType.slice(0, -2) +
-                                      (schedule_interval > 1 ? 's' : ''));
-                            Util.logger.warn(
-                                ` - scheduled automation '${
-                                    originalMetadataMap[key].name
-                                }' deployed Active: runs every ${intervalString} starting ${
-                                    schedule_StartDateTime.split('T').join(' ').split('.')[0]
-                                } ${schedule_timezoneString}`
-                            );
-                        } catch (ex) {
-                            Util.logger.error(
-                                `- Could not start scheduled automation '${originalMetadataMap[key].name}': ${ex.message}`
-                            );
-                        }
-                    }
-                } else {
-                    Util.logger.warn(
-                        ` - scheduled automation '${originalMetadataMap[key].name}' deployed Paused`
+            const oldKey = Util.changedKeysMap?.[this.definition.type]?.[key] || key;
+            delete Util.changedKeysMap?.[this.definition.type]?.[key];
+
+            if (!item.type) {
+                // create response does not return the type attribute
+
+                const scheduleHelper = item.schedule || item.startSource.schedule;
+
+                // el.type
+                item.type = scheduleHelper
+                    ? 'scheduled'
+                    : item.fileTrigger
+                    ? 'triggered'
+                    : undefined;
+
+                // el.schedule.timezoneName
+                if (item.type === 'scheduled') {
+                    // not existing for triggered automations
+                    scheduleHelper.timezoneName ||= Util.inverseGet(
+                        this.definition.timeZoneMapping,
+                        scheduleHelper.timezoneId
                     );
                 }
+
+                // el.status
+                item.status ||= Util.inverseGet(this.definition.statusMapping, item.statusId);
             }
-            if (metadataMap[key].startSource) {
-                metadataMap[key].schedule = metadataMap[key].startSource.schedule;
+            // need to put schedule on here if status is scheduled
+            await Automation.#scheduleAutomation(metadataMap, originalMetadataMap, key, oldKey);
+
+            // need to update notifications separately if there are any
+            await Automation.#updateNotificationInfoREST(metadataMap, key);
 
-                delete metadataMap[key].startSource;
+            // rewrite upsert to retrieve fields
+            if (item.steps) {
+                for (const step of item.steps) {
+                    step.name = step.annotation;
+                    delete step.annotation;
+                }
             }
-            if (metadataMap[key].schedule) {
-                metadataMap[key].schedule.typeId = metadataMap[key].schedule.scheduleTypeId;
-                delete metadataMap[key].schedule.scheduleTypeId;
+        }
+        if (Util.OPTIONS.execute || Util.OPTIONS.schedule) {
+            Util.logger.info(`Executing: ${this.definition.type}`);
+            await this.execute(Object.keys(metadataMap));
+        }
+    }
+    /**
+     * helper for {@link Automation.postDeployTasks}
+     *
+     * @param {TYPE.AutomationMap} metadataMap metadata mapped by their keyField
+     * @param {string} key current customer key
+     * @returns {Promise.<void>} -
+     */
+    static async #updateNotificationInfoREST(metadataMap, key) {
+        if (this.notificationUpdates[key]) {
+            // create & update automation calls return programId as 'legacyId'; retrieve does not return it
+            const programId = metadataMap[key]?.legacyId;
+            if (programId) {
+                const notificationBody = {
+                    programId,
+                    workers: this.notificationUpdates[key].map((notification) => ({
+                        programId,
+                        notificationType: notification.type,
+                        definition: Array.isArray(notification.email)
+                            ? notification.email.join(',')
+                            : notification.email,
+                        body: notification.message,
+                        channelType: 'Account',
+                    })),
+                };
+                try {
+                    const result = await this.client.rest.post(
+                        '/legacy/v1/beta/automations/notifications/' + programId,
+                        notificationBody
+                    );
+                    if (result) {
+                        // should be empty if all OK
+                        throw new Error(result);
+                    }
+                } catch (ex) {
+                    Util.logger.error(
+                        `Error updating notifications for automation '${metadataMap[key].name}': ${ex.message} (${ex.code}))`
+                    );
+                }
+                Util.logger.info(
+                    Util.getGrayMsg(
+                        ` - updated notifications for automation '${metadataMap[key].name}'`
+                    )
+                );
             }
+        }
+    }
 
-            // re-retrieve deployed items because the API does not return any info for them except the new id (api key)
-            try {
-                const { metadata } = await this.retrieve(null, null, null, key);
-                metadataMap[key] = Object.values(metadata)[0];
-                // postRetrieveTasks will be run automatically on this via super.saveResult
-            } catch (ex) {
-                throw new Error(
-                    `Could not get details for new ${this.definition.type} ${key} from server (${ex.message})`
+    /**
+     * helper for {@link Automation.postDeployTasks}
+     *
+     * @param {TYPE.AutomationMap} metadataMap metadata mapped by their keyField
+     * @param {TYPE.AutomationMap} originalMetadataMap metadata to be updated (contains additioanl fields)
+     * @param {string} key current customer key
+     * @param {string} [oldKey] old customer key before fixKey / changeKeyValue / changeKeyField
+     * @returns {Promise.<{key:string, response:object}>} metadata key and API response
+     */
+    static async #scheduleAutomation(metadataMap, originalMetadataMap, key, oldKey) {
+        let response = null;
+        oldKey ||= key;
+        if (originalMetadataMap[oldKey]?.type === 'scheduled') {
+            // Starting Source == 'Schedule': Try starting the automation
+            if (originalMetadataMap[oldKey].status === 'Scheduled') {
+                let schedule = null;
+                try {
+                    schedule = this._buildSchedule(originalMetadataMap[oldKey].schedule);
+                } catch (ex) {
+                    Util.logger.error(
+                        `- Could not create schedule for automation '${originalMetadataMap[oldKey].name}' to start it: ${ex.message}`
+                    );
+                }
+                if (schedule !== null) {
+                    try {
+                        // remove the fields that are not needed for the schedule but only for CLI output
+                        const schedule_StartDateTime = schedule._StartDateTime;
+                        delete schedule._StartDateTime;
+                        const schedule_interval = schedule._interval;
+                        delete schedule._interval;
+                        const schedule_timezoneString = schedule._timezoneString;
+                        delete schedule._timezoneString;
+                        // start the automation
+                        response = await this.client.soap.schedule(
+                            'Automation',
+                            schedule,
+                            {
+                                Interaction: {
+                                    ObjectID: metadataMap[key][this.definition.idField],
+                                },
+                            },
+                            'start',
+                            {}
+                        );
+                        const intervalString =
+                            (schedule_interval > 1 ? `${schedule_interval} ` : '') +
+                            (schedule.RecurrenceType === 'Daily'
+                                ? 'Day'
+                                : schedule.RecurrenceType.slice(0, -2) +
+                                  (schedule_interval > 1 ? 's' : ''));
+                        Util.logger.warn(
+                            ` - scheduled automation '${
+                                originalMetadataMap[oldKey].name
+                            }' deployed as Active: runs every ${intervalString} starting ${
+                                schedule_StartDateTime.split('T').join(' ').split('.')[0]
+                            } ${schedule_timezoneString}`
+                        );
+                    } catch {
+                        // API does not return anything usefull here. We have to know the rules instead
+                        Util.logger.error(
+                            ` ☇ error starting scheduled ${this.definition.type}${key}: Please check schedule settings`
+                        );
+                    }
+                }
+            } else {
+                Util.logger.info(
+                    Util.getGrayMsg(
+                        ` - scheduled automation '${originalMetadataMap[oldKey].name}' deployed as Paused`
+                    )
                 );
             }
         }
+        if (metadataMap[key].startSource) {
+            metadataMap[key].schedule = metadataMap[key].startSource.schedule;
+
+            delete metadataMap[key].startSource;
+        }
+        if (metadataMap[key].schedule?.scheduleTypeId) {
+            metadataMap[key].schedule.typeId = metadataMap[key].schedule.scheduleTypeId;
+            delete metadataMap[key].schedule.scheduleTypeId;
+        }
+        return { key, response };
     }
+
     /**
      * generic script that retrieves the folder path from cache and updates the given metadata with it after retrieve
      *
@@ -549,118 +1146,6 @@ class Automation extends MetadataType {
         }
     }
 
-    /**
-     * parses retrieved Metadata before saving
-     *
-     * @param {TYPE.AutomationItem} metadata a single automation definition
-     * @returns {TYPE.AutomationItem | void} parsed item
-     */
-    static parseMetadata(metadata) {
-        // folder
-        this.setFolderPath(metadata);
-        // automations are often skipped due to lack of support.
-        try {
-            if (metadata.type === 'scheduled' && metadata.schedule?.startDate) {
-                // Starting Source == 'Schedule'
-
-                try {
-                    if (this.definition.timeZoneMapping[metadata.schedule.timezoneName]) {
-                        // if we found the id in our list, remove the redundant data
-                        delete metadata.schedule.timezoneId;
-                    }
-                } catch {
-                    Util.logger.debug(
-                        `- Schedule name '${metadata.schedule.timezoneName}' not found in definition.timeZoneMapping`
-                    );
-                }
-                try {
-                    // type 'Running' is temporary status only, overwrite with Scheduled for storage.
-                    if (metadata.type === 'scheduled' && metadata.status === 'Running') {
-                        metadata.status = 'Scheduled';
-                    }
-                } catch {
-                    Util.logger.error(
-                        `- ${this.definition.type} ${metadata.name} does not have a valid schedule setting.`
-                    );
-                    return;
-                }
-            } else if (metadata.type === 'triggered' && metadata.fileTrigger) {
-                // Starting Source == 'File Drop'
-                // Do nothing for now
-            }
-            if (metadata.steps) {
-                for (const step of metadata.steps) {
-                    const stepNumber = step.stepNumber || step.step;
-                    delete step.stepNumber;
-                    delete step.step;
-
-                    for (const activity of step.activities) {
-                        try {
-                            // get metadata type of activity
-                            activity.r__type = Util.inverseGet(
-                                this.definition.activityTypeMapping,
-                                activity.objectTypeId
-                            );
-                            delete activity.objectTypeId;
-                        } catch {
-                            Util.logger.warn(
-                                ` - Unknown activity type '${activity.objectTypeId}'` +
-                                    ` in step ${stepNumber}.${activity.displayOrder}` +
-                                    ` of Automation '${metadata.name}'`
-                            );
-                            continue;
-                        }
-
-                        // if no activityObjectId then either serialized activity
-                        // (config in Automation ) or unconfigured so no further action to be taken
-                        if (
-                            activity.activityObjectId === '00000000-0000-0000-0000-000000000000' ||
-                            activity.activityObjectId == null ||
-                            !this.definition.dependencies.includes(activity.r__type)
-                        ) {
-                            // empty if block
-                        }
-                        // / if managed by cache we can update references to support deployment
-                        else if (
-                            Definitions[activity.r__type]?.['idField'] &&
-                            cache.getCache(this.buObject.mid)[activity.r__type]
-                        ) {
-                            try {
-                                activity.activityObjectId = cache.searchForField(
-                                    activity.r__type,
-                                    activity.activityObjectId,
-                                    Definitions[activity.r__type].idField,
-                                    Definitions[activity.r__type].nameField
-                                );
-                            } catch (ex) {
-                                // getFromCache throws error where the dependent metadata is not found
-                                Util.logger.warn(
-                                    ` - Missing ${activity.r__type} activity '${activity.name}'` +
-                                        ` in step ${stepNumber}.${activity.displayOrder}` +
-                                        ` of Automation '${metadata.name}' (${ex.message})`
-                                );
-                            }
-                        } else {
-                            Util.logger.warn(
-                                ` - Missing ${activity.r__type} activity '${activity.name}'` +
-                                    ` in step ${stepNumber}.${activity.displayOrder}` +
-                                    ` of Automation '${metadata.name}' (Not Found in Cache)`
-                            );
-                        }
-                    }
-                }
-            }
-            return JSON.parse(JSON.stringify(metadata));
-        } catch (ex) {
-            Util.logger.warn(
-                ` - ${this.definition.typeName} '${metadata[this.definition.nameField]}': ${
-                    ex.message
-                }`
-            );
-            return null;
-        }
-    }
-
     /**
      * Builds a schedule object to be used for scheduling an automation
      * based on combination of ical string and start/end dates.
@@ -680,6 +1165,9 @@ class Automation extends MetadataType {
             const a = obj.split('=');
             recurHelper[a[0]] = a[1];
         }
+        if (recurHelper.INTERVAL) {
+            recurHelper.INTERVAL = Number.parseInt(recurHelper.INTERVAL);
+        }
         // the ical schedule is all in caps but soap objects require Title Case.
         const keyStem = recurHelper.FREQ.charAt(0) + recurHelper.FREQ.slice(1, -2).toLowerCase();
 
@@ -708,13 +1196,18 @@ class Automation extends MetadataType {
                 'Scheduling automatically not supported for Weekly, Monthly and Yearly, please configure manually.'
             );
         }
+        if (recurHelper.FREQ === 'MINUTELY' && recurHelper.INTERVAL && recurHelper.INTERVAL < 5) {
+            throw new Error(
+                'The smallest interval you can configure is 5 minutes. Please adjust your schedule.'
+            );
+        }
 
         if (this.definition.timeZoneMapping[scheduleObject.timezoneName]) {
             scheduleObject.timezoneId =
                 this.definition.timeZoneMapping[scheduleObject.timezoneName];
         } else {
-            Util.logger.error(
-                `- Could not find timezone ${scheduleObject.timezoneName} in definition.timeZoneMapping`
+            throw new Error(
+                `Could not find timezone ${scheduleObject.timezoneName} in definition.timeZoneMapping`
             );
         }
         schedule.TimeZone.ID = scheduleObject.timezoneId;
@@ -808,8 +1301,8 @@ class Automation extends MetadataType {
         // create new Date object reflecting SFMC's servertime
         const dateServer = new Date(utc + 3600000 * offsetServer);
 
-        // return time as a string without trailing "Z"
-        return dateServer.toISOString().slice(0, -1);
+        // return time as a string without trailing "Z" and without miliseconds (separated by .)
+        return dateServer.toISOString().slice(0, -1).split('.')[0];
     }
     /**
      * Experimental: Only working for DataExtensions:
@@ -836,7 +1329,7 @@ class Automation extends MetadataType {
         const automationType = { scheduled: 'Schedule', triggered: 'File Drop' };
         output += `**Started by:** ${automationType[json.type] || 'Not defined'}\n\n`;
         output += `**Status:** ${json.status}\n\n`;
-        if (json.type === 'scheduled') {
+        if (json.type === 'scheduled' || json.schedule) {
             const tz =
                 this.definition.timeZoneDifference[
                     this.definition.timeZoneMapping[json?.schedule?.timezoneName]
@@ -846,7 +1339,7 @@ class Automation extends MetadataType {
                 output += `**Schedule:**\n\n`;
                 output += `* Start: ${json.schedule.startDate.split('T').join(' ')} ${tz}\n`;
                 output += `* End: ${json.schedule.endDate.split('T').join(' ')} ${tz}\n`;
-                output += `* Timezone:  ${json.schedule.timezoneName}\n`;
+                output += `* Timezone: ${json.schedule.timezoneName}\n`;
 
                 const ical = {};
                 for (const item of json.schedule.icalRecur.split(';')) {
@@ -855,9 +1348,20 @@ class Automation extends MetadataType {
                 }
                 const frequency = ical.FREQ.slice(0, -2).toLowerCase();
 
-                output += `* Recurrance: every ${ical.INTERVAL > 1 ? ical.INTERVAL : ''} ${
-                    frequency === 'dai' ? 'day' : frequency
-                }${ical.INTERVAL > 1 ? 's' : ''} ${ical.COUNT ? `for ${ical.COUNT} times` : ''}\n`;
+                output += `* Recurrance: `;
+                output +=
+                    ical.COUNT == 1
+                        ? 'run only once'
+                        : `every${ical.INTERVAL > 1 ? ' ' + ical.INTERVAL : ''} ${
+                              frequency === 'dai' ? 'day' : frequency
+                          }${ical.INTERVAL > 1 ? 's' : ''}${
+                              ical.COUNT
+                                  ? ` for ${ical.COUNT} times`
+                                  : ical.UNTIL
+                                  ? ' until end date'
+                                  : ''
+                          }`;
+                output += '\n';
             } else if (json.schedule) {
                 output += `**Schedule:** Not defined\n`;
             }
@@ -868,6 +1372,27 @@ class Automation extends MetadataType {
             output += `* Pattern: ${json.fileTrigger.fileNamingPattern}\n`;
             output += `* Folder:  ${json.fileTrigger.folderLocationText}\n`;
         }
+        // add empty line to ensure the following notifications are rendered properly
+        output += '\n';
+        if (json.notifications?.length) {
+            output += `**Notifications:**\n\n`;
+            // ensure notifications are sorted by type regardless of how the API returns it
+            const notifications = {};
+            for (const n of json.notifications) {
+                notifications[n.type] =
+                    (Array.isArray(n.email) ? n.email.join(',') : n.email) +
+                    (n.message ? ` ("${n.message}")` : '');
+            }
+            if (notifications.Complete) {
+                output += `* Complete: ${notifications.Complete}\n`;
+            }
+            if (notifications.Error) {
+                output += `* Error: ${notifications.Error}\n`;
+            }
+        } else {
+            output += `**Notifications:** _none_\n\n`;
+        }
+
         // show table with automation steps
         if (tabled && tabled.length) {
             // add empty line to ensure the following table is rendered properly
@@ -975,11 +1500,10 @@ class Automation extends MetadataType {
                 // as part of retrieve & manual execution we could face an empty folder
                 return;
             }
-            await Promise.all(
-                Object.keys(metadata).map((key) => {
-                    this._writeDoc(docPath + '/', key, metadata[key], 'md');
-                    return metadata[key];
-                })
+            return await Promise.all(
+                Object.keys(metadata).map((key) =>
+                    this._writeDoc(docPath + '/', key, metadata[key], 'md')
+                )
             );
         }
     }
@@ -1017,7 +1541,7 @@ class Automation extends MetadataType {
      * @param {string} key customer key
      * @returns {Promise.<string>} objectId or enpty string
      */
-    static async _getObjectIdForSingleRetrieve(key) {
+    static async #getObjectIdForSingleRetrieve(key) {
         const response = await this.client.soap.retrieve('Program', ['ObjectID'], {
             filter: {
                 leftOperand: 'CustomerKey',
@@ -1036,7 +1560,7 @@ class Automation extends MetadataType {
      */
     static async deleteByKey(customerKey) {
         // the delete endpoint returns a general exception if the automation does not exist; handle it gracefully instead by adding a retrieve first
-        const objectId = customerKey ? await this._getObjectIdForSingleRetrieve(customerKey) : null;
+        const objectId = customerKey ? await this.#getObjectIdForSingleRetrieve(customerKey) : null;
         if (!objectId) {
             Util.logger.error(` - automation not found`);
             return false;