Releases
Version | Datum | Hinweise | Kompatibilität |
---|---|---|---|
1.1.0 | 13.02.2018 | Erste veröffentlichte Fassung | ab Nuclos 4.25.1 |
1.1.2 | 04.07.2019 | E-Mail Queue und verbesserte API | ab Nuclos 4.33.8 |
1.1.3 | 17.12.2021 | E-Mail-Templates | ab Nuclos 4.47.3 |
Überblick
Das Nuclet "E-Mail-Versand" bietet zusätzlichen Komfort bei der Nutzung der Nuclos Mail API (siehe http://api.nuclos.de/org/nuclos/api/provider/MailProvider.html#send(org.nuclos.api.mail.NuclosMail)).
Es ermöglicht insbesondere die Umleitung aller E-Mails zu Testzwecken oder auf Testumgebungen sowie die Archivierung aller versandten E-Mails inkl. Dateianhänge zu Dokumentationszwecken.
Außerdem gibt es einen Job zum Versenden und Empfangen von E-Mails. Damit werden E-Mail etwas später versendet, können nach Fehlern aber zurück gerollt werden, so dass sie nicht mehrfach versehndet werden.
Des weiteren gibt es auch die Möglichkeit, Vorlagen / Templates für E-Mails zu konfigurieren.
Version 1.1.3
Beschreibung von Version 1.1.3
Thema | Beschreibung |
---|---|
E-Mail Template | Das BO E-Mail-Template bietet die Möglichkeit, Vorlagen für E-Mails zu erstellen, die dann aus Regeln heraus versendet werden können. Ein Administrator hat damit die Möglichkeit, die von Nuclos versendeten E-Mails selbst zu gestalten und kurzfristig zu ändern. Die Templates bieten hierzu viele Möglichkeiten:
Komplexere E-Mail-Bestandteile, wie z.B. eine Tabelle mit allen Auftragspositionen, müssen durch eine Regel unterstützt werden. |
E-Mail Baustein | Können Bausteine definiert werden, die dann in den E-Mail-Templates zur Verfügung stehen. Möglich sind
Zur Sicherheit lassen sich Bausteine auf bestimmte BO's einschränken, wenn z.B. wenn der Baustein Bearbeiter für die BO's Rechnung und Auftrag existiert, aber nicht für das BO Artikel |
E-Mail Sprache | Definiert die zur Verfügung stehenden Sprachen |
Regelbausteine | Zur Erzeugung einer E-Mail aus einem E-Mail-Template muss eine Instanz einer Klasse mit übergeben werden, die das Interface Regelbausteine implementiert. |
Konfiguration von E-Mail-Templates von Version 1.1.3
Bereich E-Mail-Template | ||
---|---|---|
Name | Pflicht | Eindeutiger Name des Templates |
Basis-Nuclet | optional | Das Nuclet aus dem das Basis-BO kommen soll |
Basis-BO | optional | Das BO, auf das sich die E-Mail bezieht (z.B. Auftrag) |
Empfänger | optional | Ein Regelbaustein, der als Empfänger gekennzeichnet ist und für die die Methode getRecipient() in der Regelbaustein-Implementierung ein Ergebnis mit E-Mail-Adresse, Anrede und ggf. Sprache zurück liefert. |
Footer | optional | Ein als Footer gekennzeichneter Textbaustein |
Signatur | optional | Ein als Signatur gekennzeichneter Textbaustein |
Bereich Weitere Eigenschaften | ||
Sprache (Baustein) | optional | Die Sprache, in der die E-Mail versendet werden soll, definiert durch einen als Sprache gekennzeichneten Textbaustein |
Sprache (statisch) | optional | Die Sprache, in der die E-Mail versendet werden soll, direkt angegeben |
Html? | optional | E-Mail wird im Html-Format versendet (empfohlen) |
Nach Versand löschen? | optional | Sensible E-Mails (z.B. mit Passwort-Links o.ä.) können nach dem Versand automatisch aus dem E-Mail-Protokoll gelöscht werden |
Aktiv? | optional | Aktiviert oder deaktiviert den Versand der E-Mails |
Bereich Template-Test | ||
ID des Basis-BO | optional | Wenn ein Basis-BO angegeben ist, kann hier eine intid angegeben werden, für die die Vorschau erstellt und die Test-E-Mail versendet werden soll |
Sprache | optional | Hier kann die Sprache der Vorschau und der Test-E-Mail forciert werden |
Empfänger der Test-E-Mail | optional | Wenn kein Empfänger angegeben ist, wird die E-Mail an die im Nucletparameter Email Umleitung auf hinterlegte Adresse versendet |
Erzeuge Vorschau | Erzeugt eine Vorschau im Reiter Vorschau | |
Sendet Test-E-Mail | Für den finalen Test kann damit eine Test-E-Mail versendet werden | |
Reiter Konfiguration | ||
Betreff + Nachricht | optional | Hier können Betreff und Nachricht definiert werden. Dabei können verwendet werden
Für Betreff und Nachricht können alternative Texte in anderen Sprachen angegeben werden (siehe Reiter Betreffs(übersetzt) und Nachrichten (übersetzt)) |
Reiter Adressen | optional | Wenn ein Empfänger angegeben ist, wird die E-Mail an die dort ermittelte E-Mail-Adresse versendet. Zusätzlich oder alternativ können weitere Adressen hinzugefügt werden aus
|
Reiter Anhänge | optional | Hier können Anhänge für die E-Mail definiert werden, z.B.
Für jeden Anhang können alternative Anhänge in anderen sprachen definiert werden |
Weitere | ||
Reiter Beschreibung | optional | Hier können weitere Informationen für das Template hinterlegt werden |
Reiter E-Mails | Zeigt die E-Mails an, die bereits aus diesem Template generiert wurden |
Verwendung von E-Mail-Templates von Version 1.1.3
Initialisierung | |
---|---|
Nach dem Nucletimport muss einmal der Job Initialisiere Nuclet Emailversand ausgeführt werden | |
E-Mail-Template | |
Ein E-Mail-Template für eine Rechnung könnte z.B. so aussehen | |
Rechnungsformular als Anhang | |
Regelbaustein für einen Empfänger | |
Das Interface Regelbausteine | |
| |
Beispiel (Text) | |
public String getValue(final String name, final Modifiable<Long> bo, EMailTemplateSprache language, TemplateParameters parameters, RuleContext context) throws BusinessException { throw new BusinessException("Unbekannter Name für einen Regelbaustein: \"" + name + "\""); | |
Beispiel (Empfänger) | |
@Override if (ANSPRECHPARTNER.equals(name)) { throw new BusinessException("Unbekannter Name für einen Empfänger: \"" + name + "\""); | |
Beispiel (Verwendung in Regeln) | |
Einfachster Fall | EMailTemplate template = EMailUtils.getEMailTemplate(Konstanten.EMailTemplate.RECHNUNG); |
In einigen Fällen muss man womöglich noch zu zusätzliche Informationen an das Template weiter geben. Diese geschieht durch parameter. | EMailTemplate template = EMailUtils.getEMailTemplate(Konstanten.EMailTemplate.SERIENNUMMER); |
Version 1.1.2
Beschreibung von Version 1.1.2
Thema | Beschreibung |
---|---|
E-Mail Umleitung | Für den Testbetrieb kann die E-Mail Umleitung aktiviert werden. Dabei werden alle ausgehenden E-Mails auf eine festgelegte Adresse umgeleitet. In der E-Mail steht zusätzlich, an wen diese eigentlich gegangen wäre. |
E-Mail Protokoll | Alle zu versendenden und alle versendeten E-Mails werden im E-Mail-Protokoll (unter System) gespeichert. Das Speichern der versendeten Emails kann in den Nucletparametern ausgeschaltet werden. |
E-Mail Queue | Für den E-Mail-Versand gibt es zwei verschiedene Möglichkeiten: Sofort versenden Die E-Mail wird sofort versendet. Ist der Versand von einem Benutzer angestoßen (z.B. durch einen Statuswechsel, der einen E-Mail-Versand auslöst), so muss er warten, bis dieser Vorgang abgeschlossen ist, bevor er weiter arbeiten kann. Kommt es beim E-Mail-Versand zu einem Fehler, so wird die gesamte Aktion (z.B. Statuswechsel) des Benutzers rückgängig gemacht. Versand über Email Queue Die E-Mail wird erst im E-Mail-Protokoll als nicht versendete E-Mail gespeichert und erst durch einen regelmäßig laufenden Job versendet (Administration > Jobsteuerung > Versende Emails). Dieser muss natürlich aktiviert sein. Der Benutzer wird dadurch bei seiner Bearbeitung nicht unnötig lange aufgehalten und ein fehlerhafter E-Mail-Versand führt nicht zum Abbruch seiner Aktion. |
E-Mail Empfang | Der Job EMailEmpfang erzeugt für neue E-Mails auf dem in den IMAP-Systemparametern angegebenen Server einen Eintrag im E-Mail-Protokoll mit den Flags Versendet = false, Empfangen = true, Verarbeitet = false. |
Verwendung in Regeln | Die Klasse EmailVersand stellt zwei Methoden bereit |
Verwendung in der Regelprogrammierung von Version 1.1.2
Klasse EMailVersand | |
---|---|
static void sendMail(EMailContext context) | Versendet die im context definierte E-Mail |
static void sendMailNow(EMailContext context) | Versendet die im context definierte E-Mail sofort, unabhängig von den Einstellungen in den Nucletparametern |
Klasse EMailContext | |
void addRecipient(String address, int type) | Fügt einen Empfänger hinzu (type = To, CC oder BCC) |
void addRecipient(String address) | Fügt einen Empfänger hinzu (To) |
void addRecipients(List<String> lRecipients, int type) | Fügt eine Liste von Empfängern hinzu (type = To, CC oder BCC) |
void addRecipients(List<String> lRecipients) | Fügt eine Liste von Empfängern hinzu (To) |
void addAttachment(NuclosFile file) | Fügt einen Anhang hinzu |
void addAttachments(List<NuclosFile> lAttachments) | Fügt eine Liste von Anhängen hinzu |
void setReplyTo(String replyTo) | Definiert (vom Sender abweichende) Antwortadresse |
void setMessage(String message) | Definiert die E-Mail-Nachricht |
void setSubject(String subject) | Definiert den E-Mail-Betreff |
void setReference(String reference) | Definiert eine Referenz. Das kann z.B. eine Auftragsnummer sein. Die Referenz hat keinen Einfluss auf die E-Mail, hilft aber, E-Mails im Protokoll wiederzufinden, die zu einem bestimmten Auftrag gehören. |
void resetAttachments() | Leert die Liste der Anhänge |
void resetRecipients() | Leert die Liste der Empfänger |
Beispiel (E-Mail-Versand) | |
EMailContext context = new EMailContext(); | |
Beispiel (E-Mail-Empfang) | |
Query<EMailProtokoll> query = QueryProvider.create(EMailProtokoll.class); |
Integration von Version 1.1.2
Die Integration nach erfolgtem Nucletimport (siehe Nuclet Import) ist wie folgt vorzunehmen.
Schritt | Beschreibung | Screenshot | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
1 | Konfigurieren Sie die Nuclos Parameter für die Nutzung des MailProviders in Nuclos (unter Administration > Parameter):
Siehe dazu auch Email (SMTP/IMAP/Pop3). | |||||||||||||||||||||
2 | Konfigurieren Sie die Nuclet Parameter des Nuclets Emailversand (unter Konfiguration > Nuclet Management)
|
Version 1.1.0
Integration / Beschreibung von Version 1.1.0
Die Integration nach erfolgtem Nucletimport (siehe Nuclet Import) ist wie folgt vorzunehmen.
Schritt | Beschreibung |
---|---|
1 | Konfigurieren Sie die, für die Nutzung des MailProviders in Nuclos erforderlichen, SMTP-Systemparameter (mindestens SMTP Authentication, SMTP Username, SMTP Password, SMTP Server, SMTP Sender). Siehe dazu auch Email (SMTP/IMAP/Pop3). |
2 | Konfigurieren Sie die durch Nuclos zu setzende From/ReplyTo-Adresse im Nucletparameter "Email Sender Address". Aktivieren oder deaktivieren Sie desweiteren wie gewünscht die Umleitung in den Nucletparametern "Email Forwarding" ("Y" oder "N") und "Email Forwarding Address". Ist die Umleitung aktiviert, werden alle E-Mails, die über dieses Nuclet versandt werden, nicht an den eigentlichen Empfänger gesandt, sondern an die in "Email Forwarding Address" angegebene Adresse umgeleitet. Auf diese Weise lässt sich die Umsetzung automatisch zu versendender E-Mails in Ihrem eigenen Nuclet einfach testen, bzw. es lässt sich damit ein Testsystem leicht so konfigurieren, dass es keine E-Mails an Ihre Kunden oder Lieferanten sendet. |
3 | Passen Sie die zu verwendende Signatur in der Klasse EMailSignatur an Ihre Anforderungen an. |
4 | Nutzen Sie die neu gewonnene Funktionalität durch Versand von E-Mails z.B. an Ihre Kunden und Lieferanten. Dazu stehen Ihnen folgende Methoden zur Verfügung: EMailVersand.sendEmail(String sRecipient, String sSubject, String sMessage, NuclosFile attachment, String lang) EMailVersand.sendEmail(List<String> lRecipient, String sSubject, String sMessage, NuclosFile attachment, String lang) EMailVersand.sendEmail(List<String> lRecipient, List<String> lRecipientCC, List<String> lRecipientBCC, String sSubject, String sMessage, Über diese Methoden versandte E-Mails werden unter dem Menüpunkt System | E-Mail-Protokoll abgelegt und archiviert. Denken Sie daran, Ihre Anwender bei Bedarf für diesen Menüpunkt lesend zu berechtigen. Beispiel: String sSubject = "Ihre Rechnung"; String sMessage = "Im Anhang erhalten Sie Ihre Rechnung"; (new EMailVersand()).sendEmail(kunde.getEmailadresse(), sSubject, sMessage, pdfInvoice, "de"); |