الانتقال إلى المحتوى الرئيسي

​
نظرة عامة

يرشدك هذا الدليل إلى كيفية إعداد ملف CSV لاستيراد ناجح. اتّبع هذه الخطوات لتجنّب الأخطاء.

​
الخطوة 1: التحقّق من متطلبات الملف

قبل البدء، تأكّد من أنّ ملفك يستوفي هذه المتطلبات:
المتطلبتفاصيل
التنسيقCSV، XLSX، أو XLS
الحد الأقصى للحجم10,000 سجل لكل ملف
الترميزيوصى باستخدام UTF-8
البنيةنوع كائن واحد لكل ملف
بالنسبة لمجموعات البيانات التي تزيد على 10,000 سجل، قم بتقسيمها إلى عدة ملفات أو استخدم الاستيراد عبر API.

​
الخطوة 2: تنزيل الملف النموذجي

هذه هي أهم خطوة. يوضّح لك الملف النموذجي أسماء الأعمدة الدقيقة والتنسيق الذي تتوقعه Twenty.
  1. انتقل إلى عرض الكائن (الأشخاص، الشركات، إلخ)
  2. انقر ⋮ → استيراد السجلات
  3. انقر تنزيل الملف النموذجي
  4. استخدم هذا الملف كقالب
نصيحة احترافية: بدلًا من ذلك، صدِّر عددًا قليلًا من السجلات الموجودة. سيوفّر لك هذا أمثلة حقيقية على كيفية تنسيق البيانات، كما ستُطابَق أسماء الأعمدة تلقائيًا أثناء الاستيراد.

​
الخطوة 3: إزالة القيم المكررة

تفرض Twenty التفرّد على حقول معيّنة. ستتسبب القيَم المكررة في أخطاء أثناء الاستيراد.
كائنالحقول الفريدة
الأشخاصid, email
الشركاتid, domain
كائنات مخصصةid، بالإضافة إلى أي حقل وضعته كفريد
قبل الاستيراد:
  1. قم بفرز جدول البيانات حسب الحقل الفريد (البريد الإلكتروني أو النطاق)
  2. أزِل الصفوف المكررة أو ادمجها
  3. تحقّق من التكرارات الموجودة مسبقًا في Twenty
السجلات المحذوفة مؤقتًا تُحتسب ضمن التفرّد. السجلات الموجودة في قائمة الأوامر → عرض السجلات المحذوفة ستتسبب في أخطاء تكرار. احذفها نهائيًا أو استعدها وقم بتحديثها.

​
الخطوة 4: تنسيق كل نوع من الحقول بشكل صحيح

تتطلب أنواع الحقول المختلفة تنسيقات محددة. إليك المرجع الكامل:

​
حقول النص

  • لا يلزم تنسيق خاص
  • تُزال الفراغات في البداية والنهاية تلقائيًا

​
حقول البريد الإلكتروني

  • يجب أن يكون بتنسيق بريد إلكتروني صالح: [email protected]
  • يجب أن تكون فريدة (بدون تكرارات في الملف أو في Twenty)
  • للعناوين الإضافية للبريد الإلكتروني، استخدم هذا التنسيق في عمود Emails / Additional Emails:
[\"[email protected]\",\"[email protected]\"]

​
حقول النطاق

  • التنسيق الموصى به: https://domain.com
  • يتطابق هذا مع التنسيق المستخدم في مزامنة صندوق البريد/التقويم (يمنع التكرارات)
  • املأ كلا العمودين:
    • Domain / Domain Label: domain.com
    • Domain / Domain URL: https://domain.com
  • يجب أن تكون فريدة داخل ملفك وفي Twenty

​
حقول الهاتف

الهاتف حقل متداخل يتطلب عدة أعمدة:
العمودمثال
Phones / Primary Phone Number4159095555
Phones / Primary Phone Country CodeUS
Phones / Primary Phone Calling Code+1

​
حقول العنوان

العنوان هو حقل متداخل يحتوي على أعمدة متعددة (يمكن ترك بعضها فارغًا):
  • العنوان / العنوان 1: السطر الأول لعنوان الشارع
  • العنوان / العنوان 2: السطر الثاني لعنوان الشارع (اختياري)
  • العنوان / المدينة: اسم المدينة
  • العنوان / الولاية: ولاية أو مقاطعة
  • العنوان / البلد: اسم البلد
  • العنوان / الرمز البريدي: رمز بريدي/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)

​
حقول العملة

