pierpaolo.mammi eec3a620c9 PROPOSTA_CCT_OPERATORE: aggiornamento valori percentuali delle ritenute
## Description

Aggiornamento dei valori numerici delle percentuali di ritenuta a seguito di entrata in vigore di nuovo regolamento.

### Reason

Il nuovo regolamento specifica nuovi valori per le percentuali di ritenute da applicare sulle istanze di Proposta Contratto Conto Terzi / Convenzione inseriti tramite elixForms.

Allo stato attuale esistono le seguenti percentuali di ritenute:

- Contratto economico
  - Ritenuta pari al 3% da destinare all'Amministrazione dell'Ateneo (per conto terzi)
  - Ritenuta pari al 4% Fondo Comune di Ateneo (per conto terzi)
  - Ritenuta pari al 1% "Welfare integrativo" (per conto terzi)
  - Eventuale ulteriore ritenuta deliberata dalla struttura, fino a un massimo del 2% del corrispettivo
- Contratto non economico
  - Ritenuta pari al 6% da destinare all'Amministrazione dell'Ateneo (per conto terzi)
  - Ritenuta pari al 8% Fondo Comune di Ateneo (per conto terzi)
  - Ritenuta pari al 2% "Welfare integrativo" (per conto terzi)
  - Eventuale ulteriore ritenuta deliberata dalla struttura, fino a un massimo del 2% degli overheads

Per le ritenute da destinare ad Amministrazione, Fondo Comune e Welfare sono già previsti campi specifici dove vengono salvati i valori di default.
Per l'ulteriore ritenuta esiste un unico campo condiviso da entrambe le tipologie di contratto.
Tali valori vengono inoltre riportati in forma testuale in vari punti del modulo:

- label dei campi di inserimento valori
- messaggi di warning in fase di compilazione
- template per la generazione automatica in PDF delle determine

### Implementazione

Per una migliore manutenibilità del modulo per futuri aggiornamenti:

- Separazione in due campi differenti del valore massimo percentuale per le ulteriori ritenute e opportuna modifica dove necessario
- Aggiornamento dei template di determina in modo che nel testo vengano inseriti i valori presi dal modulo
- Aggiornamento del codice EFTL per produrre messaggi dinamici recuperando dinamicamente i valori presi dal modulo

Altro:

- Aggiornamento manuale delle label dei campi relativi

### Remarks

Non è possibile implementare unit test.

## Co-authors

N/A

## Check-lists

### Common

- [ ] At least 1 unit-test added.

### Database

N/A
Reviewed-on: #1
2026-09-08 12:31:57 +02:00
2026-06-18 16:21:15 +02:00
2026-09-03 14:58:52 +02:00

ElixForms Moduli

Repository per l'archiviazione e il versionamento dei moduli ElixForms dell'Università di Parma.

Il progetto automatizza l'esportazione dei moduli dalla console ElixForms e affianca a ogni file .elx una rappresentazione testuale dei suoi contenuti. In questo modo configurazioni, form, traduzioni e validazioni possono essere consultate e confrontate tramite Git senza dover analizzare direttamente il file di export completo.

Prerequisiti

L'ambiente operativo previsto è Windows. Prima dell'installazione sono necessari:

  • Git;
  • PowerShell 7.4 o successivo, disponibile tramite il comando pwsh;
  • Node.js 20 o successivo, con npm disponibile nel PATH;
  • Google Chrome, utilizzato in modalità headless per l'esportazione;
  • accesso di rete alla console ElixForms UniPR e credenziali abilitate al backoffice.

Installazione e preparazione

Clonare il repository e posizionarsi nella sua directory:

git clone https://gitea.unipr.it/elixForms/elixforms-moduli.git
cd elixforms-moduli

Avviare quindi la preparazione dell'ambiente:

.\setup-environment.bat

Lo script:

  1. richiede i valori mancanti per ELIXFORMS_USERNAME, ELIXFORMS_PASSWORD ed ELIXFORMS_MODULE_TAG;
  2. salva la configurazione locale nel file .env in radice;
  3. installa con npm le dipendenze degli strumenti presenti in tools/extract-elx, tools/playwright e tools/selenium.

Il file .env è escluso da Git e non deve essere aggiunto al repository, perché contiene credenziali. ELIXFORMS_MODULE_TAG completa la configurazione richiesta dagli strumenti di automazione; i launcher di esportazione sostituiscono questo valore, solo per l'esecuzione corrente, con il tag ricevuto come argomento o inserito interattivamente.

Per modificare successivamente la configurazione è possibile aggiornare .env oppure eseguire di nuovo setup-environment.bat dopo aver svuotato il valore interessato.

Utilizzo

Esportare ed estrarre un modulo

Il comando principale esegue l'intero flusso per un tag ElixForms:

.\export-and-extract-elx.bat NOME_TAG_MODULO

Se il tag non viene specificato, il launcher lo richiede in modo interattivo. Il risultato viene salvato in:

