مقدمة عن مسارات الكيان

مسارات الكيان هي إحدى المميزات القوية في نظام Nama ERP، حيث توفر مرونة عالية في تنفيذ إجراءات مخصصة بناءً على تفاعل المستخدم مع النظام، دون الحاجة إلى خبرة برمجية.

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

متى يتم تشغيل المسار

يتم تنفيذ مسار الكيان تلقائيًا بعد اتخاذ المستخدم لإجراء معين مثل:

• حفظ سجل
• تعديل سجل
• حذف سجل
• مراجعة سجل
• ... إلخ

يمكن تشغيل المسار من خارج النظام أيضًا

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

كيفية إنشاء مسار كيان

1. افتح شاشة مسارات الكيان.
2. حدد نوع الكيان (مثل: فاتورة مبيعات، أمر شراء، عميل، مورد...).
3. يمكن تحديد شرط اختياري عبر حقل "يطبق عند التوافق مع الاستعلام"، لتطبيق المسار فقط على السجلات التي يرجع منها الاستعلام أي قيمة (باستثناء 0 أو NULL).
4. يمكن أيضًا تحديد:
   • دفتر معين
   • توجيه معين
   • معايير إضافية لفلترة السجلات المستهدفة

مكونات تفاصيل المسار

في جدول التفاصيل لكل مسار كيان، ستجد:

• اسم العنصر: اسم الـ Class البرمجي المرتبط، الذي ينفذ المهمة المطلوبة.
• عنوان مدخل 1 إلى 15: وصف لكل مدخل متاح، يوضح المطلوب إدخاله.
• قيمة مدخل 1 إلى 15: القيمة الفعلية التي سيتم تمريرها للعنصر، وتحدد كيفية تنفيذ المهمة.
• مع الإجراء: يحدد متى يتم تنفيذ هذا العنصر ضمن مراحل تنفيذ المسار (مثل: بعد الحفظ، بعد المراجعة، ...إلخ).

النظام يدعم حتى 15 مدخل لكل عنصر، مما يتيح مرونة كبيرة في تخصيص السلوك المطلوب.

تشغيل المسار في الخلفية

في الوضع المعتاد يعمل المسار داخل عملية الحفظ: تضغط حفظ، فيعمل المسار، ثم ينتهي الحفظ. وأيًّا كان ما يفعله المسار — مهما كان بطيئًا، ومهما كان احتمال فشله — فالمستخدم جالس ينتظره، وأي فشل في المسار يُفشل الحفظ.

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

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

وتأجيل المسار يثير الأسئلة التي تصاحب أي عمل يجري دون مراقبة، والحقول المجاورة لصندوق التعليم هي إجابتها:

الحقل	ماذا يفعل
طابور المهام	المسار الذي يُعالَج فيه المسار المؤجل. المسارات على طوابير مختلفة تُعالَج في نفس الوقت، والمسارات التي تتشارك طابورًا تُعالَج واحدًا تلو الآخر بترتيب رفعها. وإذا تُرك فارغًا انضم المسار إلى المسار الافتراضي مع بقية المسارات غير المخصصة. انظر طوابير المهام.
Max Retry Count	كم مرة يُعاد تشغيل التشغيل الفاشل قبل أن يستسلم النظام. وإذا تُرك فارغًا فالفشل الأول نهائي.
Retry Every Seconds	كم ينتظر النظام بين المحاولات — وهو الإعداد الذي يجعل المسار يصمد أمام انقطاع مؤقت لنظام خارجي.
انتظار انتهاء معالجة الكميات	يحجز المسار ما دامت هناك أعمال مخزنية لم تنتهِ، حتى لا يقرأ كميات مخزون أو تكاليف على وشك أن تتغير.

خمسة أحداث فقط تقبل التأجيل

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

الأوبشن ( يعمل بعد حفظ المستند نهائيا و التأثير على قاعدة البيانات ) لا يعمل مع الإجراء

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

أين ترى المسارات المؤجلة

المسار المؤجل الذي رُفع ولم يعمل بعد هو صف حقيقي يمكنك النظر إليه، في جدول مسارات الكيانات في قائمة الانتظار الخاص بطابور مهامه — بحالته، وعدد مرات محاولته، وأي خطأ فيه. وهذا هو المكان الذي تنظر فيه حين يقول أحدهم إن المسار «لم يحدث».

فهم دورة حياة السجل في مسارات الكيان

