mcdev 3.0.3 → 3.1.0

package/lib/metadataTypes/AccountUser.js

@@ -0,0 +1,389 @@
+'use strict';
+
+const MetadataType = require('./MetadataType');
+const Util = require('../util/util');
+const File = require('../util/file');
+
+/**
+ * MessageSendActivity MetadataType
+ * @augments MetadataType
+ */
+class AccountUser extends MetadataType {
+    /**
+     * Retrieves SOAP based metadata of metadata type into local filesystem. executes callback with retrieved metadata
+     * @param {String} retrieveDir Directory where retrieved metadata directory will be saved
+     * @param {String[]} _ Returns specified fields even if their retrieve definition is not set to true
+     * @param {Object} buObject properties for auth
+     * @returns {Promise<Object>} Promise of metadata
+     */
+    static async retrieve(retrieveDir, _, buObject) {
+        if (buObject.eid !== buObject.mid) {
+            Util.logger.info('Skipping User retrieval on non-parent BU');
+            return;
+        }
+        Util.logger.info('- Caching dependent Metadata: AccountUserAccount');
+
+        // get BUs that each users have access to
+        const optionsBUs = {};
+        let resultsBatch;
+        await Util.retryOnError(`Retrying ${this.definition.type}`, async () => {
+            resultsBatch = await new Promise((resolve, reject) => {
+                this.client.SoapClient.retrieve(
+                    'AccountUserAccount',
+                    [
+                        'AccountUser.AccountUserID',
+                        'AccountUser.UserID',
+                        'Account.ID',
+                        'Account.Name',
+                    ],
+                    optionsBUs,
+                    (ex, response) => (ex ? reject(ex) : resolve(response.body.Results))
+                );
+            });
+        });
+        this.userIdBuMap = {};
+        resultsBatch.forEach((item) => {
+            this.userIdBuMap[item.AccountUser.AccountUserID] =
+                this.userIdBuMap[item.AccountUser.AccountUserID] || [];
+            this.userIdBuMap[item.AccountUser.AccountUserID].push({
+                ID: item.Account.ID,
+                Name: item.Account.Name,
+            });
+        });
+        // get actual user details
+        const options = {
+            queryAllAccounts: true,
+
+            filter: {
+                leftOperand: {
+                    // normal users
+                    leftOperand: 'Email',
+                    operator: 'like',
+                    rightOperand: '@',
+                },
+                operator: 'OR',
+                rightOperand: {
+                    // installed packages
+                    leftOperand: {
+                        leftOperand: 'Name',
+                        operator: 'like',
+                        rightOperand: ' app user', // ! will not work if the name was too long as "app user" might be cut off
+                    },
+                    operator: 'AND',
+                    rightOperand: {
+                        // this is used to filter out system generated installed packages. in our testing, at least those installed packages created in the last few years have hat set this to false while additional (hidden) installed packages have it set to true.
+                        leftOperand: 'MustChangePassword',
+                        operator: 'equals',
+                        rightOperand: 'false',
+                    },
+                },
+            },
+        };
+
+        return super.retrieveSOAPgeneric(retrieveDir, buObject, options);
+    }
+    /**
+     *
+     * @param {string} date first date
+     * @param {string} date2 second date
+     * @returns {number} time difference
+     */
+    static timeSinceDate(date) {
+        const interval = 'days';
+        const second = 1000,
+            minute = second * 60,
+            hour = minute * 60,
+            day = hour * 24,
+            week = day * 7;
+        date = new Date(date);
+        const now = new Date();
+        const timediff = now - date;
+        if (isNaN(timediff)) {
+            return NaN;
+        }
+        let result;
+        switch (interval) {
+            case 'years':
+                result = now.getFullYear() - date.getFullYear();
+                break;
+            case 'months':
+                result =
+                    now.getFullYear() * 12 +
+                    now.getMonth() -
+                    (date.getFullYear() * 12 + date.getMonth());
+                break;
+            case 'weeks':
+                result = Math.floor(timediff / week);
+                break;
+            case 'days':
+                result = Math.floor(timediff / day);
+                break;
+            case 'hours':
+                result = Math.floor(timediff / hour);
+                break;
+            case 'minutes':
+                result = Math.floor(timediff / minute);
+                break;
+            case 'seconds':
+                result = Math.floor(timediff / second);
+                break;
+            default:
+                return undefined;
+        }
+        return result + ' ' + interval;
+    }
+    /**
+     * helper to print bu names
+     * @param {Util.BuObject} buObject needed for eid
+     * @param {string} buObject.eid needed to check for parent bu
+     * @param {numeric} id bu id
+     * @returns {string} "bu name (bu id)""
+     */
+    static getBuName(buObject, id) {
+        let name;
+        if (buObject.eid == id) {
+            name = '_ParentBU_';
+        } else {
+            name = this.buIdName[id];
+        }
+        return `<nobr>${name} (${id})</nobr>`;
+    }
+    /**
+     * Creates markdown documentation of all roles
+     * @param {Util.BuObject} buObject properties for auth
+     * @param {Object} [metadata] user list
+     * @returns {Promise<void>} -
+     */
+    static async document(buObject, metadata) {
+        if (buObject.eid !== buObject.mid) {
+            Util.logger.error(
+                `Users can only be retrieved & documented for the ${Util.parentBuName}`
+            );
+            return;
+        }
+        if (!metadata) {
+            // load users from disk if document was called directly and not part of a retrieve
+            try {
+                metadata = this.readBUMetadataForType(
+                    File.normalizePath([
+                        this.properties.directories.retrieve,
+                        buObject.credential,
+                        Util.parentBuName,
+                    ]),
+                    true
+                ).accountUser;
+            } catch (ex) {
+                Util.logger.error(ex.message);
+                return;
+            }
+        }
+        // init map of BU Ids > BU Name
+        this.buIdName = {};
+
+        // initialize permission object
+        this.allPermissions = {};
+        const users = [];
+        // traverse all permissions recursively and write them into allPermissions object once it has reached the end
+        for (const id in metadata) {
+            const user = metadata[id];
+            // TODO resolve user permissions to something readable
+            let userPermissions = '';
+            if (user.UserPermissions) {
+                if (!user.UserPermissions.length) {
+                    // 1 single user permission found, normalize it
+                    user.UserPermissions = [user.UserPermissions];
+                }
+                userPermissions = user.UserPermissions.map((item) => item.ID * 1)
+                    .sort(function (a, b) {
+                        return a < b ? -1 : a > b ? 1 : 0;
+                    })
+                    .join(', ');
+            }
+            // user roles
+            // TODO think about what to do with "individual role" entries
+            let roles = '';
+            if (user.Roles) {
+                roles =
+                    '<nobr>' +
+                    user.Roles.map((item) => item.Name)
+                        .sort(function (a, b) {
+                            return a < b ? -1 : a > b ? 1 : 0;
+                        })
+                        .join(',</nobr><br> <nobr>') +
+                    '</nobr>';
+            }
+            let associatedBus = '';
+            if (user.AssociatedBusinessUnits__c) {
+                associatedBus = user.AssociatedBusinessUnits__c.map((item) => {
+                    this.buIdName[item.ID] = item.Name;
+                    return this.getBuName(buObject, item.ID);
+                })
+                    .sort(function (a, b) {
+                        return a < b ? -1 : a > b ? 1 : 0;
+                    })
+                    .join(',<br> ');
+            }
+            const defaultBUName = this.getBuName(buObject, user.DefaultBusinessUnit);
+            users.push({
+                TYPE: user.type__c,
+                UserID: user.UserID,
+                AccountUserID: user.AccountUserID,
+                CustomerKey: user.CustomerKey,
+                Name: user.Name,
+                Email: user.Email,
+                NotificationEmailAddress: user.NotificationEmailAddress,
+                ActiveFlag: user.ActiveFlag === 'true' ? '✓' : '-',
+                IsAPIUser: user.IsAPIUser === 'true' ? '✓' : '-',
+                MustChangePassword: user.MustChangePassword === 'true' ? '✓' : '-',
+                DefaultBusinessUnit: defaultBUName,
+                AssociatedBusinessUnits__c: associatedBus,
+                Roles: roles,
+                UserPermissions: userPermissions,
+                LastSuccessfulLogin: this.timeSinceDate(user.LastSuccessfulLogin),
+                CreatedDate: user.CreatedDate.split('T').join(' '),
+                ModifiedDate: user.ModifiedDate.split('T').join(' '),
+            });
+        }
+        users.sort(function (a, b) {
+            return a.Name < b.Name ? -1 : a.Name > b.Name ? 1 : 0;
+        });
+        const columnsToPrint = [
+            ['Name', 'Name'],
+            ['Last successful Login', 'LastSuccessfulLogin'],
+            ['Active', 'ActiveFlag'],
+            ['API User', 'IsAPIUser'],
+            ['Must change PW', 'MustChangePassword'],
+            ['Default BU', 'DefaultBusinessUnit'],
+            ['BU Access', 'AssociatedBusinessUnits__c'],
+            ['Roles', 'Roles'],
+            ['User Permissions', 'UserPermissions'],
+            ['Login', 'UserID'],
+            ['ID', 'AccountUserID'],
+            ['Key', 'CustomerKey'],
+            ['E-Mail', 'Email'],
+            ['Notification E-Mail', 'NotificationEmailAddress'],
+            ['Modified Date', 'ModifiedDate'],
+            ['Created Date', 'CreatedDate'],
+        ];
+        let output = `# User Overview - ${buObject.credential}`;
+        output += this._generateDocMd(
+            users.filter((user) => user.TYPE === 'User' && user.ActiveFlag === '✓'),
+            'User',
+            columnsToPrint
+        );
+        output += this._generateDocMd(
+            users.filter((user) => user.TYPE === 'User' && user.ActiveFlag === '-'),
+            'Inactivated User',
+            columnsToPrint
+        );
+        output += this._generateDocMd(
+            users.filter((user) => user.TYPE === 'Installed Package'),
+            'Installed Package',
+            columnsToPrint
+        );
+        const docPath = File.normalizePath([this.properties.directories.users]);
+
+        try {
+            const filename = buObject.credential;
+            // ensure docs/roles folder is existing (depends on setup in .mcdevrc.json)
+            if (!File.existsSync(docPath)) {
+                File.mkdirpSync(docPath);
+            }
+            // write to disk
+            await File.writeToFile(docPath, filename + '.accountUser', 'md', output);
+            Util.logger.info(`Created ${docPath}${filename}.accountUser.md`);
+            if (['html', 'both'].includes(this.properties.options.documentType)) {
+                Util.logger.warn(
+                    'HTML-based documentation of accountUser currently not supported.'
+                );
+            }
+        } catch (ex) {
+            Util.logger.error(`AccountUser.document():: error | `, ex.message);
+        }
+    }
+    /**
+     * 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 {DataExtensionItem} json dataextension
+     * @param {Array} tabled prepped array for output in tabular format
+     * @returns {string} file content
+     */
+    /**
+     *
+     * @param {Object[]} users list of users and installed package
+     * @param {'Installed Package'|'User'} type choose what sub type to print
+     * @param {Array[]} columnsToPrint helper array
+     * @param {Object} buObject properties for auth
+     * @returns {string} markdown
+     */
+    static _generateDocMd(users, type, columnsToPrint) {
+        let output = `\n\n## ${type}s (${users.length})\n\n`;
+        let tableSeparator = '';
+        columnsToPrint.forEach((column) => {
+            output += `| ${column[0]} `;
+            tableSeparator += '| --- ';
+        });
+        output += `|\n${tableSeparator}|\n`;
+        users.forEach((user) => {
+            columnsToPrint.forEach((column) => {
+                output += `| ${user[column[1]]} `;
+            });
+            output += `|\n`;
+        });
+        return output;
+    }
+
+    /**
+     * manages post retrieve steps
+     * @param {Object} metadata a single query
+     * @returns {Object[]} Array with one metadata object and one query string
+     */
+    static postRetrieveTasks(metadata) {
+        return this.parseMetadata(metadata);
+    }
+    /**
+     * parses retrieved Metadata before saving
+     * @param {Object} metadata a single query activity definition
+     * @returns {Array} Array with one metadata object and one sql string
+     */
+    static parseMetadata(metadata) {
+        metadata.type__c = 'Installed Package';
+        if (metadata.Email.includes('@') && !metadata.Name.endsWith('app user')) {
+            metadata.type__c = 'User';
+        }
+
+        if (this.userIdBuMap[metadata.ID]) {
+            metadata.AssociatedBusinessUnits__c = this.userIdBuMap[metadata.ID];
+        } else {
+            metadata.AssociatedBusinessUnits__c = [];
+        }
+
+        let roles;
+        if (metadata.Roles.Role) {
+            // normalize to always use array
+            if (!metadata.Roles.Role.length) {
+                metadata.Roles.Role = [metadata.Roles.Role];
+            }
+            // convert complex object into basic set of info
+            roles = metadata.Roles.Role.map((item) => ({
+                Name: item.Name,
+                CustomerKey: item.CustomerKey,
+            })).sort(function (a, b) {
+                return a.Name < b.Name ? -1 : a.Name > b.Name ? 1 : 0;
+            });
+        } else {
+            // set to empty array
+            roles = [];
+        }
+        metadata.Roles = roles;
+
+        return metadata;
+    }
+}
+
+// Assign definition to static attributes
+AccountUser.definition = require('../MetadataTypeDefinitions').accountUser;
+
+module.exports = AccountUser;

