#حدث ما بعد الإجراء

#مقدمة

جميع التغييرات التي يجريها المستخدمون على البيانات في النظام تتم عادةً من خلال إجراء معين، والذي يكون غالبًا بالنقر على زر. قد يكون هذا الزر زر إرسال في نموذج أو زر إجراء في كتلة بيانات. تُستخدم أحداث ما بعد الإجراء لربط سير العمل ذات الصلة بهذه الإجراءات، وذلك لضمان تشغيل عملية محددة بعد إكمال المستخدم للإجراء بنجاح.

على سبيل المثال، عند إضافة بيانات أو تحديثها، يمكن للمستخدمين تهيئة خيار "ربط سير العمل" لزر معين. بعد اكتمال الإجراء، سيتم تشغيل سير العمل المرتبط به.

على مستوى التنفيذ، نظرًا لأن معالجة أحداث ما بعد الإجراء تتم في طبقة البرمجيات الوسيطة (middleware) (برمجيات Koa الوسيطة)، فإن استدعاءات واجهة برمجة تطبيقات HTTP الخاصة بـ NocoBase يمكنها أيضًا تشغيل أحداث ما بعد الإجراء المحددة.

#التثبيت

هذه إضافة مدمجة، لا تتطلب تثبيتًا.

#تهيئة المشغل

#إنشاء سير عمل

عند إنشاء سير عمل، اختر "حدث ما بعد الإجراء" كنوع:

#وضع التنفيذ

بالنسبة لأحداث ما بعد الإجراء، يمكنك أيضًا اختيار وضع التنفيذ "متزامن" أو "غير متزامن" عند الإنشاء:

إذا كانت العملية تتطلب التنفيذ والعودة الفورية بعد إجراء المستخدم، فيمكنك استخدام الوضع المتزامن؛ وإلا، فإن الوضع الافتراضي هو غير المتزامن. في الوضع غير المتزامن، يكتمل الإجراء فور تشغيل سير العمل، وسيتم تنفيذ سير العمل تباعًا في قائمة انتظار في خلفية التطبيق.

#تهيئة المجموعة

ادخل إلى لوحة سير العمل، وانقر على المشغل لفتح نافذة التهيئة المنبثقة، ثم اختر أولاً المجموعة المراد ربطها:

#اختيار وضع التشغيل

ثم اختر وضع التشغيل، وهناك وضعان: محلي وعام:

حيث:

• الوضع المحلي يُشغَّل فقط على أزرار الإجراءات التي تم ربط سير العمل هذا بها. النقر على الأزرار التي لم يتم ربط سير العمل هذا بها لن يؤدي إلى تشغيله. يمكنك تحديد ما إذا كنت تريد ربط سير العمل هذا بناءً على ما إذا كان يجب أن تشغل النماذج ذات الأغراض المختلفة نفس العملية.
• الوضع العام يُشغَّل على جميع أزرار الإجراءات المهيأة في المجموعة، بغض النظر عن النموذج الذي أتت منه، ولا يتطلب ربط سير العمل المقابل.

في الوضع المحلي، أزرار الإجراءات التي تدعم الربط حاليًا هي كالتالي:

• زرا "إرسال" و"حفظ" في نموذج الإضافة.
• زرا "إرسال" و"حفظ" في نموذج التحديث.
• زر "تحديث البيانات" في صفوف البيانات (الجدول، القائمة، لوحة كانبان، إلخ).

#اختيار نوع الإجراء

إذا اخترت الوضع العام، فستحتاج أيضًا إلى اختيار نوع الإجراء. حاليًا، يتم دعم "إجراء إنشاء البيانات" و"إجراء تحديث البيانات". كلا الإجراءين يشغلان سير العمل بعد نجاح الإجراء.

#اختيار بيانات العلاقة المحملة مسبقًا

إذا كنت بحاجة إلى استخدام البيانات المرتبطة بالبيانات المشغلة في العمليات اللاحقة، فيمكنك اختيار حقول العلاقة التي تحتاج إلى تحميلها مسبقًا:

بعد التشغيل، يمكنك استخدام هذه البيانات المرتبطة مباشرة في العملية.

#تهيئة الإجراء

بالنسبة للإجراءات في وضع التشغيل المحلي، بعد اكتمال تهيئة سير العمل، يجب العودة إلى واجهة المستخدم وربط سير العمل بزر إجراء النموذج في كتلة البيانات المقابلة.

