Personalizzazione delle etichette

La personalizzazione delle etichette ci dà la possibilità di configurare il testo delle notifiche da inviare. Questa fuzionalità permette tramite le etichette custom di definire "cosa" inviare, personalizzando sia l'oggetto della mail che il suo contenuto. Ovviamente si tratta di potenziali funzionalità, in quanto nel caso si decida di non precedere con la personalizzazione, il sistema prevede dei valori di default con impostazioni molto semplici per ogni tipologia di oggetto con flusso (RM/AP) a cui possono essere applicate le notifiche.

In visione completa dal percorso "Configurazione -> Gestione etichette - > Cerca etichette custom" è possibile definire le etichette desiderate. In seguito viene specificato come inserire chiave e valore e la sintassi necessaria.

Come definire la chiave dell’etichetta

La chiave dell’etichetta può essere espressa come segue, il sistema cerca il valore dal più specifico fino ad arrivare al più generico:

-> per l’oggetto della mail, dal più specifico:

ap.identificativo_tipologia.mail.enter.stato_arrivo.attore.subject

ap.identificativo_tipologia.mail.enter.stato_arrivo.subject

ap.identificativo_tipologia.mail.enter.attore.subject

ap.identificativo_tipologia.mail.enter.subject

ap.identificativo_tipologia.mail.subject

Esempio

la presenza dell’etichetta -> ap.prj.mail.enter.owner.subject

    è prioritaria rispetto a -> ap.prj.mail.subject

-> per il corpo della mail è possibile esprimere il contenuto sia con una etichetta di tipo html, sia come un testo semplice non formattato. Il sistema, a parità di specificità, dà la precedenza alla tipologia html. Da notare che la chiave dell'etichetta del corpo è più specifica rispetto a quella dell'oggetto. Infatti sono presenti le declinazioni body.html e body.text, mentre per subject la chiave è espressa senza specifiche del tipo di properties.

ap.identificativo_tipologia.mail.enter.stato_arrivo.attore.body.html

ap.identificativo_tipologia.mail.enter.stato_arrivo.attore.body.text

ap.identificativo_tipologia.mail.enter.stato_arrivo.body.html

ap.identificativo_tipologia.mail.enter.stato_arrivo.body.text

ap.identificativo_tipologia.mail.enter.attore.body.html

ap.identificativo_tipologia.mail.enter.attore.body.text

ap.identificativo_tipologia.mail.enter.body.html

ap.identificativo_tipologia.mail.enter.body.text

ap.identificativo_tipologia.mail.body.html

ap.identificativo_tipologia.mail.body.text

Esempio

la presenza dell’etichetta -> ap.prj.mail.enter.draft.body.text

    è prioritaria rispetto a -> ap.prj.mail.body.html

Oppure la presenza dell’etichetta -> ap.prj.mail.enter.draft.body.html

                 è prioritaria rispetto a -> ap.prj.mail.enter.draft.body.text

Il parametro "stato_arrivo" rappresenta lo stato in cui in ingresso viene attivata la notifica. Il parametro "attore" rappresenta il tipo di destinatario della notifica. Tale attore deve necessariamente avere almeno il permesso di lettura sullo stato in questione. Per determinare quale valori usare è necessario consultare la documentazione nelle pagine di riferimento di ogni flusso.

Da notare che oltre alla gerarchia già espressa è possibile creare etichette che seguono la gerarchia delle tipologie degli oggetti. Il parametro “identificativo_tipologia” può infatti essere espresso con gli identificativi gerarchici presenti nel file Excel delle tipologie.

Esempio

la presenza dell’etichetta -> ap.prj.research.priv.mail.enter.draft.body.text

    è prioritaria rispetto a -> ap.prj.mail.enter.draft.body.text
Da notare che tutte queste etichette hanno la chiave scritta principalmente con caratteri minuscoli. I vari parametri (stato/attore) devono essere riportati nella stessa dicitura della documentazione, la notazione è case sensitive.

