Overview

Import

Abilita l'importazione dati da file Excel (.xls, .xlsx) nella route corrente della tabella metadata.

Quando attivo, nel List Grid compare un pulsante in toolbar (Import XLS/XLSX) che apre il file picker e invia il file al metodo di import già disponibile lato backend.

Metadato tabella

Il toggle principale e:

md_importable

Significato: mostra/nasconde il pulsante di import nella toolbar del List Grid.

Valori: true | false.

Default: false (se assente).

Extra props (`md_props_bag`)

Le opzioni di import si configurano in extraProps.import (derivate da md_props_bag).

Snippet 1JSON

{
  "import": {
    "enabled": true,
    "skipsettings": false,
    "allowedExtensions": ["xls", "xlsx"],
    "import_type": "I",
    "commit_level": "R",

Note operative

Il pulsante e visibile se md_importable = true.
Il file e validato lato client per estensione (xls, xlsx) prima dell'upload.
L'import viene eseguito sulla route corrente (md_route_name) del datasource attivo.
skipsettings:

- false (default): apre il dialog intermedio per scegliere opzioni import prima dell'upload.

- true: salta il dialog e avvia upload/import diretto usando le opzioni già definite in md_props_bag.import.

Default consigliati nel suggest:

- use_column_captions = "C" (use column captions).

- use_descriptive_fkey = true.

UI e progress

Dopo la conferma import, si apre un dialog di progress con percentuale realtime.
Azioni disponibili:

- Continua in background: chiude il dialog e crea una notifica di progress.

- Annulla import (rollback): annulla e fa rollback.

- Stop e commit parziale: interrompe e conferma quanto fatto.

A fine import viene creata una notifica riassuntiva (stesso testo del toast); click porta alla route dell'import senza refresh se si e già sulla stessa pagina.

Tabelle con chiave MAX

Sulle route con md_primary_key_type = "MAX" (e sulla "chiave dipendente" delle chiavi composte) la chiave di ogni riga nuova e' il massimo + 1, calcolato dentro l'insert con un lock sulla tabella: righe nuove dello stesso file prendono chiavi consecutive e inserimenti contemporanei non collidono. Il lock resta fino alla fine dell'import (una transazione per file): nel frattempo gli altri inserimenti sulla stessa tabella aspettano, e su Oracle anche update e delete. Per file grandi su tabelle molto usate conviene mettere la chiave nel file, o passare la tabella a IDENTITY/SEQUENCE.

Comportamento PK esistente (import solo insert)

Se import_type = "I" e la PK del record esiste già:

l'insert viene saltato;
il record viene conteggiato nel riepilogo come “inserimenti saltati (PK esistente)”.

Colonne del file e lookup (export e import)

Export XLS e import usano le stesse regole, quindi un file esportato si reimporta così com'è.

Intestazioni

Ogni colonna ha come intestazione la sua caption (mc_display_string_in_view; se vuota, il nome della colonna).
Se nello stesso file due colonne hanno la stessa caption, a ciascuna si aggiunge il nome fisico tra parentesi: People (ContactPersonID), People (LastEditedBy). Senza collisioni le intestazioni restano quelle di sempre.
L'import riconosce una colonna dalla caption, dalla caption con il nome fisico (o il nome colonna) tra parentesi, oppure dal nome fisico / nome colonna.
Un'intestazione che corrisponde a più colonne (per esempio un file vecchio con due colonne People) viene rifiutata con l'errore "Ambiguous column": va scritta nella forma caption (nome fisico).

Colonne lookup: `fkey_mode`

md_props_bag.import.fkey_mode decide come viaggiano le colonne lookup (mc_ui_column_type = lookupByID):

Valore	Nel file	Note
`description` (default)	la descrizione del record collegato, sotto la caption	come sempre
`key`	la chiave del record collegato, sotto la caption
`both`	due colonne: la descrizione sotto la caption, la chiave sotto il nome fisico (`Ordine` + `OrderID`)	se la caption coincide con il nome fisico, la colonna descrizione diventa `caption (campo testo del lookup)`, es. `OrderID (CustomerPurchaseOrderNumber)`

L'export segue il valore della route; se fkey_mode manca vale use_descriptive_fkey (true = description, false = key).
Nel dialog di import la scelta "Colonne lookup nel file" è preselezionata dallo stesso valore e si può cambiare per il singolo import.

Da descrizione a chiave

Solo la chiave: usata così com'è.
Solo la descrizione: si cerca il record collegato con quella descrizione (campo testo del lookup).

- Un solo record: si usa la sua chiave.

- Nessun record: errore sulla riga.

- Più record con la stessa descrizione: se la riga aggiorna un record esistente e la chiave che ha già corrisponde a quella descrizione, il collegamento resta com'è (l'utente non l'ha toccato). Altrimenti, e sempre per le righe nuove, è un errore che elenca le chiavi candidate: per inserire serve la chiave, cioè key o both.

Chiave e descrizione (`both`): vale la chiave, se il suo record ha quella descrizione; se non coincidono (una delle due è stata cambiata e l'altra no) la riga va in errore.
Una chiave primaria che è anche un lookup (tabella 1:1) viene risolta prima del controllo di esistenza del record.
Con commit_level R o I un errore di lookup ferma l'import senza salvare; con C o T la riga viene saltata e l'import prosegue.

Date

Le celle data scritte dall'export (numero con formato data, come in Excel) vengono lette come date: un file esportato e reimportato senza modifiche non viene più rifiutato sulle colonne data.

Le date scritte come testo (file CSV, celle di testo del foglio) si leggono così: ISO 8601 (2026-10-13, 2026-10-13T14:30:00, 2026-10-13 14:30:00) sempre; altrimenti nel formato della cultura del server (su un server italiano 13/10/2026, su uno americano 10/13/2026). Un testo che non si legge in nessuno dei due modi fa fallire la riga con errors.input.date_not_iso, con colonna e valore nel log dell'import. Fuori dall'import (insertRecord, updateRecord, batchRecord, OData) una data inviata come testo deve essere ISO 8601: il formato locale risponde 400 errors.input.date_not_iso.