Lavorare con strumenti di gestione delle relazioni con i clienti, come la Marketing Automation, spesso implica l'elaborazione di una grande quantità di dati. Questi dati devono poi essere inseriti, o importati, nel sistema. Effettivamente, gli utenti autorizzati possono importare nuovi contatti nella Marketing Automation, ma i contatti rappresentano solo un tipo di dati.

Per rispondere a questa esigenza, Splio offre una soluzione attraverso la funzionalità di import automatico. Grazie a questa funzionalità, puoi fornire a Splio vari tipi di dati in modo organizzato. Basta preparare i file e caricarli in una cartella apposita, da cui uno script automatico li raccoglierà e importerà i dati per te.

Prerequisiti

• La funzionalità di import automatico deve essere prima configurata dal tuo Splio Project Manager di riferimento.
• È necessario poter aprire e salvare i file in formato CSV e con codifica UTF-8.
• È necessario poter spostare, copiare e rinominare i file a livello locale.
• Per caricare gli import files è necessaria una connessione SFTP.

Fasi di importazione

Segui questi passaggi per far sì che Splio importi automaticamente i tuoi file di dati:

• Prepara i file CSV - segui le linee guida riportate di seguito per creare e formattare i file contenenti i tuoi dati.
• Carica i file - collegati al repository sFTP e carica i file. Il tuo Project Manager ti fornirà i dettagli della connessione se ne hai bisogno.
• Controlla lo status - Splio elabora i file importati in modo programmato e invia avvisi e risultati agli indirizzi email configurati a tale scopo. Puoi anche esaminare i file di log presenti nel repository per avere maggiori dettagli.

Linee guida per i file di dati

Per la preparazione dei file di dati da caricare, si consiglia di seguire le linee guida riportate di seguito.

• Ogni file deve contenere dati appartenenti a una sola sezione.
• I file devono utilizzare il formato CSV, senza dati multilinea.
• Utilizza la codifica UTF-8 senza BOM.
• I nomi dei file devono indicare l'universo, la sezione, la sottosezione e la data.
• La priorità di import dipende dalle sezioni e può essere sovrascritta raggruppando i file.
• È possibile utilizzare identificatori opzionali per distinguere i file.

Queste linee guida sono spiegate in dettaglio qui di seguito.

📘

Per facilitare la gestione, i file di import possono essere caricati come archivi.

Sezioni

Ogni import file deve appartenere un tipo di dati o "sezione" che Splio è in grado di riconoscere. Tutti i nomi delle sezioni sono predefiniti e scritti in minuscolo. Qui, la distinzione tra lettere maiuscole e minuscole è importante.

Di seguito sono elencati tutte le sezioni disponibili, con brevi descrizioni. Il nome di ogni sezione è un link su cui è possibile cliccare per aprire la guida corrispondente.

• contacts – persone, clienti o contatti nel tuo database;
• stores – negozi e POS;
• products – prodotti nel catalogo;
• abandonedcarts – carrelli abbandonati od ordini che non sono mai stati completati o pagati;
• orders – ordini effettuati dai clienti;
• ordersitems – singoli prodotti contenuti in orders e abandonedcarts (come i singoli articoli di un ordine).

Consulta le guide dedicate per sapere quali campi dati (colonne) devi e puoi includere per ogni sezione.

Campi di cancellazione

Splio supporta la cancellazione dei dati dal database grazie alla funzionalità di importazione automatica. Nel caso in cui sia necessario cancellare dei dati, si prega di consultare la guida sulla cancellazione.

Sezioni Loyalty

Esistono diverse sezioni aggiuntive che vengono utilizzate per importare i dati dei programmi Loyalty. Segui i link per maggiori informazioni sulle diverse sezioni:

• cardcode – per gestire l'iscrizione individuale ai programmi Loyalty;
• creditpoints – per accreditare (assegnare) punti ai membri dei programmi Loyalty;
• events – per associare gli eventi alle persone;
• masterreward, earnreward, e burnreward – per creare voci di master rewards, per assenarli ai membri dei programmi (earn) e consentire loro di ottenere (burn) rewards;

Formato di un file

I file di importazione utilizzano il formato Comma-Separated Values (valori separati da virgole), per cui vengono solitamente chiamati file CSV o file *.csv. In pratica, 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 riga del file è una riga. Si tratta di un formato molto usato, modificabile con gli editor di testo, che può anche essere salvato ed esportato dalla maggior parte dei database e dei fogli di calcolo.

Codifica UTF-8

