Releases

VersionDatumHinweiseKompatibilität
1.1.013.02.2018Erste veröffentlichte Fassungab Nuclos 4.25.1
1.1.204.07.2019E-Mail Queue und verbesserte APIab Nuclos 4.33.8
1.1.317.12.2021E-Mail-Templatesab 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 versendet 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

ThemaBeschreibung
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:

  • Der Zugriff auf beliebig weit referenzierte Attribute aus einem frei wählbaren Basis-BO (z.B Auftrag), ähnlich wie bei Nuclos-Formularen
  • Verschiedene Quellen von Adressen (Attribut, Nucletparameter, Benutzer, Benutzergruppe, ...)
  • Verschiedene Quellen von Anhängen (Datei, Formular, ...)
  • Verschiedene Sprachen von Betreff, Nachricht und Anhang
  • Textbausteine
  • E-Mail-Empfänger, die E-Mail-Adresse, Anrede und Sprache der E-Mail bestimmen
  • Standardisierte und konfigurierbare Footer und Signaturen
  • Vorschau und Test des Templates

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

Textbaustein

  • Reine (ggf. mehrsprachige) Standard-Textbausteine (AGB, Versandinfos, Signatur, ...)
  • Bausteine, die einen Footer oder eine Signatur bereitstellen

Regelbaustein

  • Komplexe Bausteine, die eine Regelunterstützung benötigen (z.B. Tabelle mit Auftragspositionen)
  • Bausteine, die eine oder mehrere E-Mail-Adressen ermitteln (z.B. für Subscribe-Funktionalitäten)
  • Bausteine, die eine Sprache definieren

Empfänger

  • Bausteine, die den E-Mail-Empfänger (Adresse, Anrede, Sprache) definieren

Anhang

  • Bausteine, die einen Anhang generieren

Versandbedingung

  • Bausteine, die entscheiden, ob eine E-Mail versendet werden soll oder nicht

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 SpracheDefiniert 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.

Das Nuclet bringt eine Implementierung mit, die einige Beispiele enthält. Wenn Sie eigene Regelbausteine benötigen, sollten Sie sich eine eigene Implementierung in Ihrem Nuclet anlegen, damit diese nicht überschrieben wird, wenn das E-Mail-Nuclet mal aktualisiert wird.

In der Methode EMailUtils.getRegelBausteine() dann einfach diese Implementierung erzeugen.

Konfiguration von E-Mail-Templates von Version 1.1.3

Bereich E-Mail-Template
Name Pflicht Eindeutiger Name des Templates
Basis-NucletoptionalDas Nuclet aus dem das Basis-BO kommen soll
Basis-BOoptionalDas BO, auf das sich die E-Mail bezieht (z.B. Auftrag)
Empfänger optionalEin 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
Empfänger-BOoptionalWenn der Emfpänger z.B. allgemein als Regelbaustein für das BO Mitarbeiter implementiert wurde, kann hier einfach Mitarbeiter angegeben werden
Empfänger-RolleoptionalWenn der Mitarbeiter in verschiedenen Rollen im Basis-BO vorkommt, kann diese hier spezifiziert werden, z.B. Ansprechpartner  oder Kundenberater  
Footer optionalEin als Footer  gekennzeichneter Textbaustein
Signatur optionalEin als Signatur gekennzeichneter Textbaustein
Bereich Weitere Eigenschaften
Sprache (Baustein)optionalDie Sprache, in der die E-Mail versendet werden soll, definiert durch einen als Sprache  gekennzeichneten Textbaustein
Sprache (statisch)optionalDie Sprache, in der die E-Mail versendet werden soll, direkt angegeben
Html?optionalE-Mail wird im Html-Format versendet (empfohlen)
Nach Versand löschen?optionalSensible E-Mails (z.B. mit Passwort-Links o.ä.) können nach dem Versand automatisch aus dem E-Mail-Protokoll gelöscht werden
Aktiv?optionalAktiviert oder deaktiviert den Versand der E-Mails
VersandbedingungoptionalHier kann Regelbaustein ausgewählt werden, der eine Versandbedingung ist, die entscheidet, ob die E-Mail versendet werden soll
Bereich Template-Test
ID des Basis-BOoptionalWenn 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
SpracheoptionalHier kann die Sprache der Vorschau und der Test-E-Mail forciert werden
Empfänger der Test-E-MailoptionalWenn 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 + Nachrichtoptional

