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

#مقدمة

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

إذا تم تنفيذ عقدة "إنهاء سير العمل" في سير العمل الذي تم تشغيله، أو إذا فشلت أي عقدة أخرى في التنفيذ (بسبب خطأ أو عدم اكتمال آخر)، فسيتم اعتراض إجراء النموذج. بخلاف ذلك، سيتم تنفيذ الإجراء المقصود بشكل طبيعي.

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

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

#إنشاء مشغل

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

#اختيار المجموعة

في مشغل سير عمل الاعتراض، أول ما يجب تهيئته هو المجموعة المطابقة للإجراء:

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

#وضع الاعتراض

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

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

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

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

#شروط الاعتراض

في "حدث ما قبل الإجراء"، هناك شرطان يؤديان إلى اعتراض الإجراء المقابل:

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

بعد استيفاء شروط الاعتراض، لن يتم تنفيذ الإجراء المقابل. على سبيل المثال، إذا تم اعتراض تقديم طلب، فلن يتم إنشاء بيانات الطلب المقابلة.

#المعلمات ذات الصلة للإجراء المقابل

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

#إخراج رسالة الاستجابة

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

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

#حالة رسالة الاستجابة

إذا تم تهيئة عقدة "إنهاء سير العمل" للخروج بحالة "نجاح"، فسيظل طلب الإجراء معترضًا عند تنفيذ هذه العقدة، ولكن رسالة الاستجابة المعادة ستُعرض بحالة "نجاح" (بدلاً من "خطأ"):

#مثال

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

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

يتم اختيار الكائن للتكرار كمصفوفة "تفاصيل الطلب" من بيانات الطلب المقدمة:

تُستخدم عقدة الشرط ضمن سير عمل التكرار لتحديد ما إذا كان مخزون كائن المنتج الحالي في التكرار كافيًا:

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

كما ترى، لا تشير رسالة الاستجابة إلى أن المنتج الأول "iPhone 15 pro" نفد من المخزون، بل تشير فقط إلى أن المنتج الثاني "iPhone 14 pro" نفد. هذا لأن المنتج الأول في التكرار كان مخزونه كافيًا، لذلك لم يتم اعتراضه، بينما كان مخزون المنتج الثاني غير كافٍ، مما أدى إلى اعتراض تقديم الطلب.

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

يتم حقن حدث ما قبل الإجراء نفسه خلال مرحلة معالجة الطلب، لذا فهو يدعم أيضًا التشغيل عبر استدعاءات واجهة برمجة تطبيقات 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 المقابلة. بعد اكتمال معالجة سير العمل المقابل بشكل متزامن، سيتم إنشاء البيانات وإرجاعها بشكل طبيعي.

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

إذا تم تهيئة عقدة "رسالة الاستجابة" أيضًا قبل عقدة النهاية، فسيتم إرجاع الرسالة التي تم إنشاؤها في نتيجة الاستجابة. هيكل الخطأ هو:

{
  "errors": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

هيكل الرسالة عندما يتم تهيئة "عقدة النهاية" للنجاح هو:

{
  "messages": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

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

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"