2.06. Servicii de email
Prezentare generală
Serviciile de email SocrateCloud sunt create cu scopul de a centraliza și controla trimiterea de email-uri din intreg sistemul. Pentru a activa acest mecanism se foloseşte componenta SocrateCloud Email Service (SEMS)
Structura conține o parte publica (in core-framework) și o parte privata (în sems). In partea publică stă întreg engine-ul de email, iar în partea privată, diferite implementări de servicii de email (după cum se poate vedea în poza de mai jos). Dată fiind această structură, în viitor se pot adaugă și alte componente SocrateCloud care sa conțină implementări specifice ale serviciului de email.
S-a păstrat şi funcționalitatea de bază (SocrateOpen/Compiere), astfel încât, dacă nu se face nicio setare, email-urile se trimit ca și până la apariția componentei (același cod java), cu setările de mail de pe fiecare titular, cu excepția că apelurile trec prin serviciile SocrateCloud iar mesajele se țin într-o locație nouă în baza de date și într-un alt format (prezentat mai jos)
majoritatea proceselor de trimitere email țin cont de setările de pe titular
excepția o reprezintă notificările de pe acțiuni sesizare, care pleacă tot timpul prin serviciul de email activ și implicit setat la nivel de System (în fereastra ”Email Services”),
iar dacă acestea nu există, atunci se folosește serviciul definit la nivel de Titular!
altfel se primește eroare: ”no request email for tenant ....”
email-urile pot pleca de la diverse module: WebUI, Server, WebAPI. IP-urile curente ale acestor servere sunt:
35.156.100.227 - API
3.120.119.65 - Server
52.57.197.206 - WebUI
la încercarea de trimitere email se scrie un log disponibil in fereastra ”Mesaje email” pe titular
prima tură
created = data când a început să trimită emailul
procesare acum = Y, cât timp încearcă prima tură
dacă se trimite cu succes, pune bifa de trimis și actualizează câmpul: ”Actualizat la”
daca nu, nu pune bifa de trimis, scrie eroarea în câmpul ”Rezultat” și scoate bifa de pe ”Procesare acum”
apoi încearcă retrimiterea de încă 2 ori, la interval de 5 minute. Dacă tot nu se poate trimite, scoate bifa de activ, ca să nu mai încerce transmiterea
bifa activ este editabilă, dacă este pusă și trimis este N, serverul reîncearcă trimiterea acelui mesaj
Erorile se pot găsi și în Loggly
Reguli generale
adresele de email către care se trimit mesajele trebuie să fie corecte sintactic, să respecte standardul RFC 822;
dacă una sau mai multe adrese de email nu sunt corecte, email-ul nu se trimite şi se întoarce mesaj de eroare cu adresele greșite și cu un tip de eroare corespunzător (INVALID_EMAIL);
adresele de email se folosesc o singură dată (nu se acceptă duplicări);
o adresă nu poate fi și în To și în Cc (duplicările sunt șterse);
dacă nu se specifică nicio adresă destinatar, se întoarce mesaj de eroare și tipul de eroare NO_RECIPIENTS;
dacă email-ul are destinatari, dar niciunul nu are notificare de tip Email (cel puțin), se întoarce mesaj de eroare cu adresele către care nu se trimit email-uri și cu tipul de eroare corespunzător (NO_RECIPIENTS);
există procese care pot trimite email-uri având ca expeditor utilizatorul care face acţiunea. Pentru acest tip de email se folosesc setările de email de pe titular şi datele de autentificare de pe utilizator;
adresa Replay To setată pe macheta mail se folosește doar programatic, în procesele în care s-a cerut si dezvoltat acest lucru. Implicit se foloseste adresa de email setată pe titular în campul Replay To.
pentru serviciile de email de tipul Amazon (SES) și SBS Email nu se vor putea trimite în mod complet mesajele de e-mail dacă acestea conțin fișiere atașate ce depășesc ca dimensiune totală limita de 5MB!
doar mesajul text va fi livrat către destinatari, dar:
fără fișierele atașate;
cu un mesaj suplimentar de forma: ”Failed to add attachment <<name of file>>(<<size>>MB) since more than 5MB is not supported. Message ID: <<nn>>. Please contact your system administrator to provide you the file needed”
mesajele se vor genera și înregistra în fereastra ”Mesaje email”, unde administratorul aplicației poate regăsi și fișierele atașate. Mesajul se poate regăsi ușor după ID-ul indicat în textul adăugat email-ului.
Arhitectura în linii mari este prezentată în poza de mai jos. În funcție de setările serviciului de email se folosește implementarea corespunzătoare.
Interfaţa utilizator - setup servicii email
Pentru a configura, respectiv activa un anumit serviciu de email, se folosesc următoarele:
tipurile de servicii de email şi serviciul activ (implicit) - acestea sunt predefinite de către BIT, iar administratorul de sistem poate stabili care este serviciul pe care il activează pentru mediul lui. Atenţie! setarea este efectuată la nivel de sistem, deci valabilă pentru toţi titularii din mediul respectiv.
setările specifice (opţional) de la nivel de titular
Setup
se instalează componenta SEMS
se intră cu System și se deschide fereastra Servicii Email, se selectează un tip de Tip de serviciu și se completează cu setările serviciului respectiv. În poza de mai jos e un exemplu de configurare cont Gmail care necesită doar user și parolă (în poza e expandat tabul de setări din fereastra de setări de email)
Pentru serviciul de email de tipul Amazon (SES), înainte de a configura serviciul în SocrateCloud este necesară configurarea în AWS a accesului la serviciul SES (Simple Email Service).
Pentru serviciul de email de tipul SBS Email, înainte de a configura serviciul în SocrateCloud este necesară configurarea în SBS a accesului la serviciul Outbound Email.
pentru ca serviciul să fie folosit este necesar să fie marcat ca Activ și Implicit, iar după salvare (master și detaliu) să se aplice un Cache Reset Client + Server
pentru mediul ”cloud partajat” se pot face setări particulare la nivel de Titular (din fereastra ”Titular”), iar acestea se vor aplica după regula de mai jos:
Setări folosite la trimiterea de email-uri
dacă nu este instalată componenta SEMS se folosesc setările de la nivel de titular, din fereastra Tenant (implementarea implicită a serviciului);
dacă se instalează componenta SEMS și nu se configurează nimic, la fel, se folosesc setările de pe titular (implementarea implicită a serviciului);
dacă se instalează componenta SEMS și adaugă servicii dar nu se marchează niciunul ca implicit, se folosesc setările de pe titular (implementarea implicită a serviciului);
dacă se definește un serviciu de email de tip SocrateOpen standard și se marchează ca implicit, atunci se vor folosi setările de pe titularul System la trimiterea email-urilor (pentru orice titular);
dacă se definește orice alt tip de serviciu de email (diferit de SocrateOpen standard), se va ține cont de setările serviciului, fără a se mai ţine cont de setările de pe titulari (nici de pe System);
dacă se trimite email în numele unui utilizator (de pe anumite procese) atunci se folosesc setările de la nivel de Titular (plus setarile utilizatorului - cont email si parola email din fereastra Utilizatori).
Observatii
nu se pot seta servicii de email la nivel de Titular;
de o singura setare de pe titular se tine cont tot timpul la trimiterea de email-uri, și anume "Reply To EMail", adresa la care se face reply la mesaje.
Fluxul de livrare al mesajelor
la primul apel al serviciului de email (care se face prin clasa java org.bitsoftware.sems.SCEmailService) sau la cache reset se încarcă implementarea specificată în setările serviciului de mail;
dacă nu se face nicio setare, se încarcă implementarea implicită ce folosește setările de mail de pe fiecare titular;
dacă apare o eroare la încărcarea unui serviciu de email marcat ca implicit se trece automat la încărcarea următorului serviciu în ordinea secvenței în care au fost definite;
un serviciu încărcat fără erori va fi folosit pentru toate apelurile de trimitere de email până la următorul cache reset;
serviciul de email poate sa creeze un email (o instanta a clasei org.compiere.util.EMail) pe care să îl trimită ulterior sau să îl creeze și să îl și trimită automat;
atunci când se apelează trimiterea unui email, acesta se și salvează în baza de date în tabela SEMS_Message (fereastra se poate vedea mai jos);
dacă mesajul nu a fost trimis cu succes se va reîncerca retrimiterea lui de către procesorul de email-uri (vezi fereastra și descrierea de mai jos).
Procesorul de email-uri
Este în standard și rulează pentru toți titularii. Mesajele se trimit în coadă câte unul pe rând.
Mod de lucru:
parcurge tabela SEMS_Message pentru mesaje active ce nu au fost trimise și nu sunt în curs de trimitere;
creează un Email folosind implementarea curentă a serviciului de email (poate sa difere de implementarea cu care a rulat inițial trimiterea de email-uri) cu informațiile stocate în baza de date;
în caz de succes se marchează mesajul ca trimis și se trece la următorul mesaj;
în caz de eșec se verifică dacă s-a atins numărul maxim de încercări (setabil din interfață pe procesor, vezi fereastra de mai jos), caz în care mesajul se marchează ca inactiv. Dacă nu s-a atins maximul se incrementează contorul, se salvează mesajul de eroare și se trece la următorul mesaj.
Modul de funcționare este schițat și în diagrama de mai jos
Interfaţa utilizator - ferestrele de gestionare a email-urilor
Fereastra: Tip serviciu email
Componenta: SEMS
Acces: System
Aici sunt definite clasele care execută implementarea serviciului de email. Aceste clase trebuie să respecte interfața org.bitsoftware.sems.SCEmailServiceImplInterface.
Fereastra: Servicii Email
Componenta: SEMS
Acces: System
Aici se definesc serviciile de email. Se pot defini mai multe servicii dar se încarcă doar cel implicit.
O singura înregistrare poate fi activa și implicita
Pentru tipul de serviciu "SocrateOpen standard" setările sunt cele de pe titularul System
Tabul de jos afișează setări diferite în funcție de tipul de serviciu ales
Fereastra: Mesaje Email
Componenta: SocrateCloud Dictionary
Acces: System+Titular (pe titular nu se vad mesajele de pe System)
Mai jos sunt două imagini, una cu varianta implicită, cu grupurile "Avansat" și "Stare" restrânse și alta cu grupurile extinse
Dacă email-ul ar fi fost trimis și unor persoane aflate în Cc sau în Bcc ar fi apărut și aceste câmpuri (acum sunt ascunse)
Dacă la destinatar sunt mai multe persoane atunci adresele de email vor fi enumerate în câmpul "Către" sau "Cc"/"Bcc"
Câmpurile "Către", "Cc" și "Bcc" sunt coloane virtuale. Informațiile sunt luate din taburile de jos ce reprezinta legătura dintre mesaj și utilizatori (legătură many-to-many). În aceste câmpuri nu se vor afișa mai mult de zece adrese de email. Pentru vizualizarea tuturor adreselor se navighează în taburile de sub mesaj.
Tabul "Făra utilizator" păstrează adresele de email către care acesta a fost trimis și pentru care nu exista utilizator in SocrateCloud
În grupul "Avansat" se regăsesc informații referitoare la serviciul cu care a fost trimis email-ul, id-ul acestuia, macheta de mail folosită și modulul web de unde a fost trimis email-ul
În grupul "Stare" se pozate verifica dacă mesajul este în curs de trimitere, dacă a fost trimis sau dacă nu; dacă nu a fost trimis cu succes, de câte ori s-a încercat retrimiterea și ultimul mesaj de eroare.
Varianta extinsă
Fereastra: Mesaje Email (coadă)
Componenta: SEMS
Acces: System+Titular (pe titular nu se vad mesajele de pe System)
Fereastra are același format ca și fereastra "Mesaje Email" cu excepția că sunt afișate doar mesajele care nu au fost încă trimise dar urmează sa fie trimise (sunt active) cum e cazul mesajelor n curs de trimitere sau mesajele ce au dat eroare dar se reincearca trimiterea lor (de către procesorul de email-uri) de câteva de ori (număr setabil tot la nivel de procesor de email-uri)
Fereastra: Mesaje Email (fără utilizator)
Componenta: SEMS
Acces: System+Titular (pe titular nu se vad mesajele de pe System)
Fereastra are același format ca și fereastra "Mesaje Email" cu excepția că sunt afișate doar mesajele trimise la adrese de email ce nu sunt asociate cu utilizatori din SocrateCloud
Fereastra: Mesaje Email (netrimise)
Componenta: SEMS
Acces: System+Titular (pe titular nu se vad mesajele de pe System)
Fereastra are același format ca și fereastra "Mesaje Email" cu excepția că sunt afișate doar mesajele ce nu au fost trimise și nici nu se mai încearcă retrimiterea lor (mesaje dezactivate de procesorul de email-uri ce a încercat să trimită aceste mesaje de câteva ori)
Fereastra: Procesor Serviciu Email
Componenta: SEMS
Acces: System
Aici se păstrează setările pentru procesorul de email-uri. Acesta parcurge mesaje de mail stocate în baza de date, care sunt active, nu au fost trimise și nu sunt în curs de trimitere. În fereastra se setează numărul maxim de încercări de trimitere a email-ului și frecventa cu care să ruleze.
Fereastra: Titular
Este folosit câmpul Reply To EMail pentru a specifica adresa de reply distinctă pentru fiecare titular în parte. Se recomandă să se completeze mai ales în cazul utilizării serviciului de email de la nivel de System (în mediul cloud partajat):
excepție: mesajele trimise prin procese care au la bază o ”Machetă mail” și în care se poate seta o adresă particulară pentru Reply To.
Fereastra: Utilizatori
Componenta: Dictionary
Acces: System+Titular
În tab-ul Mesaje Email din fereastra Utilizatori se pot vedea toate adresele de email (în limita a 10 adrese pe grup) la care a fost trimis mesajul, mai putin cele din Bcc
Process: Testare serviciu email
Componenta: SEMS
Acces: System+Titular
Procesul trimite un email cu setările serviciului de mail la adresa specificata (vezi poza mai jos)
Exemplu de email trimis cu procesul de mai sus:
Fereastra: Machetă Mail
Se utilizează pentru a defini machete de mail specifice, care pot fi folosite pentru notificări prin email de la procese sau fluxuri.
Este recomandat ca machetele de mail să fie definite folosind sintaxa ”freemarker template language”.
Se completează următoarele câmpuri:
Societate - macheta poate fi folosită pe titular (*) sau pe o societate specifică;
Denumire - se precizează denumirea machetei de mail;
Tip machetă email - se precizează tipul machetei în funcție de scopul în care vor fi folosite. Se pot alege următoarele valori:
Sesizare - pentru machete care pot fi folosite doar în ferestrele de sesizări
Marketing - pentru machete care pot fi folosite la procesele ”Trimite EMail”
Flux - pentru machete care pot fi folosite doar din nodurile de Fluxuri de ”Trimite EMail”
Generică - pentru machete care pot fi folosite de oriunde
Necesită EMail individual - se marchează atunci când, în procesul de trimitere pot rezulta mai mulți destinatari, caz în care se dorește trimiterea de e-mail-uri separate către fiecare dintre aceștia. În caz contrar sistemul generează un singur e-mail în care trece pe toți destinatarii la Bcc. Atenție, dacă rezultă mai mult de 50 de destinatari, mesajul nu va putea fi trimis decât individual.
Reply to email - opțional, se poate completa cu o anumită adresă fixă, către care clientul să trimită răspunsul;
Subiect - subiectul emailului, cu maxim 2000 de caractere;
Text mail (1,2,3, etc.) - conținutul emailului;
în câmpurile "Text mail" se pot introduce mai mult de 2000 de caractere;
textul poate să fie:
simplu
să conțină parametri care să fie preluați din contextul ferestrei (ex. @SalesRep_ID@);
dinamic - când este necesar ca textul sa fie dinamic, acesta trebuie să fie definit folosind sintaxa ”freemarker template language”:
pe prima linie trebuie să fie: <#ftl>
variabilele care trebuie să apară în corpul email-ului trebuie scrise între ${ și } , exemplu: ${SalesRep_ID}
dacă sunt sub forma ${Field} - informația este preluată din câmpul Field de pe tabela corespunzătoare ferestrei;
dacă sunt sub forma ${Table.Field} - informația este adusă din câmpul Field, care se găseste în tabela referită de câmpul Table_ID
dacă sunt sub forma ${Table.Field!"n/a"} și nu se găsește valoare, în mail se va trece "n/a";
în cazul în care se modifică conținutul unui câmp și se dorește a fi specificat, se folosește formula (exemplu):
<#if R_RequestType_ID_isChanged!false>
Request Type: ${R_RequestType_ID_old} -> ${R_RequestType_ID}
</#if>
pentru a adauga un URL, se folosește formula (exemplu):
<#if misc.sowebUrl??>
URL: ${misc.sowebUrl}#ViewRequest$${R_Request_ID}
</#if>
"HTML" - pentru textele concepute HTML, dacă se pune această bifă, se vor aplica formatările HTML (ex: bold, italic, subliniat, dimensiune, font etc); dacă nu se bifează, textul va fi afișat ca atare, cu tag-urile HTML vizibile (ex. Bold: <b>Text/Câmp</b>);
Pentru mai multe informații referitor la modul de definire a machetelor de mail, accesați site-ul: https://freemarker.apache.org/docs/ref.html
Conținutul din master document este exprimat în limba definită la nivel de System (en_US).
Tab-ul Traduceri se va ajusta corespunzător pentru fiecare limbă în parte.
Logica de preluare a traducerii de pe Macheta Mail este următoarea:
Prioritate 0 - limba indicată în definiția Terțului;
Prioritate 1 - limba indicată la nivel de Titular;
Prioritate 2 - limba de bază stabilită la nivel de System (considerată a fi cea de pe master document Machetă Mail).
Dacă se aduc modificări asupra machetei de mail sau a traducerii acesteia, pentru ca acestea să fie preluate la folosirea machetei, după salvare, trebuie să se facă Resetare cache client + server!