العملة هي حقل متداخل يتطلب عمودين يجب ملؤهما كليهما:
العمودمثال
المبلغ / المبلغ1234.56
المبلغ / العملةUSD

​
حقول منطقية

استخدم أحرفًا كبيرة: TRUE أو FALSE
الأحرف الصغيرة true أو false لن تعمل.

​
اختر الحقول

استخدم اسم واجهة برمجة التطبيقات (API) للخيار، وليس اسم العرض. كيفية العثور على أسماء واجهة برمجة التطبيقات (API):
  1. انتقل إلى الإعدادات → نموذج البيانات
  2. اختر الكائن والحقل
  3. فعّل الوضع المتقدم (المبدّل في أسفل اليمين)
  4. انسخ اسم واجهة برمجة التطبيقات (مثال: OPTION_1، وليس “Option 1”)
خيارات الاختيار الجديدة لا يتم إنشاؤها تلقائيًا. أضِفها في الإعدادات → نموذج البيانات قبل الاستيراد.

​
حقول متعددة الاختيار

استخدم أسماء واجهة برمجة التطبيقات بصيغة المصفوفة: 
["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,[email protected],https://acme.com
Jane,Doe,[email protected],https://widgets.co
قواعد مهمة للعلاقات:
  • يجب أن يكون السجل الأب موجودًا مسبقًا في Twenty
  • استخدم صيغة عنوان المجال (Domain URL) (https://domain.com) وليس التسمية
  • قم بربط مُعرّف فريد واحد فقط (لا تُدرج كلاً من companyId وcompanyDomain)
  • بالنسبة لأعضاء مساحة العمل، استخدم البريد الإلكتروني الخاص بهم (وليس الاسم)
ترتيب الاستيراد مهم!استورد طرف “الواحد” قبل طرف “الكثير”:
  1. الشركات أولاً
  2. الأشخاص ثانيًا (مع مرجع الشركة)
  3. الفرص ثالثًا
يجب أن يوجد السجل الأب قبل أن تتمكن من الإشارة إليه.
اطلع على كيفية استيراد العلاقات للحصول على تعليمات مفصلة.

​
الخطوة 6: تأكد من وجود الحقول في Twenty

تقوم عملية الاستيراد بإنشاء سجلات، وليس حقولًا. يجب أن تكون جميع الحقول التي تريد استيرادها موجودة مسبقًا في نموذج البيانات لديك. قبل الاستيراد:
  1. انتقل إلى الإعدادات → نموذج البيانات
  2. اختر الكائن الخاص بك
  3. أنشئ أي حقول مخصصة تحتاجها
  4. دوّن أسماء الحقول بدقة (يجب أن تتطابق مع عناوين أعمدتك)

​
الخطوة 7: قائمة التحقق النهائية

قبل رفع ملفك، تحقّق مما يلي:
الملف بصيغة CSV أو XLSX أو XLS
يحتوي الملف على أقل من 10,000 سجل
الترميز UTF-8
لا توجد رسائل بريد إلكتروني مكررة (للأشخاص) أو نطاقات (للشركات)
التواريخ تستخدم تنسيقًا موحدًا طوال الملف
النطاقات تستخدم الصيغة https://domain.com
الحقول المنطقية تستخدم TRUE أو FALSE (أحرف كبيرة)
حقول الاختيار تستخدم أسماء واجهة برمجة التطبيقات، وليس أسماء العرض
جميع الحقول المخصصة موجودة في الإعدادات → نموذج البيانات
تم استيراد السجلات الأصلية قبل السجلات الفرعية
أعمدة العلاقات تشير إلى سجلات موجودة

​
أخطاء شائعة يجب تجنبها

الخطأالحل
استخدام true بدلًا من TRUEيجب أن تكون القيم المنطقية بأحرف كبيرة
استخدام أسماء العرض لحقول الاختياراعثر على أسماء واجهة برمجة التطبيقات في الإعدادات واستخدمها
استيراد الأشخاص قبل الشركاتاحرص دائمًا على استيراد الكائنات الأصل أولًا
رمز العملة مفقود لحقول العملةاملأ عمودي المبلغ والعملة معًا
تنسيق نطاق غير صحيحاستخدم https://domain.com بصورة متسقة
ربط عدة حقول فريدة للعلاقاتاربط حقلًا واحدًا فقط (النطاق أو المعرّف، وليس كليهما)

​
الخطوات التالية

ملفك جاهز! الآن: