From a55512b4df196e8af57a45272effc61e7be46d6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rn=20Berkefeld?= Date: Tue, 22 Nov 2022 21:14:12 +0100 Subject: [PATCH] #557: add support for transactionalEmail add/update/retrieve/delete --- README.md | 2 + docs/dist/documentation.md | 79 +++++++++++ lib/MetadataTypeDefinitions.js | 1 + lib/MetadataTypeInfo.js | 1 + lib/metadataTypes/TransactionalEmail.js | 101 +++++++++++++ .../TransactionalEmail.definition.js | 133 ++++++++++++++++++ 6 files changed, 317 insertions(+) create mode 100644 lib/metadataTypes/TransactionalEmail.js create mode 100644 lib/metadataTypes/definitions/TransactionalEmail.definition.js diff --git a/README.md b/README.md index 69e8a956d..2ae589fe9 100644 --- a/README.md +++ b/README.md @@ -408,6 +408,7 @@ The following metadata types are currently supported: | Mobile Connect Code | `mobileCode` | Yes | No | No | - | Mobile Connect Shore or Long Codes used for sending. First 50 per BU are retrieved | | Mobile Connect Keyword | `mobileKeyword` | Yes | Yes | Yes | - | Mobile Connect keywords configured within the Business UNit. First 50 per BU are retrieved | | Role | `role` | Yes | Yes | Yes (`bt`) | Yes | User Roles define groups that are used to grant users access to SFMC systems. | +| Transactional Email | `transactionalEmail` | Yes | Yes | Yes | Yes | Lets you send immediate Email messages via API events | | Transactional SMS | `transactionalSMS` | Yes | Yes | Yes | Yes | Lets you send immediate SMS messages via API events | | Triggered Send | `triggeredSendDefinition` | Yes | Yes | Yes (`bt`) | Yes | **DEPRECATED**: Sends emails via API or DataExtension Event. | | User | `accountUser` | Yes | in backlog | - | - | Users and Installed Packages including their assigned Roles, BUs and personal permissions | @@ -774,6 +775,7 @@ Currently supported types: | Data Extension Field | `dataExtensionField` | | Email Send Definition | `Email Send Definition` | | List | `list` | +| Transactional Email | `transactionalEmail` | | Transactional SMS | `transactionalSMS` | | Triggered Send | `triggeredSendDefinition` | diff --git a/docs/dist/documentation.md b/docs/dist/documentation.md index ba4eef611..e0fa50da8 100644 --- a/docs/dist/documentation.md +++ b/docs/dist/documentation.md @@ -101,6 +101,9 @@ Provides default functionality that can be overwritten by child metadata type cl
SetDefinition ⇐ MetadataType

SetDefinition MetadataType

+
TransactionalEmail ⇐ MetadataType
+

TransactionalEmail MetadataType

+
TransactionalSMS ⇐ MetadataType

TransactionalSMS MetadataType

