تدفقات n8n

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

مثال: خبر منشور على موقع الشركة

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

يمكن أن يقوم تدفق n8n بعد ذلك بـ:

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

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

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

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

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

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

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

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

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

الحقول

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

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

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

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

مثال على جسم JSON

إذا عرفت الحقول بأسماء prompt, customerName, audiences وdate، ستصل n8n إلى هذه JSON الجسم. يضيف AI-Corporate كائن integration تلقائياً.

{
  "prompt": "قم بعمل ملخص قصير للطلب.",
  "customerName": "مثال المنظمة",
  "audiences": ["الموظفين", "العملاء"],
  "date": "2026-09-22",
  "integration": {
    "runId": "document-chat-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "رمز-مؤقت-للإجراء-هذا"
  }
}

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

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

يمكن لـ AI-Corporate عرض ما ترسله 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-create-started",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_create",
    "label": "إنشاء المستند"
  },
  "message": "يتم إنشاء المستند."
}

• استخدم قيمة eventId فريدة لكل حدث ضمن التنفيذ نفسه.
• استخدم label عربي واضح؛ هذا النص سيظهر في التطبيق.
• إذا قمت بتفعيل الإخطار بنهاية التدفق، أرسل دائماً في النهاية type: "completed"، أو type: "failed" أو type: "rejected".
• أضف كائن 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 وتحقق من ذلك داخل {{ $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": "document_check",
    "label": "فحص المستند"
  },
  "approval": {
    "question": "هل يستمر التدفق؟",
    "context": "افحص المستند الناتج أولاً.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "الموافقة" },
      { "value": "reject", "label": "رفض" }
    ]
  }
}

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

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

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

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

https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowCallback

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

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

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

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

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

أرسل أخطاء متوقعة عبر callback من النوع failed. Create أيضاً مسار خطأ مركزي كـ Error Workflow:

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

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

3. ضع في URL هذه الـ production-url الثابتة:

   https://europe-west1-ai-corporate.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 سبّباً واحداً على الأقل بـ executionId: "{{ $execution.id }}". عندئذ فقط يمكن لـ AI-Corporate ربط وجود خطأ غير متوقع بالتنفيذ الصحيح.

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

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

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

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