# DigiWF E-Mail-Integration

Die DigiWF E-Mail-Integration ermöglicht es Benutzern, E-Mails über die DigiWF-Plattform zu senden. Prozessentwickler können mit dieser Integration E-Mail-Kommunikation in ihre BPMN-Prozesse integrieren.

Die E-Mail-Integration ermöglicht sowohl das Senden einfacher E-Mails als auch von E-Mails mit Dateianhängen. Die Dateianhänge können aus einem S3 Bucket geladen werden. Zudem ist es möglich den E-Mail Body durch Templates zu generieren und somit ein Logo und einen Link in der E-Mail anzeigen zu lassen.

# Verwendung

Die E-Mail-Integration ermöglicht es den Benutzern von DigiWF, E-Mails aus einem Prozess heraus zu senden. Hierbei können sowohl einfache E-Mails als auch E-Mails mit Dateianhängen versendet werden. Die Dateianhänge werden hierbei aus einem S3 Bucket geladen. Zusätzlich kann direkt im Prozess auf untenstehende Fehler reagiert werden. Der Body der E-Mail kann mit reinem Text oder durch ein Template mit einem Logo und einem Link befüllt werden.

# E-Mail senden

Um eine E-Mail mit der E-Mail-Integration zu senden, muss ein E-Mail-Event an das Kafka-Topic der E-Mail-Integration gesendet werden. Den Namen des Topics können Sie in der Konfiguration der E-Mail-Integration unter spring.cloud.stream.bindings.functionRouter-in-0.destination finden. Zusätzlich muss im E-Mail-Event der Header type auf sendMailFromEventBus gesetzt werden.

Standardmäßig heißen die Topics dwf-email-${DIGIWF_ENV}, wobei DIGIWF_ENV die aktuelle Umgebung ist.

Nachfolgend ist ein Beispiel-Event für eine E-Mail aufgeführt:

{
  "receivers": "receivers@example.com",
  "receiversCc": "receivers-on-cc@example.com",
  "receiversBcc": "receivers-on-bcc@example.com",
  "subject": "My important email",
  "body": "Some text I want to send",
  "replyTo": "replyto@example.com",
  "attachments": []
}

1
2
3
4
5
6
7
8
9

# E-Mail mit Dateianhang senden

Sie können Dateien aus einem S3 Bucket an die E-Mails anhängen, die Sie senden. Dafür müssen Sie vorab presigned URLs für die Dateianhänge mit der S3-Integration erstellen und diese unter attachments dem Mail-Event mitgeben. Die E-Mail-Integration lädt die Dateien herunter und fügt sie der E-Mail vor dem Versenden als Anhang hinzu.

Hinweis: Die E-Mail-Integration unterstützt nur presigned URLs, die mit der GET-Aktion erstellt wurden. Alle anderen Dateiaktionen funktionieren nicht und führen zu einem Fehler.

Nachfolgend ist ein Beispiel-Event für eine E-Mail mit einem Dateianhang aufgeführt:

{
  "receivers": "receivers@example.com",
  "receiversCc": "receivers-on-cc@example.com",
  "receiversBcc": "receivers-on-bcc@example.com",
  "subject": "My important email",
  "body": "Some text I want to send",
  "replyTo": "replyto@example.com",
  "attachments": [
    {
      "url": "http://localhost:9000/s3-bucket/some/path/to/file/image.png",
      "path": "path/to/file/in/s3",
      "action": "GET"
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Email mit Logo und Link senden

Das Senden einer Email mit Logo und Link funktioniert wie das oben beschriebene Senden einer E-Mail. Der Header type im Email Event muss jedoch auf sendMailWithLogoAndLink gesetzt werden.

Nachfolgend ist ein Beispiel Event für eine Email mit Template aufgeführt:

{
  "receivers": "receivers@example.com",
  "receiversCc": "receivers-on-cc@example.com",
  "receiversBcc": "receivers-on-bcc@example.com",
  "subject": "My important email",
  "text": "Some text I want to send",
  "replyTo": "replyto@example.com",
  "attachments": [],
  "template": "mail-template.ftl",
  "bottomBody": "Some greeting",
  "buttonText": "Some button text",
  "buttonLink": "example.com"
}

1
2
3
4
5
6
7
8
9
10
11
12
13

buttonText und buttonLink sind optional, müssen jedoch immer zusammen angegeben werden. Anhänge können wie oben beschrieben übergeben werden.

# Fehlerbehandlung

Bei der Fehlerbehandlung wird zwischen BPMN-Errors und Incident-Errors unterschieden. BPMN-Errors können im Prozess behandelt werden, während Incident-Errors nicht im Prozess behandelt werden können und einen Incident erzeugen.

Nachfolgend sind die BPMN-Errors aufgeführt, die von der E-Mail-Integration geworfen werden können:

# BPMN-Error

Error Code	Error Message	Beschreibung	Handlungsempfehlung
`VALIDATION_ERROR`	Fehlermeldung der auftretenden `ValidationException`	Die übergebenen E-Mail-Daten sind nicht valide.	Korrigieren Sie die Daten und versuchen es erneut
`MESSAGING_EXCEPTION`	Fehlermeldung der auftretenden `MessagingException`	Die E-Mail konnte mit den übergebenen Daten nicht erstellt werden.	Überprüfen Sie, ob die Daten valide sind und versuchen es erneut.
`MAIL_SENDING_FAILED`	Fehlermeldung der auftretenden `MailException`	Die E-Mail konnte nicht versand werden. Es kann sein, dass die E-Mail-Adressen nicht valide sind oder ein technischer Fehler aufgetreten ist	Analysieren Sie die Fehlermeldung, korrigieren invalide E-Mail-Adressen und versuchen es erneut.
`LOAD_FILE_FAILED`	An attachment could not be loaded from presigned url: attachment	Die Datei konnte nicht geladen werden	Stellen Sie sicher, dass die presigned URL nicht abgelaufen ist. Stellen Sie sicher, dass die Datei im S3 Bucket vorhanden ist
`FILE_TYPE_NOT_SUPPORTED`	File type not supported of the attachment: attachment	Der Dateityp der Datei wird nicht unterstützt oder wurde nicht erkannt	Die Datei kann nicht als E-Mail-Anhang versendet werden.
`LOAD_TEMPLATE_FAILED`	The template template could not be loaded	Das Template konnte nicht geladen werden.	Überprüfen Sie ob der Templatename richtig ist und versuchen Sie es erneut.
`TEMPLATE_MERGING_FAILED`	Fehlermeldung der auftretenden `TemplateException`	Das Template konnte nicht mit den übergebenen Daten befüllt werden.	Überprüfen Sie die übergebenen Daten und versuchen Sie es erneut.

# Konfiguration

Allgemeine Konfigurationen für DigiWF-Integrationen sind unter Eigene Integration erstellen beschrieben.

Die Konfiguration der CoSys Integration ist in der README.md (opens new window) beschrieben.

← DigiWF Cosys Integration DigiWF S3 Integration →