تطبيق attcron لسحب بيانات الحضور (The attcron Attendance Agent)

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

attcron هو التطبيق الصغير الذي يسد هذه الفجوة. يتم تنصيبه في الفرع، بجوار ماكينة الحضور، حيث يستطيع الوصول إليها بحرية. وعلى فترات مجدولة يقوم بجمع البصمات الجديدة ودفعها إلى الخارج باتجاه نما. ولأن كل اتصال يبدأ من الفرع، فلا يحتاج أي فرع إلى IP ثابت ولا إلى فتح أي منفذ وارد؛ كل ما يحتاجه الفرع هو القدرة على الوصول إلى خادم نما.

اقرأ صفحة الإعدادات أولًا

كل ما يفعله attcron — أي ماكينة، وأي استعلام، وأي جدولة — يتحدد من خلال سجل إعدادات ماكينة الحضور في نما. فالتطبيق لا يحتفظ تقريبًا بأي إعدادات خاصة به؛ بل يسأل نما عن تعليماته في كل مرة يبدأ فيها العمل. جهّز ذلك السجل أولًا: ماكينات الحضور.

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

ما تحتاجه قبل البدء

على جهاز الفرع الذي سيشغّل التطبيق — وهو عادةً نفس الجهاز الذي يعمل عليه برنامج ماكينة الحضور:

• JDK 21
• Apache Tomcat 10، مع ضبط نوع التشغيل على Automatic حتى يعود التطبيق للعمل بعد إعادة تشغيل الجهاز

وفي نما:

• سجل بيانات اعتماد الـ API (API Credentials) — احتفظ بـ Client ID و Client Secret
• سجل إعدادات ماكينة الحضور محفوظ — احتفظ بـ الكود الخاص به

التنصيب

يتم تسليم التطبيق عبر ملف تنصيب صغير يقوم بتحميله وفك ضغطه نيابةً عنك.

1. حمّل ملف التنصيب من https://namasoft.com/bin/nama-attcron-upgrader.jar.
2. ضع الملف داخل مجلد Tomcat وشغّله من هناك. فهو يبحث عن مجلد webapps بجواره؛ وإن شغّلته من أي مكان آخر فسيتوقف مع الرسالة "Please run from inside tomcat folder".
3. يقوم بتحميل التطبيق، ثم ينتظر حتى يحرر Tomcat النسخة السابقة، ثم يضع النسخة الجديدة مكانها. ظهور رسائل عن انتظار حذف أحد المجلدات أمر طبيعي — امنحه دقيقة أو دقيقتين.
4. افتح المتصفح على ذلك الجهاز وادخل إلى http://localhost:8080/attcron.

لا تُعِد تسمية ملف التنصيب

يحدد ملف التنصيب ما الذي يقوم بتنصيبه من اسم الملف نفسه. وإعادة تسميته إلى اسم لا يحتوي على "cron" تجعله يُنصّب تطبيقًا خاطئًا.

المتصفح يحتاج إلى اتصال بالإنترنت

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

التشغيل الأول: الاتصال بنما

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

الحقل	ما الذي تُدخله
Nama Server URL	عنوان خادم نما لديك، مثل https://erp.example.com.
Nama Client Id	من سجل بيانات اعتماد الـ API.
Nama Client Secret	من سجل بيانات اعتماد الـ API.
Attendance Machine Config File Code	كود سجل إعدادات ماكينة الحضور.

يمكنك كتابة عنوان الخادم بالصيغة المتوفرة لديك — بشرطة مائلة في نهايته أو بدونها، وبـ /erp أو بدونها — والتطبيق يستنتج الباقي.

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

احمِ المنفذ

كل من يستطيع فتح صفحة التطبيق يستطيع تشغيل عملية سحب البيانات، بل ويستطيع — على تطبيق غير مُعدّ بعد — توجيهه إلى أي خادم يشاء. فالإجراء Logout وحده هو الذي يطلب بيانات دخول. أبقِ منفذ Tomcat محميًا بجدار حماية بحيث لا يُتاح إلا للجهاز المحلي، واستخدم https في عنوان خادم نما حتى لا تُرسل بيانات الاعتماد عبر الشبكة بشكل مكشوف.

