> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# مشغلات أتمتة KayanOS

> اختيار حدث KayanOS الدقيق المسموح له ببدء مسار العمل، وتضييقه واختباره وتوثيقه.

## ما هو المشغّل؟

المشغّل هو حدث KayanOS الذي يبدأ الأتمتة. ليس اشتراكاً عاماً في كل ما يحدث داخل المؤسسة. يجيب المشغّل الجيد عن سؤال محدد: **ما الذي حدث، وعلى أي كائن، ولماذا هذه هي اللحظة التي يجب أن يبدأ فيها مسار العمل؟**

قبل اختيار المشغّل، اختر وتحقق من [اتصال KayanOS](/ar/build/automations-connections) المعتمد على مستوى المؤسسة. الاتصال مطلوب للكتالوج الصادر حتى عندما يعمل المشغّل والإجراء اللاحق مع بيانات KayanOS الداخلية فقط.

في خدمة التراخيص، تكون عبارة «تم تحديث سجل» واسعة في الغالب. أما «انتقل طلب الترخيص من `Completeness review` إلى `Ready for inspection`» فهي بداية مفيدة لأنها تصف تغيراً محدداً وقابلاً للمراجعة.

## اختر المشغّل المناسب أولاً

| إذا كان المسار يجب أن يبدأ عندما…    | فاختر غالباً                             | السبب                                                              |
| ------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------ |
| يُنشأ سجل جديد لأول مرة              | **New Record Created**                   | يستجيب مرة واحدة عند الإنشاء ويناسب توجيه الإدخال.                 |
| يهم أي تغير على سجل                  | **Record Updated**                       | استخدمه فقط إذا كان كل تحديث ذي صلة؛ وإلا فضّله بشرط.              |
| تهم عمليات محددة على السجل           | **Record Changes**                       | يتيح اختيار العمليات المرصودة وهو أكثر أماناً لدورة سجل متنوعة.    |
| ينفذ مستخدم زر/إجراء نموذج مضبوطاً   | **On Form Action**                       | الإجراء مقصود من المستخدم، ولذلك هو نقطة قرار أفضل من تغير مسودة.  |
| تصبح نتيجة توقيع متاحة               | **On Form Signature Signed**             | يربط المسار بخطوة التوقيع بدلاً من تعديل نموذج غير مرتبط.          |
| ينفذ إجراء على مهمة أو عمل مجمّع     | **On Task Action** أو **On Epic Action** | يواصل دورة عمل محكومة.                                             |
| ينفذ إجراء على حقل سجل               | **On Entity Action**                     | يضيّق الحدث إلى حقل الكيان والإجراء المختارين.                     |
| تحتاج لوحة معلومات إلى بيانات محسوبة | **On Dashboard Widget Call**             | يبدأ مسار طلب/استجابة للعنصر.                                      |
| يحتاج نموذج إلى استجابة مضبوطة       | **On Form Call**                         | يبدأ مسار طلب/استجابة للنموذج.                                     |
| يُفتح رابط دخول عام                  | **Short Link Opened**                    | يناسب نقطة دخول عامة مصممة لهذا الغرض، وليس قراراً داخلياً حساساً. |

عندما يبدو أن مشغّلين صالحان، اختر المشغّل الذي يحمل المعنى التشغيلي الأقوى. إجراء نموذج مثل `Submit for review` أكثر موثوقية من مراقبة عشرات التعديلات على حقول النموذج.

## كتالوج المشغلات الحالي

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

### أحداث السجلات

| المشغّل                | التكوين المطلوب            | الاستخدام                                                | ملاحظات التصميم                                                                                                  |
| ---------------------- | -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **New Record Created** | `Table Name`               | إنشاء سجل إدخال أو حالة أو طلب أو أصل أو معاينة.         | أضف شرطاً إن كان نوع واحد فقط من السجلات الجديدة يجب أن يتابع. قد يكون السجل ناقصاً عند إنشائه.                  |
| **Record Updated**     | `Table Name`               | الاستجابة للتحديثات التي تحتاج مراجعة.                   | لا تنشئ عملاً عند كل تحديث. قارن الحالة أو القيمة ذات الصلة في الشرط.                                            |
| **Record Deleted**     | `Table Name`               | تسجيل متابعة حذف مضبوطة.                                 | استخدمه بحذر: قد لا يعود السجل متاحاً للبحث لاحقاً. احتفظ فقط بسياق التدقيق المسموح به.                          |
| **Record Changes**     | `Table Name`؛ `Operations` | مراقبة عمليات إنشاء أو تحديث أو حذف مختارة في مسار واحد. | اختر فقط العمليات التي يفهمها المسار. يكون المسار المنفصل أوضح غالباً عندما يتطلب الإنشاء والحذف قرارين مختلفين. |

