> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://helpdesk.ggcircuit.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 👥 ggLeap استيراد المستخدمين

# 🧭 المقدمة

يتطلب استيراد المستخدمين إلى ggLeap تكوين كيفية تعيين حقول مدخلات CSV إلى قاعدة بيانات مستخدمي ggLeap الداخلية. يشرح هذا الدليل الحقول المدعومة للمستخدمين وكيفية إعداد تكوين تعيين الاستيراد الخاص بك.

---

## 📋 الحقول المدعومة للمستخدمين

الحقول التالية مدعومة حالياً لاستيراد المستخدمين:

* `UniversityUserId` (حصري لمراكز الجامعات والمدارس K–12)
* `Email`
* `Username`
* `FirstName`
* `LastName`

---

## 📦 إجراءات الاستيراد

تدعم وظيفة الاستيراد في ggLeap **إنشاء** و**تحديث** و**أرشفة** المستخدمين.

* إذا كان ملف CSV الخاص بك يستخدم أسماء أعمدة مخصصة، فيرجى تقديم عينة إلى فريق دعم ggCircuit للمساعدة في تكوين التعيينات.
* وبدلاً من ذلك، يمكنك تكوين التعيين بنفسك باستخدام API (لا يتوفر حالياً أي تكوين عبر واجهة المستخدم).

---

## ⚙️ تكوين التعيين

### 4.1 إعداد المحدد

المحدد الافتراضي هو `,` لكن يمكن تعيينه إلى `"auto-detect"` بتحديد `null`.

---

### 4.2 تعيين الأعمدة: CSV → حقول ggLeap

مثال على تكوين التعيين:

```
{
"Config": {
"Mappings": {
"UniversityUserId": {
"TargetFieldName": "UniversityUserId",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "UniversityIdNumber"
},
"MembershipPlaytime": {
"TargetFieldName": "MembershipPlaytime",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "Playtime",
"IsCustomField": false
},
"Membership Start Date": {
"TargetFieldName": "Membership Start Date",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "MembershipStartDate",
"IsCustomField": true
},
"Membership End Date": {
"TargetFieldName": "Membership End Date",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "MembershipEndDate",
"IsCustomField": true
},
"Affiliation": {
"TargetFieldName": "Affiliation",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": null,
"IsCustomField": true
}
},
"Enabled": true,
"Delimiter": null,
"DateFormats": ["yyyy-MM-dd"],
"BooleanValues": {
"FalseValues": ["N", "F", "No", "False", "0"],
"TrueValues": ["Y", "T", "Yes", "True", "1"]
},
"NullValues": ["NULL"]
}
}
```

**مرجع الحقول:**

* `TargetFieldName`: الحقل المقصود في ggLeap.
* `IgnoreField`: اضبط على true لاستبعاد هذا الحقل من الاستيراد.
* `RequireValue`: يشير إلى ما إذا كانت قيمة غير فارغة مطلوبة.
* `SourceHeaderName`: اسم الحقل في ملف CSV المصدر.
* `IsCustomField`: اضبط على `true` للحقول التي لا تكون أصلية في ggLeap (تأكد من وجود هذه الحقول في تكوين تفاصيل المستخدم).

---

### 4.3 حقل الحذف

* `true`: أرشفة المستخدم
* `false`: إلغاء أرشفة المستخدم

---

### 4.4 MembershipPlaytime

يحدد مدة وقت تشغيل Gamepass للمستخدمين المستوردين.

---

### 4.5 تواريخ العضوية

قم بتكوين تواريخ البداية والنهاية للـ Gamepass لكل مستخدم.

---

### 4.6 تحديث تكوين استيراد CSV

استخدم **واجهة برمجية تطبيقات تحديث تكوين استيراد CSV** لتعديل التعيين.

---

### 4.7 الحصول على التكوين الحالي

استخدم **واجهة برمجية تطبيقات الحصول على تكوين استيراد CSV** لجلب التكوين الموجود.

---

### 4.8 إلغاء مهمة الاستيراد

لإيقاف استيراد قيد التشغيل، استخدم **واجهة برمجية تطبيقات إلغاء مهمة استيراد المستخدمين**.

---

## ✅ القيم المنطقية

القيم المقبولة لحقول صحيح/خاطئ:

* **صحيح**: `Y`, `T`, `Yes`, `True`, `1`
* **خاطئ**: `N`, `F`, `No`, `False`, `0`

---

## 📅 صيغ التاريخ

صيغ التاريخ المدعومة في CSV:

* `yyyy-MM-dd`
* `dd/MM/yyyy`
* `MM/dd/yy`
* `dd.MM.yyyy`

---

## 🗺️ نصائح لتعيين أعمدة CSV

عيّن رؤوس CSV المصدرية إلى حقول ggLeap المتوقعة باستخدام تنسيق المثال. قد تخصص هذا بناءً على بنية البيانات الخاصة بمركزك.

---

## 🧠 منطق الاستيراد الإضافي والملاحظات

### مطابقة المستخدمين الموجودين

1. حاول العثور على المستخدم بواسطة `UniversityIdNumber` (معين إلى `StudentId`).
2. إذا لم يتم العثور عليه، حاول المطابقة حسب `EmailAddress`.
3. إذا لم يتم العثور عليه حتى الآن:

* إذا كان لدى مركز آخر نفس البريد الإلكتروني: سجّل **تضارباً**، وتخطَّ السجل.
* إذا كان نفس اسم المستخدم موجوداً في المركز الحالي: سجّل **تضارباً**، وتخطَّ السجل.
* وإلا: **أنشئ مستخدماً جديداً**، واختياراً عين Gamepass.

### تحديث المستخدمين الموجودين

* حدّث جميع الحقول من ملف CSV.
* قبل تحديث `Username`، تحقق من التفرد في المركز الحالي.
* قبل تحديث `EmailAddress`، تحقق من التفرد العام في ggLeap.
* إذا تم أرشفة المستخدم، عيّن كمحذوف.
* إذا تغيّرت قيم العضوية، حدّث أو احذف Gamepass:

* إذا كان `MembershipStartDate` هو `NULL`: أزل Gamepass.
* وإلا: استبدل بـ `MembershipPlaytime` الجديد.

### معالجة الأخطاء والتسجيل

* يجب تسجيل جميع الأخطاء في **سجل الاستيراد**.
* إذا حدثت 5 أخطاء داخلية أو أكثر، أوقف عملية الاستيراد.
* لكل مستخدم تم تحديثه أو إضافته، سجّل الإجراء.
* حدّث **حالة/ملخص الاستيراد** كل 2–5 ثوان.