Datahub - Panoramica

ℹ️ |  Utilizzare uno strumento di marketing come Splio implica l'utilizzo di una grande quantità di dati che devono essere integrati oppure importati nel sistema. Gli utenti con diritti di amministratore possono importare nuovi contatti su Splio, ma i contatti sono solo un tipo di dati.

Per affrontare questa esigenza, Splio offre una funzionalità di import automatico. Grazie agli import automatici, puoi caricare in Splio vari tipi di dati in modo organizzato. Tutto quello che devi fare è preparare i file ed inserirli nella cartella corretta, dalla quale uno script automatico preleverà i file importando i dati per tuo conto.

Prerequisiti

• La funzionalità di import automatico deve dapprima essere configurata dal tuo Project Manager in Splio
• Devi essere in grado di aprire e salvare i file utilizzando il formato CSV e la codifica UTF-8
• Devi essere capace di spostare, copiare e rinominare i file in locale
• È richiesta una connessione FTP per caricare i file di import

Passaggi per l'import

Segui questi passaggi per far in modo che Splio importi i file di dati automaticamente:

• Prepara i tuoi file CSV – segui le linee guida qui di seguito per creare e formattare i file con i tuoi dati.
• Carica i file – collegati al repository SFTP e carica i file. Il tuo Project Manager ti fornirà i dati di connessione se ne hai bisogno.
• Verifica lo stato – Splio elabora i file importati secondo una programmazione, inviando notifiche e risultati agli indirizzi email configurati a tale scopo. Puoi anche verificare i file log nel repository per maggiori informazioni.

Linee guida per i file di dati

Segui le linee guida qui di seguito per preparare i file di dati da caricare.

• Ogni file deve contenere dati appartenenti ad un singolo ambito.
• I file devono utilizzare il formato CSV, senza dati multi-linea.
• Deve essere utilizzata la codifica UTF-8 senza BOM.
• I nomi file devono indicare l'universo, l'ambito, la sotto-sezione e la data.
• La priorità di import dipende dagli ambiti e può essere modificata raggruppando i file.
• Possono essere utilizzati degli ID facoltativi per distinguere i file.

Queste linee guida sono spiegate con maggior dettaglio a continuazione.

💡 | Per una gestione più semplice, i file di import possono essere caricati come archivi.

Ambiti

Ogni file di import deve appartenere ad un tipo di dati, o "ambito" (scope), che Splio può identificare. Tutti i nomi degli ambiti sono predefiniti, in minuscolo e con distinzione tra maiuscole e minuscole.

Tutti gli ambiti disponibili sono elencati a continuazione, con una breve descrizione. Il nome di ogni ambito è un link per accedere direttamente alla guida corrispondente.

• contatti – individui, clienti o contatti nel tuo database;
• negozi – negozi fisici e online;
• prodotti – prodotti nel catalogo;
• carrelli abbandonati – carrelli abbandonati o scontrini che non sono mai stati completati o pagati;
• scontrini – ordini creati dai clienti (scontrini);
• righe scontrino – singoli prodotti all'interno di "orders" e "abandonedcarts" (come articoli singoli all'interno di uno scontrino).

Consulta le guide per conoscere le colonne di cui hai bisogno e che puoi includere in ogni ambito.

Ambito di eliminazione

Splio supporta l'eliminazione di record dal database utilizzando la funzionalità di import automatico. Se devi eliminare dei record, consulta la guida per l'eliminazione.

Ambito di loyalty

Esistono ambiti extra per importare i dati dei programmi loyalty. Segui i link per saperne di più:

• iscrizioni loyalty (codice carta) – per gestire la singola iscrizione nei programmi loyalty;
• accredito/addebito punti – per accreditare (aggiungere) punti ai membri del programma loyalty;
• premi loyalty (masterreward, earnreward e burnreward) – per creare premi master, assegnarli ai membri del programma (earn) e consentire loro di utilizzare (burn) i premi;
• eventi – per associare eventi a individui.

Formato di file

