تدفقات n8n

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

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

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

بعدها قد يقوم تدفق n8n بما يلي:

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

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

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

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

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

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

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

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

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

الحقول

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

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

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

البيانات من AI-School موجودة في n8n تحت body. لذا تكون بيانات التكامل تحت body.integration. لا تحذف هذه البيانات في عقدة Edit Fields أو Set أو Code. أمثلة أدناه تقرأها دائماً من عقدة Start workflow.

مثال على جسم JSON

إذا قمت بتعريف الحقول بأسماء prompt، klantnaam، doelgroepen وdatum، فسيستلم n8n على سبيل المثال هذا الجسم JSON. يضيف AI-School كائن integration تلقائياً.

{
  "prompt": "Maak een korte samenvatting van de aanvraag.",
  "klantnaam": "Voorbeeldorganisatie",
  "doelgroepen": ["medewerkers", "ouders"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "tijdelijk-token-voor-deze-uitvoering"
  }
}

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

اختياري: إرسال التحديثات والتكليل

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

إعداد عقدة HTTP Request

1. أضف عقدة HTTP Request وسمّها مثلًا إبلاغ التقدم.

2. اضبط Method على POST.

3. انقر عند URL على Expression.

4. انسخ تمامًا هذا التعبير:

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

5. اختر عند Authentication خيار None. سيُضاف الرمز المؤقت في الخطوة التالية كرأس.

6. شغّل خيار Send Headers وأضف هذين الرأسين:

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

7. شغّل خيار Send Body.

8. اختر Body Content Type: JSON وSpecify Body: Using JSON.

9. الصق JSON التالي في الحقل JSON:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-maken-gestart",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "Document maken"
  },
  "message": "Het document wordt gemaakt."
}

10. اختر Execute step أثناء اختبار التدفق عبر التطبيق. من المفترض أن تعود العقدة بحالة 200.

انسخ هذه العقدة HTTP Request لكل حالة إشعار حالة. اضبط في كل نسخه على الأقل eventId، step.id، step.label وmessage.

إعداد آخر callback

إذا كان خيار إبلاغ نهاية التدفق مفعلاً، يجب وجود callback أخير في نهاية كل مسار ممكن. استخدم type: "completed" عند النجاح، type: "failed" عند خطأ تتولى أنت معالجته وtype: "rejected" عندما يرفض المستخدم التدفق.

لتنفيذ ناجح، يمكن أن يبدو الجسم كالتالي:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "workflow-afgerond",
  "type": "completed",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "afronding",
    "label": "Workflow afgerond"
  },
  "message": "الاعتماد قد اكتمل.",
  "output": {
    "resultaat": "Korte omschrijving of link naar het resultaat"
  }
}

استخدم في كل تنفيذ لـ callback مختلف eventId. كما يجب أن يظهر نص واضح في step.label للمستخدم في نافذة التنفيذ.

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

إعداد عقدة Wait

1. أضف عقدة Wait في المكان الذي تحتاج فيه الموافقة.
2. اختر في Resume خيار On Webhook Call.
3. اضبط HTTP Method على POST.
4. اختر Authentication لـ Header Auth.
5. اختر نفس اعتماد Header Auth كما في عقدة Start workflow.
6. ضع قبل عقدة Wait نسخة من عقدة HTTP Request التي تم إعدادها سابقاً وسمّها طلب الموافقة.
7. استخدم في هذه العقدة نفس URL الديناميكي ورؤوس HTTP. استبدل فقط جسم JSON بـ:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "controle-document",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_document",
    "label": "Document controleren"
  },
  "approval": {
    "question": "Mag de workflow doorgaan?",
    "context": "Controleer eerst het gegenereerde document.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Goedkeuren" },
      { "value": "reject", "label": "Afwijzen" }
    ]
  }
}

قوم بربط Vraag goedkeuring مع عقدة Wait. سيعرض المستخدم الأزرار في AI-School. عنوان الاستئناف السري لن يُعرض للمستعرض؛ سيرسل الخادم الاختيار بأمان إلى عقدة Wait.

معالجة الاختيار بعد عقدة Wait

1. أضف عقدة Switch بعد عقدة Wait.

2. استخدم القيمة التي يجب التحقق منها:

   {{ $json.body.decision }}

3. أنشئ مساراً مثلاً لـ approve ومساراً لـ reject.

4. اجعل كل مسار ينتهي بـ callback مناسب من completed، rejected أو failed.

يمكن لقيمة الاختيار أن تحتوي فقط على حروف وأرقام و_ و-. يجب أن يحتوي عنوان التسمية على نص مفهوم للقارئ.

ضبط عنوان callback الإنتاجي

عنوان callback الإنتاجي لـ AI-School هو:

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

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

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

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

الدوال triggerCustomN8nWorkflow وtriggerN8nWorkflow وresumeN8nWorkflow يتم استدعاؤها بواسطة التطبيق نفسه. لا تحتاج لإعداد هذه URLs في n8n.

إرسال أخطاء غير متوقعة

استدعاء فشل عادي يعمل فقط عندما تصل التدفق إلى عقدة HTTP Request المعنية. استخدم أيضًا مسار Error Workflow مركزي لأي أخطاء عقدة غير متوقعة.

إنشاء Error Workflow مركزي

1. أنشئ في n8n تدفق عمل منفصل باسم AI-School - أخطاء لإرسالها.

2. أضف عقدة Error Trigger.

3. ثم أضف عقدة HTTP Request.

4. اضبط Method على POST.

5. ضع في URL هذا عنوان الإنتاج الثابت:

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

6. اختر Authentication: None.

7. شغّل خيار Send Headers وأضف:

   Name	Value
   n8n-handihow-name	القيمة السرية الافتراضية التي تتلقاها من مشرف المنصة
   Content-Type	application/json

8. شغّل خيار Send Body، اختر JSON والصق هذه الجسم:

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

9. فعّل Error Workflow.
10. افتح إعدادات التدفق العادي واختر في Error Workflow هذه ال Error Workflow الجديدة.

أرسل مباشرة بعد Start workflow على الأقل استدعاء تتابعي واحد مع executionId: "{{ $execution.id }}". وبذلك تعرف التطبيق في أي تنفيذ ينتمي خطأ n8n غير المتوقع.

القيود الهامة

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

حل المشاكل

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