mcdev 4.2.1 → 4.3.0

package/lib/metadataTypes/Interaction.js

@@ -2,34 +2,700 @@
 
 const TYPE = require('../../types/mcdev.d');
 const MetadataType = require('./MetadataType');
+const TransactionalEmail = require('./TransactionalEmail');
+const Util = require('../util/util');
+const cache = require('../util/cache');
+const File = require('../util/file');
 
 /**
- * Script MetadataType
+ * Interaction MetadataType
+ * ! BETA RELEASE of journey support (v4.3.0); it so far only resolves a limited amount of dependencies and will likely break during cross-BU deployments!
+ * id: A unique id of the journey assigned by the journey’s API during its creation
+ * key: A unique id of the journey within the MID. Can be generated by the developer
+ * definitionId: A unique UUID provided by Salesforce Marketing Cloud. Each version of a journey has a unique DefinitionID while the Id and Key remain the same. Version 1 will have id == definitionId
  *
  * @augments MetadataType
  */
 class Interaction extends MetadataType {
     /**
      * Retrieves Metadata of Interaction
-     * Endpoint /interaction/v1/interactions?extras=all&pageSize=50000 return 50000 Scripts with all details.
      *
      * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
      * @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.MetadataTypeMapObj>} Promise
      */
-    static retrieve(retrieveDir, _, __, ___, key) {
-        return super.retrieveREST(
-            retrieveDir,
-            `/interaction/v1/interactions${
-                key ? '/key:' + encodeURIComponent(key) : ''
-            }?extras=all`,
-            null,
-            null,
-            key
+    static async retrieve(retrieveDir, _, __, key) {
+        if (retrieveDir) {
+            // only print this during retrieve, not during retrieveForCache
+            Util.logBeta(this.definition.type);
+        }
+
+        let singleKey = '';
+        let mode = 'key';
+        if (key) {
+            /* eslint-disable unicorn/prefer-ternary */
+
+            if (key.startsWith('id:') || key.startsWith('%23')) {
+                // ! allow selecting journeys by ID because that's what users see in the URL
+                // if the key started with %23 assume an ID was copied from the URL but the user forgot to prefix it with id:
+
+                // remove id: or %23
+                singleKey = key.slice(3);
+                if (singleKey.startsWith('%23')) {
+                    // in the journey URL the Id is prefixed with an HTML-encoded "#" which could accidentally be copied by users
+                    // despite the slicing above, this still needs testing here because users might have prefixed the ID with id: but did not know to remove the #23
+                    singleKey = singleKey.slice(3);
+                }
+                if (singleKey.includes('/')) {
+                    // in the journey URL the version is appended after the ID, separated by a forward-slash. Needs to be removed from the ID for the retrieve as we always aim to retrieve the latest version only
+                    singleKey = singleKey.split('/')[0];
+                }
+                mode = 'id';
+            } else {
+                // assume actual key was provided
+                singleKey = 'key:' + encodeURIComponent(key);
+            }
+            /* eslint-enable unicorn/prefer-ternary */
+        }
+        // full details for retrieve, only base data for caching; reduces caching time from minutes to seconds
+        const extras = retrieveDir ? 'all' : '';
+
+        try {
+            return await super.retrieveREST(
+                retrieveDir,
+                `/interaction/v1/interactions/${singleKey}?extras=${extras}`,
+                null,
+                null,
+                key
+            );
+        } catch (ex) {
+            // if the interaction does not exist, the API returns an error code which would otherwise bring execution to a hold
+            if (
+                [
+                    'Interaction matching key not found.',
+                    'Must provide a valid ID or Key parameter',
+                ].includes(ex.message)
+            ) {
+                Util.logger.info(
+                    `Downloaded: ${this.definition.type} (0)${Util.getKeysString(
+                        mode === 'id' ? singleKey : key,
+                        mode === 'id'
+                    )}`
+                );
+            } else {
+                throw ex;
+            }
+        }
+    }
+    /**
+     * Delete a metadata item from the specified business unit
+     *
+     * @param {string} key Identifier of item
+     * @returns {Promise.<boolean>} deletion success status
+     */
+    static async deleteByKey(key) {
+        let version;
+        let singleKey = '';
+        /* eslint-disable unicorn/prefer-ternary */
+        if (key.startsWith('id:') || key.startsWith('%23')) {
+            // ! allow selecting journeys by ID because that's what users see in the URL
+            // if the key started with %23 assume an ID was copied from the URL but the user forgot to prefix it with id:
+
+            // remove id: or %23
+            singleKey = key.slice(3);
+            if (singleKey.startsWith('%23')) {
+                // in the journey URL the Id is prefixed with an HTML-encoded "#" which could accidentally be copied by users
+                // despite the slicing above, this still needs testing here because users might have prefixed the ID with id: but did not know to remove the #23
+                singleKey = singleKey.slice(3);
+            }
+            if (singleKey.includes('/')) {
+                // in the journey URL the version is appended after the ID, separated by a forward-slash.
+                [singleKey, version] = singleKey.split('/');
+            }
+        } else {
+            if (key.includes('/')) {
+                // in the journey URL the version is appended after the ID, separated by a forward-slash.
+                [key, version] = key.split('/');
+            }
+
+            // delete by key with specified version does not work, therefore we need to get the ID first
+            const response = await this.client.rest.get(
+                `/interaction/v1/interactions/key:${encodeURIComponent(key)}?extras=`
+            );
+            const results = this.parseResponseBody(response, key);
+            singleKey = results[key].id;
+            Util.logger.debug(`Deleting interaction ${key} via its ID ${singleKey}`);
+        }
+        if (!/^\d+$/.test(version)) {
+            throw new TypeError(
+                'Version is required for deleting interactions to avoid accidental deletion of the wrong item. Please append it at the end of the key or id, separated by forward-slash. Example for deleting version 4: ' +
+                    key +
+                    '/4'
+            );
+        }
+        Util.logger.warn(
+            `Deleting Interactions via this command breaks following retrieve-by-key/id requests until you've deployed/created a new draft version! You can get still get the latest available version of your journey by retrieving all interactions on this BU.`
         );
+        /* eslint-enable unicorn/prefer-ternary */
+        return super.deleteByKeyREST(
+            '/interaction/v1/interactions/' + singleKey + `?versionNumber=${version}`,
+            key,
+            false
+        );
+    }
+    /**
+     * Deploys metadata - merely kept here to be able to print {@link Util.logBeta} once per deploy
+     *
+     * @param {TYPE.MetadataTypeMap} metadata metadata mapped by their keyField
+     * @param {string} deployDir directory where deploy metadata are saved
+     * @param {string} retrieveDir directory where metadata after deploy should be saved
+     * @returns {Promise.<TYPE.MetadataTypeMap>} Promise of keyField => metadata map
+     */
+    static async deploy(metadata, deployDir, retrieveDir) {
+        Util.logBeta(this.definition.type);
+        return super.deploy(metadata, deployDir, retrieveDir);
+    }
+
+    /**
+     * Updates a single item
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @returns {Promise} Promise
+     */
+    static update(metadata) {
+        return super.updateREST(metadata, '/interaction/v1/interactions/', true);
+    }
+
+    /**
+     * Creates a single item
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single item
+     * @returns {Promise} Promise
+     */
+    static create(metadata) {
+        return super.createREST(metadata, '/interaction/v1/interactions/');
+    }
+    /**
+     * Helper for writing Metadata to disk, used for Retrieve and deploy
+     *
+     * @param {TYPE.MetadataTypeMap} results metadata results from deploy
+     * @param {string} retrieveDir directory where metadata should be stored after deploy/retrieve
+     * @param {string} [overrideType] for use when there is a subtype (such as folder-queries)
+     * @param {TYPE.TemplateMap} [templateVariables] variables to be replaced in the metadata
+     * @returns {Promise.<TYPE.MetadataTypeMap>} Promise of saved metadata
+     */
+    static async saveResults(results, retrieveDir, overrideType, templateVariables) {
+        if (Object.keys(results).length) {
+            // only execute the following if records were found
+            await this._postRetrieveTasksBulk(results);
+        }
+        return super.saveResults(results, retrieveDir, overrideType, templateVariables);
+    }
+
+    /**
+     * helper for Interaction's {@link saveResults}. Gets executed after retreive of metadata type and
+     *
+     * @param {TYPE.MetadataTypeMap} metadataMap key=customer key, value=metadata
+     */
+    static async _postRetrieveTasksBulk(metadataMap) {
+        let needTransactionalEmail = false;
+        for (const key in metadataMap) {
+            if (metadataMap[key].definitionType == 'Transactional') {
+                needTransactionalEmail = true;
+                break;
+            }
+        }
+        if (needTransactionalEmail && !cache.getCache()?.transactionalEmail) {
+            // ! interaction and transactionalEmail both link to each other. caching transactionalEmail here "manually", assuming that it's quicker than the other way round
+            Util.logger.info(' - Caching dependent Metadata: transactionalEmail');
+            TransactionalEmail.buObject = this.buObject;
+            TransactionalEmail.client = this.client;
+            TransactionalEmail.properties = this.properties;
+            const result = await TransactionalEmail.retrieveForCache();
+            cache.setMetadata('transactionalEmail', result.metadata);
+        }
+    }
+
+    /**
+     * manages post retrieve steps
+     * ! BETA RELEASE of journey support (v4.3.0); it so far only resolves a limited amount of dependencies and will likely break during cross-BU deployments!
+     *
+     * @param {TYPE.MetadataTypeItem} metadata a single query
+     * @returns {TYPE.MetadataTypeItem} Array with one metadata object and one query string
+     */
+    static postRetrieveTasks(metadata) {
+        // folder
+        super.setFolderPath(metadata);
+
+        switch (metadata.definitionType) {
+            case 'Multistep': {
+                // Multi-Step Journey
+                // ~~~ TRIGGERS ~~~~
+                // eventDefinition / definitionType==='Multistep' && channel==='' && triggers[].type === 'EmailAudience'|'APIEvent'
+                if (
+                    metadata.triggers?.length > 0 &&
+                    metadata.triggers[0].metaData?.eventDefinitionKey
+                ) {
+                    // trigger found; there can only be one entry in this array
+                    try {
+                        const edId = cache.searchForField(
+                            'eventDefinition',
+                            metadata.triggers[0].metaData.eventDefinitionKey,
+                            'eventDefinitionKey',
+                            'id'
+                        );
+                        if (metadata.triggers[0].metaData.eventDefinitionId !== edId) {
+                            throw new Error(
+                                `eventDefinitionId not matching Id found on eventDefinition with key in eventDefinitionKey`
+                            );
+                        }
+                        delete metadata.triggers[0].metaData.eventDefinitionId;
+                    } catch (ex) {
+                        Util.logger.warn(
+                            ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                                metadata[this.definition.keyField]
+                            }): ${ex.message}.`
+                        );
+                    }
+                }
+
+                // ~~~ ACTIVITIES ~~~~
+
+                // triggeredSend + email+asset / activities[].type === 'EMAILV2'
+                // TODO email / asset
+                for (const item of metadata.activities) {
+                    // check if all triggeredSends are there
+                    try {
+                        if (item.configurationArguments?.triggeredSendKey) {
+                            // triggeredSendKey is not always set but triggeredSendId is
+                            cache.searchForField(
+                                'triggeredSendDefinition',
+                                item.configurationArguments.triggeredSendKey,
+                                'CustomerKey',
+                                'CustomerKey'
+                            );
+                            delete item.configurationArguments.triggeredSendId;
+                        } else if (item.configurationArguments?.triggeredSendId) {
+                            // triggeredSendKey is not always set but triggeredSendId is
+                            item.configurationArguments.triggeredSendKey = cache.searchForField(
+                                'triggeredSendDefinition',
+                                item.configurationArguments.triggeredSendId,
+                                'ObjectID',
+                                'CustomerKey'
+                            );
+                            delete item.configurationArguments.triggeredSendId;
+                        }
+                    } catch (ex) {
+                        Util.logger.warn(
+                            ` - ${this.definition.type} '${metadata[this.definition.nameField]}' (${
+                                metadata[this.definition.keyField]
+                            }): Could not find triggeredSendDefinition (${ex.message})`
+                        );
+                    }
+                }
+
+                // TODO: Filters / activities[].type === 'MULTICRITERIADECISION'
+                // - activities[].arguments.filterResult
+                // - activities[].arguments.configurationArguments.criteria
+
+                // TODO: wait activity / activities[].type === 'WAIT'
+
+                // TODO: journey template id? / metaData.templateId
+                break;
+            }
+            case 'Quicksend': {
+                // Single Send Journey
+                Util.logger.warn(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): definitionType Quicksend is not fully supported yet.`
+                );
+                // ~~~ TRIGGERS ~~~~
+                // eventDefinition && triggers[].type === 'ContactAudience'
+                if (
+                    metadata.triggers?.length > 0 &&
+                    metadata.triggers[0].metaData?.eventDefinitionKey
+                ) {
+                    // trigger found; there can only be one entry in this array
+                    try {
+                        const edId = cache.searchForField(
+                            'eventDefinition',
+                            metadata.triggers[0].metaData.eventDefinitionKey,
+                            'eventDefinitionKey',
+                            'id'
+                        );
+                        if (metadata.triggers[0].metaData.eventDefinitionId !== edId) {
+                            throw new Error(
+                                ` - ${this.definition.type} ${
+                                    metadata[this.definition.nameField]
+                                } (${
+                                    metadata[this.definition.keyField]
+                                }): eventDefinitionId not matching Id found on eventDefinition with key in eventDefinitionKey`
+                            );
+                        }
+                        delete metadata.triggers[0].metaData.eventDefinitionId;
+                    } catch (ex) {
+                        Util.logger.warn(
+                            ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                                metadata[this.definition.keyField]
+                            }): ${ex.message}.`
+                        );
+                    }
+                }
+
+                // ~~~ ACTIVITIES ~~~~
+                try {
+                    // TODO channel=='email'
+                    // TODO channel=='sms'
+                    // TODO channel=='push' / activities[].type === 'PUSHNOTIFICATIONACTIVITY'
+                } catch (ex) {
+                    Util.logger.warn(
+                        ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                            metadata[this.definition.keyField]
+                        }): ${ex.message}.`
+                    );
+                }
+                break;
+            }
+            case 'Transactional': {
+                // Transactional Send Journey
+                // ~~~ TRIGGERS ~~~~
+                // ! journeys so far only supports transactional EMAIL messages. SMS and Push do not create their own journey.
+                // ! transactional (email) journeys only have a dummy trigger without real content.
+                // transactionalEmail / definitionType==='Transactional' && channel==='email' && triggers[].type === 'transactional-api'
+                // --> nothing to do here
+
+                // ~~~ ACTIVITIES ~~~~
+                // ! transactional (email) journeys only have one activity (type=EMAILV2) which links back to the transactionalEmail ()
+                switch (metadata.channel) {
+                    case 'email': {
+                        if (
+                            metadata.activities?.length > 0 &&
+                            metadata.activities[0].configurationArguments?.triggeredSendKey
+                        ) {
+                            // trigger found; there can only be one entry in this array
+                            try {
+                                const tEmailId = cache.searchForField(
+                                    'transactionalEmail',
+                                    metadata.activities[0].configurationArguments?.triggeredSendKey,
+                                    'definitionKey',
+                                    'definitionId'
+                                );
+                                if (
+                                    tEmailId !=
+                                    metadata.activities[0].configurationArguments?.triggeredSendId
+                                ) {
+                                    throw new Error(
+                                        ` - ${this.definition.type} ${
+                                            metadata[this.definition.nameField]
+                                        } (${
+                                            metadata[this.definition.keyField]
+                                        }): transactionalEmailId not matching Id found on transactionalEmail with key in transactionalEmailKey`
+                                    );
+                                }
+                                if (
+                                    metadata.activities[0].metaData?.highThroughput
+                                        ?.definitionKey &&
+                                    metadata.activities[0].metaData?.highThroughput
+                                        ?.definitionKey !=
+                                        metadata.activities[0].configurationArguments
+                                            ?.triggeredSendKey
+                                ) {
+                                    throw new Error(
+                                        ` - ${this.definition.type} ${
+                                            metadata[this.definition.nameField]
+                                        } (${
+                                            metadata[this.definition.keyField]
+                                        }): metaData.highThroughput.definitionKey not matching key in configurationArguments.transactionalEmailKey`
+                                    );
+                                }
+                            } catch (ex) {
+                                Util.logger.warn(
+                                    ` - ${this.definition.type} ${
+                                        metadata[this.definition.nameField]
+                                    } (${metadata[this.definition.keyField]}): ${ex.message}.`
+                                );
+                            }
+                        }
+
+                        break;
+                    }
+                    default: {
+                        // it is expected that we'll see 'sms' and 'push' here in the future
+                        Util.logger.warn(
+                            ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                                metadata[this.definition.keyField]
+                            }): channel ${
+                                metadata.channel
+                            } is not supported yet. Please open a ticket at https://github.com/Accenture/sfmc-devtools/issues/new/choose to request it`
+                        );
+                    }
+                }
+
+                break;
+            }
+            default: {
+                Util.logger.warn(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): definitionType ${
+                        metadata.definitionType
+                    } is not supported yet. Please open a ticket at https://github.com/Accenture/sfmc-devtools/issues/new/choose to request it`
+                );
+            }
+        }
+
+        return metadata;
+    }
+    /**
+     * prepares a TSD for deployment
+     * ! BETA RELEASE of journey support (v4.3.0); it so far only resolves a limited amount of dependencies and will likely break during cross-BU deployments!
+     *
+     * @param {TYPE.MetadataTypeItem} metadata of a single TSD
+     * @returns {TYPE.MetadataTypeItem} metadata object
+     */
+    static async preDeployTasks(metadata) {
+        if (metadata.status !== 'Draft') {
+            metadata.status !== 'Draft';
+        }
+
+        // folder
+        super.setFolderId(metadata);
+
+        switch (metadata.definitionType) {
+            case 'Multistep': {
+                // Multi-Step Journey
+                // ~~~ TRIGGERS ~~~~
+
+                // eventDefinition / definitionType==='Multistep' && channel==='' && triggers[].type === 'EmailAudience'|'APIEvent'
+                if (
+                    metadata.triggers?.length > 0 &&
+                    metadata.triggers[0].metaData?.eventDefinitionKey
+                ) {
+                    // trigger found; there can only be one entry in this array
+                    metadata.triggers[0].metaData.eventDefinitionId = cache.searchForField(
+                        'eventDefinition',
+                        metadata.triggers[0].metaData.eventDefinitionKey,
+                        'eventDefinitionKey',
+                        'id'
+                    );
+                }
+
+                // transactionalEmail / definitionType==='Transactional' && channel==='email' && triggers[].type === 'transactional-api'
+
+                // ~~~ ACTIVITIES ~~~~
+
+                // triggeredSend + email+asset / activities[].type === 'EMAILV2'
+                // TODO email / asset
+                for (const item of metadata.activities) {
+                    // check if all triggeredSends are there
+                    if (!item.configurationArguments?.triggeredSendKey) {
+                        continue;
+                    }
+                    // triggeredSendKey is not always set but triggeredSendId is
+                    item.configurationArguments.triggeredSendId = cache.searchForField(
+                        'triggeredSendDefinition',
+                        item.configurationArguments.triggeredSendKey,
+                        'CustomerKey',
+                        'ObjectID'
+                    );
+                }
+
+                // TODO: Filters / activities[].type === 'MULTICRITERIADECISION'
+                // - activities[].arguments.filterResult
+                // - activities[].arguments.configurationArguments.criteria
+
+                // TODO: wait activity / activities[].type === 'WAIT'
+
+                // TODO: journey template id? / metaData.templateId
+                break;
+            }
+            case 'Quicksend': {
+                // Single Send Journey
+                Util.logger.warn(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): definitionType Quicksend is not supported yet and might fail to deploy.`
+                );
+                // ~~~ TRIGGERS ~~~~
+                // eventDefinition && triggers[].type === 'ContactAudience'
+                if (
+                    metadata.triggers?.length > 0 &&
+                    metadata.triggers[0].metaData?.eventDefinitionKey
+                ) {
+                    // trigger found; there can only be one entry in this array
+                    try {
+                        metadata.triggers[0].metaData.eventDefinitionId = cache.searchForField(
+                            'eventDefinition',
+                            metadata.triggers[0].metaData?.eventDefinitionKey,
+                            'eventDefinitionKey',
+                            'id'
+                        );
+                    } catch (ex) {
+                        Util.logger.warn(
+                            ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                                metadata[this.definition.keyField]
+                            }): ${ex.message}.`
+                        );
+                    }
+                }
+
+                // ~~~ ACTIVITIES ~~~~
+                try {
+                    // TODO channel=='email'
+                    // TODO channel=='sms'
+                    // TODO channel=='push' / activities[].type === 'PUSHNOTIFICATIONACTIVITY'
+                } catch (ex) {
+                    Util.logger.warn(
+                        ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                            metadata[this.definition.keyField]
+                        }): ${ex.message}.`
+                    );
+                }
+                break;
+            }
+            case 'Transactional': {
+                // Transactional Send Journey
+                // ~~~ TRIGGERS ~~~~
+                // ! journeys so far transactional EMAIL messages. SMS and Push do not create their own journey.
+                // ! transactional (email) journeys only have a dummy trigger without real content.
+
+                // transactionalEmail / definitionType==='Transactional' && channel==='email' && triggers[].type === 'transactional-api'
+                // --> nothing to do here
+
+                // ~~~ ACTIVITIES ~~~~
+                // ! transactional (email) journeys only have one activity (type=EMAILV2) which links back to the transactionalEmail ()
+                switch (metadata.channel) {
+                    case 'email': {
+                        if (
+                            metadata.activities?.length > 0 &&
+                            metadata.activities[0].configurationArguments?.triggeredSendKey
+                        ) {
+                            // trigger found; there can only be one entry in this array
+                            metadata.activities[0].configurationArguments.triggeredSendId =
+                                cache.searchForField(
+                                    'transactionalEmail',
+                                    metadata.activities[0].configurationArguments?.triggeredSendKey,
+                                    'definitionKey',
+                                    'definitionId'
+                                );
+                            if (
+                                metadata.activities[0].metaData?.highThroughput?.definitionKey &&
+                                metadata.activities[0].metaData?.highThroughput?.definitionKey !=
+                                    metadata.activities[0].configurationArguments?.triggeredSendKey
+                            ) {
+                                throw new Error(
+                                    ` - ${this.definition.type} ${
+                                        metadata[this.definition.nameField]
+                                    } (${
+                                        metadata[this.definition.keyField]
+                                    }): metaData.highThroughput.definitionKey not matching key in configurationArguments.transactionalEmailKey`
+                                );
+                            }
+                        }
+
+                        break;
+                    }
+                    default: {
+                        // it is expected that we'll see 'sms' and 'push' here in the future
+                        throw new Error(
+                            ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                                metadata[this.definition.keyField]
+                            }): channel ${
+                                metadata.channel
+                            } is not supported yet. Please open a ticket at https://github.com/Accenture/sfmc-devtools/issues/new/choose to request it`
+                        );
+                    }
+                }
+
+                break;
+            }
+            default: {
+                throw new Error(
+                    ` - ${this.definition.type} ${metadata[this.definition.nameField]} (${
+                        metadata[this.definition.keyField]
+                    }): definitionType ${
+                        metadata.definitionType
+                    } is not supported yet. Please open a ticket at https://github.com/Accenture/sfmc-devtools/issues/new/choose to request it`
+                );
+            }
+        }
+        return metadata;
+    }
+
+    /**
+     *
+     * @param {TYPE.MetadataTypeItem} metadata single metadata itme
+     * @param {string} metadataKey key of item we are looking at
+     * @param {boolean} hasError error flag from previous code
+     * @param {TYPE.MetadataTypeItemDiff[]} metadataToUpdate list of items to update
+     * @param {TYPE.MetadataTypeItem[]} metadataToCreate list of items to create
+     */
+    static createOrUpdate(metadata, metadataKey, hasError, metadataToUpdate, metadataToCreate) {
+        const normalizedKey = File.reverseFilterIllegalFilenames(
+            metadata[metadataKey][this.definition.keyField]
+        );
+        // Update if it already exists; Create it if not
+        if (Util.logger.level === 'debug' && metadata[metadataKey][this.definition.idField]) {
+            // TODO: re-evaluate in future releases if & when we managed to solve folder dependencies once and for all
+            // only used if resource is excluded from cache and we still want to update it
+            // needed e.g. to rewire lost folders
+            Util.logger.warn(
+                ' - Hotfix for non-cachable resource found in deploy folder. Trying update:'
+            );
+            Util.logger.warn(JSON.stringify(metadata[metadataKey]));
+            if (hasError) {
+                metadataToUpdate.push(null);
+            } else {
+                metadataToUpdate.push({
+                    before: {},
+                    after: metadata[metadataKey],
+                });
+            }
+        } else {
+            const cachedVersion = cache.getByKey(this.definition.type, normalizedKey);
+            if (cachedVersion && cachedVersion.status === 'Draft') {
+                // normal way of processing update files
+                if (!this.hasChanged(cachedVersion, metadata[metadataKey])) {
+                    hasError = true;
+                }
+
+                if (hasError) {
+                    // do this in case something went wrong during pre-deploy steps to ensure the total counter is correct
+                    metadataToUpdate.push(null);
+                } else {
+                    // add ObjectId to allow actual update
+                    metadata[metadataKey][this.definition.idField] =
+                        cachedVersion[this.definition.idField];
+                    // add ObjectId to allow actual update
+                    metadata[metadataKey].version = cachedVersion.version;
+
+                    metadataToUpdate.push({
+                        before: cachedVersion,
+                        after: metadata[metadataKey],
+                    });
+                }
+            } else {
+                if (hasError) {
+                    // do this in case something went wrong during pre-deploy steps to ensure the total counter is correct
+                    metadataToCreate.push(null);
+                } else {
+                    if (cachedVersion) {
+                        Util.logger.info(
+                            ` - Found ${this.definition.type} ${
+                                metadata[metadataKey][this.definition.nameField]
+                            } (${
+                                metadata[metadataKey][this.definition.keyField]
+                            }) on BU, but it is not in Draft status. Will create new version.`
+                        );
+                    }
+
+                    metadataToCreate.push(metadata[metadataKey]);
+                }
+            }
+        }
     }
 }