recurring email reminders

recurring email series, parameter for the current date, dispatch condition for subform Addresses

Log draft as preview for an email, mark attachment as mandatory field, show use of blocks

Display and use Nuclos fields, email series according to schedule list, maximum attachment size, allow locked users

Via the Nuclet parameter Allow locked users sending emails to addresses with a locked user can be allowed (default: "N").

The block Creator (user) returns no result when locked.

...
 <b>bis spätestens ##{(HEUTE|TODAY)([+-][0-9]{1,4})([TD]|M|[JY])}</b>
...

Examples:

##{HEUTE}

##{HEUTE-14T}

##{TODAY+3M}

The BO E-Mail-Template offers the option to create templates for emails, which can then be sent from within rules. This gives an administrator the option to design the emails sent by Nuclos themselves and to change them at short notice. The templates offer many options for this:

• Access to arbitrarily deeply referenced attributes from a freely selectable base BO (e.g. sales order), similar to Nuclos forms
• Various sources of addresses (attribute, Nuclet parameter, user, user group, ...)
• Various sources of attachments (file, form, ...)
• Different languages of subject, message and attachment
• Text blocks
• Email recipients that determine the email address, salutation and language of the email
• Standardised and configurable footers and signatures
• Preview and test of the template

More complex email components, such as a table with all sales order items, must be supported by a rule.

Blocks can be defined that are then available in the email templates. Possible are

Textbaustein

• Reine (ggf. mehrsprachige) Standard-Textbausteine (AGB, Versandinfos, Signatur, ...)
• Blocks that provide a footer or a signature

Rule block

• Complex blocks that require rule support (e.g. table with sales order items)
• Blocks that determine one or more email addresses (e.g. for subscribe functionalities)
• Blocks that define a language

Recipients

• Blocks that define the email recipient (address, salutation, language)

Attachment

• Blocks that generate an attachment

Versandbedingung

• Blocks that decide whether an email should be sent or not

For safety, blocks can be restricted to certain BOs, e.g. if the block Bearbeiter  for the BOs Rechnung and Sales order exists but not for the BO Articles 

To create an email from an email template, an instance of a class must be passed that implements the interface Regelbausteine  is implemented.

The Nuclet comes with an implementation that contains some examples. If you need your own rule blocks, you should create your own implementation in your Nuclet so that it is not overwritten when the email Nuclet is updated.

In the method EMailUtils.getRegelBausteine() then simply create this implementation.

Here subject and message can be defined. The following can be used

• Any text
• Data fields from the base BO in the form e.g. #{Auftragsnr} or #{Kunde.Kundengruppe.Name}. Available data fields can be found as help in the tab Available data fields  zu finden
• Text blocks that are either not restricted to a BO (##{AGB}) or are allowed for the base BO (##{Ansprechpartner}), can be found as help in the tab Available text blocks 

Alternative texts in other languages can be specified for subject and message (see tab Subjects (translated) and Messages (translated))

Wenn ein Recipients is specified, the email is sent to the email address determined there. Additionally or alternatively, further addresses can be added from

• direkt angegebenen Adressen (z.B. CC info@firma.de)
• a Nuclos user
• all Nuclos users of a certain user group
• an attribute of the base BO (or further referenced attributes, e.g. the email address of the person responsible for the sales order)
• a Nuclet parameter
• a block that is marked as E-Mail-Adresse gekennzeichnet ist

Here attachments for the email can be defined, e.g.

• a report or form 
• a file stored in the template
• a block that is marked as Attachment and for which the method getAttachments() returns a list of files

Alternative attachments in other languages can be defined for each attachment

Here you can configure at which state change the email should be sent. However, a corresponding rule must be assigned for every possible state change of the affected state model. Helpful for this rule is then the method

EMailUtils.sendAllAcceptedEMails(StateChangeContext context, RegelBausteine regelBausteine)

After the Nuclet import, the job Initialisiere Nuclet Emailversand must be run once.

Among other things, the job creates some standard email blocks so that you can build a template right away.

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("Unknown name for a rule block: \"" + name + "\"");
}

@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("Unknown name for a recipient: \"" + name + "\"");
}

EMailTemplate template = EMailUtils.getEMailTemplate(Konstanten.EMailTemplate.RECHNUNG);
if (template.getAktiv()) {
    EMailVersand.sendMail(new EMailContext(template, EMailUtils.getRegelBausteine(), rechnung, context));
}

The class EMailTemplateKonfiguration provides data structures and methods to create languages, blocks and templates via rules.

This can be particularly helpful during Nuclet development, to recreate such objects on other instances.

