SAINET apis and documentation

Mails

L’environnement SAINet fournit toute une API pour envoyer des e-mails sous différents formats, avec pièces jointes, etc. Ce guide explique les différentes possibilités de paramétrage et de configuration permettant de donner un maximum la main à l’utilisateur.

Pour voir comment configurer un compte mail pour envoyer des mails, se référer à la documentation administrateur sur les mails.

Point d’entrée Java

La classe de base permettant d’accéder à toute l’interface des mails est un helper accessible à travers l’appel standard :

MailHelpers mailHelper = businessTask.getHelper(MailHelpers.class);

cette classe permet de récupérer un mail type paramétré par l’utilisateur, d’envoyer un mail ainsi que d’autres possibilités décrites dans les chapitres suivants.

Contexte du mail

Dans tous les mails paramétrés, le contenu du mail est bien souvent dynamique. Que se soit le nom du destinataire Bonjour Madame Y, ou des informations pertinentes concernant le contenu, il est possible d’injecter dans la construction du mail un contexte.

Le contexte Velocity des mails se construit à travers un appel standard au moteur.

//Initialisation du contexte
VelocityEngineContext veloCtx = VelocityEngineContext.newContext(resources, businessTask);

Il s’agit maintenant de le remplir. Par exemple, avec la variable classique $VELOHLP utilisée dans les templates.

//Génération d'un contexte velocity. L'appel se fait sur la tâche business
//Attention: Page/NotificationHandler, utiliser businessTask.getVelocityHelpers à la place.
VelocityHelpers velohlp = getVelocityHelpers(null, null);
velohlp.setContext(tableId, pageId, pageOcc, null);
veloCtx.putContext(VelocityMergeUtils.VELOCITY_VELOHLP, velohlp);

Il est également possible de remplir le contexte avec diverses entrées. Par exemple, ici le contexte est remplit avec un dossier permettant alors des appels typiques de Velocity tel que l’accès à des entrées du dossier ex: $dos.DLABEL

Dossier<Crmprjdossier> dos = getDossier(Crmprjdossier.class, "test");
veloCtx.putContext("child", new EntityDataDossier(dos.getEntity(), velohlp));

Chargement du mail depuis UNI95

La tâche UNI95 permet de saisir des mails type avec du contenu dynamique. Ces entrées peuvent être chargées et remplies avec un contexte fourni directement depuis le code business

//Récupération du mail UNI95 en français
MailSourceInterface mailSource = mailHelper.getVelocityMail("MY_EMAIL", "FR", veloCtx);

Voici les étapes pour créer une entrée dans UNI95 :

  1. Créer l’entrée pour la langue voulue en lui donnant un identifiant unique correspondant à l’identifiant voulu par l’appel. Il est possible d’avoir un même message défini dans des langues différentes Identification

  2. Définir le sujet du mail. Ce sujet à accès au contexte velocity il peut donc être dynamique en fonction de variables Sujet

  3. Définir le type de contenu. Dans le cas de contenu HTML, les balises sont prises en compte et les retours à la ligne doivent être définis sous forme de <br/> html valides. Dans le cas de plain texte, il n’est pas possible d’introduire des effets visuels mais les retours à la ligne seront ceux de l’entrée UNI95 Type de contenu

  4. Définir le contenu en fonction du bon type. Contenu

A noter qu’il est possible de récupérer les destinataires des mails dynamiquement depuis velocity, mais par un soucis de lisibilité et de praticité, les destinataires sont généralement calculés coté serveur avant l’envoi.

Attention:

Lorsque plusieurs mails sont envoyés, il est indispensable d’executer la récupération du mail Velocity pour chacun des destinataires dans la mesure ou le contexte va probablement être différent à chaque fois.

Configuration des destinataires

Les destinataires sont fournis sous la forme d’une chaine de caractères des adresses emails séparées par des virgules. Pour cela, utiliser la méthode SAIStringUtils.buildStringFromList qui permet de transformer automatiquement une liste en chaine de caractères, tel que montré dans l’exemple ci dessous.