لفهم كيفية عمل مسارات الكيان في نظام Nama ERP بشكل دقيق، من المهم أولًا فهم تسلسل الإجراءات التي يمر بها أي سجل أثناء إنشائه أو تعديله. النظام يوفر نقاط تنفيذ (Events) يمكنك ربط عناصر المسار بها للتحكم في منطق العمل بدقة.

Init — عند إنشاء سجل جديد

يتم تنفيذ هذا الإجراء مباشرة بعد ضغط المستخدم على زر "جديد".

• الغرض: تعيين قيم افتراضية لبعض الحقول.
• ملاحظة: يمكن للمستخدم تعديل هذه القيم لاحقًا قبل الحفظ.

PreUpdateCalculatedFields — قبل تحديث الحقول المحسوبة

بعض الحقول يتم حسابها تلقائيًا أثناء الحفظ. مثل:

• إجمالي السعر = الكمية × سعر الوحدة
• قيمة الضريبة = النسبة × الأساس
• إجمالي الفاتورة = مجموع القيم + الضرائب

الغرض من هذا الإجراء هو تعديل القيم قبل أن يقوم النظام بحساب هذه الحقول المحسوبة.

• مثال: إذا أردت تغيير الكمية قبل أن يُحسب إجمالي السعر، فيجب فعل ذلك هنا.

AfterTemplate — بعد تطبيق قالب القيم الافتراضية

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

• مفيد لضبط قيم إضافية بناءً على ما تم تعيينه في القالب.

UpdateCalculatedFields — بعد تحديث الحقول المحسوبة

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

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

SaveDraft — حفظ كمسودة

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

• يتم تحديث الحقول المحسوبة فقط.
• لا يتم تنفيذ باقي إجراءات الحفظ.
• العناصر المرتبطة بهذا الإجراء لن تعمل إلا عند حفظ المسودة فقط.

ValidateOnSave — إمكانية الحفظ

بعد تطبيق القيم الافتراضية وحساب الحقول، يبدأ النظام في التحقق من صحة البيانات، مثل:

• التأكد من وجود كمية كافية في المخزون.
• التأكد من أن العميل مسموح له بالشراء.

يمكنك استخدام هذا الإجراء لربط عناصر تساعد في التحقق مثل:

• EAPreventChangingFields: يمنع الحفظ إذا تم تغيير حقول محددة تم تحديدها في مدخلات المسار.

PreApplyEffects — ما قبل تأثيرات الحفظ

بعد نجاح التحقق من البيانات، يستعد النظام لتطبيق التأثيرات مثل:

• إنشاء قيود محاسبية.
• تعديل الكميات بالمخزون.
• تحديث ملفات مرتبطة.

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

PostCommit — تأثيرات الحفظ

يتم تنفيذ هذا الإجراء بعد إتمام جميع تأثيرات السند.

• يستخدم عادةً لإنشاء سجلات مرتبطة بعد الحفظ.
• مثال شائع: إنشاء موقع مخزني بنفس كود العميل مباشرة بعد حفظ العميل.

PreSendRequest — PreSend Business Request

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

أنواع طلبات المعالجة:

• LedgerTransReq: خاص بالتأثيرات المحاسبية.
• InvTransReq: خاص بالتأثيرات المخزنية، ويشمل الكميات والتكاليف.

استخدام هذا الإجراء:

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

---

PostInvTransReqRequestCreation — بعد إنشاء طلب التأثير المخزني

كما ذكرنا، يتم إنشاء InvTransReq لكل تأثير مخزني (سواء تغيير في الكمية أو التكاليف) ويرسل إلى طابور المعالجة.

حتى في الحالات التي لا يوجد فيها تأثير مباشر، قد يتم إنشاء هذا الطلب لأغراض تحقق مثل:

• التأكد من الكميات المتاحة دون حجز فعلي، عند تفعيل خيار "التأكد من الكميات مع الحفظ" فقط.

استخدام هذا الإجراء:

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

PreValidateOnDelete — ما قبل إمكانية الحذف

عند محاولة حذف أي سجل، يبدأ النظام أولًا بالتحقق مما إذا كانت عملية الحذف ممكنة دون الإضرار بسلامة البيانات. من أمثلة الحالات التي يُمنع فيها الحذف:

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

يتم تنفيذ العناصر المرتبطة بـ PreValidateOnDelete قبل عملية التحقق.
يمكنك مثلًا:

• حذف سند تم إنشاؤه آليًا بناءً على هذا السجل، كتحضير لعملية الحذف.

---

ValidateOnDelete — إمكانية الحذف

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