الشاشة اليومية

بعد إتمام الإعداد يعرض التطبيق صفحة حالة تسرد آخر عمليات سحب البيانات — تاريخ وعدد القراءات لكل عملية — وتُحدّث نفسها كل ثلاثين ثانية. وفوقها أربعة أزرار:

الزر	ما الذي يفعله
Send Now	ينفذ عملية سحب بيانات فورًا، تمامًا كما لو حان موعد الجدولة.
Read For Period	يطلب تاريخ ووقت "من" و"إلى"، ثم يعيد قراءة تلك الفترة بالتحديد.
Refresh	يعيد تحميل جدول الإحصائيات.
Logout	يفصل التطبيق عن نما. ويتطلب اسم مستخدم وكلمة مرور صحيحين في نما.

يظهر رقم إصدار التطبيق بجوار الأزرار، كما يُرسَل إلى نما مع كل عملية إرسال، حيث يظهر في حقل Current Release Version على سجل الإعدادات.

زر Read For Period هو أداة تعويض البيانات الناقصة

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

جدول الإحصائيات ليس سجلًا تاريخيًا

قائمة عمليات سحب البيانات محفوظة في الذاكرة فقط. فإعادة تشغيل Tomcat تفرغها، كما يتم تقليمها متى تجاوزت خمسين سطرًا تقريبًا. إنها مؤشر حالة، وليست سجلًا. أما السجل الدائم فهو في نما، في تبويب Statistics على سجل الإعدادات.

ماذا يحدث في كل عملية سحب بيانات

يسأل التطبيق نما عن إعداداته الحالية، ثم يتخاطب مع الماكينة بالطريقة التي تحددها تلك الإعدادات — واجهة الويب الخاصة بـ ZkBioTime، أو قاعدة بيانات SQL Server، أو ملف Microsoft Access. ثم يجمع كل ما هو أحدث من النقطة التي وصل إليها آخر مرة، ويرسله إلى نما على دفعات، ويحفظ موضعه الجديد.

بعض الأرقام التي يفيد معرفتها وأنت تراقب عمله:

• عمليات السحب من قواعد البيانات تُرسَل على دفعات من 500 قراءة، ويُحفظ الموضع بعد كل دفعة — لذا فالعملية التي تنقطع في منتصفها تحتفظ بما أنجزته.
• عمليات السحب من ZkBioTime تُقرأ صفحة بصفحة، بواقع 100 قراءة لكل صفحة.
• إذا رفض نما إحدى عمليات الإرسال، يعيد التطبيق المحاولة حتى ثلاث مرات بفاصل ثانيتين تقريبًا قبل أن يتوقف ويسجل الفشل. ثم تحاول العملية المجدولة التالية مرة أخرى من نفس الموضع.
• عملية Read For Period لا تُحرّك الموضع المحفوظ عمدًا.

يعمل Send Now و Read For Period أثناء انتظارك في المتصفح. وقد تستغرق عملية تعويض كبيرة وقتًا طويلًا وتبقى الصفحة واقفة حتى تنتهي؛ وهذا أمر متوقع.

أين يحفظ التطبيق بياناته

في ملفين، كلاهما في مجلد عمل Tomcat (وهو عادةً مجلد bin، وإن كان ذلك يعتمد على طريقة تنصيب Tomcat):

attcron.properties يحتوي على القيم الأربع من شاشة الدخول — مع تخزين الـ client secret مشفّرًا لا كنص صريح — إضافةً إلى الطابع الزمني الذي وصل إليه التطبيق في سحب البيانات.

namasoft.log هو سجل التطبيق، ويُستبدل عند بلوغه 100 ميجابايت مع الاحتفاظ بخمس نسخ مضغوطة. وهنا تكمن التفاصيل الحقيقية عندما يفشل شيء ما بصمت.

ويترتب على ذلك أمران:

