المهام المجدولة (Task Scheduler)

يتيح لك Task Scheduler أتمتة العمليات المتكررة في Nama ERP. سواء كنت بحاجة إلى إرسال تقارير يومية للمديرين، أو تشغيل استعلامات صيانة النظام، أو إطلاق إشعارات عند توافر شروط معينة، يتكفل Task Scheduler بكل ذلك — يعمل في الخلفية بينما تركز أنت على أعمالك.

أنواع المهام

عند إنشاء مهمة مجدولة، أول قرار ستتخذه هو اختيار نوع الجدولة (Schedule Type). يحدد هذا الخيار نوع الإجراء الذي ستنفذه المهمة عند تشغيلها. فيما يلي شرح لكل نوع:

Report (إرسال تقرير بالبريد الإلكتروني)

الاستخدام الأكثر شيوعًا. يقوم النظام بتشغيل تقرير وإرساله بالبريد الإلكتروني إلى المستلمين المحددين. ستختار تعريف التقرير، وتحدد تنسيق المخرجات (HTML، PDF، Excel)، ومن يستلمه.

Print Report (طباعة تقرير)

مشابه لنوع Report، لكن بدلًا من الإرسال بالبريد الإلكتروني، يُرسل التقرير مباشرة إلى طابعة. ستحتاج إلى تحديد اسم الطابعة المهيأة على الخادم.

Notification (إشعار)

يرسل إشعارات للمستخدمين استنادًا إلى نتائج الاستعلامات والقوالب. يمكنك إعداد قوالب الإشعارات لـ:

• الإشعارات داخل التطبيق
• رسائل البريد الإلكتروني
• رسائل SMS

System (نظام)

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

Action (إجراء)

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

Parameterized Report (Email) (تقرير بمعاملات - بريد إلكتروني)

نوع متقدم من Report. بدلًا من تشغيل التقرير مرة واحدة، ينفّذ أولًا استعلام SQL للحصول على قيم المعاملات، ثم يشغّل التقرير عدة مرات — مرة لكل صف مُعاد. يمكن أن يذهب كل تنفيذ إلى مستلمين مختلفين.

Parameterized Report (Print) (تقرير بمعاملات - طباعة)

مثل النوع السابق، لكن يرسل كل تكرار للتقرير إلى طابعة بدلًا من البريد الإلكتروني.

Recurring Document (مستند متكرر)

يؤتمت إنشاء المستندات المتكررة. تربط المهمة بتعريف مستند متكرر وتُنشئ مستندات جديدة وفق الجدول الزمني.

Read Magento Orders / Read Magento Returns

لتكامل التجارة الإلكترونية — يسحب الطلبات أو المرتجعات من موقع Magento مهيأ.

Purge Expired Reward Points

مهمة متخصصة لبرامج الولاء تزيل نقاط المكافآت المنتهية الصلاحية من النظام.

Read E-Invoice Notifications

لتكاملات الفواتير الإلكترونية — يقرأ الإشعارات من خادم وسيط للفوترة الإلكترونية.

خيارات الجدولة

يوفر المجدول مقاربتين: واجهة مربعات اختيار سهلة الاستخدام أو تعبيرات cron متقدمة.

الجدولة البسيطة (Checkbox Mode)

عندما يكون Using Cron غير محددًا، تحصل على واجهة جدولة بديهية:

تشغيل كل X دقائق/ساعات/أيام/أشهر أبسط مقاربة. اضبط Run On على رقم (مثل 5) و Run On Type على "Minute" للتشغيل كل 5 دقائق. أمثلة:

• Run On: 10، Run On Type: Minute → يعمل كل 10 دقائق
• Run On: 2، Run On Type: Hour → يعمل كل ساعتين
• Run On: 1، Run On Type: Day → يعمل يوميًا

الجدول الأسبوعي فعّل Weekly ثم اختر أيام الأسبوع التي تريد التشغيل فيها. يمكنك اختيار أي مجموعة من السبت حتى الجمعة.

الجدول الشهري فعّل Monthly واختر:

• الأشهر التي تريد التشغيل فيها (يناير حتى ديسمبر)
• أيام الشهر التي تريد التشغيل فيها (1 حتى 31)

وقت اليوم للجداول الأسبوعية والشهرية، تحدد الوقت الدقيق للتشغيل خلال اليوم. اختر أي فترة زمنية بفاصل 30 دقيقة من 00:00 حتى 23:30.

الجدولة المتقدمة (Cron Mode)

عندما يكون Using Cron محددًا، تدخل تعبير cron مباشرةً باستخدام هذه الحقول الخمسة:

الحقل	القيم المسموح بها
Minute	0-59، أو * لكل دقيقة، أو */5 لكل 5 دقائق
Hour	0-23، أو * لكل ساعة
Day of Month	1-31، أو * لكل يوم
Month	1-12، أو * لكل شهر
Day of Week	0-6 (الأحد=0) أو SUN,MON,TUE,WED,THU,FRI,SAT