List<String> recipients = new ArrayList<>(2);
recipients.add("test@sai-erp.net");
recipients.add("info@sai-erp.net");
mailSource.setRecipients(SAIStringUtils.buildStringFromList(recipients));

Il est possible de gérer les CC et BCC directement depuis cette même liste. Afin de simplifier la création et l’utilisation de l’API, il suffit de prefixer les adresses email concernées par (CC) ou (BCC) pour que le système sache que les destinataires doivent être insérés dans le champ correspondant dans le mail.

Ajout de fichiers

Il est possible de rajouter des documents à l’envoi d’un email. Que se soit une quittance, une information, une newsletter, tout est possible avec divers formats. A noter que certains serveurs mails n’autorisent pas la transmissions de formats particuliers tels que des programmes executables, ou des scripts. Tous les serveurs mails acceptent les pdf et les images normalement. La liste des fichiers attachés se transmet sous forme de List<File>

//Création de la liste de fichiers
List<File> files = new ArrayList<>();
....
//Remplissage de la liste avec des documents générés / récupérés
....
//On insère les documents dans le mail
mailSource.getAttachedFiles().addAll(files);

Il est également possible d’attacher des fichiers qui auraient été mis en note directement sur un champ dans une page. Pour cela, utiliser l’entrée directement disponible sur le mail paramétré et ajouter les notes à travers l’appel $MAILHLP.addAttachment(${entity}).

#set($dossier = $VELOHLP.getEntity("ADRDOS.ID_PK", "<id>"))
$MAILHLP.addAttachment($dossier.RAPPORTS.COURRIERBTN)

Il est possible de mettre des pièces jointes en note sur l’enregistrement UNI95 et ensuite de les référencer avec le code suivant, la variable $unieml étant automatiquement injectée dans ce contexte:

$MAILHLP.addAttachment($unieml, "Pièce jointe")

Envoi

L’envoi se déclare simplement à travers le helper. Il retourne un statut permettant d’avoir des informations sur la réussite de l’envoi. En cas d’erreur, le statut contient également la cause qui est disponible.

SmtpStatus status = mailHelper.sendMail(mailSource);
if(status.isSent()) {
    //yeah!
} else {
    //ooow no...!
    throw new BusinessMessage("CRM_EMAIL_SEND_FAILURE").
        putVariable("CAUSE", status.getCause());
}
Attention!!:

Dans le cas ou le serveur mail envoie un mail à un destinataire invalide, le fait que ce destinataire n’existe pas n’est pas retourné immédiatement mais arrivera potentiellement plus tard à l’adresse de l’envoi. Si l’adresse de l’envoi n’est pas une adresse avec une boite mail ou n’est pas relevée, l’information comme quoi le destinataire n’existe pas sera perdue.

De même, certains hebergeurs de serveur mail ont des quotas, et le dépassement du quota n’est pas indiqué immédiatement, et l’information peut être perdue également.

Tester

Il est possible d’intégrer un serveur mail local directement dans les tests. Les emails envoyés par ce serveur mail sont immédiatement récupérés en local et ne sont pas envoyés pour de vrai. Il sera ensuite possible à travers les tests de les consulter et de lire le contenu.

Pour démarrer le serveur mail local lors des tests, ajouter la ligne suivante à la déclaration du SAINetTestServer dans le package de test : .withLocalMailManager(). Exemple :

public static final SAINetTestServer server = SAINetTestServer.fromTestServer(EPAData.class, EPAData.PACKAGE).withLocalMailManager();

Le serveur possède désormais la possibilité d’envoyer des emails. Il sont accessibles à travers l’appel

    List<SmtpMessage> mails = testServer.getReceivedEmails();
    assertEquals(2, mails.size());

Pour savoir ce qu’il est possible de faire avec ces messages, consulter l’api de com.dumbster.smtp.SmtpMessage