تدفقات عمل 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. اضبط Header authentication باستخدام اسم ترويسة وقيمة ترويسة سرية.
6. ضمن الردود من n8n، فعّل فقط الأجزاء المبنية فعليًا في هذا التدفق: التقدم، الموافقة و/أو نهاية التدفق.
7. أضف الحقول التي يجب إرسالها في طلب POST إن لزم الأمر.
8. احفظ التدفق.

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

الحقول

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

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

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

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

مثال على JSON body

إذا عرّفت حقولًا بالأسماء prompt وklantnaam وdoelgroepen وdatum، فسيستقبل n8n مثلًا JSON body التالي. يضيف 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"
  }
}

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

اختياري: إرسال التقدم والانتهاء

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

إعداد عقدة HTTP Request

1. أضف عقدة HTTP Request وسمّها مثلًا Meld voortgang.

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

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

4. الصق هذا التعبير حرفيًا:

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

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

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" عندما يرفض المستخدم التدفق.

يمكن أن يبدو body للتنفيذ الناجح مثل هذا:

{
  "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": "De workflow is afgerond.",
  "output": {
    "resultaat": "Korte omschrijving of link naar het resultaat"
  }
}

استخدم eventId مختلفًا لكل callback ضمن التنفيذ الواحد. واستخدم دائمًا step.label واضحًا: هذا النص يراه المستخدم في نافذة التنفيذ.

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

إعداد عقدة Wait

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

{
  "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. لا يُعطى عنوان resume-url السري للمتصفح؛ بل يرسل الخادم الخيار بأمان إلى عقدة Wait.

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

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

2. استخدم القيمة التالية للتحقق:

   {{ $json.body.decision }}

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

4. اجعل كل مسار ينتهي بواحدة من callbacks المناسبة: completed أو rejected أو failed.

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

إعداد URL callback الإنتاجي

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

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

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

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

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

يتم استدعاء triggerCustomN8nWorkflow وtriggerN8nWorkflow وresumeN8nWorkflow من التطبيق نفسه. لا تحتاج إلى ضبط هذه الـ URLs داخل n8n.

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

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

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

1. أنشئ في n8n تدفقًا منفصلًا باسم AI-School - fouten terugsturen.

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	de geheime standaardwaarde die je van de platformbeheerder ontvangt
   Content-Type	application/json

8. فعّل Send Body، واختر JSON، والصق هذا body:

{
  "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 دائمًا على الأقل callback تقدم واحدًا مع executionId: "{{ $execution.id }}". بذلك تعرف التطبيق أي تنفيذ يرتبط بخطأ n8n غير المتوقع.

قيود مهمة

• تُدعم فقط webhooks التشغيلية.
• تُدعم فقط عناوين webhook الإنتاجية.
• تُرفض عناوين test-webhook التي تحتوي على /webhook-test/.
• يُدعم POST فقط.
• يُدعم فقط generic header authentication.
• تُعامل قيمة الترويسة كسرّ داخل التطبيق.
• تُعالج رموز callback وعناوين resume-url من جهة الخادم فقط، ولا تكون متاحة مباشرة للمستخدمين.
• يُحدَّد tenant من جهة الخادم اعتمادًا على المستخدم المسجّل دخوله، وليس من قيمة يرسلها المتصفح.

استكشاف المشكلات وإصلاحها

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