• Sprache
• Baustein
• Template
• Restriction
• Adresse
• State change
• Attachment
• BausteinTranslation
• AnhangTranslation
• SubjectTranslation
• MessageTranslation

• 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)

public static final EMailTemplateKonfiguration.Baustein FOOTER_INTERN = new EMailTemplateKonfiguration.Baustein() {{
   setName(RegelBausteineImpl.Footer.FOOTER_INTERN);
   setText("<br>\n<br>Many thanks and best regards,\n<br>\n<br>##{" + RegelBausteineImpl.Standard.AKTUELLER_BENUTZER + "}");
   setFooter(true);
}};

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>the project #{@Nummer} has just been created.");
   setFooter(RegelBausteineImpl.Footer.FOOTER_INTERN);
   setSignature(RegelBausteineImpl.Signature.SIGNATUR);
   addAddress(new EMailTemplateKonfiguration.Adresse() {{
      setAttribute("Beauftragtdurch");
      setAttributeRef("Emailbenutzer");
      setPflichtfeld(true);
   }});
}};

EMailTemplateKonfiguration.createBaustein(FOOTER_INTERN, jobContext);
EMailTemplateKonfiguration.createTemplate(TEMPLATE_PROJEKT, jobContext);

For test operation, email redirection can be activated. All outgoing emails are then redirected to a defined address.

The email additionally states to whom it would actually have gone.

There are two different options for sending emails:

Send immediately

The email is sent immediately. If sending is triggered by a user (e.g. by a state change that triggers an email dispatch), they must wait until this process is complete before they can continue working. If an error occurs during email dispatch, the entire action (e.g. state change) of the user is undone.

Dispatch via email queue

The email is first stored in the email log as an unsent email and only sent by a regularly running job (Administration > Job control > Send emails). This must of course be activated. This means the user is not held up unnecessarily long during their work, and a faulty email dispatch does not lead to the cancellation of their action.

The job EMailEmpfang creates an entry in the email log with the flags for new emails on the server specified in the IMAP system parameters Versendet = false, Empfangen = true, Verarbeitet = false.
The flag Verarbeitet can, after the successful further processing of the mail, be set to true be set.

static void sendMail(EMailContext context)

static void sendMailNow(EMailContext context)

void addRecipient(String address, int type)

void addRecipient(String address)

void addRecipients(List<String> lRecipients, int type) 

void addRecipients(List<String> lRecipients)

void addAttachment(NuclosFile file) 

void addAttachments(List<NuclosFile> lAttachments)

void setReplyTo(String replyTo)

void setMessage(String message)

void setSubject(String subject)

void setReference(String reference)

void resetAttachments()

void resetRecipients()

EMailContext context = new EMailContext();
context.addRecipient(auftrag.getKundeBO.getEmailadresse());
context.addRecipient("chef@firma.de", EMailContext.BCC);
context.addAttachment(auftrag.getRechnung());
context.setSubject("Invoice for order " + auftrag.getAuftragsnr());
context.setMessage("...");
context.setReplyTo("kundenservice@firma.de");
context.setReference(auftrag.getKundeBO().getKundennr());
EMailVersand.sendMail(context);

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();
}

Configure the Nuclos parameters for using the MailProvider in Nuclos (under Administration > Parameters): 

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

See also Parameter für Mailversand.

Configure the Nuclet parameters of the Nuclets Emailversand (under Configuration > Nuclet Management)

Configure the SMTP system parameters required for using the MailProvider in Nuclos (at least SMTP Authentication, SMTP Username, SMTP Password, SMTP Server, SMTP Sender). See also Parameter für Mailversand.

Configure the From/ReplyTo address to be set by Nuclos in the Nuclet parameter "Email Sender Address". Furthermore, activate or deactivate the redirection as desired in the Nuclet parameters "Email Forwarding" ("Y" or "N") and "Email Forwarding Address". If the redirection is activated, all emails sent via this Nuclet are not sent to the actual recipient, but redirected to the address specified in "Email Forwarding Address". In this way, the implementation of automatically sent emails in your own Nuclet can be tested easily, or a test system can be configured easily so that it does not send any emails to your customers or suppliers.

Use the newly gained functionality by sending emails e.g. to your customers and suppliers. The following methods are available for this:

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)

Emails sent via these methods are stored and archived under the menu item System | Email log. Remember to grant your users read permission for this menu item if necessary.

Example:

String sSubject = "Your invoice";

String sMessage = "Please find your invoice attached";

(new EMailVersand()).sendEmail(kunde.getEmailadresse(), sSubject, sMessage, pdfInvoice, "de");