Widget Importer
Il widget Importer permette agli utenti finali di caricare dati CSV o Excel nella tua app senza aprire il Builder. È diverso da un import una tantum che esegui tu come admin: qui operatori, partner o cittadini caricano file come parte di un workflow normale — risparmi ticket di supporto e mantieni l'inserimento bulk dentro i permessi che hai già definito.
Scenari tipici:
- un impiegato comunale carica un elenco mensile di candidati;
- un partner inserisce un aggiornamento catalogo prodotti in un portale B2B;
- un team ops reimporta righe corrette e ha bisogno di un log chiaro quando qualcosa fallisce;
- dopo l'import, gli utenti devono arrivare su una pagina di conferma o sulla schermata detail del nuovo batch.
Per un caricamento una tantum da parte di un amministratore, usa Import sull'oggetto nel Builder — vedi Import ed export nel Builder. L'import del Builder può anche creare nuovi campi dalle intestazioni CSV; il widget Importer live mappa su campi che esistono già.
Come funziona
- Trascina un widget Importer in una pagina e scegli l'oggetto di destinazione.
- Configura quali campi possono essere importati, i template, la gestione dei duplicati e la policy sugli errori (vedi sotto).
- Gli utenti caricano un file CSV o Excel (
.xlsx), confermano il mapping delle colonne (salvo se lo hai bloccato) e avviano l'import. - Bobuild elabora le righe (in modo asincrono quando il job è grande), mostra il progresso, poi esegue eventuali Task configurati e regole Follow-Up.
Mentre un job è in corso, l'UI mostra Import in progress... e fa polling fino al completamento prima di reindirizzare — così gli utenti non vengono mandati via prima che i dati siano pronti.
Le righe completamente vuote (newline finali tipici dei fogli di calcolo) vengono saltate e non creano record vuoti.
Opzioni del widget
Apri le impostazioni dell'Importer nel Builder per modellare l'esperienza di upload.
Campi e impostazioni colonna
Scegli quali campi dell'oggetto compaiono nell'importer. Per ogni campo puoi impostare:
- Column header — etichetta di intestazione attesa (predefinita: etichetta del campo)
- Column is required — rifiuta l'upload se quella colonna non è mappata
- Value is required — rifiuta le righe in cui la cella è vuota
- Map to field — per i campi Reference, quale campo dell'oggetto collegato identifica il valore nel file (predefinito: id)
- Separator — per Multiple Choice / Reference Array, carattere usato per separare i valori nella cella (predefinito: virgola)
Puoi limitare l'import ai soli campi elencati, oppure lasciare disponibili tutti i campi importabili controllando comunque ordine e impostazioni per campo.
Template
Abilita Provide downloadable CSV/Excel template così gli utenti scaricano un file con le intestazioni attese. Opzionalmente Include empty sample row in template.
On parsing errors
| Policy | Comportamento |
|---|---|
| Leave failed fields blank and continue | Inserisce la riga; le celle con errore di parsing restano vuote |
| Skip rows with parsing errors | Scarta intere le righe con qualsiasi errore di parsing |
| Abort the whole import if any parsing error is found | Dry-run preliminare; non importa se trova errori |
Duplicate/match mode
| Modalità | Comportamento |
|---|---|
| Insert; update row when id matches | Le righe nuove vengono inserite; quelle con id corrispondente aggiornano il record |
| Insert only (skip duplicates) | Non sovrascrive mai le righe esistenti |
| Update existing row when unique key matches | Abbina sui vincoli di unicità dell'oggetto e aggiorna |
CSV format defaults
Imposta Separator, Encoding e Treat NULL as empty string predefiniti. Abilita Lock format options for end users quando i partner non devono poter cambiare queste impostazioni.
Mapping e import recenti
- Require headers line — tratta sempre la prima riga come intestazioni
- Disable custom mappings — schermata di mapping in sola lettura (solo anteprima)
- Skip mapping screen when headers match — con mapping bloccati e intestazioni obbligatorie, passa direttamente da upload a import quando l'auto-map riesce
- Show recent imports on the upload screen — elenca i job recenti per questo widget
Opzioni di mapping (utenti finali)
Quando i mapping non sono bloccati, gli utenti possono ancora regolare:
- Ignore the first row (riga di intestazione), salvo se richiedi le intestazioni
- separatore e encoding (salvo se bloccati)
- Treat "NULL" as empty string
- mapping colonna → campo
Follow-Up
Apri la scheda Follow-Up per decidere dove vanno gli utenti quando il job termina (stessa pagina, pagina padre, pagina chiamante per i popup, pagina figlia o altra pagina). Puoi mostrare un messaggio di conferma (predefinito: The import job was completed.).
Se un Task durante l'import crea record collegati, i follow-up possono puntare a pagine che hanno bisogno di quei nuovi id — lo stesso pattern dei follow-up del form.
Task dopo l'import
Configura Task da eseguire su ogni record importato (o record collegati): invia e-mail, aggiorna dati collegati, memorizza il file caricato e altro. Ogni Task dell'importer può includere più azioni, come i Task di form o di oggetto. Vedi task e il widget form per i dettagli delle azioni.
Azione utile specifica dell'importer: imposta un campo file to the imported file così il CSV/Excel originale resta sul record per audit.
Log di import
Per gli import avviati dalla finestra Import del Builder, usa View import logs per ispezionare stato, mapping ed errori per riga mentre un job lungo è in corso (e dopo che termina). Quella visibilità trasforma fallimenti opachi in problemi di mapping correggibili — soprattutto su file grandi.