# JK6 - Per chi amministra

# JK6.1 - Importare i modelli legacy

**In una frase.** I modelli di stampa del gestionale storico si portano in GPEnext tutti insieme, dall'elenco dei modelli, senza ridisegnarli.

Anni di documenti già impaginati non si buttano. L'importazione li trasforma in modelli di GPEnext: da quel momento si aprono nel designer e si ritoccano come gli altri.

<p class="callout warning">**Attenzione.** L'importazione funziona solo se sul server c'è la cartella con i dati del vecchio programma delle stampe. Se manca, la finestra non elenca niente e dice quale delle due cose non va: la cartella non è indicata al servizio, oppure è indicata ma dentro non ci sono i modelli. In tutti e due i casi va chiesto a chi gestisce il server.</p>

1. **Apri l'importazione.** Nella pagina **Modelli di stampa** premi **Strumenti** e scegli **Import MDL**. Si apre la finestra «Import massivo da GPE» e parte da sola la ricerca nella cartella del server.
    
    ![La finestra «Import massivo da GPE» su un server dove la cartella dei vecchi modelli è indicata ma vuota](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/k-gpenext-img-importare-i-modelli-legacy-01-import-massivo.png)
    
    *La finestra «Import massivo da GPE» su un server dove la cartella dei vecchi modelli è indicata ma vuota*
2. **Guarda cosa ha trovato.** Per ogni modello vedi nome, descrizione e quali file ha accanto: il modello, lo schema dei dati, un esempio di dati. Una colonna dice se è già stato importato.
3. **Scegli e avvia.** Spunta i modelli che vuoi, o tutti insieme con la casella in alto. Avvia e aspetta la fine senza chiudere la finestra.
4. **Leggi il riepilogo.** Dice quanti modelli sono entrati, quanti sono stati saltati e quali hanno un avviso. Un avviso vuol dire che una parte del vecchio modello non è stata convertita: apri il modello nel designer e controllala.
5. **Controlla un documento importante.** Genera l'anteprima e confrontala con la stampa di sempre, prima di metterlo in uso.

## Se un modello c'è già

