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

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

تبدأ المهمة بالعمل وفق جدولها بعد دقائق قليلة من تشغيل الخادم (راجع قسم التأخير الأولي)، كما يمكنك تشغيل أي مهمة فورًا عبر زر تشغيل الآن (Run Now).

أنواع المهام

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

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

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

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

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

Notification (إشعار)

يرسل إشعارات للمستخدمين استنادًا إلى استعلام وقالب أو أكثر. يمكنك استهداف ثلاث قنوات في آنٍ واحد:

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

System (نظام)

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

Action (إجراء)

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

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

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

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

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

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

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

Read Magento Orders / Read Magento Returns

لتكامل التجارة الإلكترونية — يسحب الطلبات أو المرتجعات من موقع Magento مهيأ. في بيئات النسخ المتماثل (replication) متعددة المواقع، تعمل هذه المهام على المركز الرئيسي فقط أو على المواقع المدرجة في Run in Sites.

Purge Expired Reward Points

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

Read E-Invoice Notifications

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

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

يوفر المجدول طريقتين للتعبير عن متى تعمل المهمة: واجهة مربعات اختيار سهلة، أو حقول cron مباشرة. أيًا كان اختيارك، فالنتيجة واحدة في الأساس — تُترجم مربعات الاختيار إلى حقول 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 → يعمل مرة يوميًا

"التشغيل كل X" له الأولوية

عند تعبئة Run On + Run On Type، يتجاوز نمط "كل X" اختيارات وقت اليوم والأسبوعي والشهري للوحدة المطابقة. استخدم إما "التشغيل كل X" أو محددات الأسبوعي/الشهري + وقت اليوم — وليس كليهما لنفس الوحدة.

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

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

• الأشهر التي تريد التشغيل فيها (فعّل Run On All Months، أو اختر من يناير حتى ديسمبر)
• أيام الشهر التي تريد التشغيل فيها (1 حتى 31)

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

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

عندما يكون Using Cron محددًا، تملأ خمسة حقول جدولة منفصلة مباشرةً. يتحكم كل حقل في جزء من التوقيت:

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

يقبل كل حقل صيغ cron القياسية: قيمة مفردة (8)، أو قائمة (1,3,5)، أو مدى (1-5)، أو خطوة (*/5). الحقل المتروك فارغًا يُعامل كـ *. يجب أن يكون كل حقل رمزًا واحدًا بدون مسافات.

متى تعمل المهمة بالضبط؟

تعمل المهمة عند بداية (الثانية :00) من كل دقيقة تطابق الحقول الخمسة جميعها. لذا فإن Minute = 0 و Hour = 8 تعني "الساعة 08:00:00 كل يوم".

أنماط شائعة:

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

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

تشغيل مهمة عند الطلب

لست مضطرًا لانتظار الموعد المجدول التالي. افتح المهمة واضغط تشغيل الآن (Run Now) لتنفيذها فورًا — مفيد لاختبار مهمة جديدة أو إعادة تشغيل مهمة بعد إصلاح مشكلة. يتصرف التشغيل اليدوي تمامًا كالتشغيل المجدول، بما في ذلك تسجيل التشغيل وإشعارات الأخطاء.

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

تتوفر عدة طرق لتحديد من يستلم التقارير والإشعارات، ويمكن دمجها معًا:

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

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

Target Reference (مرجع الاستهداف)

اختر مرجعًا واحدًا يُحوَّل إلى شخص أو أكثر:

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

Target Criteria (معايير الاستهداف)

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

Target Lines (سطور الاستهداف)

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

تُدمج كل هذه الطرق معًا: العناوين المستخرجة من المراجع والمعايير وسطور الاستهداف تُجمع مع Target Emails المباشرة في قائمة مستلمين واحدة.

التقارير بمدخلات (Parameterized Reports)

تشغّل هذه الميزة تقريرًا واحدًا عدة مرات بمدخلات مختلفة — مثالية لإرسال نسخة مخصصة لكل مدير أو عميل أو فرع. اختر Parameterized Report (Email) أو Parameterized Report (Print) كنوع للجدولة.

توجد طريقتان لتوفير صفوف المدخلات:

1. استعلام SQL — ضع الاستعلام في حقل Query وتعيين أسماء الأعمدة في Query Fields. يعمل التقرير مرة لكل صف مُعاد. (إذا تركت Query Fields فارغًا، تُستخدم أسماء أعمدة الاستعلام نفسها.)
2. جدول Params — تعرّف الصفوف يدويًا بدلًا من كتابة استعلام (راجع قسم مجموعة المدخلات (Params)).