package/lib/metadataTypes/Asset.js

@@ -162,6 +162,7 @@ class Asset extends MetadataType {
         } else {
             Util.logger.info(`- Caching Subtype: ${subType}`);
         }
+        const subtypeIds = subTypeArray?.map(subTypeItemName => Asset.definition.typeMapping[subTypeItemName]);
         const uri = 'asset/v1/content/assets/';
         const options = {
             uri: uri + 'query',
@@ -178,9 +179,9 @@ class Asset extends MetadataType {
         if (templateName) {
             options.json.query = {
                 leftOperand: {
-                    property: 'assetType.name',
+                    property: 'assetType.id',
                     simpleOperator: 'in',
-                    value: subTypeArray,
+                    value: subtypeIds,
                 },
                 logicalOperator: 'AND',
                 rightOperand: {
@@ -191,9 +192,9 @@ class Asset extends MetadataType {
             };
         } else {
             options.json.query = {
-                property: 'assetType.name',
+                property: 'assetType.id',
                 simpleOperator: 'in',
-                value: subTypeArray,
+                value: subtypeIds,
             };
             options.json.sort = [{ property: 'id', direction: 'ASC' }];
         }
@@ -232,9 +233,9 @@ class Asset extends MetadataType {
                 // Since we sort by ID, we can get the last ID then run new requests from there
                 options.json.query = {
                     leftOperand: {
-                        property: 'assetType.name',
+                        property: 'assetType.id',
                         simpleOperator: 'in',
-                        value: subTypeArray,
+                        value: subtypeIds,
                     },
                     logicalOperator: 'AND',
                     rightOperand: {
@@ -441,7 +442,7 @@ class Asset extends MetadataType {
         await this._mergeCode(metadata, deployDir, subType);
 
         // #2 get file from local disk and insert as base64
-        await this._readExtendedFileFromFS(metadata, deployDir, subType);
+        await this._readExtendedFileFromFS(metadata, subType, deployDir);
 
         return metadata;
     }

package/lib/metadataTypes/Automation.js

@@ -92,14 +92,10 @@ class Automation extends MetadataType {
      * @returns {Promise<{metadata:AutomationMap,type:string}>} Promise of metadata
      */
     static async retrieve(retrieveDir) {
-        const results = await new Promise((resolve) => {
-            this.client.SoapClient.retrieve('Program', ['ObjectID'], (error, response) => {
-                if (error) {
-                    throw new Error(error);
-                } else {
-                    resolve(response.body.Results);
-                }
-            });
+        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(
@@ -116,6 +112,60 @@ class Automation extends MetadataType {
         Util.logger.info(
             `Downloaded: ${this.definition.type} (${Object.keys(savedMetadata).length})`
         );
+        return { metadata: savedMetadata, type: this.definition.type };
+    }
+    /**
+     * Retrieves Metadata of Automation
+     * @returns {Promise<{metadata:AutomationMap,type:string}>} 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 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);
+        });
+        details.map((item) => {
+            item.key = item.CustomerKey;
+        });
+
+        const parsed = this.parseResponseBody({ items: details });
+
         return { metadata: parsed, type: this.definition.type };
     }
 
@@ -315,9 +365,8 @@ class Automation extends MetadataType {
                 delete metadata.schedule.scheduledTime;
                 delete metadata.schedule.scheduledStatus;
                 if (this.definition.timeZoneMapping[metadata.schedule.timezoneName]) {
-                    metadata.schedule.timezoneId = 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`
@@ -435,44 +484,56 @@ class Automation extends MetadataType {
                     }
                     if (schedule !== null) {
                         try {
-                            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 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}`
+                                    );
+                                }
                             );
                         } catch (ex) {
                             Util.logger.error(
@@ -684,9 +745,8 @@ class Automation extends MetadataType {
         }
 
         if (this.definition.timeZoneMapping[scheduleObject.timezoneName]) {
-            scheduleObject.timezoneId = 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`
@@ -780,6 +840,9 @@ class Automation extends MetadataType {
 // Assign definition to static attributes
 Automation.definition = Definitions.automation;
 Automation.cache = {};
+/**
+ * @type {Util.ET_Client}
+ */
 Automation.client = undefined;
 
 module.exports = Automation;