### النماذج والتوقيعات وإجراءات الكيانات

| المشغّل                      | التكوين المطلوب           | الاستخدام                                                   | خيارات التضييق المتاحة في الكتالوج                                     |
| ---------------------------- | ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- |
| **On Form Action**           | `Form`                    | الإرسال أو التوجيه أو طلب المراجعة أو إجراء نموذج آخر مسمى. | يضبط `Form Versions` و`Actions` المسار على النموذج والإجراء المقصودين. |
| **On Form Signature Signed** | `Form`                    | بدء خطوة لاحقة بعد نتيجة توقيع مراجع.                       | تميز `Signatures` و`Rules` و`Resolutions` مسار التوقيع ذي الصلة.       |
| **On Entity Action**         | `Table Name`؛ `Field Key` | الاستجابة لإجراء مضبوط على حقل كيان.                        | تحقق من حقل الكيان ومن المستخدمين المسموح لهم بالإجراء قبل التمكين.    |

### المهام والعمل المجمّع

| المشغّل            | التكوين المطلوب | الاستخدام                                       | خيارات التضييق المتاحة في الكتالوج                                             |
| ------------------ | --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ |
| **On Task Action** | `Task Type`     | متابعة مهمة موافقة أو معاينة أو إسناد أو تصعيد. | يجعل `Old Status` و`New Status` الانتقال صريحاً.                               |
| **On Epic Action** | `Epic Type`     | متابعة دورة عمل مجمّعة أو متعددة الخطوات.       | يساعد `Old Status` و`New Status` على منع التشغيل بسبب تحديثات تقدم غير مرتبطة. |

### الأحداث التفاعلية ونقاط الدخول العامة

| المشغّل                      | التكوين المطلوب     | الاستخدام                                                   | اقترنه مع                                                                                     |
| ---------------------------- | ------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **On Dashboard Widget Call** | `Mode`؛ `Input`     | إرجاع بيانات محسوبة وواعية للصلاحيات إلى عنصر لوحة معلومات. | **Return Dashboard Widget Response**.                                                         |
| **On Form Call**             | `Mode`؛ `Input`     | إرجاع نتيجة مضبوطة إلى نقطة تكامل نموذج.                    | **Return Form Response**.                                                                     |
| **Short Link Opened**        | لا توجد حقول مطلوبة | قياس أو توجيه نقطة دخول عامة مصممة صراحةً.                  | يمكن لـ `Metadata Filter` و`Open Type` تضييق الحدث. لا تستخدمه دليلاً على الهوية أو الموافقة. |

## اضبط المشغّل بأمان

1. **اكتب جملة الحدث.** صفه بلغة واضحة: «عندما ينتقل طلب ترخيص مكتمل إلى `Ready for inspection`».
2. **اختر أضيق نطاق مصدر.** اختر الجدول أو النموذج أو نوع المهمة أو نوع العمل المجمّع أو مفتاح الحقل أو نقطة الدخول التي تملك الحدث.
3. **طبّق مرشحات الكتالوج.** اختر نسخة النموذج والإجراء وقاعدة التوقيع وانتقال الحالة وعملية السجل وبيانات الرابط ذات الصلة متى كانت متاحة.
4. **شغّل اختبار المشغّل بسجل غير إنتاجي معتمد واحد.** استخدم سجلاً معروفاً مثل `PERMIT-TEST-001`؛ ولا تستخدم بيانات مواطنين أو موظفين حقيقية في هذه الخطوة.
5. **افحص المخرجات قبل إضافة الإجراءات.** في اختبار حدث سجل، أعاد KayanOS القيم `action` و`oldData` و`data` و`changedFields`. تعامل مع مخرج الاختبار الفعلي بوصفه المرجع: قد تظهر سياقات مختلفة لأنواع أحداث مختلفة.
6. **حدد المدخلات الثابتة.** فضّل المعرّفات ورموز الحالة وقيم الجدول وحقول العلاقات الصريحة على التسميات التي يمكن للمستخدم تعديلها.
7. **أضف شرط القرار.** اطلب الحالة المتوقعة والاكتمال وعدم وجود متابعة سابقة قبل أي كتابة أو إشعار.
8. **سجّل النتيجة المتوقعة.** دوّن السجل أو المهمة أو الاستجابة أو الإشعار الذي يجب أن يظهر ومن سيؤكده.

## اقرأ مخرجات المشغّل بوعي

لوحة الاختبار ليست مجرد فحص اتصال؛ فهي تعرض البيانات التي سيتلقاها مسارك. راجعها حقلاً حقلاً:

