mcdev 3.1.3 → 4.0.1

package/lib/metadataTypes/Automation.js

@@ -1,165 +1,96 @@
 'use strict';
 
 const MetadataType = require('./MetadataType');
+const TYPE = require('../../types/mcdev.d');
 const Util = require('../util/util');
 const File = require('../util/file');
 const Definitions = require('../MetadataTypeDefinitions');
-
-/**
- * @typedef {Object} AutomationActivity
- * @property {string} name name (not key) of activity
- * @property {string} [objectTypeId] Id of assoicated activity type; see this.definition.activityTypeMapping
- * @property {string} [activityObjectId] Object Id of assoicated metadata item
- * @property {number} displayOrder order within step; starts with 1 or higher number
- * @property {string} r__type see this.definition.activityTypeMapping
- *
- * @typedef {Object} AutomationStep
- * @property {string} name description
- * @property {string} [annotation] equals AutomationStep.name
- * @property {number} step step iterator
- * @property {number} [stepNumber] step iterator, automatically set during deployment
- * @property {AutomationActivity[]} activities -
- *
- * @typedef {Object} AutomationSchedule REST format
- * @property {number} typeId ?
- * @property {string} startDate example: '2021-05-07T09:00:00'
- * @property {string} endDate example: '2021-05-07T09:00:00'
- * @property {string} icalRecur example: 'FREQ=DAILY;UNTIL=20790606T160000;INTERVAL=1'
- * @property {string} timezoneName example: 'W. Europe Standard Time'; see this.definition.timeZoneMapping
- * @property {number} [timezoneId] see this.definition.timeZoneMapping
- *
- * @typedef {Object} AutomationScheduleSoap SOAP format
- * @property {Object} Recurrence -
- * @property {Object} Recurrence.$ {'xsi:type': keyStem + 'lyRecurrence'}
- * @property {'ByYear'} [Recurrence.YearlyRecurrencePatternType] * currently not supported by tool *
- * @property {'ByMonth'} [Recurrence.MonthlyRecurrencePatternType] * currently not supported by tool *
- * @property {'ByWeek'} [Recurrence.WeeklyRecurrencePatternType] * currently not supported by tool *
- * @property {'ByDay'} [Recurrence.DailyRecurrencePatternType] -
- * @property {'Interval'} [Recurrence.MinutelyRecurrencePatternType] -
- * @property {'Interval'} [Recurrence.HourlyRecurrencePatternType] -
- * @property {number} [Recurrence.YearInterval] 1..n * currently not supported by tool *
- * @property {number} [Recurrence.MonthInterval] 1..n * currently not supported by tool *
- * @property {number} [Recurrence.WeekInterval] 1..n * currently not supported by tool *
- * @property {number} [Recurrence.DayInterval] 1..n
- * @property {number} [Recurrence.HourInterval] 1..n
- * @property {number} [Recurrence.MinuteInterval] 1..n
- * @property {number} _interval internal variable for CLI output only
- * @property {Object} TimeZone -
- * @property {number} TimeZone.ID AutomationSchedule.timezoneId
- * @property {string} _timezoneString internal variable for CLI output only
- * @property {string} StartDateTime AutomationSchedule.startDate
- * @property {string} EndDateTime AutomationSchedule.endDate
- * @property {string} _StartDateTime AutomationSchedule.startDate; internal variable for CLI output only
- * @property {'EndOn'|'EndAfter'} RecurrenceRangeType set to 'EndOn' if AutomationSchedule.icalRecur contains 'UNTIL'; otherwise to 'EndAfter'
- * @property {number} Occurrences only exists if RecurrenceRangeType=='EndAfter'
- *
- * @typedef {Object} AutomationItem
- * @property {string} [id] Object Id
- * @property {string} key key
- * @property {string} name name
- * @property {string} description -
- * @property {'scheduled'|'triggered'} type Starting Source = Schedule / File Drop
- * @property {'Scheduled'|'Running'} status -
- * @property {AutomationSchedule} [schedule] only existing if type=scheduled
- * @property {Object} [fileTrigger] only existing if type=triggered
- * @property {string} fileTrigger.fileNamingPattern -
- * @property {string} fileTrigger.fileNamePatternTypeId -
- * @property {string} fileTrigger.folderLocationText -
- * @property {string} fileTrigger.queueFiles -
- * @property {Object} [startSource] -
- * @property {AutomationSchedule} [startSource.schedule] rewritten to AutomationItem.schedule
- * @property {Object} [startSource.fileDrop] rewritten to AutomationItem.fileTrigger
- * @property {string} startSource.fileDrop.fileNamingPattern -
- * @property {string} startSource.fileDrop.fileNamePatternTypeId -
- * @property {string} startSource.fileDrop.folderLocation -
- * @property {string} startSource.fileDrop.queueFiles -
- * @property {number} startSource.typeId -
- * @property {AutomationStep[]} steps -
- * @property {string} r__folder_Path folder path
- * @property {string} [categoryId] holds folder ID, replaced with r__folder_Path during retrieve
- *
- * @typedef {Object.<string, AutomationItem>} AutomationMap
- */
+const cache = require('../util/cache');
 
 /**
  * Automation MetadataType
+ *
  * @augments MetadataType
  */
 class Automation extends MetadataType {
     /**
      * Retrieves Metadata of Automation
+     *
      * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
-     * @returns {Promise<{metadata:AutomationMap,type:string}>} Promise of metadata
+     * @param {void} [_] unused parameter
+     * @param {void} [__] unused parameter
+     * @param {void} [___] unused parameter
+     * @param {string} [key] customer key of single item to retrieve
+     * @returns {Promise.<TYPE.AutomationMapObj>} Promise of metadata
      */
-    static async retrieve(retrieveDir) {
-        const results = await new Promise((resolve, reject) => {
-            this.client.SoapClient.retrieve('Program', ['ObjectID'], (ex, response) =>
-                ex ? reject(ex) : resolve(response.body.Results)
-            );
-        });
-        const details = (
-            await Promise.all(
-                results.map((a) =>
-                    this.client.RestClient.get({
-                        uri: '/automation/v1/automations/' + a.ObjectID,
-                    })
-                )
-            )
-        ).map((b) => b.body);
+    static async retrieve(retrieveDir, _, __, ___, key) {
+        /** @type {TYPE.SoapRequestParams} */
+        let requestParams = null;
+        if (key) {
+            requestParams = {
+                filter: {
+                    leftOperand: 'CustomerKey',
+                    operator: 'equals',
+                    rightOperand: key,
+                },
+            };
+        }
+        const results = await this.client.soap.retrieveBulk('Program', ['ObjectID'], requestParams);
+
+        const details = results.Results
+            ? await Promise.all(
+                  results.Results.map((a) =>
+                      this.client.rest.get('/automation/v1/automations/' + a.ObjectID)
+                  )
+              )
+            : [];
         const parsed = this.parseResponseBody({ items: details });
 
+        // * retrieveDir is mandatory in this method as it is not used for caching (there is a seperate method for that)
         const savedMetadata = await this.saveResults(parsed, retrieveDir, null, null);
         Util.logger.info(
             `Downloaded: ${this.definition.type} (${Object.keys(savedMetadata).length})`
         );
+        if (this.properties.metaDataTypes.documentOnRetrieve.includes(this.definition.type)) {
+            await this.document(this.buObject, savedMetadata);
+        }
         return { metadata: savedMetadata, type: this.definition.type };
     }
     /**
      * Retrieves Metadata of Automation
-     * @returns {Promise<{metadata:AutomationMap,type:string}>} Promise of metadata
+     *
+     * @returns {Promise.<TYPE.AutomationMapObj>} Promise of metadata
      */
     static async retrieveChangelog() {
-        const results = await new Promise((resolve, reject) => {
-            this.client.SoapClient.retrieve(
-                'Program',
-                ['ObjectID'],
-
-                (ex, response) => (ex ? reject(ex) : resolve(response.body.Results))
-            );
-        });
+        const results = await this.client.soap.retrieveBulk('Program', ['ObjectID']);
         const details = [];
-        (
-            await Promise.all(
-                results.map(async (a) => {
-                    const options = {
-                        filter: {
-                            leftOperand: 'ProgramID',
-                            operator: 'equals',
-                            rightOperand: a.ObjectID,
-                        },
-                    };
-
-                    return new Promise((resolve, reject) => {
-                        this.client.SoapClient.retrieve(
-                            'Automation',
-                            [
-                                'ProgramID',
-                                'Name',
-                                'CustomerKey',
-                                'LastSaveDate',
-                                'LastSavedBy',
-                                'CreatedBy',
-                                'CreatedDate',
-                            ],
-                            options,
-                            (ex, response) => (ex ? reject(ex) : resolve(response.body.Results))
-                        );
-                    });
-                })
-            )
-        ).forEach((item) => {
-            details.push(...item);
-        });
+        for (const item of results.Results
+            ? await Promise.all(
+                  results.Results.map((a) =>
+                      this.client.soap.retrieveBulk(
+                          'Automation',
+                          [
+                              'ProgramID',
+                              'Name',
+                              'CustomerKey',
+                              'LastSaveDate',
+                              'LastSavedBy',
+                              'CreatedBy',
+                              'CreatedDate',
+                          ],
+                          {
+                              filter: {
+                                  leftOperand: 'ProgramID',
+                                  operator: 'equals',
+                                  rightOperand: a.ObjectID,
+                              },
+                          }
+                      )
+                  )
+              )
+            : []) {
+            details.push(...item.Results);
+        }
         details.map((item) => {
             item.key = item.CustomerKey;
         });
@@ -171,73 +102,54 @@ class Automation extends MetadataType {
 
     /**
      * Retrieves automation metadata for caching
-     * @returns {Promise<{metadata:AutomationMap,type:string}>} Promise of metadata
+     *
+     * @returns {Promise.<TYPE.AutomationMapObj>} Promise of metadata
      */
     static async retrieveForCache() {
-        const results = await new Promise((resolve) => {
-            this.client.SoapClient.retrieve(
-                'Program',
-                ['ObjectID', 'CustomerKey', 'Name'],
-                (error, response) => {
-                    if (error) {
-                        throw new Error(error);
-                    } else {
-                        resolve(response.body.Results);
-                    }
-                }
-            );
-        });
+        const results = await this.client.soap.retrieveBulk('Program', [
+            'ObjectID',
+            'CustomerKey',
+            'Name',
+        ]);
         const resultsConverted = {};
-        for (const m of results) {
-            resultsConverted[m.CustomerKey] = {
-                id: m.ObjectID,
-                key: m.CustomerKey,
-                name: m.Name,
-            };
+        if (Array.isArray(results?.Results)) {
+            for (const m of results.Results) {
+                resultsConverted[m.CustomerKey] = {
+                    id: m.ObjectID,
+                    key: m.CustomerKey,
+                    name: m.Name,
+                };
+            }
         }
         return { metadata: resultsConverted, type: this.definition.type };
     }
 
     /**
      * Retrieve a specific Automation Definition by Name
+     *
      * @param {string} templateDir Directory where retrieved metadata directory will be saved
      * @param {string} name name of the metadata file
-     * @param {Util.TemplateMap} templateVariables variables to be replaced in the metadata
-     * @returns {Promise<{metadata:AutomationMap,type:string}>} Promise of metadata
+     * @param {TYPE.TemplateMap} templateVariables variables to be replaced in the metadata
+     * @returns {Promise.<TYPE.AutomationItemObj>} Promise of metadata
      */
     static async retrieveAsTemplate(templateDir, name, templateVariables) {
-        const results = await new Promise((resolve) => {
-            this.client.SoapClient.retrieve(
-                'Program',
-                ['ObjectID', 'Name'],
-                {
-                    filter: {
-                        leftOperand: 'Name',
-                        operator: 'equals',
-                        rightOperand: name,
-                    },
-                },
-                (error, response) => {
-                    if (error) {
-                        throw new Error(error);
-                    } else {
-                        resolve(response.body.Results);
-                    }
-                }
-            );
+        const results = await this.client.soap.retrieve('Program', ['ObjectID', 'Name'], {
+            filter: {
+                leftOperand: 'Name',
+                operator: 'equals',
+                rightOperand: name,
+            },
         });
-        if (results && results[0]) {
+        if (Array.isArray(results?.Results)) {
             // eq-operator returns a similar, not exact match and hence might return more than 1 entry
-            const [metadata] = results.filter((item) => item.Name === name);
+            const metadata = results.Results.find((item) => item.Name === name);
             if (!metadata) {
                 Util.logger.error(`${this.definition.type} '${name}' not found on server.`);
                 return;
             }
-            const details = (
-                await this.client.RestClient.get({
-                    uri: '/automation/v1/automations/' + metadata.ObjectID,
-                })
-            ).body;
+            const details = await this.client.rest.get(
+                '/automation/v1/automations/' + metadata.ObjectID
+            );
             let val = null;
             let originalKey;
             // if parsing fails, we should just save what we get
@@ -249,7 +161,7 @@ class Automation extends MetadataType {
                         Util.replaceByObject(JSON.stringify(parsedDetails), templateVariables)
                     );
                 }
-            } catch (ex) {
+            } catch {
                 val = JSON.parse(JSON.stringify(details));
             }
             if (val === null) {
@@ -259,14 +171,12 @@ class Automation extends MetadataType {
             }
             // remove all fields not listed in Definition for templating
             this.keepTemplateFields(val);
-            File.writeJSONToFile(
+            await File.writeJSONToFile(
                 [templateDir, this.definition.type].join('/'),
                 originalKey + '.' + this.definition.type + '-meta',
                 val
             );
-            Util.logger.info(
-                `Automation.retrieveAsTemplate:: Written Metadata to filesystem (${name})`
-            );
+            Util.logger.info(`- templated ${this.definition.type}: ${name}`);
             return { metadata: val, type: this.definition.type };
         } else if (results) {
             Util.logger.error(`${this.definition.type} '${name}' not found on server.`);
@@ -278,26 +188,21 @@ class Automation extends MetadataType {
     }
     /**
      * manages post retrieve steps
-     * @param {AutomationItem} metadata a single automation
-     * @param {string} [_] unused
-     * @param {Boolean} [isTemplating] signals that we are retrieving templates
-     * @returns {AutomationItem} metadata
+     *
+     * @param {TYPE.AutomationItem} metadata a single automation
+     * @returns {TYPE.AutomationItem} metadata
      */
-    static postRetrieveTasks(metadata, _, isTemplating) {
-        // if retrieving template, replace the name with customer key if that wasn't already the case
-        if (isTemplating) {
-            const warningMsg = null;
-            this.overrideKeyWithName(metadata, warningMsg);
-        }
+    static postRetrieveTasks(metadata) {
         return this.parseMetadata(metadata);
     }
 
     /**
      * Deploys automation - the saved file is the original one due to large differences required for deployment
-     * @param {AutomationMap} metadata metadata mapped by their keyField
+     *
+     * @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
-     * @returns {Promise<AutomationMap>} Promise
+     * @returns {Promise.<TYPE.AutomationMap>} Promise
      */
     static async deploy(metadata, targetBU, retrieveDir) {
         const orignalMetadata = JSON.parse(JSON.stringify(metadata));
@@ -309,7 +214,8 @@ class Automation extends MetadataType {
 
     /**
      * Creates a single automation
-     * @param {AutomationItem} metadata single metadata entry
+     *
+     * @param {TYPE.AutomationItem} metadata single metadata entry
      * @returns {Promise} Promise
      */
     static create(metadata) {
@@ -319,8 +225,9 @@ class Automation extends MetadataType {
 
     /**
      * Updates a single automation
-     * @param {AutomationItem} metadata single metadata entry
-     * @param {AutomationItem} metadataBefore metadata mapped by their keyField
+     *
+     * @param {TYPE.AutomationItem} metadata single metadata entry
+     * @param {TYPE.AutomationItem} metadataBefore metadata mapped by their keyField
      * @returns {Promise} Promise
      */
     static update(metadata, metadataBefore) {
@@ -331,14 +238,14 @@ class Automation extends MetadataType {
 
     /**
      * Gets executed before deploying metadata
-     * @param {AutomationItem} metadata metadata mapped by their keyField
-     * @returns {Promise<AutomationItem>} Promise
+     *
+     * @param {TYPE.AutomationItem} metadata metadata mapped by their keyField
+     * @returns {Promise.<TYPE.AutomationItem>} Promise
      */
     static async preDeployTasks(metadata) {
         if (this.validateDeployMetadata(metadata)) {
             try {
-                metadata.categoryId = Util.getFromCache(
-                    this.cache,
+                metadata.categoryId = cache.searchForField(
                     'folder',
                     metadata.r__folder_Path,
                     'Path',
@@ -346,7 +253,7 @@ class Automation extends MetadataType {
                 );
                 if (metadata.r__folder_Path !== 'my automations') {
                     Util.logger.warn(
-                        `Automation '${
+                        ` - Automation '${
                             metadata[this.definition.nameField]
                         }' is located in subfolder ${
                             metadata.r__folder_Path
@@ -354,12 +261,12 @@ class Automation extends MetadataType {
                     );
                 }
                 delete metadata.r__folder_Path;
-            } catch (ex) {
+            } catch {
                 throw new Error(
                     `Folder '${metadata.r__folder_Path}' was not found on the server. Please create this manually in the GUI. Automation-folders cannot be deployed automatically.`
                 );
             }
-            if (metadata.type === 'scheduled' && metadata.schedule && metadata.schedule.startDate) {
+            if (metadata.type === 'scheduled' && metadata?.schedule?.startDate) {
                 // Starting Source == 'Schedule'
 
                 delete metadata.schedule.rangeTypeId;
@@ -399,26 +306,33 @@ class Automation extends MetadataType {
             delete metadata.schedule;
             delete metadata.type;
             let i = 0;
-            for (const step of metadata.steps) {
-                for (const activity of step.activities) {
-                    if (activity.name && this.definition.dependencies.includes(activity.r__type)) {
-                        // automations can have empty placeholder for activities with only their type defined
-                        activity.activityObjectId = Util.getFromCache(
-                            this.cache,
-                            activity.r__type,
-                            activity.name,
-                            Definitions[activity.r__type].nameField,
-                            Definitions[activity.r__type].idField
-                        );
+            if (metadata.steps) {
+                for (const step of metadata.steps) {
+                    let displayOrder = 0;
+                    for (const activity of step.activities) {
+                        activity.displayOrder = ++displayOrder;
+                        if (
+                            activity.name &&
+                            this.definition.dependencies.includes(activity.r__type)
+                        ) {
+                            // automations can have empty placeholder for activities with only their type defined
+                            activity.activityObjectId = cache.searchForField(
+                                activity.r__type,
+                                activity.name,
+                                Definitions[activity.r__type].nameField,
+                                Definitions[activity.r__type].idField
+                            );
+                        }
+                        activity.objectTypeId =
+                            this.definition.activityTypeMapping[activity.r__type];
+                        delete activity.r__type;
                     }
-                    activity.objectTypeId = this.definition.activityTypeMapping[activity.r__type];
-                    delete activity.r__type;
+                    step.annotation = step.name;
+                    step.stepNumber = i;
+                    delete step.name;
+                    delete step.step;
+                    i++;
                 }
-                step.annotation = step.name;
-                step.stepNumber = i;
-                delete step.name;
-                delete step.step;
-                i++;
             }
             return metadata;
         } else {
@@ -428,52 +342,62 @@ class Automation extends MetadataType {
     /**
      * Validates the automation to be sure it can be deployed.
      * Whitelisted Activites are deployed but require configuration
-     * @param {AutomationItem} metadata single automation record
-     * @returns {Boolean} result if automation can be deployed based on steps
+     *
+     * @param {TYPE.AutomationItem} metadata single automation record
+     * @returns {boolean} result if automation can be deployed based on steps
      */
     static validateDeployMetadata(metadata) {
         let deployable = true;
+        const errors = [];
         if (metadata.steps) {
+            let stepNumber = 0;
             for (const step of metadata.steps) {
+                stepNumber++;
+                let displayOrder = 0;
+
                 for (const activity of step.activities) {
+                    displayOrder++;
                     // check if manual deploy required. if so then log warning
                     if (this.definition.manualDeployTypes.includes(activity.r__type)) {
                         Util.logger.warn(
-                            `Automation '${
-                                metadata.name
-                            }' requires additional manual configuration: '${
-                                activity.name
-                            }' in step ${step.stepNumber || step.step}.${activity.displayOrder}`
+                            `- ${this.definition.type} '${metadata.name}' requires additional manual configuration: '${activity.name}' in step ${stepNumber}.${displayOrder}`
                         );
                     }
                     // cannot deploy because it is not supported
                     else if (!this.definition.dependencies.includes(activity.r__type)) {
-                        Util.logger.error(
-                            `Automation '${
-                                metadata.name
-                            }' cannot be deployed as the following activity is not supported: '${
-                                activity.name
-                            }' in step ${step.stepNumber || step.step}.${activity.displayOrder}`
+                        errors.push(
+                            `   • not supported ${activity.r__type} activity '${activity.name}' in step ${stepNumber}.${displayOrder}`
                         );
                         deployable = false;
                     }
                 }
             }
         }
+        if (!deployable) {
+            Util.logger.error(
+                ` ☇ skipping ${this.definition.type} ${metadata[this.definition.keyField]} / ${
+                    metadata[this.definition.nameField]
+                }:`
+            );
+            for (const error of errors) {
+                Util.logger.error(error);
+            }
+        }
         return deployable;
     }
 
     /**
      * Gets executed after deployment of metadata type
-     * @param {AutomationMap} metadata metadata mapped by their keyField
-     * @param {AutomationMap} originalMetadata metadata to be updated (contains additioanl fields)
-     * @returns {Promise<void>} -
+     *
+     * @param {TYPE.AutomationMap} metadata metadata mapped by their keyField
+     * @param {TYPE.AutomationMap} originalMetadata metadata to be updated (contains additioanl fields)
+     * @returns {Promise.<void>} -
      */
     static async postDeployTasks(metadata, originalMetadata) {
         for (const key in metadata) {
             // need to put schedule on here if status is scheduled
 
-            if (originalMetadata[key] && originalMetadata[key].type === 'scheduled') {
+            if (originalMetadata[key]?.type === 'scheduled') {
                 // Starting Source == 'Schedule': Try starting the automation
                 if (originalMetadata[key].status === 'Scheduled') {
                     let schedule = null;
@@ -481,70 +405,45 @@ class Automation extends MetadataType {
                         schedule = this._buildSchedule(originalMetadata[key].schedule);
                     } catch (ex) {
                         Util.logger.error(
-                            `Could not create schedule for automation ${originalMetadata[key].name} to start it: ${ex.message}`
+                            `- Could not create schedule for automation ${originalMetadata[key].name} to start it: ${ex.message}`
                         );
                     }
                     if (schedule !== null) {
                         try {
-                            await Util.retryOnError(
-                                `Retrying ${this.definition.type}`,
-                                async () => {
-                                    await new Promise((resolve, reject) => {
-                                        this.client.SoapClient.schedule(
-                                            'Automation',
-                                            schedule,
-                                            {
-                                                Interaction: {
-                                                    ObjectID: metadata[key].id,
-                                                },
-                                            },
-                                            'start',
-                                            null,
-                                            (error, response) => {
-                                                if (
-                                                    error ||
-                                                    (response.body.Results &&
-                                                        response.body.Results[0] &&
-                                                        response.body.Results[0].StatusCode &&
-                                                        response.body.Results[0].StatusCode ===
-                                                            'Error')
-                                                ) {
-                                                    reject(
-                                                        error ||
-                                                            response.body.Results[0].StatusMessage
-                                                    );
-                                                } else {
-                                                    resolve(response.body.Results);
-                                                }
-                                            }
-                                        );
-                                    });
-                                    const intervalString =
-                                        (schedule._interval > 1 ? `${schedule._interval} ` : '') +
-                                        (schedule.RecurrenceType === 'Daily'
-                                            ? 'Day'
-                                            : schedule.RecurrenceType.slice(0, -2) +
-                                              (schedule._interval > 1 ? 's' : ''));
-                                    Util.logger.warn(
-                                        `Automation '${
-                                            originalMetadata[key].name
-                                        }' deployed Active: runs every ${intervalString} starting ${
-                                            schedule._StartDateTime
-                                                .split('T')
-                                                .join(' ')
-                                                .split('.')[0]
-                                        } ${schedule._timezoneString}`
-                                    );
-                                }
+                            await this.client.soap.schedule(
+                                'Automation',
+                                schedule,
+                                {
+                                    Interaction: {
+                                        ObjectID: metadata[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 '${
+                                    originalMetadata[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 automation '${originalMetadata[key].name}': ${ex.message}`
+                                `- Could not start scheduled automation '${originalMetadata[key].name}': ${ex.message}`
                             );
                         }
                     }
                 } else {
-                    Util.logger.warn(`Automation '${originalMetadata[key].name}' deployed Paused`);
+                    Util.logger.warn(
+                        ` - scheduled automation '${originalMetadata[key].name}' deployed Paused`
+                    );
                 }
             }
             if (metadata[key].startSource) {
@@ -561,14 +460,14 @@ class Automation extends MetadataType {
 
     /**
      * parses retrieved Metadata before saving
-     * @param {AutomationItem} metadata a single automation definition
-     * @returns {Array} Array with one metadata object and one sql string
+     *
+     * @param {TYPE.AutomationItem} metadata a single automation definition
+     * @returns {TYPE.AutomationItem} parsed item
      */
     static parseMetadata(metadata) {
         // automations are often skipped due to lack of support.
         try {
-            metadata.r__folder_Path = Util.getFromCache(
-                this.cache,
+            metadata.r__folder_Path = cache.searchForField(
                 'folder',
                 metadata.categoryId,
                 'ID',
@@ -577,7 +476,9 @@ class Automation extends MetadataType {
             delete metadata.categoryId;
             if (metadata.r__folder_Path !== 'my automations') {
                 Util.logger.verbose(
-                    `Automation '${metadata[this.definition.nameField]}' is located in subfolder ${
+                    `- automation '${
+                        metadata[this.definition.nameField]
+                    }' is located in subfolder ${
                         metadata.r__folder_Path
                     }. Please note that creating automation folders is not supported via API and hence you will have to create it manually in the GUI if you choose to deploy this automation.`
                 );
@@ -585,13 +486,13 @@ class Automation extends MetadataType {
         } catch (ex) {
             // * don't exit on missing folder for automation
             Util.logger.warn(
-                `${this.definition.typeName} '${metadata[this.definition.nameField]}': ${
+                ` - ${this.definition.typeName} '${metadata[this.definition.nameField]}': ${
                     ex.message
                 }`
             );
         }
         try {
-            if (metadata.type === 'scheduled' && metadata.schedule && metadata.schedule.startDate) {
+            if (metadata.type === 'scheduled' && metadata.schedule?.startDate) {
                 // Starting Source == 'Schedule'
 
                 try {
@@ -599,24 +500,21 @@ class Automation extends MetadataType {
                         // if we found the id in our list, remove the redundant data
                         delete metadata.schedule.timezoneId;
                     }
-                } catch (ex) {
+                } catch {
                     Util.logger.debug(
-                        `Schedule name '${metadata.schedule.timezoneName}' not found in definition.timeZoneMapping`
+                        `- 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';
+                        metadata.status = 'Scheduled';
                     }
-                } catch (ex) {
-                    Util.metadataLogger(
-                        'error',
-                        this.definition.type,
-                        'parseMetadata',
-                        `${metadata.name} does not have a valid schedule setting. `
+                } catch {
+                    Util.logger.error(
+                        `- ${this.definition.type} ${metadata.name} does not have a valid schedule setting.`
                     );
-                    return null;
+                    return;
                 }
             } else if (metadata.type === 'triggered' && metadata.fileTrigger) {
                 // Starting Source == 'File Drop'
@@ -624,6 +522,10 @@ class Automation extends MetadataType {
             }
             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
@@ -632,56 +534,50 @@ class Automation extends MetadataType {
                                 activity.objectTypeId
                             );
                             delete activity.objectTypeId;
-                            // 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] &&
-                                Definitions[activity.r__type]['idField'] &&
-                                this.cache[activity.r__type]
-                            ) {
-                                try {
-                                    activity.activityObjectId = Util.getFromCache(
-                                        this.cache,
-                                        activity.r__type,
-                                        activity.activityObjectId,
-                                        Definitions[activity.r__type].idField,
-                                        Definitions[activity.r__type].nameField
-                                    );
-                                } catch (e) {
-                                    // getFromCache throws error where the dependent metadata is not found
-                                    Util.logger.error(
-                                        `Missing ${activity.r__type} activity '${activity.name}'` +
-                                            ` in step ${step.stepNumber || step.step}.${
-                                                activity.displayOrder
-                                            }` +
-                                            ` of Automation '${metadata.name}' (${e.message})`
-                                    );
-                                    return null;
-                                }
-                            } else {
-                                Util.logger.error(
-                                    `Missing ${activity.r__type} activity '${activity.name}'` +
-                                        ` in step ${step.stepNumber || step.step}.${
-                                            activity.displayOrder
-                                        }` +
-                                        ` of Automation '${metadata.name}' (Not Found in Cache)`
+                        } 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})`
                                 );
-                                return null;
                             }
-                        } catch (ex) {
+                        } else {
                             Util.logger.warn(
-                                `Excluding automation '${metadata.name}' from retrieve (ObjectType ${activity.objectTypeId} is unknown)`
+                                ` - Missing ${activity.r__type} activity '${activity.name}'` +
+                                    ` in step ${stepNumber}.${activity.displayOrder}` +
+                                    ` of Automation '${metadata.name}' (Not Found in Cache)`
                             );
-                            return null;
                         }
                     }
                 }
@@ -689,7 +585,7 @@ class Automation extends MetadataType {
             return JSON.parse(JSON.stringify(metadata));
         } catch (ex) {
             Util.logger.warn(
-                `${this.definition.typeName} '${metadata[this.definition.nameField]}': ${
+                ` - ${this.definition.typeName} '${metadata[this.definition.nameField]}': ${
                     ex.message
                 }`
             );
@@ -700,12 +596,13 @@ class Automation extends MetadataType {
     /**
      * Builds a schedule object to be used for scheduling an automation
      * based on combination of ical string and start/end dates.
-     * @param {AutomationSchedule} scheduleObject child of automation metadata used for scheduling
-     * @returns {AutomationScheduleSoap} Schedulable object for soap API (currently not rest supported)
+     *
+     * @param {TYPE.AutomationSchedule} scheduleObject child of automation metadata used for scheduling
+     * @returns {TYPE.AutomationScheduleSoap} Schedulable object for soap API (currently not rest supported)
      */
     static _buildSchedule(scheduleObject) {
         /**
-         * @type {AutomationScheduleSoap}
+         * @type {TYPE.AutomationScheduleSoap}
          */
         const schedule = { Recurrence: {}, TimeZone: { IDSpecified: true } };
         // build recurrence
@@ -751,7 +648,7 @@ class Automation extends MetadataType {
                 this.definition.timeZoneMapping[scheduleObject.timezoneName];
         } else {
             Util.logger.error(
-                `Could not find timezone ${scheduleObject.timezoneName} in definition.timeZoneMapping`
+                `- Could not find timezone ${scheduleObject.timezoneName} in definition.timeZoneMapping`
             );
         }
         schedule.TimeZone.ID = scheduleObject.timezoneId;
@@ -769,25 +666,38 @@ class Automation extends MetadataType {
             const scheduledDate = new Date(inputStartDateString);
             const futureDate = new Date();
 
-            if (keyStem === 'Dai') {
-                // keep time from template and start today if possible
-                if (scheduledDate.getHours() <= futureDate.getHours()) {
-                    // hour on template has already passed today, start tomorrow
-                    futureDate.setDate(futureDate.getDate() + 1);
+            switch (keyStem) {
+                case 'Dai': {
+                    // keep time from template and start today if possible
+                    if (scheduledDate.getHours() <= futureDate.getHours()) {
+                        // hour on template has already passed today, start tomorrow
+                        futureDate.setDate(futureDate.getDate() + 1);
+                    }
+                    futureDate.setHours(scheduledDate.getHours());
+                    futureDate.setMinutes(scheduledDate.getMinutes());
+
+                    break;
                 }
-                futureDate.setHours(scheduledDate.getHours());
-                futureDate.setMinutes(scheduledDate.getMinutes());
-            } else if (keyStem === 'Hour') {
-                // keep minute and start next possible hour
-                if (scheduledDate.getMinutes() <= futureDate.getMinutes()) {
-                    futureDate.setHours(futureDate.getHours() + 1);
+                case 'Hour': {
+                    // keep minute and start next possible hour
+                    if (scheduledDate.getMinutes() <= futureDate.getMinutes()) {
+                        futureDate.setHours(futureDate.getHours() + 1);
+                    }
+                    futureDate.setMinutes(scheduledDate.getMinutes());
+
+                    break;
                 }
-                futureDate.setMinutes(scheduledDate.getMinutes());
-            } else if (keyStem === 'Minute') {
-                // schedule in next 15 minutes randomly to avoid that all automations run at exactly
-                // earliest start 1 minute from now
-                // the same time which would slow performance
-                futureDate.setMinutes(futureDate.getMinutes() + 1 + Math.ceil(Math.random() * 15));
+                case 'Minute': {
+                    // schedule in next 15 minutes randomly to avoid that all automations run at exactly
+                    // earliest start 1 minute from now
+                    // the same time which would slow performance
+                    futureDate.setMinutes(
+                        futureDate.getMinutes() + 1 + Math.ceil(Math.random() * 15)
+                    );
+
+                    break;
+                }
+                // No default
             }
             // return time as Dateobject
             schedule.StartDateTime = futureDate;
@@ -824,12 +734,10 @@ class Automation extends MetadataType {
      */
     static _calcTime(offsetServer, dateInput, offsetInput) {
         // get UTC time in msec
-        let utc;
-        if ('string' === typeof dateInput) {
-            utc = new Date(dateInput + offsetInput).getTime();
-        } else {
-            utc = dateInput.getTime();
-        }
+        const utc =
+            'string' === typeof dateInput
+                ? new Date(dateInput + offsetInput).getTime()
+                : dateInput.getTime();
 
         // create new Date object reflecting SFMC's servertime
         const dateServer = new Date(utc + 3600000 * offsetServer);
@@ -837,14 +745,203 @@ class Automation extends MetadataType {
         // return time as a string without trailing "Z"
         return dateServer.toISOString().slice(0, -1);
     }
+    /**
+     * Experimental: Only working for DataExtensions:
+     * Saves json content to a html table in the local file system. Will create the parent directory if it does not exist.
+     * The json's first level of keys must represent the rows and the secend level the columns
+     *
+     * @private
+     * @param {TYPE.AutomationItem} json dataextension
+     * @param {object[][]} tabled prepped array for output in tabular format
+     * @returns {string} file content
+     */
+    static _generateDocMd(json, tabled) {
+        let output = `## ${json.key}\n\n`;
+        if (json.key !== json.name) {
+            output += `**Name** (not equal to External Key)**:** ${json.name}\n\n`;
+        }
+
+        output +=
+            `**Description:** ${json.description || 'n/a'}\n\n` +
+            `**Folder:** ${
+                json.r__folder_Path ||
+                '_Hidden! Could not find folder with ID ' + json.categoryId + '_'
+            }/\n\n`;
+        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') {
+            const tz =
+                this.definition.timeZoneDifference[
+                    this.definition.timeZoneMapping[json?.schedule?.timezoneName]
+                ];
+
+            if (json.schedule?.icalRecur) {
+                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`;
+
+                const ical = {};
+                for (const item of json.schedule.icalRecur.split(';')) {
+                    const temp = item.split('=');
+                    ical[temp[0]] = temp[1];
+                }
+                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 += '\n';
+            } else if (json.schedule) {
+                output += `**Schedule:** Not defined\n\n`;
+            }
+        } else if (json.type === 'triggered' && json.fileTrigger) {
+            output += `**File Trigger:**\n\n`;
+            output += `* Queue Files: ${json.fileTrigger.queueFiles}\n`;
+            output += `* Published: ${json.fileTrigger.isPublished}\n`;
+            output += `* Pattern: ${json.fileTrigger.fileNamingPattern}\n`;
+            output += `* Folder:  ${json.fileTrigger.folderLocationText}\n`;
+        }
+        if (tabled && tabled.length) {
+            let tableSeparator = '';
+            const row1 = [];
+            for (const column of tabled[0]) {
+                row1.push(
+                    `| ${column.title}${column.description ? `<br>_${column.description}_` : ''} `
+                );
+                tableSeparator += '| --- ';
+            }
+            output += row1.join('') + `|\n${tableSeparator}|\n`;
+            for (let i = 1; i < tabled.length; i++) {
+                for (const field of tabled[i]) {
+                    output += field ? `| _${field.i}: ${field.type}_<br>${field.name} ` : '| - ';
+                }
+                output += '|\n';
+            }
+        }
+        return output;
+    }
+    /**
+     * Saves json content to a html table in the local file system. Will create the parent directory if it does not exist.
+     * The json's first level of keys must represent the rows and the secend level the columns
+     *
+     * @private
+     * @param {string} directory directory the file will be written to
+     * @param {string} filename name of the file without '.json' ending
+     * @param {TYPE.AutomationItem} json dataextension.columns
+     * @param {'html'|'md'} mode html or md
+     * @returns {Promise.<boolean>} Promise of success of saving the file
+     */
+    static async _writeDoc(directory, filename, json, mode) {
+        await File.ensureDir(directory);
+
+        const tabled = [];
+        if (json.steps && json.steps.length) {
+            tabled.push(
+                json.steps.map((step, index) => ({
+                    title: `Step ${index + 1}`,
+                    description: step.name || '-',
+                }))
+            );
+            let maxActivities = 0;
+            for (const step of json.steps) {
+                if (step.activities.length > maxActivities) {
+                    maxActivities = step.activities.length;
+                }
+            }
+            for (let activityIndex = 0; activityIndex < maxActivities; activityIndex++) {
+                tabled.push(
+                    json.steps.map((step, stepIndex) =>
+                        step.activities[activityIndex]
+                            ? {
+                                  i: stepIndex + 1 + '.' + (activityIndex + 1),
+                                  name: step.activities[activityIndex].name,
+                                  type: step.activities[activityIndex].r__type,
+                              }
+                            : null
+                    )
+                );
+            }
+        }
+        let output;
+        if (mode === 'md') {
+            output = this._generateDocMd(json, tabled);
+            try {
+                // write to disk
+                await File.writeToFile(directory, filename + '.automation-doc', mode, output);
+            } catch (ex) {
+                Util.logger.error(`Automation.writeDeToX(${mode}):: error | ` + ex.message);
+            }
+        }
+    }
+    /**
+     * Parses metadata into a readable Markdown/HTML format then saves it
+     *
+     * @param {TYPE.BuObject} buObject properties for auth
+     * @param {TYPE.AutomationMap} [metadata] a list of dataExtension definitions
+     * @returns {Promise.<void>} -
+     */
+    static async document(buObject, metadata) {
+        if (['md', 'both'].includes(this.properties.options.documentType)) {
+            if (!metadata) {
+                metadata = this.readBUMetadataForType(
+                    File.normalizePath([
+                        this.properties.directories.retrieve,
+                        buObject.credential,
+                        buObject.businessUnit,
+                    ]),
+                    true
+                ).automation;
+            }
+            const docPath = File.normalizePath([
+                this.properties.directories.retrieve,
+                buObject.credential,
+                buObject.businessUnit,
+                this.definition.type,
+            ]);
+            if (!metadata || !Object.keys(metadata).length) {
+                // 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];
+                })
+            );
+        }
+    }
+    /**
+     * should return only the json for all but asset, query and script that are saved as multiple files
+     * additionally, the documentation for dataExtension and automation should be returned
+     *
+     * @param {string[]} keyArr customerkey of the metadata
+     * @returns {string[]} list of all files that need to be committed in a flat array ['path/file1.ext', 'path/file2.ext']
+     */
+    static getFilesToCommit(keyArr) {
+        if (!this.properties.metaDataTypes.documentOnRetrieve.includes(this.definition.type)) {
+            // document automation is not active upon retrieve, run default method instead
+            return super.getFilesToCommit(keyArr);
+        } else {
+            // document automation is active. assume we want to commit the MD file as well
+            const path = File.normalizePath([
+                this.properties.directories.retrieve,
+                this.buObject.credential,
+                this.buObject.businessUnit,
+                this.definition.type,
+            ]);
+
+            const fileList = keyArr.flatMap((key) => [
+                File.normalizePath([path, `${key}.${this.definition.type}-meta.json`]),
+                File.normalizePath([path, `${key}.${this.definition.type}-doc.md`]),
+            ]);
+            return fileList;
+        }
+    }
 }
 
 // Assign definition to static attributes
 Automation.definition = Definitions.automation;
-Automation.cache = {};
-/**
- * @type {Util.ET_Client}
- */
-Automation.client = undefined;
 
 module.exports = Automation;