تدفقات n8n

يمكن لـ AI-Public بدء تدفقات n8n عبر ويبهوك إنتاجي. هذا مفيد عندما تريد بدء عملية تلقائية خارج AI-Public، مثل إنشاء مهمة أو تحديث سجل CRM أو بدء تدفق تقرير أو إرسال بيانات نموذج إلى نظام آخر.

مثال: مقالة إخبارية على موقع المؤسسة

افترض أن المؤسسة قد أنشأت تدفق عمل في n8n ينشر مقالة إخبارية على موقع WordPress. في AI-Public تملأ فقط فقرة قصيرة، على سبيل المثال سطور حول اجتماع أو مشروع أو إعلان عام. باستخدام تلك الفقرة، تبدأ التدفقات في n8n.

يمكن لتدفق n8n بعد ذلك على سبيل المثال:

1. تحويل النص القصير إلى نص مقترح أنيق باستخدام عقدة LLM وطلب مناسب ينسجم مع نبرة المؤسسة.
2. إنشاء توضيح مناسب بعقدة LLM ثانية، على سبيل المثال بألوان الهوية البصرية وبأسلوب توضيحي مميز.
3. تجهيز النص والصورة كلوحة مدونة جاهزة للنشر على موقع WordPress أو نشرها.

هكذا تعمل AI-Public وn8n معاً: في AI-Public يختار المستخدم تدفق العمل ويدخل المعلومات المطلوبة. ثم تقوم n8n بتنفيذ الخطوات الآلية وتضمن ظهور المقالة الإخبارية بشكل مناسب على الموقع.

ماذا تفعل هذه التكامل؟

تبدأ تدفق عمل ن8ن من خلال عرض التدفق. فقط webhook الإنتاجي، POST وHeader Auth واجبة. الحقول والتعليقات المرتدة من n8n اختيارية ويمكن إعدادها بشكل مستقل.

• إذا لم يكن لدى التدفق أي حقول، سيتم استدعاء الـ webhook فوراً.
• إذا كان لدى التدفق حقول، فسيظهر أولاً نموذج. يملأ المستخدم الحقول ثم يبدأ التدفق باستخدام الزر.
• تُرسَل القيم المُدخلة كـ JSON في طلب POST إلى webhook الخاص بـ n8n.
• بدون تعليقات مرتجعة، تؤكد AI-Public أن التدفق قد بدأ ويستمر في n8n. النافذة لا تعرض دوارة ويمكن إغلاقها على الفور.
• إذا تم تمكينه أثناء التسجيل، يمكن أن يعيد التدفق خطوات مرحلية أو النهاية إلى AI-Public.
• إذا تم تمكين الموافقة أثناء التسجيل، يمكن للمستخدم إجراء اختيار مباشر داخل AI-Public. ثم يواصل n8n من خطوة الانتظار التالية.

إنشاء تدفق n8n في AI-Public

يقوم المسؤول بتسجيل التدفق كما يلي:

1. اذهب إلى المساعدون.
2. افتح التدفقات.
3. اختر تدفق n8n جديد.
4. أدخل اسم التدفق ونطاق URL الإنتاجي لـ n8n.
5. اضبط المصادقة الرأسية باستخدام اسم هيدر وقيمة هيدر سرية.
6. اختر تحت التعليقات من n8n الأجزاء التي تود فعلًا أن يتم بناؤها في هذا التدفق فقط: التقدم، الموافقة و/أو نهاية التدفق.
7. أضف الحقول التي يجب إرسالها في طلب POST.
8. احفظ التدفق.

جميع خيارات التعليقات الثلاثة افتراضية معطلة. إذا أضفت لاحقاً إشعارات عودة أو خطوة موافقة في n8n، فحدّث التسجيل في AI-Public كذلك. تعرف النافذة حينها ما إذا كان يجب عرض تأكيد البدء فقط أو انتظار إشارات إضافية.

الحقول

• الحقول اختيارية.
• كل حقل له اسم حقل ونوع واحد.
• أنواع الحقول المدعومة: نص قصير، نص طويل، رقم، نعم/لا، تاريخ، اختيار واحد وخيارات متعددة.
• عند اختيار واحد وخيارات متعددة أضف الخيارات المتاحة. يظهر اختيار واحد كمُدْرج اختياري مضغوط؛ تُظهر خيارات متعددة مربعات اختيار. القيمة المختارة تُرسل في جسم JSON.
• الحقول الإلزامية يجب تعبئتها قبل أن يبدأ التدفق.
• اسم الحقل يصبح المفتاح في جسم JSON المُرسل إلى n8n.