Importare di nuovo un modello già presente non lo sovrascrive. Con la spunta su «Aggiorna già importati» il modello riceve una **bozza**: la versione in uso resta attiva finché non pubblichi. Vedi [Pubblicare](https://gsdoc.genesyssoftware.eu/link/37942).

<p class="callout info">**Nota.** Serve il livello Utente avanzato. La schermata viene da un ambiente di prova senza i vecchi modelli: dove ci sono, al posto dell'avviso compare l'elenco.</p>

<p class="callout info">**Per chi sviluppa.**  
• La cartella si indica al servizio con la variabile `GPE_DATA_ROOT`; nell'installazione con i container è la cartella dell'host `GPE_DATA_DIR`, montata in sola lettura.  
• I vecchi modelli sono file `.mdl`, con accanto lo schema `.xsd` e un file di esempio `.xml`.  
• Passi di installazione: `devops/deploy/README.md`, paragrafo 3.7. </p>

<p class="callout info">**Per approfondire.**  
• Import MDL e file XSL-FO per l'ERP: `docs/guide/gpe-next/staff/10-import-mdl.md`</p>

# JK6.2 - Il catalogo dei modelli base

**In una frase.** I modelli base sono i modelli standard, uguali per tutte le installazioni: arrivano in un pacchetto che GPEnext carica da solo all'avvio.

Chi installa ADSWnext non deve ridisegnare fatture e bolle. Trova i modelli standard già pronti, e quando ne esce una versione nuova la riceve senza perdere le proprie modifiche.

<p class="callout warning">**Attenzione.** Sul server di prova il catalogo non è ancora caricato: il meccanismo c'è, il pacchetto è da mettere al suo posto.</p>

## Come funziona

1. **Chi mantiene i modelli standard li pubblica** e ne esporta il catalogo: un solo file, con un numero di versione.
2. **Il file si mette in una cartella del server**, quella indicata nell'installazione.
3. **All'avvio GPEnext lo legge.** Se il contenuto è diverso dall'ultimo caricato, aggiorna i modelli base. Se è lo stesso, non fa niente.
4. **Le personalizzazioni restano.** Chi ha una copia personalizzata di un modello base la tiene. Sulla copia compare l'avviso che c'è un aggiornamento disponibile, oppure obbligatorio.

## Cosa c'è dentro

Il pacchetto porta i modelli base **pubblicati** (mai le bozze), le loro versioni, gli schemi dei dati, i file di esempio e le immagini che i modelli usano.

## Cosa controllare

- **Cartella vuota o file assente**: nessun modello base, ma il servizio parte lo stesso.
- **File alterato o incompleto**: GPEnext se ne accorge e non parte. Va rimesso il file giusto.
- **Quale catalogo è caricato**: il servizio lo dice (versione, quando è stato caricato, quanti modelli).

<p class="callout info">**Per chi sviluppa.**  
• Il file si chiama `catalogo-gpe.json.gz` e sta nella cartella indicata da `GPE_CATALOGO_DIR`.  
• Il controllo è un'impronta del contenuto: all'avvio viene ricalcolata e confrontata con quella dichiarata.  
• Stato: `GET /api/gpe/catalogo/stato`. Esportazione, solo per lo staff: `POST /api/gpe/catalogo/esporta`.  
• Codice: nel servizio `backend/middleware/it_gsba_gpe_next`, pacchetto «catalogo». </p>

<p class="callout info">**Per approfondire.**  
• Catalogo dei modelli base di GPE-NEXT: `docs/gpe-next/CATALOGO.md`</p>

# JK6.3 - Se qualcosa non va

**In una frase.** I problemi più comuni con le stampe, come «vedo questo, faccio questo», e le parole da sapere.

Quasi sempre il gestionale dice già cosa non va: il pulsante grigio ha un suggerimento, l'avviso ha un motivo. Qui trovi cosa fare dopo averlo letto.

## Quando stampi

- **Il pulsante della stampa o l'uscita `GPE_NEXT_PDF` sono grigi.** Passa il mouse sopra: dice perché. Se GPEnext non risponde, avvisa chi gestisce il server. Se è il tuo livello, chiedi almeno il livello Lettore.
- **Ieri avevo scelto `GPE_NEXT_PDF`, oggi non c'è più.** È voluto: l'uscita e **ANALISI** si scelgono a ogni lancio.
- **Al posto del PDF vedo la stampa grezza e un avviso.** Manca il modello: vedi [Se manca il modello](https://gsdoc.genesyssoftware.eu/link/37932).
- **Sopra la stampa di sempre leggo «PDF con `GPE-NEXT` non fatto».** Il server l'ha mandata già impaginata: chiedi a chi lo gestisce una stampante XML che mandi i dati.
- **L'avviso dice che il PDF non è riuscito.** Leggi il motivo. Premi **Riprova** quando il servizio è tornato. Con **Mostra XML** hai comunque i dati.
- **Ho cambiato il modello ma il PDF è uguale a prima.** Hai salvato? Se il modello si pubblica, hai premuto **Pubblica**? Poi premi **Rigenera**.
- **Non vedo «Modifica il modello».** Serve il livello Utente base.

## Nel designer

- **Non trovo le impostazioni della pagina.** C'è qualcosa di scelto: premi Esc.
- **Una tabella è segnata «oltre la pagina».** Sceglila e premi **Adatta**, o stringi le colonne.
- **«Genera» chiede un file di dati.** Il modello non ha dati di esempio: scegline uno nel pannello **Dati**.
- **L'anteprima dice che il servizio dei PDF non risponde.** Il modello non c'entra: riprova fra qualche minuto, poi avvisa chi gestisce il server.
- **Il nome del modello nuovo non viene accettato.** È già usato: prendi quello che la finestra propone.

## Loghi e ditte

- **Sul documento manca il logo.** Controlla nel centro ditte che la ditta abbia il logo e che il codice sia uguale a quello del gestionale.
- **Il modello nuovo è nato senza il posto per il logo.** Il logo è stato caricato dopo: aggiungi dal designer un'immagine «Logo ditta».

## Per chi amministra

- **GPEnext non parte.** Controlla i dati di collegamento al suo archivio e il file del catalogo: vedi [Il catalogo dei modelli base](https://gsdoc.genesyssoftware.eu/link/37946).
- **L'importazione non elenca niente.** La finestra dice se la cartella dei vecchi modelli non è indicata o se è vuota: vedi [Importare i modelli legacy](https://gsdoc.genesyssoftware.eu/link/37945).

## Parole da sapere

- **Modello.** Lo stampo di un documento: dove vanno logo, testi, tabelle e totali.
- **Documento.** Un tipo di stampa, con il suo nome. Può avere più modelli.
- **Designer.** La pagina dove si disegna un modello.
- **Testa, corpo, piede.** Le tre fasce del foglio. Testa e piede si ripetono su ogni pagina.
- **Bozza.** Un modello cambiato ma non ancora messo in uso.
- **Pubblicare.** Mettere in uso una versione del modello.
- **Modello base.** Un modello standard, uguale per tutti. Si personalizza facendone una copia.
- **Centro ditte.** Dove ogni ditta ha codice, logo e dati per le stampe.
- **Uscita.** Dove va a finire una stampa del gestionale storico: qui, `GPE_NEXT_PDF`.
- **Livello.** Quello che puoi fare: Lettore stampa, Utente base crea e ritocca i suoi modelli, Utente avanzato usa tutto il designer.

<p class="callout info">**Per chi sviluppa.** Per una stampa da SBHweb che non riesce: **Opzioni › Strumenti › Trace del protocollo** e filtra le righe della stampa. Dicono documento, stato e codice di ogni tentativo. Installazione e variabili: `devops/deploy/README.md`, paragrafo 3.7. Nessun PDF da nessuna parte: il contenitore `gpe-gotenberg` può restare bloccato dopo un avvio non riuscito (memoria), va riavviato.</p>