تكامل SFTP الافتراضي مع KnowledgeCity

الملخص

يتيح تكامل SFTP الافتراضي لـ KnowledgeCity تبادل البيانات مع الأنظمة الخارجية باستخدام اتصال FTP آمن (SFTP) — دون الحاجة إلى تكامل API مباشر من الجانب الخارجي.

يدعم ثلاث تدفقات أساسية:

• استيراد المستخدمين إلى KnowledgeCity من صندوق وارد SFTP
• تصدير إكمالات الدورات من KnowledgeCity إلى وجهة SFTP
• تصدير بيانات فهرس الدورات من KnowledgeCity إلى وجهة SFTP

يمكن جدولة جميع العمليات لتعمل تلقائيًا على أساس يومي أو أسبوعي.

مقدمة

الغرض من هذا التكامل هو تمكين تبادل البيانات الآلي القائم على الملفات بين KnowledgeCity ونظام خارجي عبر اتصال SFTP آمن. وهو يتيح للمسؤولين:

• التزويد التلقائي بالمستخدمين وتحديثهم في KnowledgeCity من أنظمة الموارد البشرية أو الأدلة التي تُنتج ملفات تصدير CSV
• إرسال سجلات إكمال الدورات إلى أنظمة إعداد التقارير أو الامتثال الخارجية عبر SFTP
• مشاركة فهرس دورات KnowledgeCity مع المنصات الخارجية بتنسيق CSV

يُعد هذا مثاليًا للمؤسسات التي لا تملك تكامل REST API مباشرًا متاحًا ولكن يمكنها تبادل الملفات عبر SFTP وفق جدول زمني.

المتطلبات

قبل إعداد تكامل SFTP الافتراضي، تأكد من استيفاء المتطلبات الأساسية التالية:

صلاحيات المسؤول

• يجب أن تمتلك صلاحية وصول مسؤول (Administrator) في نظام KnowledgeCity LMS لتفعيل التكاملات وتهيئتها.

الوصول إلى API الخاص بـ KnowledgeCity

• يلزم توفر عنوان API URL الأساسي ومفتاح API السري (API Secret) صالحين لـ KnowledgeCity. يُوصى بإنشاء مستخدم مخصص للتكامل واستخدام مفتاح API السري الخاص بذلك المستخدم.
• استخدم api.knowledgecity.com للبوابات القياسية، أو api-sa.knowledgecity.com لبوابات RB ومنطقة MENA.

تفاصيل خادم SFTP

يجب أن تكون تفاصيل اتصال SFTP التالية جاهزة لكل وجهة تصدير/استيراد:

• مضيف SFTP (SFTP Host)
• منفذ SFTP (SFTP Port)
• اسم مستخدم SFTP
• مفتاح SFTP الخاص (مُرمَّز بصيغة base64)
• مسار الوجهة (للتصدير) أو مساري صندوق الوارد/المستلَم (للاستيراد)

ملاحظة: يجب ترميز محتوى ملف المفتاح الخاص بصيغة base64 قبل لصقه في التهيئة. يمكنك استخدام أداة ترميز base64 عبر الإنترنت لتحويل ملف المفتاح الخاص بك.

جاهزية تنسيق ملف CSV

• بالنسبة لاستيراد المستخدمين: يجب أن يحتوي ملف CSV المصدر على عناوين أعمدة ستقوم بمطابقتها مع حقول مستخدمي KnowledgeCity (مثل مطابقة UserLoginName مع اسم المستخدم).
• بالنسبة للتصدير: ستحدد عناوين الأعمدة وترتيبها في التهيئة.

الخطوات المتبعة

1) تفعيل التكامل الافتراضي

• سجّل الدخول إلى نظام KnowledgeCity LMS بصفتك مسؤولًا.
• انتقل إلى صفحة التكاملات (Integrations).
• ابحث عن بطاقة التكامل الافتراضي (Default Integration).
• انقر على تفعيل (Enable) وتأكد من تحديد مربع تشغيل (Turn On) الرئيسي.