Tutti i file di importazione devono essere salvati utilizzando la codifica UTF-8 senza BOM. Si tratta di un sistema molto utilizzato che consente la coesistenza di caratteri di lingue diverse, ad esempio il francese e il cinese, nello stesso file.

Tutti gli editor di file di testo più moderni e i software per fogli di calcolo sono in grado di salvare file CSV con codifica UTF-8, essendo diventato un sistema predefinito in molti sistemi.

📘

Il byte order marker (BOM) è un carattere speciale aggiunto all'inizio del file. Assicurati di non usarlo.

Header

L'header è la prima riga del file CSV. Questa riga indica a Splio quante colonne ci sono nel file di dati e cosa rappresenta ogni colonna.

L'header deve sempre indicare le colonne appropriate per la categoria del file e deve contenere quelle che sono essenziali. Se aggiungi un nome di colonna non riconosciuto nella sezione o se manca una colonna essenziale, il file non verrà importato.

Righe del file

Tutte le righe del file devono contenere lo stesso numero di colonne così come nell'header. Splio salterà tutte quelle righe che non soddisfano questo requisito.

Ogni riga nel file di dati indica un singolo articolo nella sezione. I dati multilinea non sono supportati: Splio, quindi, salterà tutte le righe contenenti questo tipo di dati.

È possibile inserire i valori testuali tra doppie virgolette. Invece, non è possibile utilizzarli per fornire valori che si estendono su più righe.

Per indicare i numeri decimali, utilizzare il punto (“.”) come separatore decimale o punto. Non utilizzare alcun separatore per le migliaia. Utilizzare “-” per indicare i numeri negativi e nessun segno per i numeri positivi.

Esempio

Mike Cole ha ricevuto un file di contatti da importare. Il file è corto, quindi decide di dargli un'occhiata. Una volta aperto nel suo editor di testo e dando uno sguardo alle prime due righe:

email;firstname;lastname;cellphone;subscriptions 
"[email protected]";"Jean";"Boulanger";"33120202020";"-5" 

Mike legge l'header che contiene 5 colonne di contatti. Riconosce tutte le colonne ed effettivamente sono corrette.

Poi, passa alla seconda riga. Conta 5 colonne, un dato positivo. La prima è un valore di testo, tra virgolette, ed è un indirizzo email scritto correttamente. La seconda è anch'essa un testo tra doppie virgolette, la terza è un testo senza virgolette. Segue un valore numerico, il numero di telefono, e infine un numero negativo, che è normale per una colonna di iscrizione.

Utilizzare archivi e file compressi

Per praticità, è possibile raggruppare i file CSV in archivi per ridurne le dimensioni e diminuire il numero di file caricati. Splio supporterà i seguenti tipi di archivio, in base all'estensione del nome del file: .zip, .tar, .gz, .bz2.

Tuttavia, tutti i file all'interno degli allegati devono essere organizzati in gruppi. Lo si fa aggiungendo un apposito prefisso al nome del file secondo le regole di sequenziamento dei file descritte di seguito. Ciò consente a Splio di elaborare i file all'interno dell'archivio secondo un ordine chiaro e predefinito.

Si noti che il raggruppamento/sequenza fanno parte delle regole di denominazione. Gli import files archiviati devono comunque seguire tutte le regole di denominazione (sotto), formato e codifica (sopra). Dall'altro lato, non esistono regole specifiche per nominare gli archivi. Splio li esaminerà e li decomprimerà, e poi ne elaborerà il contenuto.

Linee guida per la denominazione dei file e ordine di elaborazione

Quando si selezionano i file da importare, Splio si basa su una specifica procedura di denominazione. Il modo in cui sono scritti i nomi dei file deve essere seguito con precisione, altrimenti l'importazione non partirà o fallirà durante il processo.

🚧

Se si utilizza lo stesso nome di file per le importazioni successive, nella directory degli archivi verrà conservato solo l'ultimo file. Ciò significa che il contenuto dei file precedenti andrà perso e non sarà possibile fornire nessuna informazione al riguardo.

Denominazione standard dei file

Tutti i file devono essere denominati in questo modo:

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

I trattini delimitano le voci che devono essere sostituite da un valore effettivo e sono obbligatorio.

Ci sono cinque parti necessarie, come spieghiamo di seguito. Considera che è possibile estendere il nome del file con informazioni aggiuntive all'inizio (chiamato prefisso). I prefissi e suffissi sono facoltativi e vengono discussi nelle sezioni seguenti.