أمثلة على Cron:

• 0 8 * * * → كل يوم الساعة 8:00 صباحًا
• */30 * * * * → كل 30 دقيقة
• 0 0 1 * * → أول يوم من كل شهر عند منتصف الليل
• 0 9 * * 1-5 → كل يوم عمل الساعة 9:00 صباحًا

تحديد المستلمين

تتوفر عدة خيارات لتحديد من يستلم التقارير والإشعارات:

عناوين البريد الإلكتروني المباشرة

أدخل عناوين البريد الإلكتروني مباشرةً في حقل Target Emails، مفصولةً بفواصل أو في أسطر منفصلة.

Target Reference

اختر من:

• Employee → موظف محدد
• Organization Position → جميع الموظفين في ذلك المنصب
• Master Group → جميع أعضاء المجموعة
• Special Responsible → بناءً على تعيينات المسؤولية الخاصة

Target Criteria

حدد معايير ديناميكية لحساب المستلمين. مفيد عندما يعتمد المستلم على البيانات التي تُعالج.

Target Lines

أضف مراجع مستلمين متعددة في جدول لقوائم المستلمين المعقدة.

البريد الإلكتروني عبر التقارير المعاملاتية

تتيح لك هذه الميزة القوية تشغيل تقرير واحد بمعاملات مختلفة لمستلمين مختلفين.

آلية العمل:

1. اضبط Schedule Type على Action
2. اضبط Action name على com.namasoft.reporting.ParamterizedReporTask
3. المدخل الأول: استعلام SQL يُعيد قيم المعاملات
4. المدخل الثاني: قائمة أسماء الأعمدة مفصولةً بفواصل

اصطلاحات أعمدة نتيجة الاستعلام:

• subject → سطر موضوع البريد الإلكتروني
• sendto → عنوان البريد الإلكتروني للإرسال إليه (بريد عادي)
• sendto#type و sendto#id → مرجع كيان للمستلم
• parameterName#type و parameterName#id → مرجع كيان لمعامل التقرير

مثال: تنبيهات انتهاء إقامة الموظفين

يرسل رسائل بريد إلكتروني مخصصة للمشرفين بشأن الموظفين الذين تنتهي إقامتهم قريبًا:

المدخل الأول (استعلام SQL):

select
  case when DATEDIFF(day, GETDATE(), residencyEnd) < 1
       then N'الاقامة انتهت منذ '
       else N'باقي علي انتهاء الاقامة '
  end + cast(ABS(DATEDIFF(day, GETDATE(), residencyEnd)) as nvarchar(100)) + N' يوم' as subject,
  'Employee' as sendto#type,
  supervisor_id as sendto#id,
  'Employee' as employee#type,
  id as employee#id
from Employee
where DATEDIFF(day, GETDATE(), residencyEnd) < 30
order by 2

المدخل الثاني:

subject,sendto#type,sendto#id,employee#type,employee#id

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

بديل: الإرسال إلى البريد الإلكتروني الخاص بالموظف

استبدل أعمدة sendto ببريد الموظف الإلكتروني للتواصل:

select
  case when DATEDIFF(day, GETDATE(), residencyEnd) < 1
       then N'الاقامة انتهت منذ '
       else N'باقي علي انتهاء الاقامة '
  end + cast(ABS(DATEDIFF(day, GETDATE(), residencyEnd)) as nvarchar(100)) + N' يوم' as subject,
  contactInfoEmail as sendto,
  'Employee' as employee#type,
  id as employee#id
from Employee
where DATEDIFF(day, GETDATE(), residencyEnd) < 30
order by 2

الإشعارات عبر استعلام SQL

أرسل إشعارات (داخل التطبيق، أو بريد إلكتروني، أو SMS) استنادًا إلى نتائج استعلام SQL.

الإعداد:

1. اضبط Schedule Type على Action
2. اضبط Action name على com.namasoft.infra.domainbase.utils.notifications.NotificationByQueryTask
3. المدخل الأول: استعلام SQL يُعيد بيانات الإشعار
4. المدخل الثاني: أسماء الأعمدة مفصولةً بفواصل
5. المدخل الثالث: نوع الإشعار (اختياري)

خيارات المدخل الثالث:

القيمة	السلوك
(فارغ)	بريد إلكتروني فقط
mail	بريد إلكتروني فقط
notification	إشعار داخل التطبيق فقط
mail,notification	كلاهما: بريد إلكتروني وإشعار

اصطلاحات أعمدة الاستعلام:

• subject → موضوع الإشعار/البريد الإلكتروني
• sendto → عنوان البريد الإلكتروني المباشر
• sendto#type و sendto#id → مرجع كيان للمستلم
• parameterName#type و parameterName#id → معاملات الكيان

مثال:

