github-actions[bot]
001c2097a3
Created by Github action <!-- mintlify-editor-comments:start --> Mintlify --- 0 threads from 0 users in Mintlify - No unresolved comments <!-- mintlify-editor-comments:end --> <!-- mintlify-comment--> <a href="https://dashboard.mintlify.com/twenty/twenty/editor/i18n-docs?source=pr_comment" target="_blank" rel="noopener noreferrer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://d3gk2c5xim1je2.cloudfront.net/assets/open-mintlify-editor-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://d3gk2c5xim1je2.cloudfront.net/assets/open-mintlify-editor-light.svg"><img src="https://d3gk2c5xim1je2.cloudfront.net/assets/open-mintlify-editor-light.svg" alt="Open in Mintlify Editor"></picture></a> <!-- /mintlify-comment --> Co-authored-by: github-actions <github-actions@twenty.com>
270 lines
10 KiB
Plaintext
270 lines
10 KiB
Plaintext
---
|
|
title: Prepara i tuoi file CSV
|
|
description: Guida completa passo passo per formattare i tuoi dati per l'importazione in Twenty.
|
|
---
|
|
|
|
## Panoramica
|
|
|
|
Questa guida ti accompagna nella preparazione del tuo file CSV per un'importazione riuscita. Segui questi passaggi per evitare errori.
|
|
|
|
## Passaggio 1: Controlla i requisiti del file
|
|
|
|
Prima di iniziare, assicurati che il tuo file soddisfi questi requisiti:
|
|
|
|
| Requisito | Dettagli |
|
|
| ------------------------ | --------------------------- |
|
|
| **Formato** | CSV, XLSX o XLS |
|
|
| **Limite di dimensione** | 10.000 record per file |
|
|
| **Codifica** | Si consiglia UTF-8 |
|
|
| **Struttura** | Un tipo di oggetto per file |
|
|
|
|
<Note>Per set di dati superiori a 10.000 record, suddividi in più file oppure usa l'[importazione tramite API](/l/it/user-guide/data-migration/how-tos/import-data-via-api).</Note>
|
|
|
|
## Passaggio 2: Scarica il file di esempio
|
|
|
|
**Questo è il passaggio più importante.** Il file di esempio ti mostra i nomi delle colonne e il formato esatti che Twenty si aspetta.
|
|
|
|
1. Vai alla vista dell'oggetto (Persone, Aziende, ecc.)
|
|
2. Fai clic su **⋮** → **Importa record**
|
|
3. Fai clic su **Scarica file di esempio**
|
|
4. Usa questo file come modello
|
|
|
|
<Note>**Suggerimento avanzato:** Esporta invece alcuni record esistenti. Questo ti fornisce esempi reali di come i dati devono essere formattati e i nomi delle colonne verranno mappati automaticamente durante l'importazione.</Note>
|
|
|
|
## Passaggio 3: Rimuovi i valori duplicati
|
|
|
|
Twenty impone l'unicità su alcuni campi. I duplicati causeranno errori di importazione.
|
|
|
|
| Oggetto | Campi unici |
|
|
| -------------------------- | ------------------------------------------------------------- |
|
|
| **Persone** | `id`, `email` |
|
|
| **Aziende** | `id`, `domain` |
|
|
| **Oggetti personalizzati** | `id`, più qualsiasi campo che hai contrassegnato come univoco |
|
|
|
|
**Prima dell'importazione:**
|
|
|
|
1. Ordina il tuo foglio di calcolo in base al campo univoco (email o dominio)
|
|
2. Rimuovi o unisci le righe duplicate
|
|
3. Verifica la presenza di duplicati già esistenti in Twenty
|
|
|
|
<Warning>**I record eliminati in modo non definitivo contano ai fini dell'unicità.** I record in Menu Comandi → Vedi record eliminati causeranno errori di duplicato. Eliminali definitivamente oppure ripristinali e aggiornali.</Warning>
|
|
|
|
## Passaggio 4: Formattta correttamente ogni tipo di campo
|
|
|
|
Tipi di campo diversi richiedono formati specifici. Ecco il riferimento completo:
|
|
|
|
### Campi di testo
|
|
|
|
* Non è richiesta una formattazione speciale
|
|
* Gli spazi iniziali/finali vengono rimossi automaticamente
|
|
|
|
### Campi email
|
|
|
|
* Deve avere un formato email valido: `name@domain.com`
|
|
* Deve essere univoco (nessun duplicato nel file o in Twenty)
|
|
* Per email aggiuntive, usa questo formato nella colonna **Email / Email aggiuntive**:
|
|
|
|
```
|
|
["jane@twenty.com","jane.doe@twenty.com"]
|
|
```
|
|
|
|
### Campi del dominio
|
|
|
|
* **Formato consigliato**: `https://domain.com`
|
|
* Questo corrisponde al formato usato dalla sincronizzazione della casella di posta/calendario (evita duplicati)
|
|
* Compila entrambe le colonne:
|
|
* **Dominio / Etichetta dominio**: `domain.com`
|
|
* **Dominio / URL dominio**: `https://domain.com`
|
|
* Deve essere univoco all'interno del tuo file e in Twenty
|
|
|
|
### Campi telefono
|
|
|
|
Il telefono è un **campo annidato** che richiede più colonne:
|
|
|
|
| Colonna | Esempio |
|
|
| -------------------------------------------------------------- | ------------ |
|
|
| **Telefoni / Numero di telefono principale** | `4159095555` |
|
|
| **Telefoni / Codice paese del telefono principale** | `US` |
|
|
| **Telefoni / Prefisso internazionale del telefono principale** | `+1` |
|
|
|
|
### Campi indirizzo
|
|
|
|
Indirizzo è un **campo annidato** con più colonne (alcune possono essere lasciate vuote):
|
|
|
|
* **Indirizzo / Indirizzo 1**: Riga indirizzo 1
|
|
* **Indirizzo / Indirizzo 2**: Riga indirizzo 2 (facoltativa)
|
|
* **Indirizzo / Città**: Nome città
|
|
* **Indirizzo / Stato**: Stato o provincia
|
|
* **Indirizzo / Paese**: Nome paese
|
|
* **Indirizzo / Codice postale**: Codice postale/CAP
|
|
|
|
### Campi data
|
|
|
|
Usa un formato coerente in tutto il file:
|
|
|
|
* `YYYY-MM-DD` (consigliato): `2024-03-15`
|
|
* `MM/DD/YYYY`: `03/15/2024`
|
|
* `DD/MM/YYYY`: `15/03/2024`
|
|
* ISO 8601: `2024-03-15T10:30:00Z`
|
|
|
|
### Campi numerici
|
|
|
|
* Solo numeri (nessun testo)
|
|
* Usa il punto per i decimali: `1234.56`
|
|
* Nessun separatore delle migliaia (non `1,234.56`)
|
|
|
|
### Campi valuta
|
|
|
|
Valuta è un **campo annidato** che richiede due colonne che **devono essere entrambe compilate**:
|
|
|
|
| Colonna | Esempio |
|
|
| --------------------- | --------- |
|
|
| **Importo / Importo** | `1234.56` |
|
|
| **Importo / Valuta** | `USD` |
|
|
|
|
### Campi booleani
|
|
|
|
Usa il maiuscolo: `TRUE` o `FALSE`
|
|
|
|
<Warning>Le minuscole `true` o `false` non funzioneranno.</Warning>
|
|
|
|
### Campi Selezione
|
|
|
|
Usa il **nome API** dell'opzione, non l'etichetta di visualizzazione.
|
|
|
|
**Come trovare i nomi API:**
|
|
|
|
1. Vai a **Impostazioni → Modello dati**
|
|
2. Seleziona l'oggetto e il campo
|
|
3. Abilita la **Modalità avanzata** (interruttore in basso a destra)
|
|
4. Copia il nome API (ad es., `OPTION_1`, non "Option 1")
|
|
|
|
<Note>Le nuove opzioni di selezione non vengono create automaticamente. Aggiungile in **Impostazioni → Modello dati** prima di importare.</Note>
|
|
|
|
### Campi a selezione multipla
|
|
|
|
Usa i nomi API in formato array:
|
|
|
|
```
|
|
["VALUE1","VALUE2"]
|
|
```
|
|
|
|
### Campi array
|
|
|
|
Usa il formato array JSON:
|
|
|
|
```
|
|
["value1","value2"]
|
|
```
|
|
|
|
### Campi di valutazione
|
|
|
|
Usa il formato: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4` o `RATING_5`
|
|
|
|
### Campi Link/URL
|
|
|
|
Compila entrambe le colonne:
|
|
|
|
* **Link / Etichetta del link**: `Twenty`
|
|
* **Link / URL del link**: `https://twenty.com`
|
|
|
|
Per i link secondari, usa la colonna **Link / Link secondari**:
|
|
|
|
```
|
|
[{"url":"https://twenty.com","label":"Twenty"}]
|
|
```
|
|
|
|
### Campi JSON
|
|
|
|
Usa un formato JSON valido:
|
|
|
|
```
|
|
{"key":"value","key2":"value2"}
|
|
```
|
|
|
|
### Campi ID
|
|
|
|
* **Opzionale**: Twenty genera automaticamente gli ID se non forniti
|
|
* **Formato**: UUID (ad es., `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`)
|
|
* **Caso d'uso**: Includi l'ID per aggiornare i record esistenti invece di crearne di nuovi
|
|
|
|
## Passaggio 5: Aggiungi colonne di relazione (se colleghi record)
|
|
|
|
Per collegare i record ad altri oggetti (ad es., Persone ad Aziende), aggiungi una colonna con l'identificatore univoco del record correlato.
|
|
|
|
**Esempio**: collegare Persone ad Aziende
|
|
|
|
Aggiungi una colonna al CSV Persone:
|
|
|
|
```
|
|
firstName,lastName,email,companyDomain
|
|
John,Smith,john@acme.com,https://acme.com
|
|
Jane,Doe,jane@widgets.co,https://widgets.co
|
|
```
|
|
|
|
**Regole importanti per le relazioni:**
|
|
|
|
* Il record padre deve già esistere in Twenty
|
|
* Usa il formato **URL del dominio** (`https://domain.com`), non l'etichetta
|
|
* Mappa un solo identificatore univoco (non includere sia `companyId` che `companyDomain`)
|
|
* Per i membri dello spazio di lavoro, usa la loro **email** (non il nome)
|
|
|
|
<Warning>
|
|
**L'ordine di importazione è importante!**
|
|
|
|
Importa il lato "uno" prima del lato "molti":
|
|
1. **Aziende** prima
|
|
2. **Persone** poi (con riferimento all'azienda)
|
|
3. **Opportunità** al terzo posto
|
|
|
|
Il record padre deve esistere prima di potervi fare riferimento.
|
|
</Warning>
|
|
|
|
Consulta [Come importare le relazioni](/l/it/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) per istruzioni dettagliate.
|
|
|
|
## Passaggio 6: Verifica che i campi esistano in Twenty
|
|
|
|
L'importazione crea record, non campi. Tutti i campi che vuoi importare devono già esistere nel tuo modello dati.
|
|
|
|
**Prima di importare:**
|
|
|
|
1. Vai a **Impostazioni → Modello dati**
|
|
2. Seleziona il tuo oggetto
|
|
3. Crea gli eventuali campi personalizzati necessari
|
|
4. Annota i nomi esatti dei campi (devono corrispondere alle intestazioni delle colonne)
|
|
|
|
## Passaggio 7: Lista di controllo finale
|
|
|
|
Prima di caricare il file, verifica:
|
|
|
|
<Check>Il file è in formato CSV, XLSX o XLS</Check>
|
|
<Check>Il file contiene meno di 10.000 record</Check>
|
|
<Check>La codifica è UTF-8</Check>
|
|
<Check>Nessuna email duplicata (per Persone) o domini (per Aziende)</Check>
|
|
<Check>Le date usano un formato coerente ovunque</Check>
|
|
<Check>I domini usano il formato `https://domain.com`</Check>
|
|
<Check>I campi booleani usano `TRUE` o `FALSE` (maiuscolo)</Check>
|
|
<Check>I campi di selezione usano i nomi API, non le etichette di visualizzazione</Check>
|
|
<Check>Tutti i campi personalizzati esistono in Impostazioni → Modello dati</Check>
|
|
<Check>I record padre sono importati prima dei record figlio</Check>
|
|
<Check>Le colonne di relazione fanno riferimento a record esistenti</Check>
|
|
|
|
## Errori comuni da evitare
|
|
|
|
| Errore | Soluzione |
|
|
| --------------------------------------------------------------- | ---------------------------------------------------- |
|
|
| Uso di `true` invece di `TRUE` | I valori booleani devono essere in maiuscolo |
|
|
| Uso delle etichette di visualizzazione per i campi di selezione | Trova e usa i nomi API in Impostazioni |
|
|
| Importare Persone prima delle Aziende | Importa sempre prima gli oggetti padre |
|
|
| Codice valuta mancante per i campi di valuta | Compila sia la colonna Importo sia la colonna Valuta |
|
|
| Formato di dominio errato | Usa `https://domain.com` in modo coerente |
|
|
| Mappatura di più campi univoci per le relazioni | Mappa solo UNO (dominio O id, non entrambi) |
|
|
|
|
## Prossimi Passi
|
|
|
|
Il tuo file è pronto! Ora:
|
|
|
|
* [Importa Aziende](/l/it/user-guide/data-migration/how-tos/import-companies-via-csv) (importale per prime)
|
|
* [Importa Contatti](/l/it/user-guide/data-migration/how-tos/import-contacts-via-csv)
|
|
* [Correggi eventuali errori di importazione](/l/it/user-guide/data-migration/how-tos/fix-import-errors)
|