Hier können Betreff und Nachricht definiert werden. Dabei können verwendet werden

  • Beliebiger Text
  • Datenfelder aus dem Basis-BO in der Form z.B. #{Auftragsnr} oder #{Kunde.Kundengruppe.Name}. Verfügbare Datenfelder sind als Hilfe im Reiter Verfügbare Datenfelder  zu finden
  • Textbausteine, die entweder nicht auf ein BO eingeschränkt (##{AGB}) sind oder für das Basis-BO erlaubt sind (##{Ansprechpartner}), als Hilfe zu finden im Reiter Verfügbare Textbausteine 

Für Betreff und Nachricht können alternative Texte in anderen Sprachen angegeben werden (siehe Reiter Betreffs(übersetzt) und Nachrichten (übersetzt))

Reiter Adressenoptional

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

  • direkt angegebenen Adressen (z.B. CC info@firma.de)
  • einem Nuclos Benutzer
  • allen Nuclos Benutzern einer bestimmten Benutzergruppe
  • einem Attribut des Basis-BO (oder weiter referenzierten Attributen, z.B. die E-Mail-Adresse des Zuständigen des Auftrages)
  • einem Nuclet Parameter
  • einem Baustein, der als E-Mail-Adresse gekennzeichnet ist
Reiter Anhängeoptional

Hier können Anhänge für die E-Mail definiert werden, z.B.

  • ein Report oder Formular 
  • eine im Template hinterlegte Datei
  • ein Baustein, der als Anhang gekennzeichnet ist und für den die Methode getAttachments() eine Liste von Dateien zurück liefert

Für jeden Anhang können alternative Anhänge in anderen sprachen definiert werden

Reiter Statuswechseloptional

Hier kann konfiguriert werden, bei welchem Statuswechsel die E-Mail versendet werden soll. Eine entsprechende Regel muss dazu allerdings für jeden möglichen Statuswechsel des betroffenen Statusmodells zugeordnet werden. Hilfreich für diese Regel ist dann die Methode

EMailUtils.sendAllAcceptedEMails(StateChangeContext context, RegelBausteine regelBausteine)

Weitere
Reiter BeschreibungoptionalHier 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

Der Job legt u.a. einige Standard-E-Mail-Bausteine an, so dass Sie gleich ein Template bauen können.

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


TextString getValue(String name, Modifiable<Long> bo, EMailTemplateSprache language, TemplateParameters parameters, RuleContext context)
AnhängeList<NuclosFile> getAttachments(String name, Modifiable<Long> bo, EMailTemplateSprache language, TemplateParameters parameters)
EmpfängerTemplateRecipient getRecipient(String name, Modifiable<Long> bo, EMailTemplateSprache language, TemplateParameters parameters)
SpracheNuclosLocale getLocale(EMailTemplateSprache langugage)
Versandbedingung

boolean isSendMail(EMailTemplateBaustein versandbedingung, Modifiable<Long> bo)

Adresse des WebclientsString getWebclientAddress()
AnredegetSalutation(User user, EMailTemplateSprache sprache)
Beispiel (Text)

public String getValue(final String name, final Modifiable<Long> bo, EMailTemplateSprache language, TemplateParameters parameters, RuleContext context) throws BusinessException {
if (SIGNATUR.equals(name)) {
return EMailHelper.getSignature();
} else if (RECHNUNGSPOSITIONEN.equals(name)) {
return EMailHelper.getRechnungspositionen(bo, parameters, name);
}
    throw new BusinessException("Unbekannter Name für einen Regelbaustein: \"" + name + "\"");
}
Beispiel (Empfänger)

@Override
public TemplateRecipient getRecipient(String name, Modifiable<Long> bo, EMailTemplateSprache language, TemplateParameters parameters) throws BusinessException {
   if (ANSPRECHPARTNER.equals(name)) {
return EMailHelper.getTemplateRecipient(EMailHelper.getAnsprechpartner(bo, parameters, name));
} else if (BEARBEITER.equals(name)) {
return EMailHelper.getTemplateRecipient(EMailHelper.getBearbeiter(bo, 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);
if (template.getAktiv()) {
EMailVersand.sendMail(new EMailContext(template, EMailUtils.getRegelBausteine(), rechnung, context));
}
Erzeugung von Templates (Klasse EMailTemplateKonfiguration)

Die Klasse EMailTemplateKonfiguration stellt Datenstrukturen und Methoden bereit, um Sprachen, Bausteine und Templates durch Regeln zu erstellen.

Dies kann besonders bei der Nucletentwicklung hilfreich sein, um solche Objekte auf anderen Instanzen neu zu erstellen.


Verfügbare Datenstrukturen
  • Sprache
  • Baustein
  • Template
  • Restriction
  • Adresse
  • Statuswechsel
  • Anhang
  • BausteinTranslation
  • AnhangTranslation
  • SubjectTranslation
  • MessageTranslation
Verfügbare Methoden zur Erstellung
  • EMailTemplate createTemplate(Template template, final JobContext context)
  • void createSprache(Sprache sprache, final JobContext context)
  • void insertBausteinTranslation(EMailTemplateBaustein baustein, BausteinTranslation translation)
  • void insertBausteinRestriction(EMailTemplateBaustein baustein, Restriction restriction)
  • EMailTemplateAnhang insertAnhang(EMailTemplate template, Anhang anhang)
  • void insertStatuswechsel(EMailTemplate template, Statuswechsel statuswechsel)
  • void insertAnhangTranslation(EMailTemplateAnhang anhang, AnhangTranslation translation)
  • void insertBetreffTranslation(EMailTemplate template, SubjectTranslation translation)
  • void insertNachrichtTranslation(EMailTemplate template, MessageTranslation translation)
  • void insertAdresse(EMailTemplate template, Adresse adresse)
  • EMailTemplateBaustein createBaustein(Baustein baustein, final JobContext context)
Beispiel (Konfiguration Baustein)
public static final EMailTemplateKonfiguration.Baustein FOOTER_INTERN = new EMailTemplateKonfiguration.Baustein() {{
setName(RegelBausteineImpl.Footer.FOOTER_INTERN);
setText("<br>\n<br>Vielen Dank und freundliche Grüße,\n<br>\n<br>##{" + RegelBausteineImpl.Standard.AKTUELLER_BENUTZER + "}");
setFooter(true);
}};
Beispiel (Konfiguration Template)
public static final EMailTemplateKonfiguration.Template TEMPLATE_PROJEKT = new EMailTemplateKonfiguration.Template() {{
setName("Projekt aktiv");
setNuclet("org.nuclet.firma");
setAktiv(false);
setTable("Projekt");
setTestID(1234567);
setSpracheStatisch(EMailUtils.DEUTSCH);
setSubject("Neues Projekt");
setMessage("##{" + RegelBausteineImpl.Standard.ALLGEMEINE_ANREDE + "}" +
"\n<br>" +
"\n<br>das Projekt #{@Nummer} wurde soeben angelegt.");
setFooter(RegelBausteineImpl.Footer.FOOTER_INTERN);
setSignature(RegelBausteineImpl.Signature.SIGNATUR);
addAddress(new EMailTemplateKonfiguration.Adresse() {{
setAttribute("Beauftragtdurch");
setAttributeRef("Emailbenutzer");
setPflichtfeld(true);
}});
}};
Beispiel Erzeugung
EMailTemplateKonfiguration.createBaustein(FOOTER_INTERN, jobContext);
EMailTemplateKonfiguration.createTemplate(TEMPLATE_PROJEKT, jobContext);

Version 1.1.2

Beschreibung von Version 1.1.2

ThemaBeschreibung
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 ProtokollAlle 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.
Das Flag Verarbeitet kann nach der erfolgreichen Weiterverarbeitung der Mail auf true gesetzt werden.

Verwendung in RegelnDie 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();
context.addRecipient(auftrag.getKundeBO.getEmailadresse());
context.addRecipient("chef@firma.de", EMailContext.BCC);
context.addAttachment(auftrag.getRechnung());
context.setSubject("Rechnung für Auftrag " + auftrag.getAuftragsnr());
context.setMessage("...");
context.setReplyTo("kundenservice@firma.de");
context.setReference(auftrag.getKundeBO().getKundennr());
EMailVersand.sendMail(context);
Beispiel (E-Mail-Empfang)

Query<EMailProtokoll> query = QueryProvider.create(EMailProtokoll.class);
query.where(EMailProtokoll.Empfangen.eq(Boolean.TRUE));
query.where(EMailProtokoll.Empfangeneemailverarbeitet.eq(Boolean.FALSE));
for (EMailProtokoll email : QueryProvider.execute(query)) {
process(email, context);
email.setEmpfangeneemailverarbeitet(Boolean.TRUE);
email.save();
}

Integration von Version 1.1.2

Die Integration nach erfolgtem Nucletimport (siehe Nuclet Import) ist wie folgt vorzunehmen.

SchrittBeschreibungScreenshot
1

Konfigurieren Sie die Nuclos Parameter für die Nutzung des MailProviders in Nuclos (unter Administration > Parameter): 

  • SMTP Authentication
  • SMTP Username
  • SMTP Password
  • SMTP Server
  • SMTP Sender

Siehe dazu auch Email (SMTP/IMAP/Pop3).

2

Konfigurieren Sie die Nuclet Parameter des Nuclets Emailversand (unter Konfiguration > Nuclet Management)

NameBeschreibung

Email Absender

Absender der E-Mails
Email Betreff PrefixOptionales Prefix für die Betreffzeile aller Nuclos-Mails (OFF = kein Prefix)
Email Nachricht AbschlussOptionale Abschlussformel der Nachricht (OFF = kein Abschluss)
Email Nachricht SignaturOptionale Signatur der Nachricht (OFF = keine Signatur)
Email sofort versendenE-Mails  werden sofort versendet und nicht in der E-Mail-Queue zwischen gespeichert (Y/N)
Email UmleitungAlle E-Mails werden umgeleitet (Y/N)
Email Umleitung aufZiel der Umleitung
Versendete Emails löschenErfolgreich versendete E-Mails aus dem Email-Protokoll löschen
Empfangene Emails löschenEmpfangene E-Mails werden vom Mail-Server gelöscht

Version 1.1.0

Integration / Beschreibung von Version 1.1.0

Die Integration nach erfolgtem Nucletimport (siehe Nuclet Import) ist wie folgt vorzunehmen.

SchrittBeschreibung
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.

3Passen 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,
List<NuclosFile> lAttachment, String lang)

Ü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");
  • No labels