select
  case when DATEDIFF(day, GETDATE(), residencyEnd) < 1
       then N'الاقامة انتهت منذ '
       else N'باقي علي انتهاء الاقامة '
  end + cast(ABS(DATEDIFF(day, GETDATE(), residencyEnd)) as nvarchar(100)) + N' يوم' as subject,
  'Employee' as sendto#type,
  supervisor_id as sendto#id,
  'Employee' as employee#type,
  id as employee#id
from Employee
where DATEDIFF(day, GETDATE(), residencyEnd) < 30
order by 2

قوالب الإشعارات

عند استخدام نوع جدولة Notification، يمكنك إعداد قوالب لثلاث قنوات:

قالب البريد الإلكتروني: محتوى HTML لجسم البريد الإلكتروني. استخدم العناصر النائبة مثل {columnName} لإدراج قيم نتائج الاستعلام.

قالب الإشعار: محتوى الإشعارات داخل التطبيق.

قالب SMS: محتوى نصي قصير لرسائل SMS.

يدعم كل قالب صيغة المُصيِّر المعقد مع عناصر نائبة تُملأ من نتائج الاستعلام.

تخصيص البريد الإلكتروني

قوالب الموضوع واسم المرفق

يمكنك تخصيص موضوعات البريد الإلكتروني وأسماء ملفات المرفقات باستخدام قوالب مع عناصر نائبة:

• Email Subject Template: قالب مع عناصر نائبة تُملأ من التقرير أو الاستعلام
• Email Subject Query: استعلام SQL لتوفير قيم قالب الموضوع
• Attachment Name Template: قالب لاسم الملف المرفق
• Attachment Name Query: استعلام SQL لتوفير قيم اسم المرفق

تنسيق المخرجات

اختر تنسيق مرفقات البريد الإلكتروني:

• HTML
• PDF
• Excel
• Word
• CSV

المُرسِل المفضّل للبريد الإلكتروني

اختر مُرسِل بريد إلكتروني محددًا ومهيأً لاستخدامه في الرسائل الصادرة من هذه المهمة.

معالجة الأخطاء

إشعار الخطأ

هيّئ When Errors Notification لإرسال تنبيهات عند فشل مهمة ما. يجب أن يكون تعريف هذا الإشعار:

• مضبوطًا على "Use Manually"
• مهيأً لـ Task Schedule

إذا لم يُهيَّأ إشعار خطأ، يُعلم النظام تلقائيًا مستخدم المسؤول بتفاصيل الخطأ.

معلومات الخطأ

عند فشل مهمة، يسجّل النظام:

• Error Message: وصف موجز لما حدث
• Error Description: تتبع الاستدعاء الكامل للتشخيص التقني

الخيارات المتقدمة

السماح بالتشغيل المتزامن

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

التشغيل في المواقع (Replication)

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

غير نشط

فعّل Inactive لتعطيل مهمة مؤقتًا دون حذفها. تبقى المهمة في النظام لكنها لن تُنفَّذ.

وضع التطوير

افتراضيًا، لا تعمل المهام المجدولة عند تشغيل الخادم في وضع التشخيص. لتفعيل تنفيذ المهام أثناء التطوير، أضف إلى nama.properties:

run-task-schedules-in-debug-mode=true

التأخير الأولي

لا تبدأ المهام فورًا عند تشغيل الخادم — هناك تأخير افتراضي مدته 5 دقائق. خصّصه في nama.properties:

tasks-initial-delay-minutes=10

تكامل مستودع التطبيق

يمكن حفظ المهام في مستودع التطبيق للنشر عبر البيئات المختلفة:

• Save to Implementation Repository: فعّله لتضمين هذه المهمة في التصديرات
• System Report: ضعه علامةً كمهمة مقدمة من النظام

مجموعة المدخلات (Params)

للمهام من نوع Parameterized Report، يمكنك تعريف المعاملات باستخدام مجموعة Params بدلًا من استعلام SQL. يحدد كل سطر معاملات:

• Send To: المستلم لهذه المجموعة من المعاملات
• P1 حتى P15: قيم المعاملات (يمكن الإشارة إلى كيانات أو استخدام قيم ثابتة)

WARNING

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

أمثلة عملية

ملخص المبيعات اليومي للإدارة

• النوع: Report
• التقرير: ملخص المبيعات اليومي
• تنسيق المخرجات: PDF
• أسبوعي: جميع أيام العمل محددة
• الوقت: 08:00
• Target Emails: management@company.com

تذكيرات الفواتير الشهرية

• النوع: Parameterized Report
• الاستعلام: تحديد الفواتير غير المدفوعة منذ أكثر من 30 يومًا
• التقرير: رسالة تذكير الفاتورة
• شهري: جميع الأشهر، اليوم 1
• الإرسال إلى: البريد الإلكتروني للتواصل لكل عميل

صيانة قاعدة البيانات الليلية

• النوع: System
• الاستعلام: EXEC sp_updatestats
• يوميًا الساعة 02:00
• لا يلزم مستلمون

مزامنة الطلبات الفورية

• النوع: Read Magento Orders
• تشغيل كل: 5 دقائق
• Magento Site: مرجع الموقع المهيأ