• è il nome del tuo universo Splio e tutti i file che hai intenzione di importare automaticamente devono essere segnalati come tali;
• è una delle sezioni descritta nel paragrafo qui sopra;
• è usata per indentificare un import specifico o le impostazioni d'import, ad esempio, il nome dell'archivio d'origine o la possibilità di scegliere se aggiornare o meno i dati esistenti. Gli indirizzi email sono configurati dal Project Manager per ogni sottosezione con il fine di ricevere avvisi e risultati.
• è la data del file usata per determinare l'ordine cronologico degli import per ogni sezione. La data deve avere questo formato: "yyyymmdd" ovvero "20180315".

Ad esempio, nell'universo Splio "myuniverse", un file della sottosezione "toystore" che contiene i contatti e che riporta una delle date sopra indicate si chiamerebbe myuniverse_contacts_toystore_20180315.csv.

Ricorda che, affinché i files siano importati, tutte le combinazioni di sezioni e nomi devono essere definite ne file di configurazione. Questo file viene gestito con il supporto del Project Manager.

Ordine di elaborazione del file

Splio segue sempre lo stesso ordine nell'importazione dei file, una sezione alla volta, passando a quella successiva solo dopo che tutte le importazioni nella sezione corrente siano terminate. I file vengono estratti dal repository FTP/SFTP nel seguente ordine:

Se non usi Loyalty:

1. gruppo di files (vedi sotto)
2. contatti
3. stores
4. prodotti
5. ordini
6. abandonedcarts (carrelli abbandonati)
7. ordersitems
8. batch

Se usi Loyalty, si possono aggiungere in seguito

1. cardcode
2. earnreward
3. burnreward
4. creditpoints
5. deletecontacts (cancellazioni di contatti)
6. events (eventi)
7. tierchange (cambio di livello)
8. masterreward

I file all'interno della stessa sezione sono ordinati in base alle date contenute nei nomi dei file, dalla data più lontana a quella più recente.

Denominazione avanzata dei file: Ordinamento dei file per gruppi

L'ordine di import predefinito è abbastanza chiaro, ma può potrebbe diventare non sufficiente. Tu ed altri utenti della vostra azienda avrete spesso bisogno d'importare file secondo un ordine specifico, ad esempio, contatti o stores prima dei dati di vendita (ordini e ordersitems) che si basano su questi contatti.

Se gli ordini vengono inseriti nel repository e vengono presi in carico per l'import prima che vengano importati i relativi contatti, Splio salterà tutte le righe che si riferiscono ai contatti non ancora importati.

Questo serio rischio, tuttavia, può essere facilmente evitato utilizzando i gruppi. In questo modo si avrà la possibilità di controllare l'ordine d'importazione dei file.

I gruppi sono creati agiungendo un apposito prefisso <groupid>.YY-ZZ all'inizio del nome del file. Questo prefisso consiste in:

• un identificatore di gruppo, o <group_id>, seguito da
• un punto ".",
• un numero a 2 cifre del file selezionato nella sequenza, reppresentato come YY,
• un trattino "-",
• un numero a 2 cifre dell'ultimo file della sequenza, rappresentato come ZZ, e un trattino basso "_".

Il <group_id> è una stringa di caratteri che rappresenta il nome del gruppo. I numeri YY e ZZ possono assumere valori compresi tra 01 e 99. I file all'interno di una sequenza devono contenere i numeri successivi iniziando con 01 e fino a ZZ.

📘

Il valore ZZ indica a Splio quanti numeri sono presenti. Non omettere alcun numero all'interno di una sequenza, altrimenti Splio resterà in attesa del file mancante.

Nomi di files ragruppati con esempi

Il nome completo del file può essere sintetizzato come:

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

Come si può vedere, la parte che inizia con è lo stesso nome di file di base che già conosci. Dai un'occhiata agli 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 files, "weekly" è ancora incompleto in attesa di un file con il prefisso weekly.01-02_ prefix da importare.

Ordinamento dei file: Como vengono processati i gruppi

Splio cerca di importare tutti i gruppi (file sequenziati) prima di importare i singoli fie (non sequenziati). L'ordine di importazione è riportato sopra.

I gruppi vengono analizzati uno a uno, in ordine alfabetico secondo il group_id.

Prima di tutto, Splio controlla se il gruppo è completo, cioè se c'è almeno un file nel gruppo per ogni numero da 01 a ZZ. Se mancano uno o più file, Splio passa al gruppo successivo. I file appartenenti al gruppo incompleto non venon rimossi o processati, ma restano in attesa dell'importazione dei file rimanenti.