I file di import utilizzano il formato "Comma-Separated Values", sono quindi generalmente denominati file CSV o file *.csv. In sostanza, i file CSV sono file di testo in cui il contenuto è organizzato in colonne e righe, come in una tabella. Le colonne sono separate da punti e virgola (";") e ogni linea nel file è una riga. Si tratta di un formato comune, modificabile tramite editor di testo, che può anche essere salvato ed esportato dalla maggior parte dei software per la gestione dei database o fogli di calcolo.

Codifica UTF-8

Tutti i file di import devono essere salvati utilizzando la codifica UTF-8 senza BOM. Questo è un sistema comune che consente caratteri in lingue diverse, ad es. Francese e Cinese, coesistenti nello stesso file.

In pratica, tutti gli editor di file di testo moderni e i software di fogli di calcolo possono salvare file CSV compatibili con UTF-8, e la codifica UTF-8 è diventata predefinita in molti sistemi.

💡 | Il marcatore dell'ordine dei byte (BOM) è un carattere speciale aggiunto all'inizio del file. Assicurati di non utilizzarlo.

Intestazione

L'intestazione è la prima linea del file CSV. Questa linea informa Splio di quante colonne è composto il file di dati e che cosa rappresentano.

L'intestazione deve sempre indicare le colonne appropriate per l'ambito del file e deve contenere le colonne richieste. Se inserisci un nome di colonna sconosciuto nell'ambito oppure ometti una colonna necessaria, il file non verrà importato.

Linee nel file

Tutte le linee nel file devono contenere lo stesso numero di colonne come nell'intestazione. Splio ignorerà tutte le linee che non soddisfano questo requisito.

Ogni linea nel file di dati rappresenta un singolo elemento nell'ambito. I dati multi-linea non sono supportati: se utilizzati, Splio ignorerà tutte le linee interessate.

Hai l'opzione di includere i valori testuali tra le doppie virgolette. Tuttavia, non puoi usare questa opzione per fornire valori su più linee.

Per rappresentare i numeri decimali, utilizza il punto (".") come separatore decimale. Non utilizzare alcun separatore per le migliaia. Utilizza "-" per contrassegnare i numeri negativi e nessun segno per i numeri positivi.

Esempio

Mike Cole ha ricevuto un file di contatti da importare. Il file è piccolo, quindi decide di darci un'occhiata. Lo apre nel suo editor di testo e osserva le prime due linee:

email;firstname;lastname;cellphone;subscriptions 
"example7445@temporarymail.org";"Jean";"Boulanger";"33120202020";"-5" 

Mike legge l'intestazione, che contiene 5 colonne di contatti. Identifica tutte le colonne e può affermare che sono corrette.

Ora passa alla seconda linea. Conta 5 colonne, il che è corretto. La prima è un valore di testo, tra virgolette, ed è un indirizzo email adeguatamente formattato. Anche la seconda contiene testo tra virgolette, mentre la terza contiene testo senza virgolette. Poi segue un valore numerico, il numero di cellulare e, infine, un numero negativo che è normale per una colonna iscrizione.

Utilizzo di archivi e file compressi

Per convenienza, puoi raggruppare i tuoi file CSV in archivi per ridurne le dimensioni e diminuire il numero di file caricati. Splio supporta i seguenti tipi di archivi, con le seguenti estensioni: .zip, .tar, .gz, .bz2.

Tuttavia, tutti i file all'interno degli archivi devono essere organizzati in gruppi aggiungendo un prefisso apposito al nome file a seconda delle regole di sequenza del file, descritte a continuazione. Questo permette a Splio di elaborare i file all'interno degli archivi in un chiaro ordine preimpostato.

Nota che il raggruppamento/la sequenza fa parte delle regole di denominazione. I file di import archiviati necessitano sempre di seguire tutte le regole di denominazione (vedi sotto), formato e codifica (vedi sopra). D'altro canto, non ci sono regole specifiche per la denominazione degli archivi. Splio li esaminerà e li decomprimerà, elaborandone i contenuti.

Linee guida per la denominazione dei file

Quando preleva i file da importare, Splio si affida a una convenzione di denominazione ben specifica. Il modo in cui i nomi file sono costruiti deve essere seguito scrupolosamente, altrimenti l'import non inizierà oppure si interromperà a metà strada. D'altro canto, è sufficiente seguire le regole qui sotto per assicurarsi che i file di import vengano elaborati.

