برو به محتوای اصلی

n8n روندکاری

AI-School می‌تواند روندهای n8n را از طریق یک webhook تولیدی آغاز کند. این مفید است وقتی می‌خواهید یک فرایند خودکار خارج از AI-School را آغاز کنید، مثلاً ایجاد یک وظیفه، به‌روزرسانی یک رکورد CRM، آغاز یک جریان گزارش‌گیری یا ارسال داده‌های فرم به سامانه‌ای دیگر.

نمونه: مقاله خبر در وب‌سایت مدرسه​

فرض کنید مدرسه یک روند n8n ساخته باشد که یک خبر را در وب‌سایت وردپرس مدرسه منتشر کند. در AI-School تنها یک قطعه متن کوتاه پر می‌کنید، مثلاً چند جمله درباره یک هفته پروژه، روز ورزشی یا روز باز. با آن متن، روند در n8n آغاز می‌شود.

روند n8n می‌تواند سپس به‌عنوان مثال:

  1. از متن کوتاه یک متن مفهومی مناسب با استفاده از گره LLM و یک پرامپ مناسب با لحن مدرسه بسازد.
  2. با گره دوم LLM یک تصویر مناسب تولید کند، مثلاً با رنگ‌های مدرسه و به سبک تصویری قابل تشخیص.
  3. متن و تصویر را به‌عنوان پست بلاگ آماده یا منتشر در وب‌سایت وردپرس قرار دهد.

به این ترتیب AI-School و n8n با هم کار می‌کنند: در AI-School کاربر روند را انتخاب می‌کند و اطلاعات لازم را وارد می‌کند. سپس n8n گام‌های خودکار را انجام داده و خبر را به‌طور مناسب روی وب‌سایت قرار می‌دهد.

این ادغام چه عملکردی دارد؟​

شما روند n8n را از نمای کل روند باز می‌دارید. فقط webhook تولیدی، POST و احراز هویت Header اجباری هستند. فیلدها و بازخوردها از n8n اختیاری بوده و به‌طور مستقل قابل پیکربندی هستند.

  • اگر روند فاقد فیلد باشد، webhook فوراً فراخوانی می‌شود.
  • اگر روند فیلد داشته باشد، ابتدا فرم باز می‌شود. کاربر فیلدها را پر می‌کند و سپس با دکمه، روند را آغاز می‌کند.
  • مقادیر پرشده به‌صورت JSON در درخواست POST به webhook n8n ارسال می‌شوند.
  • بدون بازخوردها، AI-School فقط تأیید می‌کند که روند آغاز شده و در n8n ادامه می‌یابد. پنجره spinner نشان داده نمی‌شود و می‌توان آن را بلافاصله بست.
  • اگر این گزینه در ثبت‌نام فعال شده باشد، روند می‌تواند مراحل میانی یا پایان را به AI-School بازگرداند.
  • اگر تأیید در ثبت‌نام فعال شده باشد، کاربر می‌تواند گزینه را مستقیماً در AI-School انتخاب کند. سپس n8n از همان مرحله منتظر ادامه می‌دهد.

ایجاد ن8n workflow در AI-School​

یک مدیر به‌روش زیر روند را ثبت می‌کند:

  1. به Assistenten / دستیاران بروید.
  2. به Workflows / روندها باز کنید.
  3. گزینه Nieuwe n8n workflow / روند n8n جدید را بگذارید.
  4. نام روند و آدرس تولیدی n8n را وارد کنید.
  5. Header authentication / احراز هویت Header را با نام هدر و مقدار هدر مخفی تنظیم کنید.
  6. در بخش Terugmeldingen uit n8n / بازخوردها از n8n تنها مواردی را فعال کنید که واقعاً در این ن8n-وُرق‌اِل ساخته شده‌اند: پیشرفت، تأیید و/یا پایان روند.
  7. در صورت نیاز، فیلدهایی که باید در POST ارسال شوند را اضافه کنید.
  8. روند را ذخیره کنید.

هر سه گزینه بازخوردی از پیش خاموش هستند. اگر بعداً callbacks یا مرحله تأیید را در 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. URL تولیدی گره Webhook را به فیلد n8n productie-url / آدرس تولیدی n8n در AI-School کپی کنید. از URL تست با /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 شی object 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. روش POST را انتخاب کنید.

  3. در URL روی Expression کلیک کنید.

  4. دقیقاً این بیان را الصاق کنید:

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

  5. در Authentication گزینه None را انتخاب کنید. توکن موقتی در گام بعدی به‌عنوان هدر اضافه می‌شود.

  6. Send Headers را فعال کرده و دو هدر زیر را اضافه کنید:

    NameValue
    AuthorizationBearer {{ $('Start workflow').first().json.body.integration.callbackToken }}
    Content-Typeapplication/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."
}
  1. وقتی با استفاده از اپ تست می‌کنید، این گره باید وضعیت 200 را بازگرداند.

این گره HTTP Request را برای هر وضعیت بازخورد رونویسی کنید. برای هر کپی حداقل مقادیر eventId، step.id، step.label و message را تغییر دهید.

تنظیم آخرین callback​

