المشاكل الشائعة والحلول
لم يتم تشغيل سير العمل
الأعراض: لا يعمل سير العمل كما تتوقع.
الأسباب المحتملة:
- لم يتم تفعيل سير العمل: تأكّد من تعيين سير العمل إلى “Active” وليس “Draft”
- شروط المُحفِّز غير مستوفاة: تحقّق من أن المُحفِّز يطابق الحدث الذي تتوقعه
- حقل غير مُراقَب: بالنسبة لمُحفِّزات “Record is Updated”، تأكّد من مراقبة الحقل المحدد
- الأذونات: تحقّق من أن لديك الإذن لتشغيل سير العمل
حلول:
- تحقّق من حالة سير العمل في قائمة سير العمل
- اختبر بالإجراء المحدد الذي تتوقع أن يُشغِّله
- راجِع إعداد المُحفِّز
- تواصَل مع المسؤول لديك بشأن الأذونات
مُحفِّزات سير العمل تعمل مبكراً جداً (حقول فارغة)
الأعراض: عند إنشاء سجل يدوياً في واجهة المستخدم، يتم تشغيل سير العمل قبل أن تتمكّن من ملء جميع الحقول. يعمل سير العمل مع قيم حقول فارغة في الغالب.
سبب حدوث هذا: تقوم Twenty بحفظ كل شيء في الزمن الحقيقي — لا يوجد وضع منفصل “edit” مقابل “read”. عند إنشاء سجل، يتم حفظه فوراً، مما يؤدي إلى تشغيل حدث “Record is created” قبل أن تتمكّن من ملء حقول إضافية.
متى يعمل “Record is created” بشكل جيد:
- السجلات التي تُنشأ عبر استدعاءات API (تُملأ الحقول في طلب واحد)
- السجلات التي تُنشأ عبر الاستيراد
- إنشاء السجلات تلقائياً من سير عمل أخرى
الحل: بالنسبة للسجلات التي تُنشأ يدوياً في واجهة المستخدم، استخدم “Record is created or updated” كمحفّز بدلاً من ذلك. بهذه الطريقة:
- سيتم تشغيل سير العمل بعد أن يُنهي المستخدم ملء الحقول وحفظها
- ستحصل على البيانات الكاملة بدلاً من القيم الفارغة
إذا كنت تريد تشغيل سير العمل مرة واحدة فقط لكل سجل، أضِف إجراء تصفية لفحص حقل مثل createdAt equals updatedAt (الحفظ الأول) أو استخدم حقلاً مخصصاً من نوع خانة اختيار لتتبع ما إذا كان سير العمل قد تم تشغيله بالفعل.
فشل الإجراءات
الأعراض: يعمل سير العمل لكن بعض الإجراءات تفشل.
الأسباب المحتملة:
- بيانات مفقودة: الحقول المطلوبة فارغة
- مراجع غير صالحة: المتغيّرات من الخطوات السابقة غير موجودة
- أخطاء API: تعيد الخدمات الخارجية أخطاء
- مشكلات الأذونات: يتطلب الإجراء أذونات لا تملكها
حلول:
- راجِع تفاصيل تشغيل سير العمل بحثاً عن رسائل الخطأ
- تحقّق من أن جميع الحقول المطلوبة تحتوي على قيم
- اختبر اتصالات API بشكل مستقل
- راجِع أذونات الدور
أخطاء طلبات HTTP
الأعراض: تفشل إجراءات طلب HTTP أو تُرجِع نتائج غير متوقعة.
رموز الأخطاء الشائعة:
- 400: طلب غير صالح - تحقّق من تنسيق جسم الطلب
- 401: غير مُخوَّل - تحقّق من مفتاح API
- 403: محظور - تحقّق من أذونات API
- 404: غير موجود - تحقّق من عنوان URL لنقطة النهاية
- 429: عدد كبير جداً من الطلبات - نفّذ تحديداً لمعدل الطلبات
- 500: خطأ في الخادم - مشكلة في خدمة خارجية
حلول:
- تحقّق من عنوان URL لنقطة نهاية API
- تحقّق من ترويسات المصادقة
- اختبر استدعاء API خارج Twenty أولاً
- أضِف معالجة للأخطاء في إجراءات الكود
أخطاء إجراءات الكود
الأعراض: يفشل كود JavaScript في التنفيذ.
المشكلات الشائعة:
- أخطاء الصياغة: أخطاء إملائية أو JavaScript غير صالح
- متغيّرات غير معرّفة: الإشارة إلى متغيّرات غير موجودة
- أخطاء النوع: إجراء عمليات على أنواع بيانات خاطئة
- انتهاء المهلة: يستغرق الكود وقتاً طويلاً للتنفيذ
حلول:
- استخدم التحقق المدمج في محرر الكود
- اختبر منطق الكود في وحدة تحكم JavaScript أولاً
- أضِف عبارات console.log لأغراض تصحيح الأخطاء
- بسّط العمليات المعقّدة
البريد الإلكتروني لا يُرسَل
الأعراض: لا يقوم إجراء إرسال البريد الإلكتروني بتسليم الرسائل.
الأسباب المحتملة:
- لا يوجد حساب بريد إلكتروني متصل: تحقّق من الإعدادات → الحسابات
- عنوان بريد إلكتروني غير صالح: عنوان بريد المستلم غير صحيح التنسيق
- قيود الإرسال: تم الوصول إلى حدود معدل مزوّد البريد الإلكتروني
- مرشّحات البريد العشوائي: يتم حظر الرسائل
حلول:
- تحقّق من اتصال حساب البريد الإلكتروني
- تحقّق من صحة عناوين بريد المستلمين
- تحقّق من حدود مزوّد البريد الإلكتروني
- راجِع محتوى البريد بحثاً عن عناصر قد تُحفِّز مرشّحات البريد العشوائي
تصحيح أخطاء سير العمل
استخدام عمليات تشغيل سير العمل
- انتقل إلى محرر سير العمل
- افتح لوحة Runs
- اعثر على عملية التشغيل التي فشلت
- انقر لعرض التفاصيل خطوة بخطوة
- راجِع رسائل الخطأ وبيانات المخرجات
اختبار الخطوات بشكل فردي
- بالنسبة لإجراءات الكود، استخدم زر Test
- بالنسبة لطلبات HTTP، اختبر نقطة النهاية بشكل منفصل
- أنشئ سجلات اختبار لتشغيل سير العمل
- استخدم المُحفِّزات اليدوية للاختبار المُتحكَّم فيه
أنماط شائعة لتصحيح الأخطاء
أضِف التسجيل:
استخدم إجراءات الكود لتسجيل القيم الوسيطة لأغراض تصحيح الأخطاء.
اعزل الخطوات:
اختبر كل خطوة بشكل مستقل لتحديد مواضع الفشل.
تحقّق من تدفق البيانات:
تأكّد من أن كل خطوة تتلقى بيانات الإدخال المتوقعة.
أفضل الممارسات لتجنّب المشكلات
قبل التفعيل
- اختبر بدقة في وضع المسودة
- تحقّق من صحة جميع اتصالات API
- راجِع شروط المُحفِّز بعناية
- وثّق السلوك المتوقع
أثناء التطوير
- استخدم أسماء خطوات وصفية
- أضِف تعليقات في إجراءات الكود
- اختبر ببيانات واقعية
- خطّط للحالات الحدّية
بعد التفعيل
- راقِب عمليات التشغيل الأولى عن كثب
- قم بإعداد تنبيهات لحالات الفشل
- راجِع سجلّ التشغيل بانتظام
- اجعل سير العمل بسيطًا قدر الإمكان