⚠️ | Se utilizzi lo stesso nome file per import successivi, solamente l'ultimo file sarà conservato nella directory degli archivi. Ciò significa che il contenuto dei file precedenti andrà perso e non potrà essere fornita alcuna informazione su di esso.

Denominazione del file di base

Tutti i file devono essere denominati secondo questo schema:

<universe>_<scope>_<subsection>_<date>.csv 

Gli elementi compresi tra parentesi angolari devono essere sostituiti da un valore reale e sono obbligatori.

Ci sono cinque parti obbligatorie, come spiegato qui di seguito. Tieni presente che il nome file può essere esteso con delle informazioni supplementari all'inizio (prefisso) e proprio prima dell'estensione ".csv" (suffisso). Prefissi e suffissi sono facoltativi e vengono trattati nelle sezioni successive.

• <universe> è il nome del tuo universo Splio e tutti i file che desideri importare automaticamente devono includere questo elemento;
• <scope> è uno degli ambiti descritti nella sezione ambiti di cui sopra;
• <subsection> è utilizzata per identificare un import specifico o impostazioni di import, come ad es. il nome della fonte oppure la possibilità di scegliere se aggiornare i record esistenti o meno. Gli indirizzi email per ricevere notifiche e risultati sono configurati dal tuo Project Manager per ogni setto-sezione;
• <date> è la data del file, utilizzata per determinare l'ordine cronologico degli import all'interno di ogni ambito. La data deve rispettare uno di questi due formati: "yyyymmdd", come "20180315".

Ad esempio, in un universo Splio "myuniverse", un file di sottosezione "toystore" contenente i contatti e avente una delle date di cui sopra sarà denominato myuniverse_contacts_toystore_20180315.csv. 

Affinché i file siano importati, tutte le coppie di ambiti e nomi devono essere definite nel file di configurazione. Questo file va gestito con l'assistenza del tuo Project Manager.

Ordine di trattamento del file

Splio segue sempre lo stesso ordine per importare i file, un ambito alla volta, spostandosi all'ambito successivo solo dopo aver terminato tutti gli import in quello corrente. I file sono prelevati dal repository FTP/SFTP nel seguente ordine:

Se non usi Loyalty:

1. Gruppi di file (vedi più sotto) 
2. contatti
3. negozi
4. prodotti
5. ordini
6. carrelli abbandonati
7. linee di scontrino
8. batch

Se usi Loyalty, puoi aggiungere successivamente: 

1. 1. codice di carta
   2. earnreward
   3. burnreward
   4. crédits
   5. elimina contatti
   6. eventi
   7. cambio di status
   8. masterreward

I file all'interno di uno stesso ambito sono ordinati in base alla data contenuta nel rispettivo nome file, dalla meno recente alla più recente.

Denominazione del file avanzata: sequenza del file con dei gruppi

Anche se l'ordine di import predefinito è abbastanza chiaro, potrebbe non essere sufficiente. Tu e altri utenti della tua azienda vi troverete spesso nella situazione di dover importare dei file in un ordine specifico, ad esempio contatti o negozi prima dei dati di vendita (orders e ordersitems) che si riferiscono a questi contatti. Se gli "orders" vengono inseriti nel repository e prelevati per l'import prima che i contatti pertinenti siano importati, Splio ignorerà tutte le linee che si riferiscono ai contatti che non sono stati importati.

Questo grave rischio può essere evitato facilmente utilizzando dei gruppi.

I gruppi si creano aggiungendo uno speciale prefisso <group_id>.YY-ZZ_ all'inizio del nome file. Il prefisso è formato da:

• un ID del gruppo o <group_id>, seguito da
• un punto ".",
• un numero di due cifre del file corrente nella sequenza, rappresentato come YY,
• un trattino "-",
• un numero di due cifre dell'ultimo file nella sequenza, rappresentato come ZZ e
• un underscore "_".

Il <group_id> è una stringa di caratteri che rappresenta il nome del gruppo. I numeri YY e ZZ possono essere valori compresi tra 01 e 99. I file senza una sequenza devono ricevere dei numeri successivi che iniziano con 01 fino a ZZ.

