= Appunti sull'implementazione =
Una tabella di destinatari delle email strutturata come segue
{| border=1 cellspacing=0
!Nominativo
!Email
!Gruppo 1
!Gruppo 2
!...
|-
|Alessandro Forlani
|alessandro.forlani@myemail.it
|(((√)))
|
|
|-
|...
|}

Per l'invio è stata utilizzata la libreria JavaMail (javax.mail.*).
= Guida all'utilizzo =
'''Importare la libreria''' di JSup <TT>L:\SUPERVIS\JSup\Librerie\InvioEmailAllarmi.jsupLib</TT> nell'applicazione in cui si vuole gestire l'invio delle email di allarme.

Nello script di Startup, sia del dominio shared che del dominio user, chiamare <TT>initMailSend()</TT>.

In JSup definire la '''proprietà''' <TT>sendemail.group=xxx</TT> (facendo riferimento alla tabella sopra ''xxx'' potrebbe essere ''Gruppo 1'' o ''Gruppo 2'') per i '''gruppi allarme''' per i quali si desidera che venga inviata l'email.
<!-- Definire una proprietà <TT>sendemail.priorityfilter=1..99</TT> per filtrare gli allarmi del gruppo in base alla priorità.
 -->Eventualmente definire la proprietà <TT>sendemail.group=none</TT> (oppure un altro gruppo) per i sottogruppi allarmi per i quali si vuole disabilitare l'invio (oppure specificare un altro gruppo).

Nel file di '''configurazione di JSup''' (<TT>C:\Program Files (x86)\JSup\JSup.cfg</TT>) del PC che dovrà inviare le email definire il server SMTP per l'invio della posta, definendo la proprietà <TT>-Dmail.smtp.host=smtp.server.boh</TT>.