src/NOME_TAG_MODULO/
├── elxforms_<ID>.elx
└── elxforms_<ID>_internals/

È consigliabile controllare con git diff sia il file .elx sia la directory _internals prima di creare un commit.

Comandi disponibili

Comando Funzione
export-and-extract-elx.bat <TAG> Esporta il modulo e ne rigenera subito i contenuti estratti.
export-elx.bat <TAG> Esporta soltanto il file .elx dalla console.
extract-elx-internals.bat <TAG> Rigenera _internals per il modulo indicato.
extract-elx-internals-last-updated.bat Estrae il file .elx modificato più di recente sotto src.
extract-elx-internals-all.bat Rigenera i contenuti estratti di tutti i file .elx sotto src.
convert-url-to-elix.bat <URL_ASSOLUTO> Converte un URL nel formato richiesto dalle chiamate remote/autocomplete di ElixForms.

I comandi che accettano un argomento possono essere avviati anche senza parametri; in tal caso ne richiedono il valore da tastiera.

Struttura del repository

.
├── src/                         # Moduli esportati e relative rappresentazioni estratte
├── scripts/                     # Orchestrazione PowerShell e funzioni condivise
├── tools/
│   ├── extract-elx/             # Scomposizione del JSON .elx
│   ├── selenium/                # Automazione dell'export dalla console
│   └── playwright/              # Implementazione alternativa dell'automazione
├── .env.template                # Elenco delle variabili di configurazione
├── setup-environment.bat        # Preparazione iniziale
└── *.bat                        # Comandi operativi eseguibili da Windows

Ogni sottodirectory immediata di src identifica normalmente un modulo tramite il suo tag. Al suo interno si trovano l'export originale e la directory derivata con suffisso _internals.

Funzionamento tecnico

Esportazione dalla console ElixForms

I file .bat si posizionano nella radice del repository e delegano il lavoro agli script PowerShell in scripts. Le funzioni condivise sono raccolte in scripts/elx-tools-module.psm1.

Durante l'esportazione, PowerShell legge le credenziali da .env, applica il tag ricevuto dal comando e avvia lo strumento Selenium con le variabili d'ambiente necessarie. Selenium apre Chrome in modalità headless e svolge queste operazioni:

  1. accede al backoffice ElixForms UniPR;
  2. cerca il modulo tramite il tag;
  3. apre la funzione di esportazione e include i dati di protocollo;
  4. scarica il file elxforms_<ID>.elx;
  5. sposta il file da tools/selenium/downloads a src/<TAG>.

Se la directory del tag non esiste, viene creata automaticamente. La ricerca usa il primo risultato restituito dalla console: è quindi importante utilizzare un tag completo e non ambiguo.

Il percorso richiamato dai launcher usa Selenium. In tools/playwright è mantenuta anche un'implementazione alternativa dello stesso flusso, non collegata ai comandi .bat principali.

Estrazione dei contenuti .elx

Un file .elx è un documento JSON che contiene, nelle proprietà di primo livello, molte parti eterogenee del modulo. Lo strumento Node.js tools/extract-elx/extract-elx.js lo scompone in una directory omonima con suffisso _internals.

Per ciascuna proprietà radice:

  • le stringhe XML sono riconosciute e formattate in file .xml;
  • le altre stringhe sono salvate come .txt;
  • gli oggetti sono serializzati come JSON indentato;
  • gli array producono un indice e un file separato per ogni elemento;
  • eventuali frammenti XML contenuti negli oggetti vengono estratti anche in file dedicati.

Per alcune collezioni, tra cui step, tab, schemi, validazioni e traduzioni, i nomi dei file derivano da identificatori funzionali contenuti nei dati. Gli elementi vengono inoltre ordinati quando è disponibile una chiave significativa. Questi accorgimenti mantengono stabile l'output tra due esportazioni e rendono i diff Git più leggibili.

Ogni estrazione genera anche:

  • _manifest.json, con tipo e numero di file prodotti per ciascuna proprietà;
  • crc32.txt, con il checksum CRC32 del file .elx sorgente;
  • file index.* che rappresentano valori singoli o descrivono il contenuto delle collezioni.

Gli script PowerShell richiamano l'estrattore con l'opzione --clean: la directory _internals esistente viene eliminata e ricreata a partire dal file .elx. Di conseguenza, non deve contenere modifiche manuali da preservare; la sorgente autorevole resta l'export .elx ottenuto dalla console.

Conversione degli URL

convert-url-to-elix.bat trasforma un URL assoluto nel formato usato dai servizi remoti ElixForms. Il dominio e il percorso vengono normalizzati secondo la convenzione della piattaforma, mentre i parametri di query vengono conservati, nello stesso ordine, nell'oggetto JSON restituito dal comando.

S
Description
No description provided
Readme
4.5 MiB
0 Stars 4 Watchers 0 Forks
Languages
HTML 42.2%
JavaScript 30.1%
PowerShell 18.6%
TypeScript 4.8%
Batchfile 4.3%