Journey.js

'use strict';

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');

/**
 * Journey 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 Journey extends MetadataType {
    /**
     * Retrieves Metadata of Journey
     *
     * @param {string} retrieveDir Directory where retrieved metadata directory will be saved
     * @param {void} [_] unused parameter
     * @param {void} [__] unused parameter
     * @param {string} [key] customer key of single item to retrieve
     * @returns {Promise.<TYPE.MetadataTypeMapObj>} Promise
     */
    static async retrieve(retrieveDir, _, __, key) {
        const extrasDefault = 'activities';
        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 */
        }

        try {
            const uri = `/interaction/v1/interactions/`;
            if (singleKey || !retrieveDir) {
                // full details for retrieve, only base data for caching; reduces caching time from minutes to seconds
                const extras = retrieveDir && singleKey ? extrasDefault : '';

                // caching or single retrieve
                return await super.retrieveREST(
                    retrieveDir,
                    `${uri}${singleKey}?extras=${extras}`,
                    null,
                    key
                );
            } else {
                // retrieve all
                const results = this.definition.restPagination
                    ? await this.client.rest.getBulk(uri, this.definition.restPageSize || 500)
                    : await this.client.rest.get(uri);
                // const results = this.parseResponseBody(response);
                if (results.items?.length) {
                    // empty results will come back without "items" defined
                    Util.logger.info(
                        Util.getGrayMsg(
                            ` - ${results.items?.length} ${this.definition.type}s found. Retrieving details...`
                        )
                    );
                }
                // full details for retrieve
                const extras = extrasDefault;

                const details = results.items
                    ? await Promise.all(
                          results.items.map(async (a) => {
                              try {
                                  return await this.client.rest.get(
                                      `${uri}key:${a[this.definition.keyField]}?extras=${extras}` +
                                          `&versionNumber=${a.version}`
                                  );
                              } catch (ex) {
                                  // if we do get here, we should log the error and continue instead of failing to download all automations
                                  Util.logger.warn(
                                      ` ☇ skipping ${this.definition.type} ${
                                          a[this.definition.nameField]
                                      } (${a[this.definition.keyField]}): ${ex.message} (${
                                          ex.code
                                      })${
                                          ex.endpoint
                                              ? Util.getGrayMsg(
                                                    ' - ' +
                                                        ex.endpoint.split(
                                                            'rest.marketingcloudapis.com'
                                                        )[1]
                                                )
                                              : ''
                                      }`
                                  );
                                  return null;
                              }
                          })
                      )
                    : [];
                const parsed = this.parseResponseBody({ items: details.filter(Boolean) });

                // * 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})` +
                        Util.getKeysString(key)
                );
                return {
                    metadata: parsed,
                    type: this.definition.type,
                };
            }
        } catch (ex) {
            // if the interaction does not exist, the API returns an error code which would otherwise bring execution to a hold
            if (
                [
                    'Journey 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 Journeys 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/key:' + metadata.key,
            'put'
        );
    }

    /**
     * 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 Journey's {@link Journey.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 item
     * @returns {TYPE.MetadataTypeItem} Array with one metadata object
     */
    static postRetrieveTasks(metadata) {
        // folder
        super.setFolderPath(metadata);

        switch (metadata.definitionType) {
            case 'Multistep': {
                // Multi-Step Journey
                // ~~~ TRIGGERS ~~~~
                // event / 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(
                            'event',
                            metadata.triggers[0].metaData.eventDefinitionKey,
                            'eventDefinitionKey',
                            'id'
                        );
                        if (metadata.triggers[0].metaData.eventDefinitionId !== edId) {
                            throw new Error(
                                `eventDefinitionId not matching Id found on event 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 ~~~~

                this._postRetrieveTasks_activities(metadata);

                // 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 ~~~~
                // event && 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(
                            'event',
                            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 event 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
                        ) {
                            const activity = metadata.activities[0];
                            // trigger found; there can only be one entry in this array
                            try {
                                const tEmailId = cache.searchForField(
                                    'transactionalEmail',
                                    activity.configurationArguments?.triggeredSendKey,
                                    'definitionKey',
                                    'definitionId'
                                );
                                if (tEmailId != activity.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 (
                                    activity.metaData?.highThroughput?.definitionKey &&
                                    activity.metaData?.highThroughput?.definitionKey !=
                                        activity.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;
    }
    /**
     * helper for {@link Journey.postRetrieveTasks}
     *
     * @private
     * @param {TYPE.MetadataTypeItem} metadata a single item
     */
    static _postRetrieveTasks_activities(metadata) {
        for (const activity of metadata.activities) {
            switch (activity.type) {
                case 'EMAILV2': {
                    // triggeredSend + email+asset
                    // TODO email / asset
                    try {
                        if (activity.configurationArguments?.triggeredSendKey) {
                            // triggeredSendKey is not always set but triggeredSendId is
                            cache.searchForField(
                                'triggeredSend',
                                activity.configurationArguments.triggeredSendKey,
                                'CustomerKey',
                                'CustomerKey'
                            );
                            delete activity.configurationArguments.triggeredSendId;
                        } else if (activity.configurationArguments?.triggeredSendId) {
                            // triggeredSendKey is not always set but triggeredSendId is
                            activity.configurationArguments.triggeredSendKey = cache.searchForField(
                                'triggeredSend',
                                activity.configurationArguments.triggeredSendId,
                                'ObjectID',
                                'CustomerKey'
                            );
                            delete activity.configurationArguments.triggeredSendId;
                        }
                    } catch (ex) {
                        Util.logger.warn(
                            ` - ${this.definition.type} '${metadata[this.definition.nameField]}' (${
                                metadata[this.definition.keyField]
                            }) activity-key=${activity.key}: ${ex.message}`
                        );
                    }

                    break;
                }
                case 'SMSSYNC': {
                    // mobileMessage
                    try {
                        if (activity.configurationArguments?.messageId) {
                            activity.configurationArguments.c__mobileMessage_id =
                                cache.searchForField(
                                    'mobileMessage',
                                    activity.configurationArguments.messageId,
                                    'id',
                                    'id'
                                );
                            delete activity.configurationArguments.messageId;
                        }
                    } catch (ex) {
                        Util.logger.warn(
                            ` - ${this.definition.type} '${metadata[this.definition.nameField]}' (${
                                metadata[this.definition.keyField]
                            }) activity-key=${activity.key}: ${ex.message}`
                        );
                    }
                    try {
                        // mobileKeyword
                        if (activity.configurationArguments?.keywordId) {
                            activity.configurationArguments.r__mobileKeyword_codeKeyword =
                                cache.searchForField(
                                    'mobileKeyword',
                                    activity.configurationArguments.keywordId,
                                    'id',
                                    'c__codeKeyword'
                                );
                            delete activity.configurationArguments.keywordId;
                        }
                    } catch (ex) {
                        Util.logger.warn(
                            ` - ${this.definition.type} '${metadata[this.definition.nameField]}' (${
                                metadata[this.definition.keyField]
                            }) activity-key=${activity.key}: ${ex.message}`
                        );
                    }
                    try {
                        if (activity.configurationArguments?.nextKeywordId) {
                            activity.configurationArguments.c__next_mobileKeyword =
                                cache.searchForField(
                                    'mobileKeyword',
                                    activity.configurationArguments.nextKeywordId,
                                    'id',
                                    'keyword'
                                );
                            delete activity.configurationArguments.nextKeywordId;
                        }
                    } catch (ex) {
                        Util.logger.warn(
                            ` - ${this.definition.type} '${metadata[this.definition.nameField]}' (${
                                metadata[this.definition.keyField]
                            }) activity-key=${activity.key}: ${ex.message}`
                        );
                    }
                    try {
                        // mobileCode
                        if (activity.configurationArguments?.codeId) {
                            activity.configurationArguments.c__mobileCode = cache.searchForField(
                                'mobileCode',
                                activity.configurationArguments.codeId,
                                'id',
                                'code'
                            );
                            delete activity.configurationArguments.codeId;
                        }
                    } catch (ex) {
                        Util.logger.warn(
                            ` - ${this.definition.type} '${metadata[this.definition.nameField]}' (${
                                metadata[this.definition.keyField]
                            }) activity-key=${activity.key}: ${ex.message}`
                        );
                    }

                    try {
                        // asset-asset: jsonmessage
                        if (activity.configurationArguments?.assetId) {
                            activity.configurationArguments.r__assetMessage_Name_readOnly =
                                cache.searchForField(
                                    'asset',
                                    activity.configurationArguments.assetId,
                                    'id',
                                    'name'
                                );

                            activity.configurationArguments.r__assetMessage_Key =
                                cache.searchForField(
                                    'asset',
                                    activity.configurationArguments.assetId,
                                    'id',
                                    'customerKey'
                                );
                            delete activity.configurationArguments.assetId;
                        }
                    } catch (ex) {
                        Util.logger.warn(
                            ` - ${this.definition.type} '${metadata[this.definition.nameField]}' (${
                                metadata[this.definition.keyField]
                            }) activity-key=${activity.key}: ${ex.message}`
                        );
                    }

                    // applicationExtensionId always equal "00000000-0000-0000-0000-000000000000"
                    delete activity.configurationArguments.applicationExtensionId;

                    break;
                }
            }
            // TODO: Filters / activities[].type === 'MULTICRITERIADECISION'
            // - activities[].arguments.filterResult
            // - activities[].arguments.configurationArguments.criteria

            // TODO: wait activity / activities[].type === 'WAIT'
        }
    }

    /**
     * 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 ~~~~

                // event / 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(
                        'event',
                        metadata.triggers[0].metaData.eventDefinitionKey,
                        'eventDefinitionKey',
                        'id'
                    );
                }

                // transactionalEmail / definitionType==='Transactional' && channel==='email' && triggers[].type === 'transactional-api'

                // ~~~ ACTIVITIES ~~~~

                this._preDeployTasks_activities(metadata);

                // 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 ~~~~
                // event && 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(
                            'event',
                            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;
    }

    /**
     * helper for {@link Journey.preDeployTasks}
     *
     * @private
     * @param {TYPE.MetadataTypeItem} metadata a single item
     */
    static _preDeployTasks_activities(metadata) {
        for (const activity of metadata.activities) {
            switch (activity.type) {
                case 'EMAILV2': {
                    // triggeredSend + email+asset
                    // TODO email / asset
                    if (activity.configurationArguments?.triggeredSendKey) {
                        // triggeredSendKey is not always set but triggeredSendId is
                        activity.configurationArguments.triggeredSendId = cache.searchForField(
                            'triggeredSend',
                            activity.configurationArguments.triggeredSendKey,
                            'CustomerKey',
                            'ObjectID'
                        );
                    }
                    break;
                }
                case 'SMSSYNC': {
                    // mobileMessage
                    if (activity.configurationArguments?.c__mobileMessage_id) {
                        activity.configurationArguments.messageId = cache.searchForField(
                            'mobileMessage',
                            activity.configurationArguments.c__mobileMessage_id,
                            'id',
                            'id'
                        );
                        delete activity.configurationArguments.c__mobileMessage_id;
                    }
                    // mobileKeyword
                    if (activity.configurationArguments?.r__mobileKeyword_codeKeyword) {
                        activity.configurationArguments.keywordId = cache.searchForField(
                            'mobileKeyword',
                            activity.r__mobileKeyword_codeKeyword,
                            'c__codeKeyword',
                            'id'
                        );
                        delete activity.configurationArguments.r__mobileKeyword_codeKeyword;
                    }
                    if (activity.configurationArguments?.c__next_mobileKeyword) {
                        activity.configurationArguments.nextKeywordId = cache.searchForField(
                            'mobileKeyword',
                            activity.configurationArguments.c__next_mobileKeyword,
                            'keyword',
                            'id'
                        );
                        delete activity.configurationArguments.c__next_mobileKeyword;
                    }
                    // mobileCode
                    if (activity.configurationArguments?.c__mobileCode) {
                        activity.configurationArguments.codeId = cache.searchForField(
                            'mobileCode',
                            activity.configurationArguments.c__mobileCode,
                            'code',
                            'id'
                        );
                        delete activity.configurationArguments.c__mobileCode;
                    }
                    // asset-asset: jsonmessage
                    if (activity.configurationArguments?.r__assetMessage_Key) {
                        activity.configurationArguments.assetId = cache.searchForField(
                            'asset',
                            activity.configurationArguments.r__assetMessage_Key,
                            'customerKey',
                            'id'
                        );
                        delete activity.configurationArguments.r__assetMessage_Key;
                        delete activity.configurationArguments.r__assetMessage_Name_readOnly;
                    }

                    // applicationExtensionId always equal "00000000-0000-0000-0000-000000000000"
                    activity.configurationArguments.applicationExtensionId =
                        '00000000-0000-0000-0000-000000000000';
                    break;
                }
            }
        }
    }

    /**
     * helper for {@link MetadataType.upsert}
     *
     * @param {TYPE.MetadataTypeMap} metadataMap list of metadata
     * @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
     * @returns {'create' | 'update' | 'skip'} action to take
     */
    static createOrUpdate(metadataMap, metadataKey, hasError, metadataToUpdate, metadataToCreate) {
        const action = super.createOrUpdate(
            metadataMap,
            metadataKey,
            hasError,
            metadataToUpdate,
            metadataToCreate
        );
        if (action === 'update') {
            const normalizedKey = File.reverseFilterIllegalFilenames(
                metadataMap[metadataKey][this.definition.keyField]
            );
            const cachedVersion = cache.getByKey(this.definition.type, normalizedKey);
            if (cachedVersion) {
                if (cachedVersion.status === 'Draft') {
                    // add version to ensure we update the correct one
                    metadataMap[metadataKey].version = cachedVersion.version;
                } else {
                    // remove last entry from metadataToUpdate again
                    metadataToUpdate.pop();
                    Util.logger.info(
                        ` - Found ${this.definition.type} ${
                            metadataMap[metadataKey][this.definition.nameField]
                        } (${
                            metadataMap[metadataKey][this.definition.keyField]
                        }) on BU, but it is not in Draft status. Will create new version.`
                    );
                    metadataToCreate.push(metadataMap[metadataKey]);
                    return 'create';
                }
            }
        }
        return action;
    }
}

// Assign definition to static attributes
Journey.definition = require('../MetadataTypeDefinitions').journey;

module.exports = Journey;