اگر گزینه Het einde van de workflow melden فعال شده باشد، در پایان هر مسیر ممکن باید یک 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": "De workflow is afgerond.",
  "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 که قبلاً تنظیم کرده‌اید را قرار دهید و به آن نام Vraag goedkeuring / درخواست تأیید بدهید.
  7. در این گره از همان URL پویا و هدرهای دینامیکی استفاده کنید. فقط بدنه 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 تأیید را به گره Wait وصل کنید. کاربر سپس دکمه‌ها را در AI-School می‌بیند. لینک resume مخفی است و برای مرورگر ارائه نمی‌شود؛ سرور گزینه را به‌طور امن به گره Wait می‌فرستد.

پردازش گزینه پس از Wait​

  1. پس از Wait، یک گره Switch اضافه کنید.

  2. مقدار قابل بررسی را به‌عنوان زیر استفاده کنید:

    {{ $json.body.decision }}

  3. برای مثال مسیرهایی برای approve و reject بسازید.

  4. هر مسیر را با بازخورد مناسب completed، rejected یا failed پایان دهید.

یک مقدار انتخابی فقط می‌تواند حروف، اعداد، _ و - داشته باشد. برچسب باید متن قابل خواندن عادی باشد.

تنظیم آدرس callback برای تولید​

آدرس callback تولید AI-School به‌شرح زیر است:

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

این URL را به‌عنوان متن ثابت در هر گره callback نگذارید. در فیلد URL گره HTTP Request از گزینه Expression استفاده کنید و به کار ببرید:

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

AI-School در هر آغاز به‌طور خودکار URL تولیدی مناسب را ارائه می‌دهد. URL ثابت بالا فقط برای بررسی در حین تست مفید است.

توابع triggerCustomN8nWorkflow, triggerN8nWorkflow و resumeN8nWorkflow توسط اپلیکیشن خود اجرا می‌شوند. این URLها را در n8n لازم نیست پیکربندی کنید.

بازگرداندن خطاهای غیرمنتظره​

یک callback معمول failed فقط زمانی کار می‌کند که گره HTTP Request مربوط به آن پردازش شده باشد. برای خطاهای غیرمنتظره گره‌های n8n از یک ناحیهٔ مرکزی به نام Error Workflow استفاده کنید.

ایجاد Error Workflow مرکزی​

  1. در n8n یک روند جداگانه با نام AI-School - fouten terugsturen / AI-School - ارسال خطاها بسازید.

  2. گره Error Trigger اضافه کنید.

  3. سپس یک گره HTTP Request اضافه کنید.

  4. روش را روی POST بگذارید.

  5. URL ثابت تولیدی زیر را وارد کنید:

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

  6. گزینه Authentication: None را انتخاب کنید.

  7. Send Headers را فعال کنید و اضافه کنید:

    NameValue
    n8n-handihow-nameمقدار مخفی پیش‌فرضی که از مدیر پلتفرم دریافت می‌کنید
    Content-Typeapplication/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 }}"
}
  1. Error Workflow را فعال کنید.
  2. تنظیمات روند عادی را باز کنید و در بخش Error Workflow این Error Workflow جدید را انتخاب کنید.

فوریه پس از Start workflow حداقل یک callback پیشرفت با executionId: "{{ $execution.id }}" ارسال کنید. این به اپ می‌گوید در کدام اجرای n8n خطای غیرمنتظره رخ داده است.

محدودیت‌های مهم​

  • فقط تحریک‌های webhook پشتیبانی می‌شوند.
  • فقط URLهای webhook تولیدی پشتیبانی می‌شوند.
  • URLهای تست webhook با /webhook-test/ رد می‌شوند.
  • فقط POST پشتیبانی می‌شود.
  • فقط احراز هویت header عمومی پشتیبانی می‌شود.
  • مقدار header در برنامه به‌عنوان مخفی تلقی می‌شود.
  • توکن‌های callback و resume-urlها فقط سروری‌ست و به‌طور مستقیم در دسترس کاربران نیستند.
  • tenant از سمت سرور و از کاربر واردشده تعیین می‌شود، نه مقدار فرستاده شده توسط مرورگر.

رفع اشکال​

  • 404 یا webhook ثبت نشده: روند را در n8n فعال کنید و از URL تولیدی استفاده کنید.
  • خطای احراز هویت: بررسی کنید نام هدر و مقدار آن در هر دو سامانه دقیقاً برابر باشند.
  • داده‌های از دست رفته: بررسی کنید نام فیلدها در اپ با کلیدهایی که n8n انتظار دارد برابر باشند.
  • هیچ درخواستی در n8n نیست: مطمئن شوید روند با یک webhook Trigger آغاز می‌شود و از POST استفاده می‌کند.
  • پنجره اجرایی به‌طور مداوم می‌چرخد: اگر گزینه پایان روند را فعال کرده‌اید، بررسی کنید آیا n8n یک callback نهایی با یکی از انواع completed، failed یا rejected می‌فرستد. اگر انتظار بازخوردی نیست، هر سه گزینه ثبت را خاموش کنید.
  • هیچ پیشرفتی نمایش داده نمی‌شود: بررسی کنید آیا گزینه Tussentijdse voortgang melden در ثبت فعال است یا شیء integration حفظ شده و هر callback یک eventId یکتا دارد.
  • دکمه‌های تأیید کار نمی‌کند: Wait node، resumeUrl، احراز هویت هدرها و کاراکترهای مجاز در choices[].value را بررسی کنید.
WhatsApp