Skip to main content

Importazioni CSV

Riseact importa sostenitori e donazioni da file CSV. Gli importatori servono a caricare i dati iniziali di un'organizzazione, non a sincronizzarsi con un CRM esterno.

Principi

  • I record esistenti non si aggiornano. Se un record corrisponde a uno già presente (secondo le chiavi di deduplica), resta com'è.
  • Reimportare lo stesso file non crea duplicati. La deduplica usa i riferimenti esterni (external ref) e, per le righe senza chiave, un marcatore interno di riga.
  • Report in app. Ogni importazione compare in Impostazioni > Importazioni, con stato, conteggi e righe scartate. A fine lavorazione arriva un'email di riepilogo.
  • Un'importazione alla volta per organizzazione.

Limiti del file

VincoloValore
Righe dati (esclusa l'intestazione)max 10.000
Dimensione filemax 10 MB
CodificaUTF-8 (o UTF-8 con BOM)
Separatorevirgola (,)
ValutaEUR

I file più grandi vanno divisi in più importazioni.

Formato dell'intestazione

Le intestazioni sono minuscole, con le parole separate da spazi: first name, supporter external ref, payment date. Maiuscole e spazi esterni vengono ignorati, gli spazi interni multipli ridotti a uno. È la stessa convenzione delle esportazioni, quindi un file esportato si corregge e si ricarica senza rinominare niente.

Due eccezioni:

  • le colonne dei campi personalizzati usano il prefisso custom_ (vedi Campi personalizzati);
  • le colonne identificativo (id, supporter id, donation id) vengono ignorate: gli id li assegna Riseact. Qualsiasi altra colonna sconosciuta è un errore, così i refusi vengono intercettati.

Valori: regole di formato

Valgono per entrambi gli importatori.

  • Importi (amount): x.xx, punto decimale, esattamente due decimali (regex ^\d{1,10}\.\d{2}$). Rifiutati: virgola decimale (12,34), separatore delle migliaia (1.234,56), zero o un decimale (12, 12.3), valori zero o negativi.

  • Date e timestamp (payment date): ISO 8601 stretto, per esempio:

    • 2026-12-31
    • 2026-06-25 13:29:57
    • 2026-06-25T13:29:57.566Z

    31/12/2026 non è accettato. Senza fuso orario si assume UTC, senza ora 00:00.

  • Data di nascita (date of birth): YYYY-MM-DD.

  • Codice paese (country code): ISO 3166-1 alpha-2 (es. IT).

  • Codice fiscale e partita IVA: solo validazione formale (alfanumerici, entro la lunghezza massima).

  • Booleani (consensi marketing e campi personalizzati BOOLEAN): solo t/f, true/false, 0/1, senza distinzione di maiuscole. Cella vuota = non impostato. Qualsiasi altro valore (yes, si, x) fa fallire la riga.

  • Tag multivalore: separati da virgola nella stessa cella, che va quindi racchiusa tra virgolette:

    ...,altro,"x,y,z",altro,...

    "x,y,z" produce tre tag: x, y, z.

Deduplica

Sostenitore: vince la prima chiave che trova una corrispondenza, in quest'ordine:

supporter external ref -> email -> ssn -> vat

Senza nessuna chiave valorizzata si crea sempre un nuovo sostenitore. Se una chiave secondaria (email, ssn, vat) trova più sostenitori, vince quello con id più basso.

Donazione: chiave donation external ref. Le righe con lo stesso valore confluiscono in una sola donazione con più pagamenti. Senza donation external ref ogni riga diventa una donazione one-off.

Pagamento: chiave (donazione, data pagamento, importo), così reimportare il file non duplica i pagamenti.

Campi personalizzati

Si importano con colonne custom_<key>, dove <key> è la chiave della definizione del campo personalizzato (es. custom_numero_tessera).

  • La definizione deve già esistere: una <key> sconosciuta è un errore di intestazione.
  • Il valore va all'entità della definizione: un campo sostenitore sul sostenitore, un campo donazione sulla donazione.
  • L'importatore sostenitori accetta solo campi di tipo sostenitore.
  • BOOLEAN segue la regola dei booleani sopra, SELECT deve essere una delle opzioni della definizione, TEXT è libero.

Report ed esito

In Impostazioni > Importazioni trovi:

  • lo stato (In attesa, In corso, Completata, Fallita);
  • i record creati (sostenitori, donazioni, pagamenti) e il numero di righe scartate;
  • le righe scartate con il motivo, esportabili in CSV per correggerle e ricaricarle.

Un errore sul file (CSV illeggibile, intestazioni non valide, file troppo grande, controllo preliminare fallito) fa fallire l'importazione senza creare record. Un errore su una riga scarta solo quella riga e l'importazione resta Completata.

Le colonne sono elencate in:

Fonte: https://dev.riseact.org/docs/importers/overview. Copia automatica da dev.riseact.org: non modificare qui, le modifiche vanno fatte sulla documentazione Docusaurus.

Back to top