Importazione file XML
Se il tuo sistema esporta ordini o indirizzi in XML, puoi importarli con la funzione Importazioni file — nello stesso modo dei file CSV, ma con un profilo di importazione XML.
La differenza rispetto al CSV sta nel modo in cui il profilo apprende i nomi dei campi:
| CSV | XML | |
|---|---|---|
| Colonna Nome campo | Un elenco a discesa, popolato dalla riga di intestazione di un file di esempio | Una casella di testo libero — il nome dell'elemento o il percorso viene digitato da te |
| File di esempio nel profilo | Sì (Carica file → Elabora file) | Non necessario — il profilo non ha un passaggio di caricamento |
| Struttura | Colonne piatte | Elementi annidati e attributi sono supportati |
Crea profilo
Prima di importare il file, è necessario creare un profilo di importazione.
- Andare a Profili → Indirizzi o Spedizioni → premere +
- Selezionare Tipo di importazione → Indirizzi o Spedizioni
- Aggiungere un Nome profilo (ad es. Ordini XML)
- Selezionare Tipo file di importazione → XML
- Compilare Elemento XML di riga (tag o XPath) — l'elemento che si ripete una volta per spedizione o indirizzo (vedi Scegliere l'elemento di riga)
Il Separatore decimale e il Delimitatore di valori multipli possono rimanere come di default (. e ,).
Elemento XML di riga è obbligatorio — senza di esso non è possibile continuare.
- Premere Continua
- Inserire nella colonna Nome campo il nome dell'elemento o il percorso di ogni campo che si desidera importare
Per i profili XML Nome campo è una casella di testo libero, non un elenco a discesa, e non è presente il pulsante Carica file / Elabora file. Digitare il nome esattamente come appare nel file — vedi Come i nomi degli elementi diventano nomi di campo.
La colonna con Funzione può rimanere invariata.
Se necessario, aggiungere una Trasformazione — creata e utilizzata quando i dati del file XML devono essere adattati per l'importazione. Ad esempio, se il nome del paese nel file è la Svizzera, ma il nostro sistema deve riceverlo nel formato ISO 3166-1 alpha-2 (CH).
Una volta inseriti tutti i nomi dei campi obbligatori (e facoltativi), premere Salva.
Campi della spedizione che puoi mappare
L'elenco dei campi che puoi compilare è esattamente lo stesso del CSV — indirizzo del mittente e del destinatario, dettagli di servizio, pacco e dogana, con le stesse lunghezze massime e gli stessi campi obbligatori. Vedi Campi della spedizione che puoi mappare nella pagina CSV.
Il peso è obbligatorio per ogni pacco — assicurati che il file XML contenga un elemento o un attributo di peso (in kg) prima dell'importazione.
Caricare il file XML
- Andare a Importazioni file
- Premere Importa file in alto a destra
- Selezionare il Profilo (il profilo XML creato al passaggio 1)
- Caricare il file
.xmle premere Importa
- Premere Aggiorna
Le informazioni importate compariranno nella rubrica o nelle spedizioni. Le righe che non è stato possibile importare vengono elencate con il relativo messaggio di errore, mentre il resto del file viene comunque importato.
Requisiti tecnici per il file XML
Il file deve essere un documento XML ben formato con estensione .xml e non superiore a 25 MB.
Scegliere l'elemento di riga
L'elemento XML di riga indica all'importazione dove inizia e dove termina una spedizione (o un indirizzo). Ogni elemento corrispondente diventa una riga.
Può essere indicato in due modi:
| Cosa si inserisce | Significato | Quando usarlo |
|---|---|---|
Un semplice nome di tag, ad es. shipment | Ogni elemento con quel nome | Le righe si trovano direttamente in un documento semplice |
Un'espressione XPath, ad es. //order o /root/data/orders/order | Ogni elemento selezionato dall'espressione | Le righe sono annidate più in profondità, o lo stesso nome di tag è usato in più punti |
Per questo file l'elemento di riga è shipment:
<?xml version="1.0" encoding="UTF-8"?>
<shipments>
<shipment>
<receiver_name>Andreas Brauchle</receiver_name>
<receiver_countryCode>CH</receiver_countryCode>
<receiver_zipCode>8055</receiver_zipCode>
<receiver_city>ZÜRICH</receiver_city>
<receiver_street>Schaufelbergerstrasse 30</receiver_street>
<service_code>B2B</service_code>
<weight>2.3</weight>
</shipment>
<shipment>
...
</shipment>
</shipments>
Usare l'elemento che si ripete, non il contenitore che lo racchiude. Sopra, shipment è corretto e shipments è sbagliato.
Un contenitore corrisponde una sola volta, quindi l'intero file si riduce a una sola riga che conserva solo i valori dell'ultima voce. La perdita non viene segnalata da nessuna parte: se quell'unica riga è valida, l'importazione è contrassegnata come Riuscita, e il numero di record viene mostrato solo per i file importati parzialmente — un file ridotto sembra quindi del tutto normale. Se un file con 5 voci ne importa 1, questo è il motivo.
Per un file di indirizzi racchiuso in <Recipients><Recipient>…, l'elemento di riga è quindi Recipient — oppure //Recipient, che lo trova a qualsiasi profondità:
Per questo file l'elemento di riga è //order (oppure /root/data/orders/order):
<?xml version="1.0" encoding="UTF-8"?>
<root>
<data>
<orders>
<order id="ORD-001">
<recipient>
<address>
<name>John Doe</name>
<street>Main Street 1</street>
<zip>8000</zip>
<city>Zurich</city>
<country>CH</country>
</address>
<contact>
<email>john@example.com</email>
</contact>
</recipient>
<parcel weight="2.5" service="B2B">
<reference>REF-001</reference>
</parcel>
</order>
</orders>
</data>
</root>
Se l'elemento di riga non trova corrispondenze, l'importazione termina con l'errore "No XML elements matched the configured row element". Verificare l'ortografia e le maiuscole/minuscole — i nomi degli elementi XML distinguono tra maiuscole e minuscole.
Come i nomi degli elementi diventano nomi di campo
I nomi dei campi si scrivono relativamente all'elemento di riga, con / tra i livelli e @ per gli attributi. In base all'esempio annidato order sopra:
| Nel file | Cosa digitare come campo di origine | Valore |
|---|---|---|
Attributo id sull'elemento di riga | @id | ORD-001 |
<city> direttamente sotto l'elemento di riga | city | — |
<recipient><address><city> | recipient/address/city | Zurich |
<recipient><contact><email> | recipient/contact/email | john@example.com |
Attributo weight su <parcel> | parcel/@weight | 2.5 |
<parcel><reference> | parcel/reference | REF-001 |
Regole valide per ogni valore:
- Gli spazi iniziali e finali vengono rimossi, così come i caratteri invisibili (spazi non divisibili, spazi a larghezza zero, caratteri di controllo)
- Gli elementi vuoti (
<recipient_name2></recipient_name2>o<customs_date />) vengono considerati non forniti - Il testo distribuito su più righe viene unito in un unico valore
- Gli elementi non mappati vengono semplicemente ignorati
Mantenere la coerenza all'interno di un profilo: se l'XML è annidato, indicare il percorso completo per ogni campo. Mescolare un semplice nome foglia (city) con un percorso (recipient/address/city) nello stesso profilo può lasciare vuoto il primo, perché nei file annidati il valore è disponibile solo con il percorso completo.
Avanzato: selezionare uno tra più elementi ripetuti
Quando lo stesso elemento si ripete all'interno di una riga e serve un'occorrenza specifica, aggiungere un predicato XPath al campo di origine. Dato:
<shipment id="ORD-001">
<addresses>
<address kind="billing">
<city>Zurich</city>
</address>
<address kind="shipping">
<city>Bern</city>
</address>
</addresses>
<parcels>
<parcel type="standard" weight="1.0">
<reference>REF-STD-001</reference>
</parcel>
<parcel type="express" weight="2.5">
<reference>REF-EXP-001</reference>
</parcel>
</parcels>
<items>
<item>First item</item>
<item>Second item</item>
</items>
</shipment>
| Campo di origine | Seleziona | Valore |
|---|---|---|
addresses/address[@kind='shipping']/city | L'indirizzo di spedizione, non quello di fatturazione | Bern |
parcels/parcel[@type='express']/@weight | Il peso del pacco express | 2.5 |
parcels/parcel[@type='express']/reference | Il riferimento del pacco express | REF-EXP-001 |
items/item[1] | Il primo elemento per posizione | First item |
I percorsi dei campi devono rimanere all'interno della riga. Un percorso che inizia con / o // viene rifiutato al salvataggio del profilo, con "Mapping XPaths must be relative to the root row element" — questo evita che una riga prenda per errore i dati di un'altra. I percorsi assoluti e // sono ammessi solo nell'impostazione dell'elemento di riga stesso.
XML con namespace
Se gli elementi hanno un prefisso di namespace (<ns:order>), selezionare l'elemento di riga in base al nome locale invece che al prefisso:
//*[local-name()='order']
I percorsi dei campi possono essere scritti nello stesso modo, ad es. *[local-name()='recipient']/*[local-name()='city'].
Codifica dei caratteri
I file XML dichiarano la propria codifica nella prima riga:
<?xml version="1.0" encoding="UTF-8"?>
| Impostazione Codifica del profilo | Cosa accade |
|---|---|
| Rileva automaticamente (consigliata per XML) | Viene usata la codifica indicata nella dichiarazione XML |
| Una codifica specifica (UTF-8, ISO-8859-1, Windows-1250/1251/1252) | Viene usata quella codifica |
Impostare la Codifica del profilo su Rileva automaticamente e mantenere corretta la dichiarazione nel file. Se si seleziona una codifica specifica, questa deve corrispondere al file — altrimenti i caratteri speciali si corrompono (Müller diventa Müller).
È inoltre possibile sovrascrivere la codifica per un singolo file con Codifica di importazione nella finestra Importa file, senza modificare il profilo — lasciando Usa impostazione del profilo rimane attivo il valore del profilo.
Parametri di configurazione XML
| Parametro | Tipo | Descrizione | Valori di esempio |
|---|---|---|---|
xmlTag | Stringa | L'elemento di riga — semplice nome di tag o XPath | shipment, //order |
decimalSeparator | Stringa | Separatore decimale per numeri come il peso | . (predefinito) o , |
multiValueDelimiter | Stringa | Separatore all'interno di un elemento che contiene più valori, ad es. i codici opzione | , (predefinito), ;, | |
Peso con il punto (decimalSeparator = .):
<weight>2.5</weight>
Peso con la virgola (decimalSeparator = ,):
<weight>2,5</weight>
Più codici opzione in un unico elemento (multiValueDelimiter = ,):
<option_codes>136,140</option_codes>
Limitazioni di sicurezza
Per motivi di sicurezza l'importazione rifiuta i file che contengono una definizione di tipo di documento (<!DOCTYPE ...>) o entità personalizzate, e non carica mai contenuti riferiti dall'esterno del file. Esportare i dati senza DTD.
Problemi comuni e soluzioni
"No XML elements matched the configured row element"
L'elemento di riga indicato nel profilo non esiste nel file. Aprire il file in un editor di testo e verificare l'ortografia esatta e le maiuscole/minuscole dell'elemento che si ripete. Se le righe sono annidate più in profondità, usare un XPath come //order invece di un semplice nome di tag.
Un campo mappato rimane vuoto
Il testo del campo di origine non corrisponde esattamente al file. Verificare di aver scritto il percorso completo relativo all'elemento di riga (recipient/address/city, non city), che gli attributi inizino con @ (parcel/@weight) e che le maiuscole/minuscole corrispondano.
"Invalid content type for XML"
Il file caricato non è stato riconosciuto come XML. Assicurarsi che abbia estensione .xml e che inizi con una dichiarazione XML o un elemento radice corretto — un file in realtà CSV o di testo rinominato in .xml viene rifiutato.
"Failed to parse XML file"
Il file non è ben formato (tag non chiuso, & isolato, esportazione troncata) oppure contiene una dichiarazione <!DOCTYPE ...>. Aprirlo in un browser o in un editor XML — verrà indicata la prima riga errata. Scrivere & come & e < come <.
"Mapping XPaths must be relative to the root row element"
Un percorso di campo inizia con / o //. Rimuovere le barre iniziali affinché il percorso sia relativo all'elemento di riga: recipient/address/city invece di //city.
I caratteri speciali vengono visualizzati in modo errato — ad es. Müller appare come Müller
La codifica del profilo non corrisponde al file. Impostare Codifica su Rileva automaticamente per lasciar decidere la dichiarazione XML, oppure selezionare la codifica con cui il file è realmente salvato.
Il peso non viene riconosciuto come numero
Il segno decimale non corrisponde al profilo. Impostare il Separatore decimale in base al file: una virgola (,) se il file scrive 2,5, un punto (.) se scrive 2.5.
Sono stati importati meno record di quelli contenuti nel file
L'elemento di riga punta al contenitore invece che all'elemento che si ripete, quindi tutto il file è stato letto come una sola riga. Confrontare i due nomi di elemento nel file — per <shipments><shipment>… l'elemento di riga è shipment. Vedi l'avviso in Scegliere l'elemento di riga.
Solo alcune righe sono fallite
È il comportamento previsto: ogni riga viene importata singolarmente e una riga che non supera la validazione (peso mancante, paese sconosciuto, codice postale non valido) viene elencata come fallita con il relativo messaggio di errore, mentre le altre righe vengono importate. Correggere quelle righe e importare di nuovo il file.
Il file viene quindi contrassegnato come Importato parzialmente, con Valori errati e il numero di righe interessate. Aprirlo per vedere una voce per ogni riga fallita, ciascuna con il motivo e una vista Dati grezzi dei valori letti:
Nell'esempio sopra il file usava codici paese numerici (528, 276) dove il sistema si aspetta un codice ISO di due lettere — esattamente il tipo di differenza che una Trasformazione sul campo paese risolve.
Lista di controllo prima dell'importazione
Prima di importare, verificare:
- Il file è XML ben formato e ha estensione
.xml - Nessuna dichiarazione
<!DOCTYPE ...>nel file - La dichiarazione XML indica la codifica corretta e la Codifica del profilo è impostata su Rileva automaticamente
- L'elemento di riga nel profilo corrisponde all'elemento che si ripete nel file, non al suo contenitore (maiuscole/minuscole esatte)
- Dopo l'importazione, il numero di record corrisponde al numero di voci nel file
- Ogni campo di origine mappato è scritto relativamente all'elemento di riga, con
/per i livelli e@per gli attributi - Tutti i campi obbligatori sono mappati — nome del destinatario, via, codice postale, città, paese e peso
- Il peso è in kg e il separatore decimale corrisponde al profilo
- I caratteri speciali (ä, ö, ü, é) vengono visualizzati correttamente in un editor di testo
- La dimensione del file è inferiore a 25 MB