تدفقات عمل n8n

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

مثال: مقال إخباري على موقع المنظمة

لنفترض أن المنظمة أنشأت تدفق عمل n8n ينشر مقالًا إخباريًا على موقع WordPress. في AI-Public، لا تُدخل إلا نصًا قصيرًا، مثل بضع جمل عن اجتماع أو مشروع أو إعلان عام. بهذا النص تبدأ تدفق العمل في n8n.

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

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

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

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

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

تكون جميع خيارات التحديث الراجع الثلاثة معطلة افتراضيًا. إذا أضفت لاحقًا callbacks أو خطوة موافقة في 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 productie-url في AI-Public. لا تستخدم عنوان الاختبار مع /webhook-test/.
8. فعّل تدفق العمل.

توجد البيانات المستلمة تحت body; وتوجد بيانات التكامل التقنية تحت body.integration. لا تحذفها في عقدة Edit Fields أو Set أو Code.

مثال على جسم JSON

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

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

رمز callback token خاص بتشغيل واحد. لا تحفظه في السجلات أو التهيئة الثابتة أو أنظمة أخرى.

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

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

اضبط كل عقدة callback كما يلي:

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-maken-gestart",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "Document maken"
  },
  "message": "Het document wordt gemaakt."
}

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

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

استخدم عقدة n8n Wait مع On Webhook Call عندما لا ينبغي أن يتابع تدفق العمل إلا بعد اختيار. أرسل قبل عقدة Wait callback من النوع type: "approval_required":

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

{
  "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" }
    ]
  }
}

يرى المستخدم الخيارات في نافذة التنفيذ. بعد الاختيار تتلقى عقدة Wait، من بين أشياء أخرى، decision. استخدم بعد ذلك مثلًا عقدة Switch لتحديد المسار الصحيح.

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

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

URL callback للإنتاج الخاص بـ AI-Public هو:

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

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

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

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

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

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

أعد الأخطاء المتوقعة عبر callback من النوع failed. ولأخطاء العقد غير المتوقعة، أنشئ أيضًا Error Workflow مركزيًا:

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.

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

قيود مهمة

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

استكشاف المشكلات

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