سيتم تشغيل سير العمل المهيأ لزر "إرسال" (بما في ذلك زر "حفظ البيانات") بعد أن يقوم المستخدم بإرسال النموذج المقابل واكتمال عملية البيانات.

اختر "ربط سير العمل" من قائمة تهيئة الزر لفتح نافذة تهيئة الربط المنبثقة. في هذه النافذة، يمكنك تهيئة أي عدد من سير العمل المراد تشغيلها. إذا لم يتم تهيئة أي منها، فهذا يعني عدم الحاجة إلى تشغيل. لكل سير عمل، يجب أولاً تحديد ما إذا كانت البيانات المشغلة هي بيانات النموذج بأكمله أو بيانات حقل علاقة معين في النموذج. بعد ذلك، بناءً على المجموعة المقابلة لنموذج البيانات المختار، اختر سير العمل الخاص بالنموذج الذي تم تهيئته لمطابقة نموذج هذه المجموعة.

#مثال

سنقوم هنا بتقديم عرض توضيحي باستخدام إجراء الإضافة.

لنفترض سيناريو "طلب تعويض المصروفات"، حيث نحتاج بعد أن يقدم الموظف طلب تعويض، إلى إجراء مراجعة تلقائية للمبلغ ومراجعة يدوية للمبالغ التي تتجاوز الحد المسموح به. يتم قبول الطلبات التي تجتاز المراجعة فقط، ثم تُحال إلى قسم المالية للمعالجة.

أولاً، يمكننا إنشاء مجموعة "تعويض المصروفات" تحتوي على الحقول التالية:

• اسم المشروع: نص سطر واحد
• مقدم الطلب: متعدد لواحد (مستخدم)
• المبلغ: رقم
• الحالة: اختيار واحد ("تمت الموافقة"، "اكتملت المعالجة")

بعد ذلك، أنشئ سير عمل من نوع "حدث ما بعد الإجراء" وقم بتهيئة نموذج المجموعة في المشغل ليكون مجموعة "تعويض المصروفات":

بعد تعيين سير العمل إلى حالة "مُمكّن"، سنعود لاحقًا لتهيئة عقد المعالجة المحددة للعملية.

ثم، نقوم بإنشاء كتلة جدول لـ مجموعة "تعويض المصروفات" في الواجهة، ونضيف زر "إضافة" إلى شريط الأدوات، ونُهيئ حقول النموذج المقابلة. وفي خيارات تهيئة زر إجراء "إرسال" الخاص بالنموذج، نفتح مربع حوار تهيئة "ربط سير العمل" للزر، ونختار بيانات النموذج بأكملها كسياق، وسير العمل الذي أنشأناه سابقًا:

بعد اكتمال تهيئة النموذج، نعود إلى تنظيم منطق سير العمل. على سبيل المثال، إذا كان المبلغ أكبر من 500، نطلب مراجعة يدوية من قبل المسؤول، وإلا يتم الموافقة عليه مباشرة. بعد الموافقة، يتم إنشاء سجل تعويض المصروفات، ثم يُحال إلى قسم المالية لمزيد من المعالجة (تم حذف التفاصيل).

إذا تجاهلنا المعالجة المالية اللاحقة، نكون قد أكملنا تهيئة عملية طلب تعويض المصروفات. عندما يملأ الموظف طلب تعويض ويقدمه، سيتم تشغيل سير العمل المقابل. إذا كان مبلغ المصروفات أقل من 500، سيتم إنشاء سجل تلقائيًا وينتظر المزيد من المعالجة من قبل المالية. وإلا، سيتم مراجعته من قبل المشرف، وبعد الموافقة، سيتم إنشاء سجل أيضًا وتسليمه إلى المالية للمعالجة.

يمكن أيضًا تهيئة عملية هذا المثال على زر "إرسال" العادي. يمكنك تحديد ما إذا كنت بحاجة إلى إنشاء سجل أولاً قبل تنفيذ العمليات اللاحقة بناءً على سيناريو العمل المحدد.

#الاستدعاء الخارجي

لا يقتصر تشغيل أحداث ما بعد الإجراء على عمليات واجهة المستخدم فحسب، بل يمكن أيضًا تشغيلها عبر استدعاءات واجهة برمجة تطبيقات HTTP.