Nelle [JSup Application properties#Properties|'''proprietà dell'applicazione'''] JSup definire varie proprietà:
%blue%<TT>alarm.sendemail.default.</TT>%blue%
 * %blue%<TT>.collectMinTime</TT>%blue% = tempo minimo in minuti per il quale il sistema registra le email per un gruppo di invio, ma non le invia.
 * %blue%<TT>.collectMaxTime</TT>%blue% = tempo minimo in minuti per il quale il sistema registra le email per un gruppo di invio, ma non le invia.
 * %blue%<TT>.repetitionCheckTimeLen</TT>%blue% = intervallo di tempo (in minuti) considerato per analizzare gli allarmi ripetuti.
 * %blue%<TT>.repetitionMaxCount</TT>%blue% = numero massimo di ripetizioni nell'intervallo di tempo specificato da <TT>repetitionCheckTimeLen</TT>.
 * %blue%<TT>.longRepetitionMaxCount</TT>%blue% = numero di ripetizioni ammesse senza che tra due eventi trascorra almeno repetitionCheckTimeLen; raggiunto questo numero di eventi si ritiene che sia intervenuta un '''ripetizione lunga''' e interviene il long filter che utilizza <TT>longRepetitionMaxCount</TT> al posto di <TT>repetitionMaxCount</TT> e <TT>repetitionCheckTimeLenOnLongRepetition</TT> al posto di <TT>repetitionCheckTimeLen</TT>. <br/>Una volta che interviene il long filter, occorre che non avvengano eventi per il tempo specificato da <TT>repetitionCheckTimeLenOnLongRepetition</TT> perché il filtro torni a funzionare con i parametri soliti (e non quelli 'long').<br/>Se questo valore è pari a zero (default), non viene attivato il filtro per ripetizioni lunghe.
 * %blue%<TT>.repetitionCheckTimeLenOnLongRepetition</TT>%blue% = durata della finestra di tempo utilizzata per il controllo ripetizioni durante una ripetizione lunga (default 4 volte <TT>repetitionCheckTimeLen</TT>).
 * %blue%<TT>.repetitionMaxCountOnLongRepetition</TT>%blue% = numero di ripetizioni delle email ammesse nell'intervallo specificato da repetitionCheckTimeLen durante una ripetizione lunga (default <TT>1</TT>).
 * <TT>%blue%.priorityFilter%blue%=1..99</TT> specificando, ad esempio, <TT>20</TT> vengono inviati via email solo gli eventi relativi ad allarmi con priorità minore di 20 (compreso).
 * %blue%<TT>.sendForOff</TT>%blue% = 1|0 per abilitare/disabilitare l'invio delle email per eventi ritorno normale.
 * %blue%<TT>.sendForAck</TT>%blue% = 1|0 per abilitare/disabilitare l'invio delle email per eventi di acquisizione allarmi.
 * %blue%<TT>.sendUnackOnly</TT>%blue% = 1|0 per abilitare o meno la modalità di invio per la quale vengono inviati solo gli allarmi non acquisti (anche quelli già inviati).
 * %blue%<TT>.eventStateEvaluationPeriod</TT>%blue% = imposta ogni quanti millisecondi viene eseguita la [#Gestione notifica allarmi] (default <TT>5000ms</TT>).
 * %blue%<TT>.debugEventStates</TT>%blue% = 1|0 per abilitare/disabilitare il debug del handler per la [#Gestione notifica allarmi]).
 * %blue%<TT>.eventAcceptFilterJavaCodeFunction</TT>%blue% = (superata: vedere [#Gestione notifica allarmi]) Nome di una [JavaCode functions] (definita nel [Domini di JSup|dominio shared]) con firma:<br/><TT>boolean fName(String groupName, AlarmRef alarm, AlarmEvent.EventType eventType)</TT><br/>che verrà chiamata per accettare gli eventi allarme da inviare via email. Questa funzione deve ritornare <TT>true</TT> per accettare un evento (e far inviare l'email al momento oppportuno) o <TT>false</TT> per rifiutare un evento e non inviare l'email. La funzione viene chiamata solo se altri criteri relativi all'invio delle email per il gruppo sono soddisfatti: <TT>sendForOff</TT>, <TT>sendForAck</TT>, <TT>priorityFilter</TT>.
 * %blue%<TT>.from</TT>%blue% = indirizzo email del mittente dei messaggi email inviati da [JSup] con gli allarmi.
 * %blue%<TT>.subject</TT>%blue% = titolo di messaggi email inviati.
 * %blue%<TT>.body</TT>%blue% formato per il corpo dell'email per default è <TT>''Elenco eventi allarmi %2$:\\n%3$s''</TT>; la sintassi è la medesima usata in <TT>String.format()</TT>; i parametri inseribili sono:
  * 1 = il nome del gruppo;
  * 2 = la descrizione del gruppo (si veda sotto la proprietà <TT>alarm.sendemail.group_antincendio.body</TT>);
  * 3 = la lista degli allarmi da inviare.
  * <TT>{[JSup Math code|math expression]}</TT> (senza '%' e '$') Espressione matematica il cui risultato (di solito una stringa) viene sostituito all'espressione tra graffe, questo permette di inserire del codice condizionale e il valore corrente di [JSup tag|tag].
 * %blue%<TT>.event.ACTIVE|NORMAL|ACKNOWLEDGE</TT>%blue% = Testo da visualizzare al posto degli stati in inglese degli allarmi con il parametro %4$s di format.
 * %blue%<TT>.format</TT>%blue% formato da utilizzare per comporre la linea con gli allarmi, la sintassi è la medesima usata in <TT>String.format()</TT>; i parametri utilizzabili sono i seguenti:
{|
|width=45|
|<expandible>Visualizza parametri:
 * 1 = date
 * 2 = time
 * 3 = tag name
 * 4 = state
 * 5 = priority
 * 6 = alarm name
 * 7 = alarm group name
 * 8 = alarm description
 * 9 = time: custom formattable</code>
 * 10 = username (only for acknowledge events)
 * 11 = user comment (only for acknowledge events)
 * 12 = user hostname (only for acknowledge events)
 * 13 = username@hostname: comment (only for acknowledge events)
 * 14 = last active/non active state change date
 * 15 = last active/non active state change time
 * 16 = last active/non active state change (custom formattable)</code>
Di default il formato è "<TT>%1$s $2$s %6$20s %4$11s %5$2d %7$20s %8$s %13$s</TT>".
</expandible>
|}

Le proprietà specificate sopra possono essere '''personalizzate per un gruppo allarmi''' (per esempio ''antincendio'') utilizzando delle proprietà <TT>alarm.sendemail.group_antincendio.collectMinTime</TT> ecc.

Oltre alle proprietà elencate qui sopra per il default dei gruppi, è possibile definire:
 * %blue%<TT>.description</TT>%blue% = descrizione del gruppo allarme che è possibile inserire nel <TT>alarm.sendemail.group_antincendio.body</TT> (se non viene specificato viene usato il nome del gruppo).
 * %blue%<TT>.expireMin</TT>%blue% tempo (in minuti) dopo il quale una mail che non è stato possibile spedire (problemi con il server SMTP) verrà considerata scaduta e verrà eliminata senza essere spedita. Il valore di default è -1 che indica di utilizzare la proprietà <TT>mail.defaultExpireAfter</TT> del file di configurazione [JSup.cfg]. Impostando il valore 0 si tenterà di inviare le email immediatamente, se non è possibile la mail verrà scartata, ma verranno mantenuti gli eventi da segnalare e, all'invio successivo, sarà tentato l'invio di una nuova mail con la situazione aggiornata degli allarmi da segnalare.


Esempio di configurazione:
<code>alarm.sendemail.default.body=ALLARMI NON ACQUISITI %2$S:\n%3$s\n\nEmail inviata automaticamente dal sistema di supervisione.\nSi prega di non rispondere.
alarm.sendemail.default.collectMaxTime=10
alarm.sendemail.default.collectMinTime=1
alarm.sendemail.default.event.ACKNOWLEDGE=-ACQUISIZIONE-
alarm.sendemail.default.event.ACTIVE=----ATTIVO----
alarm.sendemail.default.event.NORMAL=--NON ATTIVO--
alarm.sendemail.default.format=%4$15s %14$s %15$s %8$s [%6$s]
alarm.sendemail.default.from=allarmi.plantname@customer.com
alarm.sendemail.default.repetitionCheckTimeLen=60
alarm.sendemail.default.repetitionMaxCount=6
alarm.sendemail.default.sendForAck=0
alarm.sendemail.default.sendForOff=1
alarm.sendemail.default.sendUnackOnly=1
alarm.sendemail.default.subject=Allarme da supervisore XXXXX
alarm.sendemail.default.expireMin=2880</code>
= Gestione notifica allarmi =
E' stata aggiunta la possibilità di gestire in maniera estesa la notifica degli allarmi via email.
Questo viene fatto tramite una gestione degli stati per ogni evento, che vengono gestiti e modificati da un oggetto che implementa l'interfaccia <TT>EventCollector.EventStateHandler<AlarmEvent></TT>, ovvero il metodo
<TT>int handleEvent( final AlarmEvent event, final int currentState )</TT>
che ottiene un evento da gestire, il suo stato corrente e deve ritornare il nuovo stato (o il medesimo se non cambia).
Gli stati base sono i seguenti (si tratta di costanti <TT>int</TT>):
 * <TT>STATE_new</TT>: stato assegnato ad un evento appena creato (anche se non viene cambiato dall'handler, viene comunque cambiato in <TT>STATE_waiting</TT> al termine del primo handle)
 * <TT>STATE_forget</TT>: assegnare questo stato per far scartare l'evento, non inviarlo via email e non processarlo più.
 * <TT>STATE_waiting</TT>: stato predefinito per un evento non ancora processato (un evento in stato <TT>STATE_new</TT> passa automaticamente a questo stato se non esplicitamente cambiato al primo handle)
 * <TT>STATE_hold</TT>: l'evento è trattenuto e non viene inviato anche se avviene una notifica di eventi.
 * <TT>STATE_notifyNoTrig</TT>: richiesta di notificare l'evento, ma senza avviare un notifica per questo evento: se una notifica avverrà ci sarà anche questo evento. Assegnando questo stato, l'evento verrà tolto dall'elenco degli eventi in valutazione (handle) e passato per la notifica.
 * <TT>STATE_notify</TT>: richiesta di notificare l'evento e di avviare la notifica secondo le regole (ritardi, ripetizioni, ecc.) di questo collector
 * <TT>STATE_FIRST_CUSTOM</TT>: se si vogliono definire degli stati customizzati, il loro valore dev'essere maggiore o uguale di <TT>STATE_FIRST_CUSTOM</TT>.

Per definire e attivare l'hadler della notifica degli allarmi via email basta seguire il seguente esempio.
Nella funzione <TT>initMailSend()</TT>, prima di creare i gruppi di notifica allarmi via email (<TT>mailSendGroups = new MailSendGroups(...)</TT>), definire l'oggetto che si occuperà di gestire la notifica degli allarmi:
<code>  // impostazione filtro eventi
  final AlarmEventStateHandler aesh = new AlarmEventStateHandler();
  setAlarmNotificationStateHandler( aesh );</code>

<expandible>Esempio di implementazione di <TT>AlarmEventStateHandler</TT>
<code>private static class AlarmEventStateHandler implements EventCollector.EventStateHandler<AlarmEvent> {
  final static String caption = "EventStateHandler: ";
  public int handleEvent( final AlarmEvent event, final int currentState ) {
    try {
      int nextState = currentState;
      final AlarmRef alarm = event.getAlarmRef();
      switch( currentState ) {
        case EventCollector.Event.STATE_new:
        case EventCollector.Event.STATE_waiting:
        {
          final boolean noEmail = Tools.toBool( alarm.getProperty("noEmail", null) );
          if( noEmail ) {
            System.err.println( caption+"noEmail: "+alarm );
            nextState = EventCollector.Event.STATE_forget;
            break;
          }

          if( !event.getAlarmRef().isToAck() ) {
            if( currentState == EventCollector.Event.STATE_new ) System.err.println( caption+"acquisito: "+alarm );
            nextState = EventCollector.Event.STATE_forget;
            break;
          }

          final boolean noEmailDiSera = Tools.toBool( alarm.getProperty("noEmailDiSera", null) );
          if( noEmailDiSera && ($Hour >= 20 || $Hour < 7) ) {
            if( currentState == EventCollector.Event.STATE_new ) System.err.println( caption+"noEmailDiSera: "+alarm );
            nextState = EventCollector.Event.STATE_waiting;
            break;
          }

          if( Digital_dummy )
            nextState = EventCollector.Event.STATE_notify;

        }
      }
      return nextState;
    }
    catch( JException e ) {
      return currentState;
    }
  }
}
</code></expandible>

<expandible>Esempio 2
<code>private static class AlarmEventStateHandler implements EventCollector.EventStateHandler<AlarmEvent> {
  final static String caption = "EventStateHandler: ";
  public int handleEvent( final AlarmEvent event, final int currentState ) {
    try {
      int nextState = currentState;
      final AlarmRef alarm = event.getAlarmRef();
      switch( currentState ) {
        case EventCollector.Event.STATE_new:
        case EventCollector.Event.STATE_waiting:
        {
          final boolean noEmail = Tools.toBool( alarm.getProperty("noEmail", null) );
          if( noEmail ) {
            System.err.println( caption+"noEmail: "+alarm );
            nextState = EventCollector.Event.STATE_forget;
            break;
          }

          if( alarm.getTag().getName().equals( "A_SSL_Contatore2_com" ) ) {
            nextState = EventCollector.Event.STATE_hold;
            break;
          }

          if( alarm.getTag().getName().equals( "A_SSL_Contatore3_com" ) ) {
            nextState = EventCollector.Event.STATE_notifyNoTrig;
            break;
          }

          if( alarm.getTag().getName().equals( "A_SSL_Contatore4_com" ) ) {
            nextState = EventCollector.Event.STATE_notify;
            break;
          }

          if( !event.getAlarmRef().isToAck() ) {
            if( currentState == EventCollector.Event.STATE_new ) System.err.println( caption+"acquisito: "+alarm );
            nextState = EventCollector.Event.STATE_forget;
            break;
          }

          final boolean noEmailDiSera = Tools.toBool( alarm.getProperty("noEmailDiSera", null) );
          if( noEmailDiSera && ($Hour >= 20 || $Hour < 7) ) {
            if( currentState == EventCollector.Event.STATE_new ) System.err.println( caption+"noEmailDiSera: "+alarm );
            nextState = EventCollector.Event.STATE_waiting;
            break;
          }

          if( Digital_dummy )
            nextState = EventCollector.Event.STATE_notify;

        }
      }
      return nextState;
    }
    catch( JException e ) {
      return currentState;
    }
  }
}
</code></expandible>