📗 | Il valore ZZ indica a Splio quanti numeri ci sono. Non omettere alcun numero all'interno di una sequenza, altrimenti Splio attenderà il file mancante.

Nomi di file raggruppati con esempi

Il nome file completo può essere riassunto come segue:

<group_id>.YY-ZZ_<universe>_<scope>_<subsection>_<date>.csv 

Come puoi vedere, la parte che inizia con <universe> è lo stesso nome file di base che conosci già. Guarda gli esempi qui di seguito:

daily.01-03_myuniverse_contacts_toystore_20180315.csv 
daily.02-03_myuniverse_products_toystore_20180315.csv 
daily.03-03_myuniverse_orders_toystore_20180315.csv 
weekly.02-02_myuniverse_stores_toystore_20180315.csv 

Ci sono due gruppi: "daily" è completo, con 3 file, "weekly" è ancora incompleto in attesa che sia importato il file con il prefisso weekly.01-02.

Sequenza dei file: come vengono elaborati i gruppi

Splio prova a importare tutti i gruppi (file sequenziati) prima di importare qualsiasi file singolo (non sequenziato). L'ordine in cui sono importati è reperibile qui sopra.

I gruppi sono analizzati uno per uno, in ordine alfabetico in base al group_id.

Come prima cosa, Splio controlla se il gruppo è completo, ossia se c'è almeno un file nel gruppo per ogni numero da 01 a ZZ. Se uno o più file sono mancanti, Splio passa al gruppo successivo. I file che formano un gruppo incompleto non sono rimossi o elaborati, bensì in attesa dei file restanti da importare.

Quando si lavora con un gruppo, Splio importa i file uno per uno, nell'ordine dettato dal numero all'interno del gruppo (YY). Se vengono trovati uno o più file con lo stesso numero, viene importato per primo il file con la <date> (data) precedente. Questo permette all'import automatico di procedere anche con file inviati in differenti intervalli di tempo. Ad esempio, puoi mantenere il controllo sull'ordine di import anche se uno dei tuoi collaboratori invia file tre volte a settimana e un altro lo fa giornalmente.

⚠️ | Tieni presente che una volta iniziato l'import del gruppo, i file dello stesso sono trattati in sequenza. Se un file sequenziato viene rifiutato (ad es. una colonna obbligatoria è mancante o, al contrario, contiene una colonna illegale) Splio abbandonerà l'import del gruppo e passerà al successivo.

Denominazione del file avanzata: ID facoltativo

Quando carichi più file al giorno, potresti avere la necessità di contrassegnare alcuni file: aggiungere un commento, un ID o semplicemente un numero. Con una così grande quantità di file simili, essere in grado di distinguerli immediatamente e trovarli più velocemente è impagabile.

Per rispondere a questa esigenza, Splio offre l'ID facoltativo nella forma di un suffisso <id> aggiunto ai nomi file. I suffissi sono sempre aggiunti alla fine (proprio prima dell'estensione .csv, così come i prefissi sono aggiunti all'inizio). Il suffisso è formato da un carattere underscore seguito da caratteri alfanumerici (lettere e cifre). Un nome file che lo include può essere riassunto come segue:

<universe>_<scope>_<subsection>_<date>_<id>.csv 

Tutti gli altri componenti di questo nome file sono spiegati sopra, nella sezione relativa alla denominazione di base dei file. Gli esempi qui di seguito mostrano tre nomi file. Nota come il suffisso facoltativo aiuta a distinguerli.

myuniverse_contacts_toystore_20180315_updates.csv 
myuniverse_contacts_toystore_20180315_noon.csv 
myuniverse_orders_toystore_20180228_daily.csv 

L'ID facoltativo non è elaborato da Splio, ossia non sono intraprese azioni speciali in risposta ad esso. Tuttavia, Splio manterrà l'ID intatto spostando i file nelle directory. Contrassegnerà così anche i file log corrispondenti.

Repository SFTP/FTP presso Splio

Il repository che hai visto nel grafico all'inizio dell'articolo è creato a parte rispetto alle impostazioni del tuo universo Splio. Il tuo Project Manager ti fornirà l'indirizzo del repository FTP, un nome utente e una password. Se non sai come configurare autonomamente un client FTP, chiedi assistenza a uno specialista IT nella tua azienda.

