عقدة برنامج Python النصي (للمسؤولين): تشغيل منطق مخصص مع إدخال الملفات وإخراجها

عمليات سير العملالمسؤول9 دقيقة للقراءة

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

ما هذه الميزة؟

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

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

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

لماذا تفيدك؟ وما مزاياها الأساسية؟

معالجة أي منطق عمل مخصص أو تحويل بيانات أثناء العملية. إذا لم تستطع العُقد المدمجة التعبير عن قاعدة، تستطيع عقدة البرنامج النصي ذلك، ولا يوجد قيد على ما يمكن للكود حسابه.
تحويل صيغ الملفات تلقائيًا. حوّل ملف CSV أو Excel مرفوعًا إلى ملخص PDF، أو استخرج مجموعة من الصفوف؛ يشغّل البرنامج النصي التحويل وينتج الملف ثم يتابع سير العمل.
التحقق من البيانات وفق قواعد معقدة قبل وصولها إلى الموافقين. نفّذ فحصًا لا يمكن تمثيله بعقدة شرط بسيطة، ثم وجّه سير العمل بحسب النتيجة.
إنشاء ملفات ترفقها عُقد البريد اللاحقة وترسلها. تُحفظ ملفات مخرجات البرنامج النصي في مكتبة المستندات ويمكن الرجوع إليها في عقد البريد، ما يكمل سلسلة أتمتة من البيانات إلى الرسالة.
إبقاء الأسرار خارج سير العمل. يعمل البرنامج النصي على الخادم في بيئة مضبوطة. تبقى بيانات الاعتماد ومفاتيح API والمنطق الحساس على الخادم ولا تظهر للمستخدمين النهائيين أو في المتصفح.
ضبط مهلة تمنع البرامج غير المنتهية. تضمن المهلة القابلة للضبط من 5 ثوانٍ إلى ساعة ألا يحظر برنامج عالق مثيل سير العمل إلى أجل غير مسمى.

للمسؤولين فقط. تُخفى عقدة البرنامج النصي عن المستخدمين غير المسؤولين في الشريط الجانبي للمصمم، ولا تستطيع حساباتهم حفظها. يُطبق التحكم في الوصول على الخادم، وليس في الواجهة فقط.

قبل أن تبدأ

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

طريقة الاستخدام خطوة بخطوة

الخطوة 1: ضع العقدة على اللوحة

افتح علامة منطق في الشريط الجانبي الأيسر للمصمم المرئي.

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

الخطوة 2: اضبط التسمية والوصف والمهلة

أدخل في حقل عنوان العقدة اسمًا يصف وظيفة البرنامج النصي، مثل «معالج كشف الدوام» أو «مدقق الفاتورة». يظهر الاسم على اللوحة.
أدخل في حقل الوصف ملاحظة موجزة واختيارية تشرح غرض البرنامج.
اضبط في حقل المهلة (بالثواني) أقصى مدة يُسمح للبرنامج بالعمل خلالها قبل إيقافه قسرًا. النطاق من 5 إلى 3600 ثانية، أي حتى ساعة، والقيمة الافتراضية 300 ثانية، أي خمس دقائق.

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

الخطوة 3: اكتب الكود (علامة الكود)

اختر علامة الكود، وهي المحددة افتراضيًا.

اكتب كود Python في المحرر. توفر البيئة ثلاثة كائنات مدمجة يمكنك استخدامها مباشرة:

الكائن	كيفية استخدامه
`input_files["widgetName"][0]`	الملف المرفوع عبر أداة منتقي الملفات المسماة `widgetName`. يعيد كائنًا شبيهًا بالملف.
`output_files["outputKey"]`	مسار ملف قابل للكتابة لملف المخرجات المسجل بالمفتاح `outputKey`. اكتب إلى هذا المسار لإنتاج الملف.
`workflow_data.get("key", default)`	قيمة متغير سير العمل المسمى `key`. قدم قيمة افتراضية لحالة غياب المفتاح.

مثال بسيط:

import openpyxl

# Read the uploaded Excel file
wb = openpyxl.load_workbook(input_files["uploadBiometricFile"][0])
ws = wb.active

# Count non-empty rows (excluding header)
row_count = sum(1 for row in ws.iter_rows(min_row=2) if any(c.value for c in row))

# Save the processed workbook as the output
wb.save(output_files["timesheet"])

# Return values to use in downstream nodes
return {"rows_processed": row_count}

تكشف عبارة return في نهاية البرنامج قاموسًا من أزواج المفتاح والقيمة كمتغيرات لسير العمل. فمثلًا تجعل return {"rows_processed": 42} المتغير {{rows_processed}} متاحًا لكل عقدة لاحقة.

الخطوة 4: اضبط ملفات الإدخال (علامة ملفات الإدخال)

اختر علامة ملفات الإدخال.

أدوات منتقي الملفات:

يعرض القسم العلوي جميع أدوات منتقي الملفات المكتشفة في عقدة البدء، إذا ضُبط تكامل نموذج التطبيقات. تظهر كل أداة كزر قابل للتحديد.
اختر زر كل أداة ينبغي أن يتلقى البرنامج ملفها المرفوع. تتحول الأدوات المحددة إلى اللون السماوي وتظهر عليها علامة اختيار. استخدم في الكود input_files["widgetName"][0] للوصول إلى الملف.
إذا لم تظهر الأداة المطلوبة في القائمة، فاختر إضافة يدويًا واكتب اسمها مطابقًا تمامًا لما يظهر في النموذج.

متغيرات بيانات سير العمل:

يعرض القسم السفلي، متغيرات بيانات سير العمل، جميع أدوات النص والإدخال التي تتوفر قيمها عبر workflow_data.get("key"). هذا قسم مرجعي للقراءة فقط، ويعرض أسماء المفاتيح الدقيقة التي تستخدمها في البرنامج النصي؛ ولا تحتاج إلى اتخاذ إجراء فيه.

الخطوة 5: عرّف ملفات المخرجات (علامة ملفات المخرجات)

اختر علامة ملفات المخرجات.
اختر إضافة ملف مخرجات لكل ملف سيكتبه البرنامج.
اضبط لكل ملف مخرجات:

المفتاح (المستخدم في الكود) — المفتاح المستخدم في output_files["yourKey"] داخل البرنامج، مثل timesheet. اجعله قصيرًا وبأحرف صغيرة ومن دون مسافات.
تسمية العرض — اسم واضح للملف، مثل «مخرجات كشف الدوام». يُستخدم عند تحديد المخرج في خطوات سير العمل اللاحقة.
مفتاح الحفظ في المستندات — عند تفعيله، وهو الافتراضي، يُحفظ الملف الذي ينتجه البرنامج تلقائيًا في مكتبة المستندات ويمكن إرفاقه بعقدة بريد لاحقة. عطّله إذا لم تحتج إلى حفظ الملف.

اختر رمز سلة المهملات الأحمر لإزالة إدخال ملف مخرجات.

الخطوة 6: احفظ وصِل العقدة

اختر حفظ في تذييل مربع الحوار. يُغلق المربع.
ارسم في المصمم حوافًا من مقبض إخراج عقدة البرنامج النصي إلى الخطوة التالية.
اختر حفظ أو اضغط Ctrl+S.

شرح الخيارات والإعدادات

حقول الرأس

الحقل	ما الذي يفعله؟
عنوان العقدة	التسمية الظاهرة على اللوحة وفي سياق تنفيذ سير العمل.
الوصف	ملاحظة نصية حرة واختيارية تُحفظ مع العقدة ولا تظهر للمستخدم النهائي.
المهلة (بالثواني)	أقصى ثوانٍ يمكن للبرنامج العمل خلالها. النطاق 5–3600، والافتراضي 300. عند تجاوزها يُنهى البرنامج ويُعلّم المثيل كفاشل عند هذه الخطوة.

علامة الكود

العنصر	ما الذي يفعله؟
محرر الكود	مساحة نصية كاملة بخط ثابت العرض، تقبل أي كود Python 3.11+ صحيح.
`input_files["name"][0]`	يقرأ الملف المرفوع عبر أداة النموذج المسماة `name`. يصل `[0]` إلى أول ملف مرفوع، وقد يوفر الرفع المتعدد ملفات إضافية.
`output_files["key"]`	مسار ملف قابل للكتابة. اكتب ملف المخرجات إليه، وتخزنه المنصة تلقائيًا.
`workflow_data.get("key", default)`	يقرأ متغير سير عمل بالاسم ويعيد `default` إذا لم يوجد المفتاح.
`return {...}`	يعيد قاموس Python. يصبح كل زوج مفتاح وقيمة متغير سير عمل متاحًا للعُقد اللاحقة عبر `{{key}}`.

علامة ملفات الإدخال

العنصر	ما الذي يفعله؟
أزرار أداة منتقي الملفات	تحدد الملفات المرفوعة التي يستطيع البرنامج الوصول إليها. تُبرز الأدوات المحددة.
إضافة يدويًا	تتيح إدخال اسم أداة لم تُكتشف تلقائيًا. أدخل الاسم الدقيق الظاهر في النموذج.
قسم متغيرات بيانات سير العمل	مرجع للقراءة فقط يعرض تعبيرات `workflow_data.get("key")` لكل أداة نص أو إدخال.

علامة ملفات المخرجات

الحقل	ما الذي يفعله؟
المفتاح (المستخدم في الكود)	المفتاح المستخدم في `output_files["key"]` داخل البرنامج، ويجب أن يكون فريدًا ضمن العقدة.
تسمية العرض	الاسم الواضح المستخدم لملف المخرجات في منتقيات العُقد اللاحقة.
مفتاح الحفظ في المستندات	مفعّل افتراضيًا: يُخزن الملف تلقائيًا في المكتبة. عند تعطيله، لا يبقى الملف إلا أثناء خطوة سير العمل الحالية ولا يُحفظ.