مصدر واحد فقط

لا يمكنك استخدام Query وجدول Params في نفس المهمة. اختر واحدًا.

اختيار القناة. يحترم كل تكرار مفتاحين:

• Send As Mail (مفعّل افتراضيًا) → يرسل التقرير المُصيَّر بالبريد الإلكتروني.
• Send As Notification → ينشر التقرير أيضًا للمستلمين كإشعار داخل التطبيق.

تخطّي البريد عندما لا توجد بيانات للتكرار

إذا لم ترغب في إرسال رسالة لتكرار يخرج تقريره فارغًا، فتحكّم في ذلك من قالب التقرير (JasperReports) نفسه لا من المهمة. اضبط سلوك "When No Data" في القالب على No Pages (بدلًا من "Blank Page" أو قسم "No Data"). التقرير الذي لا يُنتج أي صفحات لا يولّد شيئًا للإرفاق، فيُتخطّى ذلك المستلم ببساطة — دون إرسال بريد فارغ. ينطبق هذا أيضًا على نوع Report العادي.

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

عند تشغيل التقرير من استعلام، تُخبر أسماء أعمدة خاصة النظامَ بكيفية استخدام كل قيمة:

العمود	المعنى
subject	سطر موضوع البريد الإلكتروني لذلك الصف
sendto	عنوان بريد إلكتروني عادي لإرسال ذلك الصف إليه
sendto#type و sendto#id	مرجع (موظف/منصب/مجموعة) يستلم أعضاؤه ذلك الصف
parameterName#type و parameterName#id	قيمة مرجع لمدخل التقرير المسمى parameterName
parameterName	قيمة عادية لمدخل التقرير المسمى parameterName

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

يرسل تقريرًا مخصصًا لمشرف كل موظف بشأن تصاريح الإقامة التي تنتهي قريبًا.

الاستعلام (Query):

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

Query Fields:

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

الإشعارات المبنية على استعلام

استخدم نوع الجدولة Notification لإرسال إشعارات داخل التطبيق أو بريد إلكتروني أو رسائل SMS مبنية من استعلام SQL. املأ:

1. Query — استعلام SQL يُعيد بيانات الإشعار.
2. Query Fields — أسماء الأعمدة مفصولةً بفواصل (اختياري؛ يفترض أسماء أعمدة الاستعلام نفسها).
3. القالب/القوالب للقناة/القنوات التي تريدها — Email و/أو Notification و/أو SMS (راجع قسم قوالب الإشعارات). تُستخدم القناة فقط عند تعبئة قالبها.

تنطبق اصطلاحات الأعمدة نفسها (subject، sendto، sendto#type/sendto#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
from Employee
where DATEDIFF(day, GETDATE(), residencyEnd) < 30
order by 2

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

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

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

قالب الإشعار (Notification Template) — محتوى الإشعارات داخل التطبيق.

قالب SMS (SMS Template) — محتوى نصي قصير لرسائل SMS.

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

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

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

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

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

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

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

• HTML
• PDF
• Excel
• Word
• CSV

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

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

المتابعة ومعالجة الأخطاء

سجل التشغيل (Execution Log)

فعّل Enable Execution Log للاحتفاظ بسجل لكل تشغيل. في كل مرة تُنفَّذ المهمة — سواء وفق الجدول أو عبر تشغيل الآن — يُسجَّل سطر جديد في جدول سجل تشغيل المهمة (Task Schedule Execution Log) على المهمة، يلتقط:

• Start Time (وقت البدء) — متى بدأ التشغيل
• End Time (وقت الانتهاء) — متى انتهى
• Status (الحالة) — قيد التشغيل (Running) أثناء التنفيذ، ثم ناجح (Success) أو فاشل (Failed)
• Error Message (رسالة الخطأ) — سبب موجز عند فشل التشغيل

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

إشعار الخطأ

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

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

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

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

عند فشل مهمة، يُحفظ آخر خطأ على المهمة نفسها (ويظهر في قائمة Task Schedule Errors):

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

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

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

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

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

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

غير نشط

فعّل 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 (Email)
• الاستعلام: تحديد الفواتير غير المدفوعة منذ أكثر من 30 يومًا، مع تعيين بريد كل عميل إلى sendto
• التقرير: رسالة تذكير الفاتورة
• شهري: جميع الأشهر، اليوم 1
• يستلم كل عميل نسخته الخاصة

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

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

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

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