مهم: تشغيل (Turn On) الرئيسي على المستوى الأعلى هو مفتاح التحكم الرئيسي. إذا لم يكن محددًا، سيتجاهل النظام جميع الإعدادات الفرعية (التصدير والاستيراد)، بغض النظر عن إعداداتها الفردية.

2) تهيئة إعدادات API الخاصة بـ KnowledgeCity

ضمن قسم KnowledgeCity API، أدخل:

• عنوان API الأساسي (Base API URL): عنوان API الأساسي لـ KnowledgeCity مع رقم الإصدار (مثل https://api.knowledgecity.com/v1)
• مفتاح API السري (API Secret): مفتاح API السري الخاص بمستخدم التكامل المخصص

احفظ التغييرات.

3) تهيئة تصدير إكمال الدورة (اختياري)

لتصدير سجلات إكمال الدورات من KnowledgeCity إلى خادم SFTP الخاص بك:

• وسّع إعداد التصدير (Export Setup) وحدد تشغيل (Turn On).
• وسّع تصدير إكمال الدورة (Export Course Completion) وحدد تشغيل (Turn On).
• عيّن نمط اسم ملف التصدير (استخدم [date]Ymd[/date] في الاسم لإدراج تاريخ التصدير تلقائيًا).
• عيّن تنسيق تاريخ التصدير لحقلي تاريخ البدء وتاريخ النجاح (اتركه فارغًا للتصدير كطابع زمني Unix).
• حدد حقول CSV: حدد عناوين الأعمدة وترتيبها في ملف الإخراج.

ضمن القسم الفرعي وجهة FTP (FTP Destination):

• حدد تشغيل (Turn On).
• أدخل تفاصيل اتصال SFTP الخاصة بك: المضيف، والمنفذ، واسم المستخدم، والمفتاح الخاص المُرمَّز بصيغة base64.
• عيّن مسار الوجهة (Target path) (نسبي أو مطلق) الذي سيتم نقل الملف الذي تم إنشاؤه إليه.

ضمن إعداد الجدولة (Schedule Setup):

• حدد تشغيل (Turn On) وقم بتهيئة التكرار اليومي أو الأسبوعي.

4) تهيئة تصدير الدورات (اختياري)

لتصدير فهرس دورات KnowledgeCity إلى خادم SFTP الخاص بك:

• ضمن إعداد التصدير، وسّع تصدير الدورات (Export Courses) وحدد تشغيل (Turn On).
• عيّن نمط اسم ملف التصدير.
• حدد حقول CSV: حدد عناوين الأعمدة وترتيبها.

ضمن القسم الفرعي وجهة FTP:

• حدد تشغيل (Turn On) وأدخل تفاصيل اتصال SFTP ومسار الوجهة.

ضمن إعداد الجدولة:

• حدد تشغيل (Turn On) وقم بتهيئة التكرار المطلوب.

5) تهيئة استيراد المستخدمين (اختياري)

لاستيراد المستخدمين من ملف CSV على خادم SFTP الخاص بك إلى KnowledgeCity:

• وسّع إعداد الاستيراد (Import Setup) وحدد تشغيل (Turn On).
• وسّع استيراد المستخدمين (Import Users) وحدد تشغيل (Turn On).
• ضمن حقول CSV، طابق عناوين الأعمدة من ملف الاستيراد الخاص بك مع حقول مستخدمي KnowledgeCity (مثل UserLoginName ← اسم المستخدم).

ضمن معالجة البيانات الوصفية (Metadata Handling)، قم بتهيئة سلوك الاستيراد:

• تعيين ترخيص تلقائي (Autoassign licence): تعيين أول ترخيص متاح للمستخدمين المستوردين (يُتجاهل إذا تم تحديد معرّف الاشتراك)
• معرّف الاشتراك (Subscription ID): تعيين اشتراك محدد للمستخدمين المستوردين
• تعيين ترخيص عند تحديث المستخدم: محاولة تعيين ترخيص أيضًا للمستخدمين الحاليين أثناء التحديثات
• تفعيل وضع المحاكاة (Enable simulation mode): وضع تجربة تشغيلية للاختبار؛ لن تُكتب أي بيانات إلى KC
• اسم المجموعة الافتراضية: إضافة المستخدمين الجدد إلى مجموعة افتراضية إذا لم تُحدَّد في ملف الاستيراد
• إنجاح المهمة عند تكرار مستخدم جديد: المتابعة مع تحذير بدلاً من الفشل إذا تم اكتشاف مستخدم مكرر
• تفعيل وتعيين ترخيص لمستخدم معطّل عند التحديث: إعادة تفعيل وترخيص مستخدم كان معطّلاً سابقًا
• تخطي المستخدم إذا كان موجودًا في إجراء الإضافة/التحديث: إنشاء مستخدمين جدد مع تخطي الموجودين منهم
• تعيين الاشتراك حسب اسم المجموعة: ربط الاشتراكات بأسماء مجموعات محددة
• تضمين/استبعاد الحقول حسب الإجراء: التحكم في الحقول التي تنطبق على إجراءي الإضافة والتحديث
• الحقول المطلوبة: تحديد الحقول التي يجب أن تكون موجودة لإجراءات الإضافة

لإلغاء تفعيل المستخدمين غير الموجودين في ملف الاستيراد، حدد تشغيل (Turn On) ضمن إلغاء تفعيل المستخدمين غير المدرجين في القائمة وقم بتهيئة:

• إلغاء التفعيل دائمًا أو إلغاء التفعيل عند العثور على كلمة مفتاحية في اسم الملف
• الحد الأدنى لعدد الصفوف: حد أمان لمنع إلغاء التفعيل الجماعي العرضي الناتج عن ملفات صغيرة أو اختبارية

ضمن القسم الفرعي مصدر FTP (FTP Source):

• حدد تشغيل (Turn On) وأدخل تفاصيل اتصال SFTP الخاصة بك.
• عيّن مسار صندوق الوارد (Inbox path) (حيث يبحث النظام عن ملفات جديدة) ومسار المستلَم (Received path) (حيث يتم نقل الملفات التي تمت معالجتها بعد تنزيلها).

ضمن إعداد الجدولة:

• حدد تشغيل (Turn On) وقم بتهيئة التكرار المطلوب.

النتيجة المتوقعة

نجاح الاتصال والمزامنة

• يكون التكامل مفعّلًا ويتم التحقق من صحة بيانات اعتماد API الخاصة بـ KnowledgeCity.
• يتم التحقق من اتصال SFTP لكل قسم تصدير/استيراد مفعّل.

تصدير إكمال الدورة (إذا كان مفعّلاً)

• يتم إنشاء ملف CSV يحتوي على سجلات الإكمال ونقله إلى مسار وجهة SFTP المُهيَّأ وفق الجدول الزمني المحدد.
• يتضمن اسم الملف تاريخ التصدير عند استخدام النمط [date]Ymd[/date].

تصدير الدورات (إذا كان مفعّلاً)

• يتم إنشاء ملف CSV يحتوي على بيانات فهرس الدورات ونقله إلى مسار وجهة SFTP المُهيَّأ وفق الجدول الزمني المحدد.

استيراد المستخدمين (إذا كان مفعّلاً)

• تُنزَّل ملفات CSV الجديدة الموجودة في صندوق وارد SFTP وتتم معالجتها.
• يتم إنشاء المستخدمين أو تحديثهم أو إعادة تنشيطهم أو إلغاء تنشيطهم في KnowledgeCity وفقًا لتهيئة الاستيراد.
• تُنقل الملفات التي تمت معالجتها من صندوق الوارد إلى مسار المستلَم.

استكشاف الأخطاء وإصلاحها