@@ -4357,6 +4360,82 @@ Retrieves Metadata of schema set definitions for caching. **Kind**: static method of [SetDefinition](#SetDefinition) **Returns**: Promise.<TYPE.MetadataTypeMapObj> - Promise + + +## TransactionalEmail ⇐ [MetadataType](#MetadataType) +TransactionalEmail MetadataType + +**Kind**: global class +**Extends**: [MetadataType](#MetadataType) + +* [TransactionalEmail](#TransactionalEmail) ⇐ [MetadataType](#MetadataType) + * [.retrieve(retrieveDir, [_], [__], [___], [key])](#TransactionalEmail.retrieve) ⇒ Promise.<TYPE.MetadataTypeMapObj> + * [.retrieveForCache()](#TransactionalEmail.retrieveForCache) ⇒ Promise.<TYPE.MetadataTypeMapObj> + * [.update(metadata)](#TransactionalEmail.update) ⇒ Promise + * [.create(metadata)](#TransactionalEmail.create) ⇒ Promise + * [.deleteByKey(buObject, key)](#TransactionalEmail.deleteByKey) ⇒ Promise.<boolean> + + + +### TransactionalEmail.retrieve(retrieveDir, [_], [__], [___], [key]) ⇒ Promise.<TYPE.MetadataTypeMapObj> +Retrieves Metadata of Mobile Keywords +Endpoint /legacy/v1/beta/mobile/code/ return all Mobile Codes with all details. + +**Kind**: static method of [TransactionalEmail](#TransactionalEmail) +**Returns**: Promise.<TYPE.MetadataTypeMapObj> - Promise of metadata + +| Param | Type | Description | +| --- | --- | --- | +| retrieveDir | string | Directory where retrieved metadata directory will be saved | +| [_] | void | unused parameter | +| [__] | void | unused parameter | +| [___] | void | unused parameter | +| [key] | string | customer key of single item to retrieve | + + + +### TransactionalEmail.retrieveForCache() ⇒ Promise.<TYPE.MetadataTypeMapObj> +Retrieves event definition metadata for caching + +**Kind**: static method of [TransactionalEmail](#TransactionalEmail) +**Returns**: Promise.<TYPE.MetadataTypeMapObj> - Promise of metadata + + +### TransactionalEmail.update(metadata) ⇒ Promise +Updates a single item + +**Kind**: static method of [TransactionalEmail](#TransactionalEmail) +**Returns**: Promise - Promise + +| Param | Type | Description | +| --- | --- | --- | +| metadata | TYPE.MetadataTypeItem | a single item | + + + +### TransactionalEmail.create(metadata) ⇒ Promise +Creates a single item + +**Kind**: static method of [TransactionalEmail](#TransactionalEmail) +**Returns**: Promise - Promise + +| Param | Type | Description | +| --- | --- | --- | +| metadata | TYPE.MetadataTypeItem | a single item | + + + +### TransactionalEmail.deleteByKey(buObject, key) ⇒ Promise.<boolean> +Delete a metadata item from the specified business unit + +**Kind**: static method of [TransactionalEmail](#TransactionalEmail) +**Returns**: Promise.<boolean> - deletion success status + +| Param | Type | Description | +| --- | --- | --- | +| buObject | TYPE.BuObject | references credentials | +| key | string | Identifier of item | + ## TransactionalSMS ⇐ [MetadataType](#MetadataType) diff --git a/lib/MetadataTypeDefinitions.js b/lib/MetadataTypeDefinitions.js index 5e8a59144..bf274dc74 100644 --- a/lib/MetadataTypeDefinitions.js +++ b/lib/MetadataTypeDefinitions.js @@ -32,6 +32,7 @@ const MetadataTypeDefinitions = { role: require('./metadataTypes/definitions/Role.definition'), script: require('./metadataTypes/definitions/Script.definition'), setDefinition: require('./metadataTypes/definitions/SetDefinition.definition'), + transactionalEmail: require('./metadataTypes/definitions/TransactionalEmail.definition'), transactionalSMS: require('./metadataTypes/definitions/TransactionalSMS.definition'), triggeredSendDefinition: require('./metadataTypes/definitions/TriggeredSendDefinition.definition'), }; diff --git a/lib/MetadataTypeInfo.js b/lib/MetadataTypeInfo.js index c125295c8..065f9b4bd 100644 --- a/lib/MetadataTypeInfo.js +++ b/lib/MetadataTypeInfo.js @@ -32,6 +32,7 @@ const MetadataTypeInfo = { role: require('./metadataTypes/Role'), script: require('./metadataTypes/Script'), setDefinition: require('./metadataTypes/SetDefinition'), + transactionalEmail: require('./metadataTypes/TransactionalEmail'), transactionalSMS: require('./metadataTypes/TransactionalSMS'), triggeredSendDefinition: require('./metadataTypes/TriggeredSendDefinition'), }; diff --git a/lib/metadataTypes/TransactionalEmail.js b/lib/metadataTypes/TransactionalEmail.js new file mode 100644 index 000000000..1646a1b9a --- /dev/null +++ b/lib/metadataTypes/TransactionalEmail.js @@ -0,0 +1,101 @@ +'use strict'; + +const TYPE = require('../../types/mcdev.d'); +const MetadataType = require('./MetadataType'); +const Util = require('../util/util'); + +/** + * TransactionalEmail MetadataType + * + * @augments MetadataType + */ +class TransactionalEmail extends MetadataType { + /** + * Retrieves Metadata of Mobile Keywords + * Endpoint /legacy/v1/beta/mobile/code/ return all Mobile Codes 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.} Promise of metadata + */ + static async retrieve(retrieveDir, _, __, ___, key) { + let keyList; + const baseUri = '/messaging/v1/email/definitions/'; + if (!key) { + // Retrieve all + const response = this.definition.restPagination + ? await this.client.rest.getBulk(baseUri) + : await this.client.rest.get(baseUri); + keyList = Object.keys(this.parseResponseBody(response)); + } else { + // Retrieve single + keyList = [key]; + } + + // get all sms with additional details not given by the list endpoint + const details = keyList + ? await Promise.all(keyList.map((key) => this.client.rest.get(baseUri + (key || '')))) + : []; + + const parsed = this.parseResponseBody({ definitions: details }); + + // * retrieveDir is mandatory in this method as it is not used for caching (there is a seperate method for that) + const savedMetadata = await this.saveResults(parsed, retrieveDir, null, null); + Util.logger.info( + `Downloaded: ${this.definition.type} (${Object.keys(savedMetadata).length})` + ); + + return { metadata: savedMetadata, type: this.definition.type }; + } + + /** + * Retrieves event definition metadata for caching + * + * @returns {Promise.} Promise of metadata + */ + static retrieveForCache() { + return super.retrieveREST(null, '/messaging/v1/email/definitions/'); + } + /** + * Updates a single item + * + * @param {TYPE.MetadataTypeItem} metadata a single item + * @returns {Promise} Promise + */ + static update(metadata) { + return super.updateREST(metadata, '/messaging/v1/email/definitions'); + } + + /** + * Creates a single item + * + * @param {TYPE.MetadataTypeItem} metadata a single item + * @returns {Promise} Promise + */ + static create(metadata) { + return super.createREST(metadata, '/messaging/v1/email/definitions'); + } + /** + * Delete a metadata item from the specified business unit + * + * @param {TYPE.BuObject} buObject references credentials + * @param {string} key Identifier of item + * @returns {Promise.} deletion success status + */ + static deleteByKey(buObject, key) { + return super.deleteByKeyREST( + buObject, + '/messaging/v1/email/definitions/' + key, + key, + false + ); + } +} + +// Assign definition to static attributes +TransactionalEmail.definition = require('../MetadataTypeDefinitions').transactionalEmail; + +module.exports = TransactionalEmail; diff --git a/lib/metadataTypes/definitions/TransactionalEmail.definition.js b/lib/metadataTypes/definitions/TransactionalEmail.definition.js new file mode 100644 index 000000000..8ee2799dd --- /dev/null +++ b/lib/metadataTypes/definitions/TransactionalEmail.definition.js @@ -0,0 +1,133 @@ +module.exports = { + bodyIteratorField: 'definitions', + dependencies: [], + hasExtended: false, + idField: 'definitionId', + keyField: 'definitionKey', + nameField: 'name', + createdDateField: 'createdDate', + createdNameField: null, + lastmodDateField: 'modifiedDate', + lastmodNameField: null, + restPagination: false, + type: 'transactionalEmail', + typeDescription: 'Lets you send immediate Email messages via API events', + typeRetrieveByDefault: true, + typeName: 'Transactional Email', + fields: { + name: { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + definitionKey: { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + description: { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + requestId: { + isCreateable: false, + isUpdateable: false, + retrieving: false, + template: false, + }, + definitionId: { + isCreateable: true, + isUpdateable: true, + retrieving: false, + template: false, + }, + status: { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: false, + }, + createdDate: { + isCreateable: false, + isUpdateable: false, + retrieving: true, + template: false, + }, + modifiedDate: { + isCreateable: false, + isUpdateable: false, + retrieving: true, + template: false, + }, + classification: { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + 'content.customerKey': { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + 'subscriptions.dataExtension': { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + 'subscriptions.list': { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + 'subscriptions.autoAddSubscriber': { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + 'subscriptions.updateSubscriber': { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + 'options.trackLinks': { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + 'options.cc': { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + 'options.bcc': { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + journey: { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + 'journey.interactionKey': { + isCreateable: true, + isUpdateable: true, + retrieving: true, + template: true, + }, + }, +};