Quando si lavora con un gruppo di files, Splio li importa uno per uno nell'ordine dettato dal numero all'interno del gruppo (YY). Se ci sono più file con lo stesso numero, viene importato prima quello con la data più recente. Questo permette all'importazione automatica di procedere anche con file consegnati a intervalli di tempo variabili. Ad esempio, è possibile mantenere il controllo sull'ordine di importazione anche se uno dei tuoi colleghi consegna file tre volte a settimana e un altro lo fa giornalmente.

🚧

Tieni presente che una volta iniziata l'importazione del gruppo, i file al suo interno vengono trattati in modo sequenziale. Se un file della sequenza viene rifiutato (ad esempio, manca una colonna obbligatoria o, al contrario, c'è una colonna non valida), Splio interrompe l'importazione del gruppo e passa a quella successiva.

Denominazione del file avanzata: identificatore opzionale

Quando si caricano più file al giorno, si potrebbe avere la necessità di contrassegnare ulteriormente alcuni file: aggiungere un commento, un identificatore o magari solo un numero. In presenza di una grande quantità di file con nomi simili, la necessità di poterli distinguere a colpo d'occhio e di trovarli più rapidamente può essere estremamente utile.

Per rispondere a questa esigenza, Splio offre un identificatore opzionale sotto forma di suffisso _ da aggiungere ai nomi dei file. I suffissi sono sempre aggiunti alla fine (immediatamente prima della parte .csv, così come i prefissi sono aggiunti all'inizio). Questo suffisso è composto da un trattino basso seguito da caratteri alfanumerici (lettere e cifre). Un nome di file che lo include potrebbe presentarsi come segue:

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

Tutti gli altri componenti di questo nome di file sono spiegati sopra nella sezione riguardante la denominazione di base dei file. Gli esempi seguenti mostrano tre nomi di file. Si noti come il suffisso opzionale aiuti a distinguerli.

myuniverse_contacts_toystore_20180315_updates.csv 
myuniverse_contacts_toystore_20180315_noon.csv 
myuniverse_orders_toystore_20180228_daily.csv 

L'identificatore opzionale non viene gestito da Splio, quindi non ci saranno azioni particolari in base a esso. Tuttavia, Splio manterrà intatto questo identificatore durante lo spostamento dei file in altre directory e utilizzerà lo stesso identificatore per contrassegnare i relativi file di log.

SFTP/FTP Repository di Splio

ll repository che hai potuto vedere nel grafico all'inizio dell'articolo è stato creato come parte della configurazione dell'universo Splio. Il tuo contatto presso Splio ti fornirà l'indirizzo del tuo repository FTP, un nome utente e una password. Se non sai come configurare un client FTP da solo, chiedi aiuto a un tecnico IT della tua azienda.

🚧

Se il repository è vuoto, contatta il tuo Project Manager o il Customer Care di Splio. La funzionalità d'import automatico potrebbe richiedere l'attivazione.

Struttura della Directory

Il repository FTP contiene una struttura predefinita di directory utilizzata dall'automazione delle importazioni.

Nella directory principale del repository si trova la cartella "imports", che include tutte le altre directory necessarie. Qui è dove devi mettere il file di configurazione e tutti i file da importare.

Quando l'importazione è terminata, il file viene rimosso dalla cartella degli import e spostato in una sottocartella specifica in base all'esito dell'importazione. Successivamente, un report viene inviato agli indirizzi email specificati nel file di configurazione.

• "archives" è l'ubicazione predefinita per i file processati. Se l'importazione è andata a buon fine, il file importato verrà spostato qui.
• "badlines" è dove vengono collocati i file con righe rifiutate (ad esempio, righe da file di contatti senza email né numero di cellulare, da file di negozi senza store_id, ecc.).
• "bogus" è la directory dove Splio sposta i file considerati non validi. Se hai dimenticato di includere una colonna obbligatoria o ne hai aggiunta una inesistente, il tuo file CSV verrà spostato qui.
• "logs" è l'ubicazione per i file di testo che contengono i dati di monitoraggio delle tue importazioni (questi file sono chiamati files o logs). Si prega di consultare la sezione dei log qui sotto.
• "notprocessed" è dove Splio colloca i file non elaborati.

Logs

Quando si esegue l'importazione automatica, Splio prepara file di monitoraggio speciali (chiamati file di log, o semplicemente log) che elencano errori ed eventi verificatisi durante l'import. Per ogni file .csv nella directory /imports/logs/, viene creato un file di log separato.

La tabella sottostante elenca i messaggi che è possibile trovare in un file di log, con una breve descrizione di ciascun messaggio e suggerimenti su cosa si può fare per risolvere eventuali problemi. Le variabili metasintattiche tra parentesi angolari verranno sostituite con i nomi e i dati reali nel log.