إنشاء تدفق عمل متوافق في n8n

1. أنشئ تدفقاً جديداً في n8n.
2. أضف كأول عقدة Webhook.
3. امنح هذه العقدة الاسم بالضبط Start workflow. تستخدم الأكواد النموذجية أدناه هذا الاسم.
4. اضبط HTTP Method على POST.
5. اختر Authentication: Header Auth واستخدم نفس اسم الهيدر والقيمة السرية كما في AI-Public.
6. اضبط Respond أو Response Mode على Immediately.
7. انسخ Production URL إلى الحقل n8n production-url في AI-Public. لا تستخدم عنوان الاختبار مع /webhook-test/.
8. فعل التدفق.

البيانات المستلمة تكون تحت body؛ بيانات التكامل التقنية تحت body.integration. لا تقم بحذفها من عقدة تحرير الحقول أو عقدة التعيين أو عقدة كود.

مثال على جسم JSON

عند تعريف الحقول بأسماء مثل prompt، clientName، audiences وdate، ستستقبل n8n على سبيل المثال هذا الجسم JSON. يضيف AI-Public كائن integration تلقائياً.

{
  "prompt": "إنشاء موجز قصير للطلب.",
  "clientName": "OrganizationExample",
  "audiences": ["residents", "employees"],
  "date": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-public-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "توكيـن-مؤقت-لهذه-التنفيذة"
  }
}

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

اختياري: إرسال التحديثات عن التقدم أو الإكمال

يمكن لـ AI-Public عرض ما تسترده n8n فقط. استخدم هذه الاستدعاءات العائدة فقط إذا قمت بتمكين في التسجيل إبلاغ بالتقدم المرحلي و/أو الإبلاغ عن إكمال تدفق العمل.

اعد ضبط كل عقدة رد كالتالي:

1. اختر Method: POST.

2. اضغط في URL على Expression والصق:

   {{ $('Start workflow').first().json.body.integration.callbackUrl }}

3. اختر Authentication: None.

4. فعّل Send Headers وأضف الرؤوس التالية.

5. فعّل Send Body واختر Body Content Type: JSON و Specify Body: Using JSON.

استخدم هذه الرؤوس:

Authorization: Bearer {{ $('Start workflow').first().json.body.integration.callbackToken }}
Content-Type: application/json

أرسل مثلاً هذا الرسالة عندما يبدأ خطوة:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-creation-started",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "إنشاء المستند"
  },
  "message": "يتم إنشاء المستند الآن."
}

• استخدم لكل حدث ضمن نفس التنفيذ قيمة eventId فريدة.
• استخدم تسمية خطوة بالعربية واضحة؛ ستظهر هذه النص في التطبيق.
• إذا قمت بتمكين الإبلاغ عن نهاية التدفق، فاجعل في النهاية دائماً type: "completed" أو type: "failed" أو type: "rejected".
• أضف في completed كائن output إذا كان هناك نتيجة.
• عند failed أضف رسالة خطأ مفهومة. يتوقف التنفيذ أيضاً في التطبيق.

اختياري: طلب الموافقة في التطبيق

استخدم عقدة Wait في n8n مع On Webhook Call عندما يسمح مسار التدفق بالمتابعة فقط بعد الاختيار. أرسل قبل عقدة Wait استدعاءاً مع type: "approval_required":

قم بإعداد عقدة Wait على Resume: On Webhook Call، HTTP Method: POST وAuthentication: Header Auth. اختر نفس بيانات اعتماد Header Auth كما في Start workflow. أضف بعد عقدة Wait عقدة Switch وتحقق من daarin {{ $json.body.decision }}.

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-control",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_document",
    "label": "فحص المستند"
  },
  "approval": {
    "question": "هل تستمر التدفق؟",
    "context": "افحص المستند الناتج أولاً.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "الموافقة" },
      { "value": "reject", "label": "رفض" }
    ]
  }
}

يرى المستخدم الاختيارات في نافذة التنفيذ. بعد الاختيار، تستقبل عقدة Wait من ضمن أمور أخرى decision. بعدها استخدم عقدة Switch لتحديد المسار الصحيح.