• يمكنك استغلال هذه المرحلة للتحقق من شروط إضافية أو لإلغاء الحذف في حالات معينة لم يغطيها النظام تلقائيًا.

---

PostDelete — تأثيرات الحذف

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

• يمكنك استخدام هذا الإجراء لإزالة سجلات إضافية تم إنشاؤها آليًا.
• مثال: حذف الموقع المخزني الذي تم إنشاؤه تلقائيًا عند حفظ العميل.

---

DeleteDraft — حذف المسودة

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

Revise — مراجعة السجل

يوفر نظام Nama ERP آلية مراجعة للسجلات تهدف إلى تثبيت البيانات وضمان سلامتها. بعد المراجعة:

• لا يمكن تعديل أو حذف السجل.
• يمكن تنفيذ إجراءات إضافية مرتبطة بالمراجعة تلقائيًا، مثل:
  • إنشاء سجلات جديدة.
  • تطبيق تأثيرات إضافية.

يتم تشغيل العناصر المرتبطة بهذا الإجراء أثناء عملية المراجعة.

---

UnRevise — إلغاء المراجعة

عند قيام المستخدم بإلغاء مراجعة سجل ما، يتم تنفيذ العناصر المرتبطة بهذا الإجراء تلقائيًا.

• مفيد لعكس التأثيرات أو حذف سجلات تم إنشاؤها مع المراجعة.

---

EInvoiceCreation — إنشاء الفاتورة الضريبية

في العديد من الدول (مثل مصر، السعودية، الأردن)، يُطلب من الشركات إرسال فواتيرها إلكترونيًا إلى الجهات الضريبية الحكومية.

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

---

PosteInvoiceSend — بعد إرسال الفاتورة الضريبية

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

• يُستخدم غالبًا لتنفيذ عمليات تسجيل أو تنبيه بناءً على نجاح الإرسال.

---

PosteInvoiceValid — بعد قبول الفاتورة الضريبية

تقوم الهيئة الحكومية بمراجعة الفاتورة والتحقق من:

• صحة البيانات.
• صحة الرقم الضريبي للعميل.
• توافق الفاتورة مع اللوائح.

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

• يُستخدم لمتابعة الإجراءات اللاحقة مثل التأكيد النهائي أو الإرسال الداخلي أو التنبيهات.

RecordView — مطالعة السجل

يتم تنفيذ العناصر المرتبطة بهذا الإجراء عند فتح أي سجل بواسطة أي مستخدم.

DANGER

نظرًا لأن هذا الحدث متكرر جدًا، فإن النظام يعطل تشغيل مسارات الكيان المرتبطة به بشكل افتراضي.

لتفعيل هذا النوع من المسارات، يجب ضبط الخيار التالي في الإعدادات العامة:

value.info.enableRecordViewEntityFlows

---

Manual — تشغيل يدوي

يُستخدم هذا الإجراء لتشغيل مسار الكيان يدويًا بواسطة المستخدم، من خلال:

• زر داخل شاشة التحرير.
• أو من قائمة "المزيد" في شاشة التحرير أو شاشة عرض القائمة.

TIP

• يجب إدراج مسارات الكيان التي تستخدم هذا الإجراء في الشاشة المستهدفة.
• يتم ذلك عبر "تعديل الشاشة" → جدول "الإجراءات والتنويهات".

حفظ السجل بعد التشغيل اليدوي

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

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

اعتبار الموافقات يحتاج إلى خيار الحفظ

خيار "اعتبار الموافقات عند الحفظ مع التنفيذ يدويا" لا معنى له وحده. إذا فعّلته بينما خيار "يتطلب الحفظ مع التنفيذ يدويا" غير مفعّل، يرفض مسار الكيان الحفظ ويشير إلى هذا الخيار.

أما رسالة التأكيد "سيذهب هذا السجل إلى الموافقة" التي تطلبها الشاشة في العادة فيتم الرد عليها آليًا، فلا يحتاج الحفظ إلى أي تدخل من المستخدم.

---

Automatic — تلقائي

بعض العناصر البرمجية تحدد الإجراء المناسب تلقائيًا، لذا تضبط الإجراء إلى Automatic لضمان عدم حدوث أخطاء عند اختيار المستخدم لإجراء غير صحيح.

WARNING

• لا يُتوقع من المستخدمين إنشاء عناصر بهذا الإجراء.
• إذا تم إنشاء عنصر باستخدام Automatic, فسيتم تشغيله مع جميع الأحداث النظامية الأخرى (باستثناء Manual).