نصائح وأفضل الممارسات

اجعل البرامج النصية مركزة وقصيرة. يسهل الحفاظ على برنامج يؤدي مهمة واحدة وتصحيح أخطائه أكثر من برنامج يفعل كل شيء. اربط عدة عُقد برامج نصية للتحويلات المعقدة متعددة الخطوات.
قدم دائمًا قيمًا افتراضية في workflow_data.get()، مثل workflow_data.get("amount", 0)، لمنع أخطاء KeyError إذا تُرك حقل اختياري فارغًا.
استخدم مفاتيح وصفية في قاموس return. تصبح المفاتيح أسماء متغيرات سير العمل. تسهل الإشارة إلى أسماء واضحة مثل invoice_total أو approval_status في الشروط والموجّهات اللاحقة أكثر من result أو val1.
اختبر الحالات الحدّية. شغّل سير العمل يدويًا بملف فارغ أو قيمة صفرية أو حقل اختياري مفقود. تؤدي أخطاء البرنامج إلى تعليم المثيل كفاشل وإيقافه عند هذه العقدة.
امنح البرامج التي تعالج ملفات مهلة كافية من دون مبالغة. تكفي خمس دقائق لمعظم التحويلات؛ ولا تخصص ساعة إلا للمعالجة الثقيلة فعلًا.
فعّل «الحفظ في المستندات» لملفات المخرجات إذا احتاجت خطوة لاحقة، مثل عقدة البريد، إلى إرفاق الملف. يجب حفظه في مكتبة المستندات حتى يمكن إرفاقه.
طابق أسماء مفاتيح المخرجات مع عقدة البريد. إذا سميت المخرج invoice_pdf، فستجده بهذا الاسم ضمن خيارات مرفقات البريد.
وثّق وظيفة البرنامج النصي في وصف العقدة وتعليقات الكود. يفيد ذلك في الصيانة؛ فقد لا يعرف المسؤول التالي الذي يحرر سير العمل الغرض الأصلي.

الأسئلة الشائعة

س: لا أرى عقدة البرنامج النصي في الشريط الجانبي. ما الخطأ؟ تُخفى عن المستخدمين غير المسؤولين. وحدها الحسابات التي تحمل دور المسؤول تستطيع رؤية عُقد البرامج النصية أو إضافتها أو حفظها. تحقق من دورك في شريط التنقل العلوي.

س: هل يمكنني استيراد مكتبات Python خارجية؟ يعمل البرنامج في بيئة خادم مضبوطة مسبقًا. تتوفر عادة وحدات المكتبة القياسية ومكتبات معالجة البيانات الشائعة مثل openpyxl وpandas وما شابه. تواصل مع مسؤول النظام للحصول على القائمة الكاملة أو لطلب حزم إضافية.

س: ماذا يحدث إذا أثار البرنامج النصي استثناءً؟ يُعلّم مثيل سير العمل كفاشل عند عقدة البرنامج النصي. افتح المثيل من كل المثيلات وراجع عرض تفاصيل سير العمل والسجلات التشغيلية. أصلح البرنامج واحفظ التصميم ثم ابدأ تشغيلًا مضبوطًا جديدًا.

س: هل يستطيع البرنامج النصي إرسال طلبات HTTP إلى أنظمة خارجية؟ يعتمد ذلك على إعداد شبكة الخادم. يمكن أن يتضمن الكود طلبات HTTP، لكن السماح بالاتصالات الصادرة إعداد على مستوى النظام. تحقق من مسؤول البنية التحتية.

س: هل يمكنني استخدام قيمة return من عقدة برنامج نصي في شرط إذا/وإلا لاحق؟ نعم. يصبح كل مفتاح في القاموس المُعاد متغيرًا. إذا أعاد البرنامج {"status": "approved"}، فيمكنك الإشارة إلى {{status}} في شرط إذا/وإلا لاحق.

س: كيف أرفق ملفًا أنشأه البرنامج النصي برسالة بريد؟ فعّل الحفظ في المستندات لملف المخرجات في علامة ملفات المخرجات. ثم اختر في إعدادات مرفقات عقدة البريد اللاحقة «ملفات مخرجات محددة»، وحدد الملف بتسمية عرضه.

س: هل يمكن وجود عدة عُقد برنامج نصي في سير العمل نفسه؟ نعم. تُضبط كل عقدة بصورة مستقلة، وتصبح المتغيرات المعادة من إحداها متاحة لكل العُقد اللاحقة، بما فيها عُقد البرامج النصية الأخرى.

هل ما زلت بحاجة إلى مساعدة؟ راجع الحصول على مساعدة من الدعم أو تواصل مع مسؤول مساحة العمل.