يمكن أن تحتوي قيمة الاختيار فقط على حروف وأرقام و_ و-. أما التسمية فيمكن أن تحتوي على نص مقروء عادي.

إعداد عنوان استدعاء إنتاج

عنوان الاستدعاء الإنتاجي لـ AI-Public هو:

https://europe-west1-ai-public-pro.cloudfunctions.net/n8nWorkflowCallback

لا تقم بوضع هذا العنوان كنص ثابت في كل عقدة رد. اختر في حقل URL لعقدة HTTP Request خيار Expression واستخدم:

{{ $('Start workflow').first().json.body.integration.callbackUrl }}

يوفر AI-Public بذلك عند كل بداية عنوان إنتاج صحيح تلقائياً. استخدم العنوان الثابت أعلاه أثناء الاختبار للتحقق من أن التعبير يشير إلى AI-Public وليس إلى AI-School أو AI-Corporate.

ستدعى واجهات triggerCustomN8nWorkflow، triggerN8nWorkflow و resumeN8nWorkflow من قبل التطبيق نفسه. لا تحتاج إلى تعيينها في n8n.

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

أرسل أخطاء متوقعة عبر استدعاء عودة من نوع failed. كما أنشئ تدفق Error مركزي للأخطاء غير المتوقعة:

1. أنشئ تدفقاً جديداً مع عقدة Error Trigger.

2. أضف عقدة HTTP Request مع Method: POST.

3. ضع في URL ثابت الإنتاج التالي:

   https://europe-west1-ai-public-pro.cloudfunctions.net/n8nWorkflowExecutionFailed

4. اختر Authentication: None وأضف رأس n8n-handihow-name بالقيمة السرية الافتراضية لمدير النظام.

5. اختر جسم JSON وألصق:

{
  "executionId": "{{ $json.execution.id }}",
  "workflowId": "{{ $json.workflow.id }}",
  "workflowName": "{{ $json.workflow.name }}",
  "lastNode": "{{ $json.execution.lastNodeExecuted }}",
  "message": "{{ $json.execution.error.message }}"
}

6. فعّل الـ Error Workflow.
7. افتح إعدادات التدفق العادي واختره في Error Workflow.

أرسل فور البدء على الأقل استدعاء عودة واحد مع executionId: "{{ $execution.id }}". فقط بذلك يمكن لـ AI-Public ربط خطأ غير متوقع بالتنفيذ الصحيح.

قيود مهمة

• الدعوات عبر webhook فقط مدعومة.
• عناوين webhook الإنتاجية فقط مدعومة.
• رفض عناوين webhook الاختبارية التي تحتوي على /webhook-test/.
• فقط POST مدعوم.
• فقط المصادقة العامة عبر الرؤوس مدعومة.
• قيمة الرأس تُعامل كسرّ في التطبيق.
• رموز الاستدعاء وURLs الاستئناف تُعالج فقط من جانب الخادم وليست متاحة للمستخدمين مباشرة.
• يتم تحديد المستأجر من جانب الخادم بناءً على المستخدم الذي سجل الدخول، وليس من قيمة يرسلها المتصفح.

حل المشاكل

• 404 أو webhook غير مسجل: فعّل التدفق في n8n واستخدم عنوان الإنتاج.
• خطأ مصادقة: تحقق من أن اسم الرأس وقيمته متطابقان في كلا النظامين.
• بيانات مفقودة: تحقق من تطابق أسماء الحقول في التطبيق مع المفاتيح التي يتوقعها n8n.
• لا يوجد طلب في n8n: تحقق من أن التدفق يبدأ من خلال Webhook Trigger ويستخدم POST.
• نافذة التنفيذ تظل قيد التشغيل: إذا فعلت الإبلاغ عن نهاية التدفق، تحقّق ما إذا أرسلت n8n أخيراً completed، failed أو rejected كـ callback. إذا لم تتوقع تعليقات، فقم بإيقاف جميع الخيارات الثلاثة في التسجيل.
• عدم رؤية التقدم: تحقق من أن إبلاغ التقدم المرحلي مُفعّل أثناء التسجيل، أو أن يظل كائن integration موجوداً وأن كل استدعاء يعود لديه معرف حدث فريد.
• أزرار الموافقة لا تعمل: تحقق من عقدة Wait وresumeUrl ومصادقة الرأس والأحرف المسموح بها في choices[].value.