Come definire il valore dell’etichetta

Nell’oggetto e nel corpo della mail è possibile utilizzare una sintassi particolare, composta da segnaposto e parentesi che verranno interpretati e sostituiti con i valori appropriati dal sistema prima dell'invio della notifica:

1) segnaposto ${}

Serve per inserire nel corpo/oggetto della mail qualsiasi informazione recuperata dall’oggetto con flusso a cui si vuole applicare l’invio della notifica. La funzionalità non è retrocompatibile, non sono quindi più utilizzabili i segnaposto semplici {} per questo tipo di notifiche. Il pregresso è già stato sanato con il rilascio della funzionalità corrente.
SINTASSI (case sensitive)

${system.searchList} -> viene sostituito con l'indirizzo della lista degli oggetti, ovvero la pagina con i filtri di ricerca accessibile da ogni voce di menu. Nel caso in cui sia impostata una notifica di tipo html viene costrutito il link opportuno completo di testo e url associato.

${system.recipient} -> viene sostituito con nome e cognome del destinatario della notifica (se noto).

${item.xxxxxx} -> xxxxxx può rappresentare ogni metadato atomico (no multitipo) presente nella scheda. Il nome da inserire all’interno del segnaposto va determinato secondo la guida presente nelle pagine Wiki che specifica il modello dati su cui si stanno attivando le notifiche, andando ad individuare la colonna Attributo, a cui bisogna porre particolare attenzione nel caso siano presenti i riferimenti fra parentesi. La notazione utilizzata è simile a quella per il servizio REST.
Esempio: ${item.identifier} oppure ${item.startDate} oppure ${item.involvementType}

${item.xxxxSet.yyyyyy} -> questa notazione rappresenta la possibilità di inserire elementi multitipo come i partecipanti o lo strutture interne. Xxxx rappresenta il tipo di oggetto multiplo (prima colonna della documentazione del modello dati). “Set” è una parola chiave per esprimere la potenziale presenza di più di un valore. Yyyyyy è l’attributo dell’oggetto multitipo, come sopra vanno utilizzati i riferimenti fra parentesi se presenti.
Esempio: ${item.partnerSet.organizationUnit} visualizza il nome di ogni struttura Partner

${item.xxxxSet:yyyyyy,zzzzzz} -> è una evoluzione della notazione precedente, ma più complessa. Quando per gli elementi multitipo è necessario visualizzare più di un attributo vanno espressi uno dopo l’altro dopo i due punti. Quindi avremo xxxx rappresenta il tipo di oggetto multiplo (prima colonna della documentazione sopra). “Set” è una parola chiave per esprimere la potenziale presenza di più di un valore. La presenza dei ‘:’ è fondamentale per questa notazione e introduce yyyyyy e zzzzzz che sono gli attributi dell’oggetto desiderati, come sopra vanno utilizzati i riferimenti fra parentesi se presenti. Dopo i ‘:’ è possibile inserire una lista separata da virgola lunga a piacere.
Esempio: ${item.ownerSet:person,role,startDate} visualizza, per ogni Responsabile, il nome, il ruolo e la data di inizio collaborazione.

In questo caso nell’etichetta di tipo testo, gli attributi vengono mostrati con un punto elenco, separati dal carattere trattino. Nel caso invece sia presente una etichetta di tipo html, i metadati vengono mostrati all’interno di una tabellina. Ogni colonna della tabella presenta una nuova etichetta contestualizzata al contenuto, potrebbe quindi essere necessario in una prima configurazione andare ad inserire tale etichette fra quelle personalizzate. Se NON si desidera la visualizzazione tramite tabella, è possibile inserire una configurazione (ap.mail.html.list.enabled = true) che permette di visualizzare un classico elenco puntato html.

2) Parentesi quadre [] e segnaposto condizionale ${}?

