دليل المزامنة مع ERP

يشرح هذا الدليل كيف تُبقي نظام تخطيط الموارد أو نظام الموارد البشرية (Oracle HCM أو SAP SuccessFactors أو Odoo أو نظام داخلي) وجديرون متطابقين: يبقى نظامك المصدر المعتمد للسجلات التي يملكها، ويبلغك جديرون بكل ما يتغير من جهته.

1. حدّد من يملك ماذا

امنح التكامل الصلاحيات اللازمة لما يكتبه ويقرؤه فقط (انظر النطاقات).

2. اربط السجلات بالمعرّفات الخارجية

يمكن أن يحمل كل سجل في مساحة العمل روابط إلى معرّفاتك: externalRefs: [{ system, externalId }]. اختر اسم system واحدًا لكل نظام مصدر تزامنه (مثل oracle-hcm) وحافظ عليه دائمًا.

اكتب بالإنشاء أو التعديل حسب المعرّف الخارجي:

curl -X PUT https://jadiroon.com/api/v1/employees/by-external/oracle-hcm/EMP-1002 \
  -H "Authorization: Bearer $JADIROON_KEY" -H "Content-Type: application/json" \
  -d '{
    "firstName": "Omar", "lastName": "Alqahtani",
    "manager": { "externalSystem": "oracle-hcm", "externalId": "EMP-1001" },
    "currentPosition": { "externalSystem": "oracle-hcm", "externalId": "POS-310" }
  }'

• لا يوجد سجل مربوط بـ oracle-hcm / EMP-1002: يُنشأ سجل من الجسم ويُربط، والرد 201.
• يوجد سجل مربوط: يُطبَّق الجسم كأنه PATCH (تبقى الحقول غير المرسلة)، والرد 200.
• الإنشاء أو التعديل متاح للوحدات التنظيمية والوظائف والموظفين (PUT /api/v1/{org-units|positions|employees}/by-external/{system}/{externalId})، وبالجملة لها وللمرشحين.
• الأوصاف الوظيفية ليس لها نقطة إنشاء أو تعديل بالمعرّف الخارجي: أنشئها بـ POST /api/v1/job-descriptions وأرسل externalRef: { externalSystem, externalId } في الجسم (أو في PATCH لاحق) لربط معرّفك. ثم تستطيع الوظائف تسميتها بمعرّفك.
• ابحث عن سجل بمعرّفك دون تغييره: GET /api/v1/employees?externalSystem=oracle-hcm&externalId=EMP-1002 (المعاملان معًا أو لا شيء).
• المعرّف الخارجي يرتبط بسجل واحد، وللسجل معرّف واحد على الأكثر لكل system. وربط معرّف مأخوذ يعيد 409 conflict، إلا إذا لم يعد السجل الذي كان يحمله موجوداً (حُذف من التطبيق مثلاً): فيُزال الربط القديم ويرتبط المعرّف بالسجل الجديد.

3. أشر إلى السجلات الأخرى بمعرّفاتك

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

{ "orgUnit": { "id": "cmv…" } }
{ "orgUnit": { "externalSystem": "oracle-hcm", "externalId": "ORG-200" } }

المرجع الذي لا يوجد في مساحة عملك يعيد 422 unresolved_reference مع المرجع في details. حمّل الآباء قبل الأبناء: الوحدات التنظيمية من الأعلى إلى الأسفل، ثم الأوصاف الوظيفية، ثم الوظائف، ثم الموظفين (المديرون قبل مرؤوسيهم، أو جولة ثانية لتعيين manager).

4. صفوف الكتالوج: بالمعرّف الثابت لا بالمعرّف

القطاعات والقطاعات الفرعية والعائلات الوظيفية في الكتالوج الوطني مشتركة بين كل مساحات العمل. اربطها بـ slug الخاص بها، فهو لا يتغير وهو نفسه في كل بيئات جديرون. أما المعرّفات فليست كذلك: تختلف بين البيئات وتتغير عند إعادة تعبئة مساحة عمل اختبارية. لا تنسخ معرّفًا من بيئة جديرون إلى أخرى.

الصفوف التي أنشأتها مساحة عملك بنفسها (عائلات أو قطاعات مخصصة) قيمتها slug: null؛ اربطها بجدول ربط خاص بك.

5. استقبل تغييرات جديرون

خياران، ويُجمع بينهما غالبًا:

• خطافات الويب (شبه فورية): اشترك بنقطة استقبال في الأحداث التي تهمك، مثل employee.* وapplication.hired. انظر خطافات الويب.
• الاستعلام الدوري: اقرأ كل قائمة بـ updatedSince وسجل المحذوفات وفق جدول. وهو أيضًا شبكة الأمان إن تعطلت نقطة الاستقبال أطول من فترة إعادة المحاولة.

تحمل كل حمولة خطاف ويب وكل كائن externalRefs، فتطابقه مع سجلك دون حفظ معرّفات جديرون.

6. ماذا يحدث للروابط عند زوال السجلات

• الحذف النهائي (في التطبيق أو الواجهة البرمجية) يزيل روابط السجل في الخطوة نفسها ويكتب أثر حذف بالروابط التي كانت له، يمكن قراءته 180 يومًا في GET /api/v1/deleted.
• إذا حُذف سجل مربوط في التطبيق ثم أرسلت المعرّف الخارجي نفسه مجددًا، ينشئ جديرون سجلًا جديدًا ويربطه: لا تحتاج إلى تنظيف مسبق.
• التعيين ينقل روابط المرشح إلى سجل الموظف الجديد.
• إنهاء الخدمة (DELETE /api/v1/employees/{id}) يُبقي السجل وروابطه، وتصبح الحالة FORMER_EMPLOYEE.

7. قائمة التحقق

• تكامل واحد لكل بيئة، بأضيق نطاق يكفي.
• اسم system واحد لكل نظام مصدر.
• ترتيب التحميل: الوحدات التنظيمية ← الأوصاف الوظيفية ← الوظائف ← الموظفون.
• التحميل الأول بالجملة (انظر الترحيل المجمّع)، ثم التغييرات فرديًا أو بدفعات صغيرة.
• اشترك في خطافات الويب واستعلم يوميًا أيضًا بـ updatedSince و/deleted كشبكة أمان.
• أعد قراءة قوائم الكتالوج (/sectors و/sub-sectors و/job-families) يوميًا.