199 lines
6.2 KiB
Plaintext
199 lines
6.2 KiB
Plaintext
---
|
|
title: Field Mapping
|
|
description: How field mapping works during data import.
|
|
---
|
|
|
|
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
|
|
|
## How Field Mapping Works
|
|
|
|
When you upload a file, Twenty analyzes your columns and attempts to match them to existing fields.
|
|
|
|
### Automatic Mapping
|
|
|
|
Twenty tries to match columns based on:
|
|
|
|
* Column header names (exact or similar matches)
|
|
* Data type detection (dates, numbers, emails)
|
|
* Common field patterns
|
|
|
|
<Note>**Quick tip:** Export a few rows from the object you want to import. The exported file will have the exact column names Twenty expects, making automatic mapping seamless during import.</Note>
|
|
|
|
### Manual Mapping Options
|
|
|
|
For each column, you can:
|
|
|
|
* **Map to a field**: Select the matching Twenty field from a dropdown
|
|
* **Do not map**: Skip the column entirely (data won't be imported)
|
|
|
|
<Note>**Fields must exist before import.** The import creates records, not fields. Create custom fields under **Settings → Data Model** before importing.</Note>
|
|
|
|
## Field Type Compatibility
|
|
|
|
All field types available in the Data Model are supported for import.
|
|
|
|
You can also import `id` values to either assign a specific ID to new records or update existing ones.
|
|
|
|
<img src="/images/user-guide/fields/all-field-types.png" style={{width:'100%'}} />
|
|
|
|
## Data Format Requirements
|
|
|
|
<Note>**Some fields have special syntax.** We recommend downloading the sample file before preparing your import to see the expected syntax for each field type.</Note>
|
|
|
|
### Address Fields
|
|
|
|
Address is a nested field with multiple columns. Some can be left empty.
|
|
|
|
* **Address / Address 1**: Street address line 1
|
|
* **Address / Address 2**: Street address line 2
|
|
* **Address / City**: City name
|
|
* **Address / State**: State or province
|
|
* **Address / Country**: Country name
|
|
* **Address / Post Code**: Postal/ZIP code
|
|
|
|
### Array Fields
|
|
|
|
Use the following format:
|
|
|
|
```
|
|
["value1","value2"]
|
|
```
|
|
|
|
### Boolean Fields
|
|
|
|
Use `TRUE` or `FALSE` (uppercase) - not `true` or `false`
|
|
|
|
### Currency Fields
|
|
|
|
Currency is a nested field with two columns that **both must be filled**:
|
|
|
|
* **Amount / Amount**: The numeric value (e.g., `1234.56`)
|
|
* **Amount / Currency**: The currency code (e.g., `USD`, `EUR`)
|
|
|
|
### Date Fields
|
|
|
|
Supported formats:
|
|
|
|
* `YYYY-MM-DD` (recommended)
|
|
* `MM/DD/YYYY`
|
|
* `DD/MM/YYYY`
|
|
* ISO 8601 format
|
|
|
|
### Domain Fields
|
|
|
|
* It is recommended to use the format `https://domain.com` to avoid creating duplicates, as this is the format used for Companies created by the mailbox and calendar synchronizations
|
|
* A `Domain Label` and `Domain URL` can be filled: best practice is to fill `domain.com` in the label and `https://domain.com` in the url
|
|
* Domains must be unique within the Companies object
|
|
* **Domains must be unique within the file to import**
|
|
|
|
### Email Fields
|
|
|
|
* Must be valid email format
|
|
* Emails must be unique within the People object
|
|
* **Emails must be unique within the file to import**
|
|
* For additional emails: use **Emails / Primary Email** for the main email, and **Emails / Additional Emails** with this format:
|
|
|
|
```
|
|
["jane@twenty.com","jane.doe@twenty.com"]
|
|
```
|
|
|
|
### Id Fields
|
|
|
|
Specifying an `id` during import is optional. Twenty auto-generates one if not provided.
|
|
|
|
Use cases for mapping an `id` column:
|
|
|
|
* **Set a specific ID**: Choose the UUID for newly created records
|
|
* **Update existing records**: Match against existing records to update them instead of creating duplicates. In that case, it is recommended to not map the other unique fields: mapping only one unique field ensures a smoother import.
|
|
|
|
<Note>If you provide an `id`, it must be in UUID format (e.g., `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).</Note>
|
|
|
|
### JSON Fields
|
|
|
|
Use valid JSON format:
|
|
|
|
```
|
|
{"key":"value","key2":"value2"}
|
|
```
|
|
|
|
### Links Fields
|
|
|
|
Similar to Domain fields:
|
|
|
|
* Fill both the label and URL columns: **Links / Link URL** and **Links / Link Label**
|
|
* Use full URL format: `https://example.com`
|
|
* For secondary links, use **Links / Secondary Links** column with this format:
|
|
|
|
```
|
|
[{"url":"https://twenty.com","label":"Twenty"}]
|
|
```
|
|
|
|
### Multi-Select Fields
|
|
|
|
Use the **API names** (not the display labels) in the following format:
|
|
|
|
```
|
|
["VALUE1","VALUE2"]
|
|
```
|
|
|
|
See [here](#finding-api-names-for-select-fields) where to find the API names.
|
|
|
|
<Note>New select options will not be created automatically by the import. They must be added under **Settings → Data Model** before importing.</Note>
|
|
|
|
<Warning>
|
|
**Import overwrites, it does not add.**
|
|
|
|
If a record already has `VALUE2` and `VALUE3` selected, and you import `["VALUE1"]`, the record will only have `VALUE1` after import. The previous selections are replaced, not merged.
|
|
</Warning>
|
|
|
|
### Number Fields
|
|
|
|
* Numbers only
|
|
* Decimals use period: `1234.56`
|
|
* No thousands separators
|
|
|
|
### Phone Fields
|
|
|
|
Phone is a nested field with multiple columns that **must be filled**
|
|
|
|
* **Phones / Primary Phone Number**: The phone number (e.g., `4159095555`)
|
|
* **Phones / Primary Phone Country Code**: Country code (e.g., `US`)
|
|
* **Phones / Primary Phone Calling Code**: Dialing code (e.g., `+1`)
|
|
|
|
### Rating Fields
|
|
|
|
Use the API name format: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4`, `RATING_5`
|
|
|
|
### Champs de relation
|
|
|
|
Please see our dedicated article: [Import Relations Between Objects](/l/fr/user-guide/data-migration/capabilities/import-relations)
|
|
|
|
### Champs de sélection
|
|
|
|
Use the **API name** of the option (not the display label):
|
|
|
|
```
|
|
VALUE1
|
|
```
|
|
|
|
Voir [ici](#finding-api-names-for-select-fields) où trouver les noms d'API.
|
|
<Note>Les nouvelles options de sélection ne seront pas créées automatiquement par l'importation. Elles doivent être ajoutées sous **Paramètres → Modèle de données** avant l'importation.</Note>
|
|
|
|
### Champs de texte
|
|
|
|
* Aucun formatage particulier requis
|
|
* Les espaces au début et à la fin sont supprimés
|
|
|
|
## Recherche des noms d'API
|
|
|
|
Pour les champs Select, Multi-Select et Array avec des options prédéfinies, vous devez utiliser les **noms d'API**, et non les libellés affichés.
|
|
|
|
### Comment trouver les noms d'API
|
|
|
|
1. Allez dans **Paramètres → Modèle de données**
|
|
2. Sélectionnez l'objet et le champ
|
|
3. Activez le **mode avancé** (bouton à bascule en bas à droite de la page des paramètres)
|
|
4. Affichez le nom d'API pour chaque option
|
|
|
|
<VimeoEmbed videoId="1144910809" title="Démonstration vidéo" />
|