• للبدء من جديد تمامًا، أوقف Tomcat، واحذف ملف attcron.properties أو أفرغه، ثم شغّله مرة أخرى. عندها يعود التطبيق إلى شاشة الدخول. وهذا أيضًا هو المخرج إن احتجت إلى توجيه التطبيق إلى خادم آخر ولم تكن لديك بيانات دخول نما التي يطلبها Logout.
• لإعادة ضبط المدى الذي وصل إليه في سحب البيانات، عدّل الطابع الزمني المخزّن في ذلك الملف أو احذفه. وبحذفه يستنتج التطبيق نقطة بداية جديدة — أولًا من آخر قراءة موجودة لدى نما لتلك الإعدادات، ثم من Fetching Transaction Start Date، وإن لم يجد أيًّا منهما فمن قبل شهرين.

الترقية

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

عندما يحدث خطأ ما

ابدأ من سجل الإعدادات في نما. فحقل Last Connection Time يخبرك إن كان التطبيق حيًّا أصلًا؛ وتبويب Statistics يخبرك بما وصل من بيانات. ثم تحرّك للخلف:

حقل Last Connection Time قديم. التطبيق لا يصل إلى نما. تأكد من أن Tomcat يعمل على جهاز الفرع، وافتح صفحته محليًا، وجرّب Send Now — وسيظهر لك الخطأ على الشاشة أيًّا كان.

عمليات الإرسال تصل لكنها فارغة. التطبيق يتخاطب مع نما بشكل سليم، لكن الماكينة لا تعطيه شيئًا. راجع الاستعلام في سجل الإعدادات وجرّب Read For Period على فترة تعلم أن بها بصمات.

القراءات تصل لكن لا يظهر شيء في مستند الحضور والانصراف. لقد وصلت إلى نما لكن لم تتحول إلى حضور بعد — راجع صندوق الوارد في تبويب Statistics على سجل الإعدادات، والمهمة المجدولة المحددة في حقل Run Task Schedule After Fetching Transactions.

عمليات السحب تبدو متباعدة. إذا لم يكن تعبير الـ cron بصيغة صحيحة من ستة حقول، يعود التطبيق بصمت إلى العمل كل اثنتي عشرة ساعة.

إعداد Access لا يبدأ العمل. يصرّ التطبيق على وجود قيم في Machine URL و Username و Password و Cron Expression، رغم أن اتصال Access لا يستخدم سوى الأول. ضع نصًّا وهميًا في البقية.

رسائل قد تظهر لك

الرسالة	المعنى
Configuration File Does not Exist / File [attcron.properties] is not found.	لم يتم إعداد التطبيق من قبل، أو تم حذف ملفه. سجّل الدخول من جديد.
Wrong Configuration File Data / Error While Reading Configuration File, There are one or more property not found.	الإعدادات المخزّنة ناقصة أو تالفة. أفرغ الملف وسجّل الدخول من جديد.
Could not Find Attendance Machine Config File Data With Code (…)	لا يوجد في نما سجل إعدادات بهذا الكود. تحقق من الكود، ومن أن السجل محفوظ.
Invalid Attendance Machine Config File Data	تم العثور على الإعدادات لكن ينقصها Machine URL أو Username أو Password أو Cron Expression.
IO Exception While Calling Nama ERP Server	الفرع لا يستطيع الوصول إلى عنوان الخادم المُدخَل. تحقق من الرابط ومن الشبكة ومن أي جدار حماية.
Failed to save attendance logs after 3 retries: …	رفض نما عملية الإرسال ثلاث مرات؛ والنص الذي يليها هو سبب الرفض من نما نفسه.
UCanAccess driver not found	مكوّن دعم Access مفقود — أعد تنصيب التطبيق.
Username And Password are Required	تم الضغط على Logout دون إدخال بيانات الدخول.

كود إعدادات خاطئ يفشل بطريقة غير مفيدة

إذا كان الكود المخزّن في التطبيق لا يطابق أي سجل إعدادات في نما، فإن عملية الإرسال تفشل برسالة خطأ عامة من الخادم بدلًا من رسالة واضحة تقول "غير موجود". فإذا فشلت عمليات الإرسال مباشرةً بعد التنصيب، تحقق من ذلك الكود أولًا.

صفحات ذات صلة

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