الترحيل المجمّع

استخدم هذا الدليل للتحميل الأول لمنظمة قائمة إلى جديرون، أو لأي مزامنة لآلاف السجلات. وهو يعتمد على نقاط الإدراج المجمّع: حتى 1,000 صف في الطلب، مربوطة بمعرّفاتك، تُعالج في الخلفية مع نتيجة لكل صف.

قبل أن تبدأ

1. أنشئ تكاملًا مخصصًا للترحيل (مثل "Oracle HCM – ترحيل") بصلاحيات الكتابة التي يحتاجها فقط: structure.org.act للوحدات التنظيمية والوظائف، وpeople.act للموظفين، وrecruitment.act للمرشحين، وstructure.functional.act إن كنت ستنشئ أوصافًا وظيفية. ولاستيراد بريد المرشحين أو هواتفهم أو أرقام هوياتهم / إقاماتهم يحتاج التكامل أيضًا إلى recruitment.candidate.contact: ودونها يفشل كل صف مرشح يحمل بيانات تواصل بـ403 forbidden (candidate_contact_required).
2. اتفق على اسم system الذي ستستخدمه في كل رابط (مثل oracle-hcm). فبه تجد المزامنات اللاحقة السجلات نفسها.
3. اربط الكتالوج. اختر قطاع مساحة العمل وقطاعاتها الفرعية وعائلاتها الوظيفية في جديرون أولًا (التهيئة أو الهيكل)، ثم اربط عائلاتك الوظيفية بها عبر slug (انظر الأعراف).
4. قرّر بشأن خطافات الويب. كل سجل مُرحَّل يرسل حدثه الخاص (حدث لكل سجل). فإن كانت نقطة استقبال مشتركة في *، فتحميل 300,000 موظف يعني 300,000 إرسال إليها. أوقف نقطة الاستقبال مؤقتًا أثناء الترحيل، أو اشترك فيما تحتاجه فقط، ثم استدرك بعد ذلك بـ updatedSince.
5. جرّبه على مساحة عمل اختبارية ببضع مئات من الصفوف قبل تشغيل الإنتاج.

ترتيب التحميل

يجب أن توجد المراجع قبل الصفوف التي تستخدمها:

إرسال المهام

• قسّم كل خطوة إلى دفعات حتى 1,000 صف.
• أعطِ كل دفعة Idempotency-Key خاصًا بها (مثل migration-2026-11-employees-chunk-0042). وإن أخفى خطأ شبكة الرد 202، فأرسل الدفعة نفسها بالمفتاح نفسه: يعود إليك jobId نفسه ولا يُنفَّذ شيء مرتين.
• يمكن أن يكون للتكامل مهمتان في الانتظار أو قيد التشغيل في الوقت نفسه. والثالثة تتلقى 429 too_many_jobs: تابع مهمة جارية، وأرسل الدفعة التالية عند انتهاء إحداهما.
• تبدأ المهمة فور الرد 202 وتعمل حتى دقيقة تقريبًا. وفي الخدمة المستضافة، يُكمل ما تبقى من مهمة لم تنتهِ حينها (والمهمة المعلّقة بإيقاف مؤقت) مُرسِلٌ يعمل في الخلفية، وتشغّله الخدمة حاليًا مرة واحدة يوميًا (03:00 بالتوقيت العالمي UTC). في الترحيل الكبير، تحقّق من كل مهمة بعد دقيقتها الأولى، وخطّط لاكتمال ما تبقى في التشغيل اليومي التالي.
• يُحسب طلب الإدراج المجمّع طلبًا واحدًا من حد المعدل (600 في الدقيقة لكل مفتاح)، فالمتابعة هي ما يستهلك رصيدك: تابع كل مهمة كل بضع ثوانٍ، لا في حلقة متواصلة.

curl -X POST https://jadiroon.com/api/v1/employees/bulk \
  -H "Authorization: Bearer $JADIROON_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: migration-2026-11-employees-chunk-0001" \
  -d @employees-chunk-0001.json
# → 202 { "jobId": "cmv…", "statusUrl": "/api/v1/bulk-jobs/cmv…" }

curl "https://jadiroon.com/api/v1/bulk-jobs/cmv…?status=failed" -H "Authorization: Bearer $JADIROON_KEY"

معالجة الصفوف الفاشلة

الصف السيئ يفشل وحده، ويستمر باقي المهمة. وعندما تصبح المهمة DONE:

1. اقرأ GET /api/v1/bulk-jobs/{id}?status=failed (مرقّمة) وصحّح كل صف حسب index.
2. أرسل الصفوف المصححة مجددًا كمهمة جديدة بـ Idempotency-Key جديد. والإنشاء أو التعديل بالمعرّف الخارجي يجعل ذلك آمنًا: الصفوف التي نجحت تُحدَّث بالقيم نفسها فقط.
3. الصفوف التي فشلت بـ internal واجهت مشكلة من جهتنا: أعد إرسالها دون تغيير في مهمة جديدة. وإن فشلت مجددًا فتواصل مع الدعم مع معرّف المهمة.

أخطاء شائعة: unresolved_reference (أب أو وظيفة أو مدير لم يُحمَّل بعد؛ راجع ترتيب التحميل)، وvalidation_failed مع details.reason (مثل first_name_required)، وconflict (duplicate_person أو position_full)، وforbidden (ينقص التكامل صلاحية).

ما يؤثر في المهام الجارية

• إيقاف التكامل مؤقتًا يعلّق مهامه: تتوقف المهمة الجارية بعد الدفعة التي تعالجها (حتى 50 صفًا)، ولا تُلتقط أي مهمة ما دام التكامل موقوفًا، ثم تُستأنف من حيث توقفت عند تفعيله. والمهام المعلّقة تُحتسب ضمن حد المهمتين.
• إلغاء المفتاح الذي أرسل المهمة لا يوقفها: تكتمل باسم التكامل الذي أرسلها. أوقف التكامل مؤقتًا لإيقافها.
• إزالة صلاحية تحتاجها المهمة (مثل people.act) تُفشل صفوفها المتبقية بـ forbidden بدءًا من الدفعة التالية.
• تعليق مساحة العمل يعلّق مهامها بالطريقة نفسها: تتوقف المهمة الجارية بعد الدفعة التي تعالجها، ثم تُستأنف مهامها من حيث توقفت عندما تعود مساحة العمل نشطة.
• المهمة التي لا يمكن تشغيلها إطلاقًا (مثل انتهاء صلاحية صفوفها) تنتهي بالحالة FAILED.
• تُحذف الصفوف التي أرسلتها عند وصول المهمة إلى DONE (وبعد نحو أسبوع من إنشائها على الأكثر)، وتبقى نتائج كل صف قابلة للقراءة.

بعد الترحيل

• تحقق من الأعداد: صفحات GET /api/v1/employees?limit=100، أو تبويب مهام الإدراج المجمّع للتكامل في الإعدادات ← التكاملات، الذي يعرض كل مهمة مع أعدادها والصفوف الفاشلة.
• استأنف نقاط الاستقبال أو اشترك بها، ثم انتقل إلى المزامنة اليومية: طلبات PUT …/by-external/… فردية أو مهام صغيرة للتغييرات، وخطافات الويب أو الاستعلام بـ updatedSince للاتجاه المعاكس. انظر دليل المزامنة مع ERP.
• توقّع أن يحتوي سجل التدقيق صفًا لكل سجل مُرحَّل، وتكاملك هو الفاعل.