⚠️ | Se dopo aver effettuato l'accesso noti che il tuo repository è vuoto, contatta il tuo Project Manager o l'assistenza di Splio. La funzionalità di import automatico potrebbe richiedere l'attivazione.

Struttura della directory

Il repository FTP contiene una struttura impostata di directory utilizzata dall'automazione di import.

All'interno del repository, troverai la directory "imports". Essa contiene tutte le altre directory. Questa directory è dove devi posizionare il tuo file di configurazione e tutti i file che vuoi importare.

Una volta completato l'import, il file di import viene eliminato dalla directory "imports" e, a seconda del risultato dell'import, posizionato in una delle sottocartelle. Successivamente viene inviato un report agli indirizzi email indicati nel file di configurazione.

• "archives" è la posizione predefinita per i file elaborati. Se l'import è avvenuto correttamente, il file di import sarà spostato lì.
• "badlines" è dove i file contengono delle linee rifiutate (ad es. linee dal file dei contatti senza email né cellulare, dai file negozi senza store_id, ecc.).
• "bougs" è la directory dove Splio sposta i file che considera illegali. Se dimentichi di inserire una colonna obbligatoria o ne inserisci una inesistente, qui è dove il file CSV sarà spostato.
• "logs" è la posizione per i file di testo che contengono i dati di monitoraggio relativi ai tuoi import (questi file sono denominati file log o log). Consulta la sezione log qui di seguito.
• "notprocessed" è dove Splio mette i file che non ha elaborato.

Log

Quando effettui un import automatico, Splio prepara appositi file di monitoraggio (chiamati file log o semplicemente log) che elencano gli errori e gli eventi avvenuti duranti l'import. Viene creato un file separato per ogni file .csv nella directory /imports/logs/.

La tabella qui di seguito elenca i messaggi reperibili in un file log, con una breve descrizione di ogni messaggio e i suggerimenti che possono essere seguiti per migliorare la situazione, se disponibili. Gli elementi contenuti tra parentesi angolari saranno sostituiti con i nomi e i dati reali nel log.

Messaggio di log	Descrizione
impossibile trovare l'universo "<universe>"	Il nome file o la voce nel file di configurazione si riferisce a un universo Splio inesistente. O l'universo deve essere creato o dovresti verificare se stai utilizzando un nome corretto di universo.
impossibile trovare l'import con ID <importid>	L'import non è ancora stato impostato.
impossibile trovare l'account ftp con ID <ftpaccountid>	Splio non riesce a prelevare i file dal repository FTP <ftpaccountid>. L'import non è stato impostato correttamente o deve ancora essere configurato.
impossibile aprire la directory di lavoro "<workdir>"	La directory <workdir> è mancante (ad es. è stata eliminata) o c'è un errore di sistema.
impossibile aprire il file "<workdir/filename>"	Il file è mancante o corrotto: prova a validare il file di import e caricalo di nuovo. Questo messaggio di log può anche indicare un errore di sistema.
JSON non valido in "<universe>_imports_config.json"	Se vedi questo errore nel tuo log, segnalalo a un operatore Splio quanto prima.
nessuna configurazione disponibile per gli import di <scope>	Apparentemente il tuo file di configurazione non contiene una configurazione per questo ambito. Se vedi questo errore nel tuo log, segnalalo a un operatore Splio quanto prima.
impossibile trovare la configurazione per importare l'ambito denominato <scope>	Se vedi questo errore nel tuo log, segnalalo a un operatore Splio quanto prima.
valore di configurazione obbligatorio mancante "<field>"	Se vedi questo errore nel tuo log, segnalalo a un operatore Splio quanto prima.
formato errato per il valore di configurazione "<$field>"	Se vedi questo errore nel tuo log, segnalalo a un operatore Splio quanto prima.
impossibile analizzare l'intestazione del file	Questo errore in genere significa che la codifica del file di import non è corretta. Assicurati che il tuo file abbia la codifica UTF-8 e caricalo di nuovo.
(<filename>:<line>) non può analizzare la linea	Indica un problema con la linea specifica del file. Dovresti poter aprire il file e controllare la linea indicata.