Questo software è parte del progetto ePAS, il sistema di rilevazione e gestione delle presenze sviluppato dal CNR.
Questo client si occupa di leggere da un file di testo contenente le timbrature (una per riga) oppure via FTP da un lettore di badge di tipo SmartClock (o con interfaccia compatibile). Il software effettua il parsing delle timbrature in funzione di un'espressione regolare configurabile e le invia via REST al server di ePAS. Nel caso di timbrature su file questi ultimi possono risiedere in locale sul server che ospita questo software oppure essere prelevate via FTP o SFTP.
Il software è distribuito come immagine Docker configurata per accedere a scadenza regolare al lettore badge o ai file contenente le timbrature ed inviare via REST le nuove timbrature al server di ePAS. Nell'immagine docker sono presenti anche i cron che servono per re-inviare notte tempo le timbrature che non è stato possibile inviare ad ePAS durante le letture giornaliere delle timbrature.
Consigliamo di creare una nuova macchina virtuale che contenga solamente il client che si interfaccerà con il lettore badge presso la vostra sede e che dovrà inviare al server centralizzato di ePAS le timbrature opportunamente normalizzate perchè il server possa correttamente interpretarle ed assegnarle al dipendente.
- CPU: 1 core è sufficiente
- Memoria: 1 GB di ram
- Storage: 10GB di Hard Disk
- 10GB consentono di contenere i vari file di log e le eventuali timbrature da reinviare con tranquillità
- Sistema operativo supportato: Ubuntu 18.04 LTS o superiori
- Docker installato
- Docker-compose installato
- aver configurato una sorgente timbratura su ePAS per la propria sede
Requisiti in caso di utilizzo smartclock
- accesso alla porta FTP del lettore badge (in caso di utilizzo dello smartclock)
Requisiti in caso di timbrature prelavate da servizio ftp/sftp remoti
- accesso alla porta del servizio ftp/sftp del servizio
- conoscere il tracciato record delle timbrature per poterne configurare il parsing
- i nomi dei file contenenti le timbrature devono essere ordinati lessicongraficamente per data, per esempio: 2020-11-05.txt, 2020-11-06.txt (il client utilizza l'ordine dei file per leggere le timbrature dai file successivi)
Requisiti in caso di timbrature prelavate da directory locale
- aver accesso alla directory contenente le timbrature da parte dell'utente che avvia il client
- conoscere il tracciato record delle timbrature per poterne configurare il parsing
- la directory con le timbrature deve essere "montata" all'interno del container, vedere per esempio https://github.com/consiglionazionaledellericerche/epas-client/blob/main/docker-compose.yml#L15
- i nomi dei file contenenti le timbrature devono essere ordinati lessicograficamente per data, per esempio: 2020-11-05.txt, 2020-11-06.txt (il client utilizza l'ordine dei file per leggere le timbrature dai file successivi)
L'installazione e configurazione consigliata per il deploy è quella via Docker / Docker-compose.
I passi da compiere sono:
- creare un utente epas (o con altro nome a vostro piacimento)
- aggiungere l'utente epas al gruppo docker
(altrimenti non può usare i comandi docker)
$ sudo adduser epas docker - creare una directory epas-client nella home dell'utente epas (es. /home/epas/epas-client)
- creare una directory data nella cartella creata al punto precedente (es. /home/epas/epas-client/data)
- copiare il file docker-compose.yml ed il file .env nella directory /home/epas/epas-client
- configurare il .env seguendo i commenti già presenti nei file di esempio, oppure consultando il paragrafo successivo
- gli ulteriori parametri configurabili nel file docker-compose.yml sono da configurare solo in casi eccezionali
| Parametro | Descrizione | Obbligatorio | Default |
|---|---|---|---|
| STAMPINGS_SERVER_PROTOCOL | Definisce la modalità con cui il client preleva le timbrature da inviare al server. I possibili valori sono: smartclock, local, ftp, sftp. Alcuni dei parametri successivi dipendendono da questo parametro e specificano le informazioni necessarie all'accesso alla timbrature in funzione della modalità scelta. NOTA: nel caso si utilizzi la modalità smartclock è necessario configurare nel docker-compose.yml il volume che effettua il mapping della cartella locale contenente le timbrature: |
SI | Nessun default |
| PARAMETRI PER L'INVIO TIMBRATURE AD EPAS | |||
| SERVER_HOST | Host del server di ePAS. Esempio: epas-demo.devel.iit.cnr.it | SI | Nessun default |
| SERVER_PROTOCOL | Protocollo per l'invio delle timbrature al server di ePAS. Possibili valori: http, https | NO | https |
| SERVER_PORT | Porta del server di ePAS. Solitamente la porta per le comunicazioni via https è la 443 | NO | 443 |
| EPAS_CLIENT_USER | Utente della "sorgente timbrature" di ePAS. | SI | Nessun default |
| EPAS_CLIENT_PASSWORD | Password della "sorgente timbrature" di ePAS | SI | Nessun default |
| PARAMETRI PER SMARTCLOCK | |||
| BR_IP_ADDRESS | Indirizzo IP del lettore badge | SI per modalità smartclock | Nessun default |
| BR_PORT | Porta del servizio FTP configurato sul lettore badge | NO | 21 |
| BR_USER | Utente del lettore bagde | SI per modalità smartclock | Nessun default |
| BR_PASSWORD | Password del lettore badge | SI per modalità smartclock | Nessun default |
| PARAMETRI PER FILE DA FTP/SFTP SERVER | |||
| FTP_SERVER_NAME | Indirizzo IP del server ftp/sftp | SI per modalità ftp/sftp | Nessun default |
| FTP_SERVER_PORT | Porta del servizio ftp/sftp | NO | 21 |
| FTP_USERNAME | Utente per l'accesso al servizio ftp/sftp | SI per modalità ftp/sftp | Nessun default |
| FTP_PASSWORD | Password per l'accesso al servizio ftp/sftp | SI per modalità ftp/sftp | Nessun default |
| FTP_SERVER_DIR | Directory del servizio ftp/sftp contenente le timbrature | NO | . |
| FTP_FILE_PREFIX | Prefisso del nome dei file da cui prelevare le timbrature. Si applica alle modalità local/ftp/sftp. Tutti i file il cui nome non inizia con questo prefisso verranno scartati. | NO | 20 |
| FTP_FILE_SUFFIX | Suffisso del nome dei file da cui prelevare le timbrature. Si applica alle modalità local/ftp/sftp. Tutti i file il cui nome non termina con questo prefisso verranno scartati. | NO | vuoto, nessun suffix |
| REGEX_STAMPING | Espressione regolare utilizzata per effettuare il parsing delle righe contenenti le timbrature. La regex di default è per SmartClock ed è la seguente: ^(?P<operazione>[0,E,U,T])(?P<tipo>\w{1})(?P<giornoSettimana>\d{1})(?P<matricolaFirma>\d{9})(?P<causale>\d{4})(?P<ora>\d{2})(?P<minuti>\d{2})(?P<secondi>\d{2})(?P<giorno>\d{2})(?P<mese>\d{2})(?P<anno>\d{2})(?P<lettore>\d{2})$. Nel caso il file contenente le timbrature utilizzi un tracciato record diverso è necessario scrivere la propria regex che rappresenti la timbratura e permetta di estrarre almeno i gruppi della regex (sono obbligatori: operazione, matricolaFirma, causale, ora, minuti, mese, anno) presenti nell'esempio sopra riportato relativo al formato utilizzato dagli Smartclock. Per facilitare a scrivere la regex potete utilizzare un sistema online come questo https://regex101.com/ |
NO | ^(?P<operazione>[0,E,U,T])(?P<tipo>\w{1})(?P<giornoSettimana>\d{1})(?P<matricolaFirma>\d{6})(?P<causale>\d{4})(?P<ora>\d{2})(?P<minuti>\d{2})(?P<secondi>\d{2})(?P<giorno>\d{2})(?P<mese>\d{2})(?P<anno>\d{2})(?P<lettore>\d{2})$ |
| PARAMETRI PER LA CONFIGURAZIONE DELL'INVIO DELLE METRICHE | |||
| METRICS_ENABLED | Attiva l'invio delle metriche di un client ad un Pushgateway Prometheus | NO | False |
| METRICS_PUSHGATEWAY_URL | Url del PushGateway a cui inviare le metriche | SI se attivate le metriche | |
| METRICS_PUSHGATEWAY_USER | Utente per l'autenticazione con il PushGateway | NO | |
| METRICS_PUSHGATEWAY_PASSWORD | Password per l'autenticazione con il PushGateway | NO | |
| Parametri generici generalmente da non impostare | |||
| OFFSET_ANNO_BADGE | Nel tracciato record delle timbrature spesso l'anno è indicato con le sole due cifre finale (es. 20 per 2020). Questo parametro permette di riportare la data nel formato completo a quattro cifre, il software somma questo offset all'anno estratto dal tracciato record delle timbrature. | NO | 2000 |
| CHECK_SUCCESS_MSG | Parametro per gli smartclock, permette di attivare/disattivare il controllo dei messaggi del lettore. Parametro da modificare solo in casi eccezionali per vecchi lettori. Possibili valori sono True o False | NO | True |
| LOG_LEVEL | Livello di log, possibili valori sono DEBUG, INFO, WARNING, ERROR | NO | INFO |
| MAX_THREADS | Eventuale livello di parallelizzazione nell'invio delle timbrature. Si consiglia di non modificare il default. | NO | 1 |
| CRON | Crono che definisce ogni quanto vengono inviate le timbrature. utilizzare il formato richiesto dal crontab. Riferimenti -> https://en.wikipedia.org/wiki/Cron#Examples | NO | */15 6-23 * * * (ogni 15 minuti dalle 6 alle 23) |
| CRON_RANDOM_SLEEP | Secondi di sleep random massimo prima di lanciare (via cron) il client per le timbrature. Questo tempo random serve per evitare che tutte le timbrature arrivino contemporaneamente al server di ePAS. | NO | 180 |
| PROBLEMS_CRON | Cron che definisce l'invio di tutte le timbrature non inviate correttamente a epas (badge non trovato o altri problemi). | NO | -0 1 * * * (all'una di notte) |
| MAX_BAD_STAMPING_DAYS | Tutte le timbrature con problemi, più vecchie di questo numero di giorni dal momento dell'esecuzione, vengono buttate via. | NO | 10 |
| SERVER_ERROR_CODES | Identifica i codici HTTP di risposta da parte di ePAS all'inserimento di una timbratura per cui è opportuno che la timbratura venga re-inviata al server per un nuovo tentativo di inserimento. Specificare i valori separati da virgola che comportano un re-invio delle timbrature. | NO | 401, 404, 500, 501, 502, 503, 504, 505, 506, 507, 508, 509 |
| MAPPING_OPERAZIONE_CLIENT_SERVER | Specifica, in formato dizionario Python, l'eventuale mapping tra il valore dell'operazione di entrata/uscita letto dalla timbratura e quello aspettato da ePAS (0 per l'ingresso, 1 per l'uscita). | NO | {'E':'0','U':'1'} |
| MAPPING_CAUSALI_CLIENT_SERVER | Specifica, in formato dizionario Python, l'eventuale mapping tra la causale della timbratura letta dalla timbratura e le causali attese da ePAS (motiviDiServizio, pausaPranzo sono le uniche due supportate al momento da ePAS). | NO | {'0000': None, '0001': 'motiviDiServizio', '0007': 'pausaPranzo'} |
Una volta configurato il file docker-compose.yml ed il file .env è possibile
verificare che la configurazione docker-compose.yml sia corretta con il comando
$ docker-compose config.
Se la configurazione è corretta per avviare il client lanciare il comando
$ docker-compose up -d.
Tramite il docker-compose.yml il container del client è già configurato per riavviarsi automaticamente in caso di riavvio della macchina virtuale ospitante il client.
La directory /home/epas/epas-client/data contiene:
- la directory log con i log del client
- la directory archives con i file scaricati nel tempo dal lettore badge (in caso di utilizzo modalità smartclock)
- il file info/last_request.txt che contiene la data ed ora dell'ultima timbratura prelevata dal client (in caso di utilizzo modalità smartclock)
- il file info/ultimo_file.txt che contiene il nome dell'ultimo file letto, le sue dimensioni e l'ultima riga letta (in caso di utilizzo modalità local, ftp, sftp)
In caso di necessità è possibile retrodatare il prelevamento delle timbrature modificando opportunamente il file info/last_request.txt o il file info/ultimo_file.txt (in funzione della modalità di prelevamento timbrature utilizzata).
Per verificare che il container docker sia attivo, da dentro la directory
/home/epas/epas-client, utilizzare il comando $ docker-compose ps.
Per riavviare il servizio utilizzare il comando $ docker-compose restart.
Se volete entrare nel container per verificarne il contenuto potete utilizzare
il comando $ docker-compose exec client bash.
Se, senza entrare nel container, volete lanciare un'acquisizione immediata delle
timbrature potete utilizzare il comando
$ docker-compose exec client /client/executeClient.sh.