github-actions[bot]
e0d4492013
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
271 lines
10 KiB
Plaintext
271 lines
10 KiB
Plaintext
---
|
|
title: CSV 파일 준비
|
|
description: Twenty로 가져오기 위한 데이터 형식 지정 단계별 가이드.
|
|
---
|
|
|
|
## 개요
|
|
|
|
이 가이드는 성공적인 가져오기를 위해 CSV 파일을 준비하는 과정을 안내합니다. 오류를 피하려면 다음 단계를 따르세요.
|
|
|
|
## 1단계: 파일 요구 사항 확인
|
|
|
|
시작하기 전에 파일이 다음 요구 사항을 충족하는지 확인하세요:
|
|
|
|
| 요구 사항 | 세부정보 |
|
|
| --------- | ---------------- |
|
|
| **형식** | CSV, XLSX 또는 XLS |
|
|
| **크기 제한** | 파일당 10,000 레코드 |
|
|
| **인코딩** | UTF-8 권장 |
|
|
| **구조** | 파일당 한 가지 오브젝트 유형 |
|
|
|
|
<Note>10,000 레코드를 초과하는 데이터세트의 경우, 여러 파일로 분할하거나 [API 가져오기](/l/ko/user-guide/data-migration/how-tos/import-data-via-api)를 사용하세요.</Note>
|
|
|
|
## 2단계: 샘플 파일 다운로드
|
|
|
|
**가장 중요한 단계입니다.** 샘플 파일은 Twenty가 기대하는 정확한 열 이름과 형식을 보여줍니다.
|
|
|
|
1. 오브젝트 보기(사람들, 회사 등)로 이동하세요.
|
|
2. **⋮** → **레코드 가져오기**를 클릭하세요
|
|
3. **샘플 파일 다운로드**를 클릭하세요
|
|
4. 이 파일을 템플릿으로 사용하세요
|
|
|
|
<Note>**전문가 팁:** 대신 기존 레코드 몇 개를 내보내세요. 이렇게 하면 데이터가 어떻게 형식화되어야 하는지 실제 예를 얻을 수 있으며, 가져오는 동안 열 이름이 자동으로 매핑됩니다.</Note>
|
|
|
|
## 3단계: 중복 값 제거
|
|
|
|
Twenty는 일부 필드에 대해 고유성을 적용합니다. 중복 항목은 가져오기 오류를 유발합니다.
|
|
|
|
| 객체 | 고유 필드 |
|
|
| ------------- | ----------------------- |
|
|
| **사람들** | `id`, `email` |
|
|
| **회사** | `id`, `domain` |
|
|
| **사용자 지정 개체** | `id`, 그리고 고유로 표시한 모든 필드 |
|
|
|
|
**가져오기 전에:**
|
|
|
|
1. 스프레드시트를 고유 필드(이메일 또는 도메인)로 정렬하세요
|
|
2. 중복 행을 제거하거나 병합하세요
|
|
3. Twenty에 이미 존재하는 중복 항목이 있는지 확인하세요
|
|
|
|
<Warning>**소프트 삭제된 레코드는 고유성에 포함됩니다.** Command Menu → 삭제된 레코드 보기에 있는 레코드는 중복 오류를 일으킵니다. 영구적으로 삭제하거나 복원한 후 업데이트하세요.</Warning>
|
|
|
|
## 4단계: 각 필드 유형을 올바르게 형식 지정하기
|
|
|
|
필드 유형에 따라 요구되는 형식이 다릅니다. 전체 참고 자료는 다음과 같습니다:
|
|
|
|
### 텍스트 필드
|
|
|
|
* 특별한 형식 지정이 필요 없습니다
|
|
* 앞/뒤 공백은 자동으로 제거됩니다
|
|
|
|
### 이메일 필드
|
|
|
|
* 유효한 이메일 형식이어야 합니다: `name@domain.com`
|
|
* 고유해야 합니다(파일 또는 Twenty에 중복이 없어야 함)
|
|
* 추가 이메일의 경우 **Emails / Additional Emails** 열에서 다음 형식을 사용하세요:
|
|
|
|
```
|
|
["jane@twenty.com","jane.doe@twenty.com"]
|
|
```
|
|
|
|
### 도메인 필드
|
|
|
|
* **권장 형식**: `https://domain.com`
|
|
* 이는 메일박스/캘린더 동기화에서 사용하는 형식과 일치하며 중복을 방지합니다
|
|
* 두 열을 모두 채우세요:
|
|
* **Domain / Domain Label**: `domain.com`
|
|
* **Domain / Domain URL**: `https://domain.com`
|
|
* 파일 내 및 Twenty에서 고유해야 합니다
|
|
|
|
### 전화번호 필드
|
|
|
|
전화번호는 여러 열이 필요한 **중첩 필드**입니다:
|
|
|
|
| 열 | 예시 |
|
|
| --------------------------------------- | ------------ |
|
|
| **Phones / Primary Phone Number** | `4159095555` |
|
|
| **Phones / Primary Phone Country Code** | `US` |
|
|
| **Phones / Primary Phone Calling Code** | `+1` |
|
|
|
|
### 주소 필드
|
|
|
|
Address는 여러 열로 구성된 **중첩 필드**이며(일부는 비워 둘 수 있음):
|
|
|
|
* **Address / Address 1**: 주소 1행
|
|
* **Address / Address 2**: 주소 2행(선택 사항)
|
|
* **Address / City**: 도시 이름
|
|
* **Address / State**: 주 또는 도
|
|
* **Address / Country**: 국가 이름
|
|
* **Address / Post Code**: 우편번호/ZIP 코드
|
|
|
|
### 날짜 필드
|
|
|
|
파일 전체에서 일관된 형식을 사용하세요:
|
|
|
|
* `YYYY-MM-DD` (권장): `2024-03-15`
|
|
* `MM/DD/YYYY`: `03/15/2024`
|
|
* `DD/MM/YYYY`: `15/03/2024`
|
|
* ISO 8601: `2024-03-15T10:30:00Z`
|
|
|
|
### 숫자 필드
|
|
|
|
* 숫자만 사용(텍스트 금지)
|
|
* 소수점 구분 기호로 점(.)을 사용: `1234.56`
|
|
* 천 단위 구분 기호 사용 금지(`1,234.56`는 사용하지 마세요)
|
|
|
|
### 통화 필드
|
|
|
|
통화는 두 개의 열이 필요한 **중첩 필드**이며, **두 열 모두** 채워야 합니다:
|
|
|
|
| 열 | 예시 |
|
|
| --------------------- | --------- |
|
|
| **Amount / Amount** | `1234.56` |
|
|
| **Amount / Currency** | `USD` |
|
|
|
|
### 부울 필드
|
|
|
|
대문자 사용: `TRUE` 또는 `FALSE`
|
|
|
|
<Warning>소문자 `true` 또는 `false`는 동작하지 않습니다.</Warning>
|
|
|
|
### 선택 필드
|
|
|
|
표시 라벨이 아니라 옵션의 **API 이름**을 사용하세요.
|
|
|
|
**API 이름을 찾는 방법:**
|
|
|
|
1. **설정 → 데이터 모델**로 이동
|
|
2. 객체와 필드를 선택하세요
|
|
3. **고급 모드**를 활성화하세요(오른쪽 하단 토글)
|
|
4. API 이름을 복사하세요(예: `OPTION_1`, "Option 1" 아님)
|
|
|
|
<Note>새 선택 옵션은 자동으로 생성되지 않습니다. 가져오기 전에 **설정 → 데이터 모델**에서 추가하세요.</Note>
|
|
|
|
### 다중 선택 필드
|
|
|
|
배열 형식으로 API 이름을 사용:
|
|
|
|
```
|
|
[\"VALUE1\",\"VALUE2\"]
|
|
```
|
|
|
|
### 배열 필드
|
|
|
|
JSON 배열 형식 사용:
|
|
|
|
```
|
|
[\"value1\",\"value2\"]
|
|
```
|
|
|
|
### 평점 필드
|
|
|
|
다음 형식을 사용: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4`, 또는 `RATING_5`
|
|
|
|
### 링크/URL 필드
|
|
|
|
두 열을 모두 채우세요:
|
|
|
|
* **Links / Link Label**: `Twenty`
|
|
* **Links / Link URL**: `https://twenty.com`
|
|
|
|
보조 링크의 경우 **Links / Secondary Links** 열을 사용하세요:
|
|
|
|
```
|
|
[{\"url\":\"https://twenty.com\",\"label\":\"Twenty\"}]
|
|
```
|
|
|
|
### JSON 필드
|
|
|
|
유효한 JSON 형식을 사용:
|
|
|
|
```
|
|
{\"key\":\"value\",\"key2\":\"value2\"}
|
|
```
|
|
|
|
### ID 필드
|
|
|
|
* **선택 사항**: 제공하지 않으면 Twenty가 ID를 자동 생성합니다
|
|
* **형식**: UUID(예: `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`)
|
|
* **사용 사례**: 새로 생성하는 대신 기존 레코드를 업데이트하려면 ID를 포함하세요
|
|
|
|
## 5단계: 관계 열 추가(레코드를 연결하는 경우)
|
|
|
|
레코드를 다른 객체에 연결하려면(예: People을 Companies에) 관련 레코드의 고유 식별자가 있는 열을 추가하세요.
|
|
|
|
**예시**: People을 Companies에 연결
|
|
|
|
People CSV에 열을 추가:
|
|
|
|
```
|
|
firstName,lastName,email,companyDomain
|
|
John,Smith,john@acme.com,https://acme.com
|
|
Jane,Doe,jane@widgets.co,https://widgets.co
|
|
```
|
|
|
|
**관계에 대한 중요 규칙:**
|
|
|
|
* 상위 레코드는 Twenty에 이미 존재해야 합니다
|
|
* 라벨이 아니라 **도메인 URL** 형식(`https://domain.com`)을 사용하세요
|
|
* 고유 식별자는 하나만 매핑하세요(`companyId`와 `companyDomain`을 모두 포함하지 마세요)
|
|
* 워크스페이스 구성원은 이름이 아닌 **이메일**을 사용하세요
|
|
|
|
<Warning>
|
|
**가져오기 순서가 중요합니다!**
|
|
|
|
"one" 측을 "many" 측보다 먼저 가져오세요:
|
|
|
|
1. **회사** 먼저
|
|
2. **연락처** 두 번째(회사 참조 포함)
|
|
3. **기회** 세 번째
|
|
|
|
참조하려면 상위 레코드가 먼저 존재해야 합니다.
|
|
</Warning>
|
|
|
|
자세한 지침은 [관계 가져오기 방법](/l/ko/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)을 참조하세요.
|
|
|
|
## 6단계: Twenty에 필드가 존재하는지 확인
|
|
|
|
가져오기는 필드가 아니라 레코드를 생성합니다. 가져오려는 모든 필드는 데이터 모델에 이미 존재해야 합니다.
|
|
|
|
**가져오기 전:**
|
|
|
|
1. **설정 → 데이터 모델**로 이동
|
|
2. 객체를 선택하세요
|
|
3. 필요한 사용자 정의 필드를 생성하세요
|
|
4. 필드 이름을 정확히 확인하세요(열 제목과 일치해야 합니다)
|
|
|
|
## 7단계: 최종 체크리스트
|
|
|
|
파일을 업로드하기 전에 다음을 확인하세요:
|
|
|
|
<Check>파일 형식이 CSV, XLSX 또는 XLS이어야 합니다</Check>
|
|
<Check>레코드 수가 10,000개 미만이어야 합니다</Check>
|
|
<Check>인코딩이 UTF-8이어야 합니다</Check>
|
|
<Check>이메일(연락처) 또는 도메인(회사)에 중복이 없어야 합니다</Check>
|
|
<Check>날짜 형식이 전체에서 일관되어야 합니다</Check>
|
|
<Check>도메인은 `https://domain.com` 형식을 사용해야 합니다</Check>
|
|
<Check>부울 필드는 `TRUE` 또는 `FALSE`(대문자)를 사용해야 합니다</Check>
|
|
<Check>선택 필드는 표시 라벨이 아닌 API 이름을 사용해야 합니다</Check>
|
|
<Check>모든 사용자 정의 필드가 설정 → 데이터 모델에 존재해야 합니다</Check>
|
|
<Check>상위 레코드를 하위 레코드보다 먼저 가져와야 합니다</Check>
|
|
<Check>관계 열이 기존 레코드를 참조해야 합니다</Check>
|
|
|
|
## 피해야 할 일반적인 실수
|
|
|
|
| 실수 | 해결책 |
|
|
| -------------------- | ----------------------------------- |
|
|
| `TRUE` 대신 `true` 사용 | 부울 값은 대문자여야 합니다 |
|
|
| 선택 필드에서 표시 라벨 사용 | 설정에서 API 이름을 찾아 사용하세요 |
|
|
| 회사보다 연락처를 먼저 가져오기 | 항상 상위 객체를 먼저 가져오세요 |
|
|
| 통화 필드에 통화 코드 누락 | Amount와 Currency 열을 모두 채우세요 |
|
|
| 잘못된 도메인 형식 | `https://domain.com` 형식을 일관되게 사용하세요 |
|
|
| 관계에 여러 개의 고유 필드를 매핑함 | 하나만 매핑하세요(도메인 또는 ID, 둘 다는 안 됨) |
|
|
|
|
## 다음 단계
|
|
|
|
파일이 준비되었습니다! 이제:
|
|
|
|
* [회사 가져오기](/l/ko/user-guide/data-migration/how-tos/import-companies-via-csv) (먼저 가져오세요)
|
|
* [연락처 가져오기](/l/ko/user-guide/data-migration/how-tos/import-contacts-via-csv)
|
|
* [가져오기 오류 수정](/l/ko/user-guide/data-migration/how-tos/fix-import-errors)
|