| المخرج الذي يجب فحصه | سبب أهميته                                                                 | سؤال مثالي                                                                                 |
| -------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `data`               | قيم الحدث أو السجل الحالية.                                                | هل يحتوي على فئة الخدمة والمنطقة وعلاقة مقدم الطلب والحالة الحالية اللازمة للإجراء التالي؟ |
| `oldData`            | القيم السابقة عندما يتضمن الحدث سياق تغير.                                 | هل انتقلت الحالة فعلاً من `Completeness review` إلى `Ready for inspection`؟                |
| `changedFields`      | الحقول التي سببت سياق التحديث.                                             | هل تغيرت الحالة ذات الصلة أم صُحح رقم هاتف فقط؟                                            |
| `action`             | سياق إجراء النموذج أو المهمة أو العمل المجمّع أو الكيان المختار عند توفره. | هل هذا هو الإجراء المعتمد بالضبط الذي يجب أن يبدأ العملية؟                                 |

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

## تجنب عمليات التشغيل المتكررة غير المقصودة

قد تحدث أحداث السجلات والمهام أكثر من مرة بصورة مشروعة. صمم المشغّل وشرطه الأول بحيث لا تؤدي إعادة المحاولة أو تغير غير مرتبط إلى إنشاء حالات أو مهام أو إشعارات أو مستندات مكررة.

مثال لمسار توجيه معاينة:

1. شغّل **Record Changes** لجدول `Permit Applications` وعملية `update`.
2. تحقق من أن الحالة الحالية هي `Ready for inspection`.
3. تحقق من أن الحالة السابقة لم تكن `Ready for inspection` بالفعل، أو من عدم وجود حالة معاينة مفتوحة للطلب.
4. عندها فقط أنشئ حالة المعاينة وأبلغ فريق المنطقة المكلّف.

إذا وجدت حالة مفتوحة، فحدّثها أو توقف مع ملاحظة مراجعة. لا تنشئ حالة أخرى لمجرد أن محرراً حفظ السجل مرة أخرى.

## أمثلة على المشغلات

### توجيه طلب ترخيص مكتمل

* **حدث العمل:** اجتاز طلب الترخيص مراجعة الاكتمال.
* **المشغّل:** `Record Changes` على `Permit Applications` مع مراقبة التحديثات.
* **الشرط:** الحالة الحالية `Ready for inspection`؛ وتتوفر قيم العنوان والمنطقة؛ ولا توجد حالة معاينة مفتوحة.
* **الإجراء التالي:** إنشاء سجل واحد في `Inspection Cases` وإشعار الفريق الداخلي المناسب.

### متابعة قرار مضبوط بالتوقيع

* **حدث العمل:** اكتمل التوقيع المطلوب للقرار.
* **المشغّل:** `On Form Signature Signed` للنموذج المختار للقرار.
* **المرشح:** اختر نسخة النموذج المعتمدة والتوقيع والقاعدة والقرار عندما تكون هذه الخيارات متاحة.
* **الإجراء التالي:** إنشاء سجل القرار أو تحديثه ثم إنشاء مهمة للدور المسؤول عن الخطوة التالية.

### خدمة عنصر لوحة معلومات بأمان

* **حدث العمل:** يطلب عنصر لوحة معلومات بياناته.
* **المشغّل:** `On Dashboard Widget Call` مع الوضع والمدخل المقصودين.
* **الشرط:** تحقق من أن المدخل ينتمي إلى نطاق الخدمة المسموح للمستخدم به.
* **الإجراء التالي:** ابحث فقط عن السجلات المسموح بها واستخدم **Return Dashboard Widget Response** مع جسم JSON محدود.

## حواجز الحماية

<Warning>يخبرك المشغّل بأن حدثاً وقع، لكنه لا يثبت أن كتابة سجل أو إرسال إشعار أو تغيير دور أو إحداث أثر خارجي مناسب. اختبر الحدث نفسه، وأضف شرطاً، وتوقف عندما يكون السياق ناقصاً أو غير متوقع.</Warning>

![اختيار مشغّل أتمتة KayanOS لمسار خدمة مضبوط.](https://kayanos.app/docs-images/ar/build/automations-triggers.png)

## متابعة البناء

* اربط النتائج في [إجراءات أتمتة KayanOS](/ar/build/automations-actions).
* اطلع على أنماط مسارات العمل الكاملة في [وصفات أتمتة KayanOS](/ar/build/automations-recipes).
* تعرّف إلى لغة التعبيرات المستخدمة في البُناة المدعومة في [التعبيرات في الباني](/ar/build/expressions-in-builder).