github-actions[bot]
37dbd94596
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
268 lines
13 KiB
Plaintext
268 lines
13 KiB
Plaintext
---
|
|
title: Prepare Your CSV Files
|
|
description: دليل كامل خطوة بخطوة لتنسيق بياناتك لاستيرادها إلى Twenty.
|
|
---
|
|
|
|
## نظرة عامة
|
|
|
|
يرشدك هذا الدليل إلى كيفية إعداد ملف CSV لاستيراد ناجح. اتّبع هذه الخطوات لتجنّب الأخطاء.
|
|
|
|
## الخطوة 1: التحقّق من متطلبات الملف
|
|
|
|
قبل البدء، تأكّد من أنّ ملفك يستوفي هذه المتطلبات:
|
|
|
|
| المتطلب | تفاصيل |
|
|
| --------------------- | --------------------- |
|
|
| **التنسيق** | CSV، XLSX، أو XLS |
|
|
| **الحد الأقصى للحجم** | 10,000 سجل لكل ملف |
|
|
| **الترميز** | يوصى باستخدام UTF-8 |
|
|
| **البنية** | نوع كائن واحد لكل ملف |
|
|
|
|
<Note>بالنسبة لمجموعات البيانات التي تزيد على 10,000 سجل، قم بتقسيمها إلى عدة ملفات أو استخدم [الاستيراد عبر API](/l/ar/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>**السجلات المحذوفة مؤقتًا تُحتسب ضمن التفرّد.** السجلات الموجودة في قائمة الأوامر → عرض السجلات المحذوفة ستتسبب في أخطاء تكرار. احذفها نهائيًا أو استعدها وقم بتحديثها.</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` |
|
|
|
|
### حقول العنوان
|
|
|
|
العنوان هو **حقل متداخل** يحتوي على أعمدة متعددة (يمكن ترك بعضها فارغًا):
|
|
|
|
* **العنوان / العنوان 1**: السطر الأول لعنوان الشارع
|
|
* **العنوان / العنوان 2**: السطر الثاني لعنوان الشارع (اختياري)
|
|
* **العنوان / المدينة**: اسم المدينة
|
|
* **العنوان / الولاية**: ولاية أو مقاطعة
|
|
* **العنوان / البلد**: اسم البلد
|
|
* **العنوان / الرمز البريدي**: رمز بريدي/ZIP
|
|
|
|
### حقول التاريخ
|
|
|
|
استخدم تنسيقًا موحدًا في كامل ملفك:
|
|
|
|
* `YYYY-MM-DD` (مُوصى به): `2024-03-15`
|
|
* ISO 8601: `2024-03-15T10:30:00Z`
|
|
|
|
### حقول الأرقام
|
|
|
|
* أرقام فقط (بدون نص)
|
|
* استخدم النقطة للفواصل العشرية: `1234.56`
|
|
* بدون فواصل لآلاف الأرقام (ليس `1,234.56`)
|
|
|
|
### حقول العملة
|
|
|
|
العملة هي **حقل متداخل** يتطلب عمودين يجب **ملؤهما كليهما**:
|
|
|
|
| العمود | مثال |
|
|
| ------------------- | --------- |
|
|
| **المبلغ / المبلغ** | `1234.56` |
|
|
| **المبلغ / العملة** | `USD` |
|
|
|
|
### حقول منطقية
|
|
|
|
استخدم أحرفًا كبيرة: `TRUE` أو `FALSE`
|
|
|
|
<Warning>الأحرف الصغيرة `true` أو `false` لن تعمل.</Warning>
|
|
|
|
### اختر الحقول
|
|
|
|
استخدم **اسم واجهة برمجة التطبيقات (API)** للخيار، وليس اسم العرض.
|
|
|
|
**كيفية العثور على أسماء واجهة برمجة التطبيقات (API):**
|
|
|
|
1. انتقل إلى **الإعدادات → نموذج البيانات**
|
|
2. اختر الكائن والحقل
|
|
3. فعّل **الوضع المتقدم** (المبدّل في أسفل اليمين)
|
|
4. انسخ اسم واجهة برمجة التطبيقات (مثال: `OPTION_1`، وليس "Option 1")
|
|
|
|
<Note>خيارات الاختيار الجديدة لا يتم إنشاؤها تلقائيًا. أضِفها في **الإعدادات → نموذج البيانات** قبل الاستيراد.</Note>
|
|
|
|
### حقول متعددة الاختيار
|
|
|
|
استخدم أسماء واجهة برمجة التطبيقات بصيغة المصفوفة:
|
|
|
|
```
|
|
["VALUE1","VALUE2"]
|
|
```
|
|
|
|
### حقول المصفوفة
|
|
|
|
استخدم صيغة مصفوفة JSON:
|
|
|
|
```
|
|
["value1","value2"]
|
|
```
|
|
|
|
### حقول التقييم
|
|
|
|
استخدم الصيغة: `RATING_1` و`RATING_2` و`RATING_3` و`RATING_4` أو `RATING_5`
|
|
|
|
### حقول الروابط/عناوين URL
|
|
|
|
املأ كلا العمودين:
|
|
|
|
* **الروابط / تسمية الرابط**: `Twenty`
|
|
* **الروابط / عنوان URL للرابط**: `https://twenty.com`
|
|
|
|
بالنسبة للروابط الثانوية، استخدم عمود **الروابط / الروابط الثانوية**:
|
|
|
|
```
|
|
[{"url":"https://twenty.com","label":"Twenty"}]
|
|
```
|
|
|
|
### حقول JSON
|
|
|
|
استخدم تنسيق JSON صالحًا:
|
|
|
|
```
|
|
{"key":"value","key2":"value2"}
|
|
```
|
|
|
|
### حقول المعرّف
|
|
|
|
* **اختياري**: يقوم Twenty بإنشاء المعرّفات تلقائيًا إذا لم تُوفَّر
|
|
* **التنسيق**: UUID (مثلًا: `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`)
|
|
* **حالة الاستخدام**: تضمين المعرّف لتحديث السجلات الموجودة بدلًا من إنشاء سجلات جديدة
|
|
|
|
## الخطوة 5: إضافة أعمدة العلاقات (إذا كنت تربط السجلات)
|
|
|
|
لربط السجلات بكائنات أخرى (مثل الأشخاص بالشركات)، أضِف عمودًا يحتوي على المعرّف الفريد للسجل المرتبط.
|
|
|
|
**مثال**: ربط الأشخاص بالشركات
|
|
|
|
أضِف عمودًا إلى ملف CSV الخاص بالأشخاص:
|
|
|
|
```
|
|
firstName,lastName,email,companyDomain
|
|
John,Smith,john@acme.com,https://acme.com
|
|
Jane,Doe,jane@widgets.co,https://widgets.co
|
|
```
|
|
|
|
**قواعد مهمة للعلاقات:**
|
|
|
|
* يجب أن يكون السجل الأب موجودًا مسبقًا في Twenty
|
|
* استخدم صيغة **عنوان المجال (Domain URL)** (`https://domain.com`) وليس التسمية
|
|
* قم بربط مُعرّف فريد واحد فقط (لا تُدرج كلاً من `companyId` و`companyDomain`)
|
|
* بالنسبة لأعضاء مساحة العمل، استخدم **البريد الإلكتروني** الخاص بهم (وليس الاسم)
|
|
|
|
<Warning>
|
|
**ترتيب الاستيراد مهم!**
|
|
|
|
استورد طرف "الواحد" قبل طرف "الكثير":
|
|
1. **الشركات** أولاً
|
|
2. **الأشخاص** ثانيًا (مع مرجع الشركة)
|
|
3. **الفرص** ثالثًا
|
|
|
|
يجب أن يوجد السجل الأب قبل أن تتمكن من الإشارة إليه.
|
|
</Warning>
|
|
|
|
اطلع على [كيفية استيراد العلاقات](/l/ar/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>حقول الاختيار تستخدم أسماء واجهة برمجة التطبيقات، وليس أسماء العرض</Check>
|
|
<Check>جميع الحقول المخصصة موجودة في الإعدادات → نموذج البيانات</Check>
|
|
<Check>تم استيراد السجلات الأصلية قبل السجلات الفرعية</Check>
|
|
<Check>أعمدة العلاقات تشير إلى سجلات موجودة</Check>
|
|
|
|
## أخطاء شائعة يجب تجنبها
|
|
|
|
| الخطأ | الحل |
|
|
| ---------------------------------- | ----------------------------------------------------------- |
|
|
| استخدام `true` بدلًا من `TRUE` | يجب أن تكون القيم المنطقية بأحرف كبيرة |
|
|
| استخدام أسماء العرض لحقول الاختيار | اعثر على أسماء واجهة برمجة التطبيقات في الإعدادات واستخدمها |
|
|
| استيراد الأشخاص قبل الشركات | احرص دائمًا على استيراد الكائنات الأصل أولًا |
|
|
| رمز العملة مفقود لحقول العملة | املأ عمودي المبلغ والعملة معًا |
|
|
| تنسيق نطاق غير صحيح | استخدم `https://domain.com` بصورة متسقة |
|
|
| ربط عدة حقول فريدة للعلاقات | اربط حقلًا واحدًا فقط (النطاق أو المعرّف، وليس كليهما) |
|
|
|
|
## الخطوات التالية
|
|
|
|
ملفك جاهز! الآن:
|
|
|
|
* [استيراد الشركات](/l/ar/user-guide/data-migration/how-tos/import-companies-via-csv) (قم باستيرادها أولًا)
|
|
* [استيراد جهات الاتصال](/l/ar/user-guide/data-migration/how-tos/import-contacts-via-csv)
|
|
* [إصلاح أي أخطاء في الاستيراد](/l/ar/user-guide/data-migration/how-tos/fix-import-errors)
|