Le parentesi quadre possono essere inserite per contrassegnare una parte del testo/oggetto della notifica che si vuole rendere condizionale. Quella parte di testo verrà visualizzata nel messaggio di notifica solo se tutti i segnaposto condizionali che si trovano all’interno sono soddisfatti, ovvero nessuno di loro restituisce un valore nullo.

Esempio

progetto = identificativo campo obbligatorio sempre presente + codice CUP che può non essere specificato nella scheda

ap.prj.mail.enter.body.text = Questo progetto ha identificativo ${item.identifier}.[ Il codice CUP è ${item.cup}?.] Cordiali saluti.

Con il CUP nullo riceveremo la mail con nel testo “Questo progetto ha identificativo PRJ-0004. Cordiali saluti.”

Mentre in presenza del CUP avremo “Questo progetto ha identificativo PRJ-0004. Il codice CUP è COD123.  Cordiali saluti.”

Esempio

progetto = identificativo campo obbligatorio sempre presente + il codice CUP e data di inizio possono non essere specificati nella scheda

ap.prj.mail.enter.body.text = Questo progetto ha identificativo ${item.identifier}.[ Il codice CUP è ${item.cup}? e la data di inizio è ${item.startDate}?.] Cordiali saluti.

Con il CUP nullo OPPURE con la data nulla e con entrambi nulli riceveremo la mail con “Questo progetto ha identificativo PRJ-0004. Cordiali saluti.”

Mentre in presenza di ENTRAMBI i valori avremo “Questo progetto ha identificativo PRJ-0004. Il codice CUP è COD123 e la data di inizio è 12-04-2022. Cordiali saluti.”

Lo stesso esempio ma con una etichetta specificata in maniera diversa

ap.prj.mail.enter.body.text = Questo progetto ha identificativo ${item.identifier}.[ Il codice CUP è ${item.cup}? e la data di inizio è ${item.startDate}.] Cordiali saluti.

Con il CUP nullo riceveremo la mail con “Questo progetto ha identificativo PRJ-0004. Cordiali saluti.”

Mentre in presenza del CUP e indipendentemente dal valore della data (segnaposto NON condizionale) avremo “Questo progetto ha identificativo PRJ-0004. Il codice CUP è COD123 e la data di inizio è 12-04-2022. Cordiali saluti.”

Oppure “Questo progetto ha identificativo PRJ-0004. Il codice CUP è COD123 e la data di inizio è <N.D.>. Cordiali saluti.”

Notiamo infatti che in un paragrafo condizionale possono essere inseriti anche segnaposto classici che non impattano sulla logica di visualizzazione. La notazione <N.D.> significa che il segnaposto non è mai condizionale e che in quel caso non è stato trovato alcun valore.

Vediamo ora alcuni esempi complessi che contengono tutte le casistiche sopra riportate, in tutte le declinazioni possibili, ovvero...

1) testo semplice, nel sistema avremo

e la notifica mail risultante sarà

2) html con tabella di default, nel sistema avremo

e la notifica mail risultante sarà

Da notare che l'intestazione delle tabelle necessita di nuove etichette apposite da inserire in quelle custom.

Viene applicato un template di default a tutte le mail formato html. La struttura del template è una configuration di sistema e permette di visualizzare i due loghi (IRIS e Ateneo) e di includere un foglio di stile che può invece essere personalizzato (si chiama notification.css).

2b) html con attivazione del punto elenco (stesso esempio, con ap.mail.html.list.enabled=true)

NOTA: nel caso in cui, durante la scrittura del valore dell'etichetta oggetto/testo della notifica, si compiano errori di sintassi nell'esprimere i vari segnaposto, l'automatismo non riesce ad effettuare una corretta sostituzione di tutti i valori. Non vi è un feedback su quale errore viene compiuto nello specifico, ma alcune parti o tutto il testo della notifica possono presentare i segnaposti originali non risolti. Gli errori più frequenti possono essere: numero di parentesi aperte/chiuse differente, utilizzo di espressioni differenti rispetto alla documentazione tecnica ufficiale.