بالنسبة لـ سير العمل المرتبطة محليًا بزر إجراء، يمكن استدعاؤها بهذه الطريقة (باستخدام زر إنشاء مجموعة posts كمثال):

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create?triggerWorkflows=workflowKey"

حيث يمثل معامل URL triggerWorkflows مفتاح سير العمل، ويتم فصل سير العمل المتعددة بفاصلة. يمكن الحصول على هذا المفتاح عن طريق تمرير مؤشر الماوس فوق اسم سير العمل في الجزء العلوي من لوحة سير العمل:

بعد نجاح الاستدعاء أعلاه، سيتم تشغيل حدث ما بعد الإجراء لـ مجموعة posts المقابلة.

إذا كنت بحاجة إلى تشغيل حدث لبيانات علاقة واحد لواحد في هذا الإجراء (لا يتم دعم علاقة واحد لمتعدد حاليًا)، يمكنك استخدام ! في المعامل لتحديد بيانات التشغيل لحقل العلاقة:

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post.",
    "category": {
      "title": "Test category"
    }
  }'
  "http://localhost:3000/api/posts:create?triggerWorkflows=workflowKey!category"

بعد نجاح الاستدعاء أعلاه، سيتم تشغيل حدث ما بعد الإجراء لـ مجموعة categories المقابلة.

#الأسئلة الشائعة

#الفرق عن حدث ما قبل الإجراء

• حدث ما قبل الإجراء: يُشغَّل قبل تنفيذ إجراء معين (مثل الإضافة، التحديث، إلخ). قبل تنفيذ الإجراء، يمكن التحقق من البيانات المطلوبة أو معالجتها ضمن سير العمل. إذا تم إنهاء سير العمل (تم اعتراض الطلب)، فلن يتم تنفيذ هذا الإجراء (الإضافة، التحديث، إلخ).
• حدث ما بعد الإجراء: يُشغَّل بعد نجاح إجراء معين من قبل المستخدم. في هذه المرحلة، تكون البيانات قد تم إرسالها بنجاح وحفظها في قاعدة البيانات، ويمكن متابعة معالجة العمليات ذات الصلة بناءً على النتيجة الناجحة.

كما هو موضح في الشكل أدناه:

#الفرق عن حدث المجموعة

تتشابه أحداث ما بعد الإجراء وأحداث المجموعة في أنها عمليات تُشغَّل بعد تغيير البيانات. ومع ذلك، تختلف مستويات تنفيذها؛ فأحداث ما بعد الإجراء تستهدف مستوى واجهة برمجة التطبيقات (API)، بينما تستهدف أحداث المجموعة تغييرات البيانات داخل المجموعة نفسها.

أحداث المجموعة أقرب إلى الطبقة الأساسية للنظام. في بعض الحالات، قد يؤدي تغيير البيانات الناتج عن حدث واحد إلى تشغيل حدث آخر، مما يخلق سلسلة من التفاعلات. خاصة عندما تتغير البيانات في بعض المجموعات المرتبطة أثناء عملية المجموعة الحالية، يمكن أيضًا تشغيل الأحداث المتعلقة بـ المجموعة المرتبطة.

لا يتضمن تشغيل أحداث المجموعة معلومات متعلقة بالمستخدم. في المقابل، أحداث ما بعد الإجراء أقرب إلى جانب المستخدم وهي نتيجة لإجراءات المستخدم. سيتضمن سياق سير العمل أيضًا معلومات متعلقة بالمستخدم، مما يجعلها مناسبة لمعالجة العمليات المتعلقة بإجراءات المستخدم. في تصميم NocoBase المستقبلي، قد يتم توسيع نطاق أحداث ما بعد الإجراء التي يمكن استخدامها للتشغيل، لذا يُوصى بشدة باستخدام أحداث ما بعد الإجراء لمعالجة العمليات التي تؤدي فيها إجراءات المستخدم إلى تغييرات في البيانات.

فرق آخر هو أن أحداث ما بعد الإجراء يمكن ربطها محليًا بأزرار نماذج محددة. إذا كانت هناك عدة نماذج، يمكن أن يؤدي إرسال بعض النماذج إلى تشغيل هذا الحدث، بينما لا يؤدي إرسال البعض الآخر إلى ذلك. أما أحداث المجموعة، فهي تتعلق بتغييرات البيانات في المجموعة بأكملها ولا يمكن ربطها محليًا.