گردش‌کارهای n8n

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

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

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

سپس گردش‌کار n8n می‌تواند مثلاً:

از متن کوتاه، با یک node از نوع LLM و یک prompt که با لحن مدرسه هماهنگ است، یک متن پیش‌نویس مرتب بسازد.
با یک node دوم از نوع LLM یک تصویرسازی مناسب تولید کند، مثلاً با رنگ‌های مدرسه و در سبکی تصویری و آشنا.
متن و تصویر را به‌صورت یک نوشته وبلاگ آماده یا منتشر کند روی وب‌سایت WordPress.

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

این یکپارچه‌سازی چه می‌کند؟

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

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

ساختن گردش‌کار n8n در AI-School

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

به Assistenten بروید.
تب Workflow assistenten را باز کنید.
در کارت بالای صفحه روی Nieuwe workflow کلیک کنید و n8n workflow را انتخاب کنید.
نام گردش‌کار و n8n productie-url را وارد کنید.
Header authentication را با یک header name و header value محرمانه تنظیم کنید.
زیر Terugmeldingen uit n8n فقط بخش‌هایی را تیک بزنید که واقعاً در این n8n-workflow ساخته شده‌اند: پیشرفت، تأیید و/یا پایان گردش‌کار.
در صورت نیاز، فیلدهایی را اضافه کنید که باید در POST-request ارسال شوند.
گردش‌کار را ذخیره کنید.

هر سه گزینه بازخورد به‌طور پیش‌فرض خاموش هستند. اگر بعداً callbackها یا یک مرحله تأیید در n8n اضافه کردید، ثبت در AI-School را هم به‌روزرسانی کنید. این کار باعث می‌شود dialog بداند فقط باید یک تأیید شروع نشان دهد یا باید منتظر سیگنال‌های بعدی هم بماند.

فیلدها

فیلدها اختیاری هستند.
هر فیلد یک نام فیلد و یک نوع دارد.
انواع پشتیبانی‌شده عبارت‌اند از متن کوتاه، متن بلند، عدد، بله/خیر، تاریخ، یک انتخاب و چند انتخاب.
در Eén keuze و Meerdere keuzes گزینه‌های موجود را اضافه می‌کنید. Eén keuze به‌صورت یک فهرست انتخاب فشرده نمایش داده می‌شود؛ Meerdere keuzes چک‌باکس‌ها را نشان می‌دهد. مقدار یا مقادیر انتخاب‌شده در بدنه JSON ارسال می‌شوند.
فیلدهای اجباری باید پر شوند تا گردش‌کار بتواند شروع شود.
نام فیلد به key در بدنه JSON ارسالی به n8n تبدیل می‌شود.

ساختن یک workflow سازگار در n8n

در n8n یک workflow جدید بسازید.
به‌عنوان اولین node یک Webhook اضافه کنید.
نام این node را دقیقاً Start workflow بگذارید. مثال‌های پایین‌تر از این نام استفاده می‌کنند.
HTTP Method را روی POST بگذارید.
در Authentication گزینه Header Auth را انتخاب کنید و یک Header Auth credential برگزینید.
در آن credential همان نام header و مقدار محرمانه‌ای را وارد کنید که در گردش‌کار AI-School استفاده شده است.
Respond یا Response Mode را روی Immediately بگذارید. در این صورت برنامه فوراً یک تأیید شروع موفق می‌گیرد، در حالی که n8n به کار ادامه می‌دهد.
Production URL node وبهوک را در فیلد n8n productie-url در AI-School کپی کنید. از test-url با /webhook-test/ استفاده نکنید.
workflow را در n8n فعال کنید.

داده‌های AI-School در n8n زیر body قرار دارند. بنابراین داده‌های یکپارچه‌سازی زیر body.integration هستند. این داده‌ها را در یک Edit Fields-، Set- یا Code-node حذف نکنید. مثال‌های زیر همیشه آن‌ها را مستقیم از node Start workflow می‌خوانند.

نمونه بدنه JSON

اگر فیلدهایی با نام‌های prompt، klantnaam، doelgroepen و datum تعریف کنید، n8n مثلاً این بدنه JSON را دریافت می‌کند. AI-School شیء integration را به‌طور خودکار اضافه می‌کند.

{
  "prompt": "یک خلاصه کوتاه از درخواست تهیه کنید.",
  "klantnaam": "سازمان نمونه",
  "doelgroepen": ["کارکنان", "والدین"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "توکن موقت برای این اجرا"
  }
}

callback token مخصوص یک اجراست. آن را در logها، پیکربندی ثابت یا سیستم‌های دیگر ذخیره نکنید.

اختیاری: ارسال پیشرفت و اتمام

AI-School فقط می‌تواند همان چیزی را نشان دهد که n8n گزارش می‌کند. از این callbacks فقط زمانی استفاده کنید که هنگام ثبت Tussentijdse voortgang melden و/یا Het einde van de workflow melden را فعال کرده باشید.

تنظیم node از نوع HTTP Request

یک node از نوع HTTP Request اضافه کنید و مثلاً نام آن را Meld voortgang بگذارید.
Method را روی POST بگذارید.
در بخش URL روی Expression کلیک کنید.

دقیقاً این expression را بچسبانید:

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

در Authentication گزینه None را انتخاب کنید. توکن موقت در مرحله بعد به‌عنوان header اضافه می‌شود.
Send Headers را روشن کنید و این دو header را اضافه کنید:

Name Value
Authorization Bearer {{ $('Start workflow').first().json.body.integration.callbackToken }}
Content-Type application/json
Send Body را روشن کنید.
Body Content Type: JSON و Specify Body: Using JSON را انتخاب کنید.
JSON زیر را در فیلد JSON بچسبانید:

Name	Value
`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": "ساختن سند"
  },
  "message": "سند در حال ساخته شدن است."
}

هنگام آزمایش workflow از طریق app، Execute step را انتخاب کنید. node باید status 200 برگرداند.

برای هر پیام وضعیت، این HTTP Request node را کپی کنید. در هر کپی دست‌کم eventId، step.id، step.label و message را تغییر دهید.

تنظیم callback نهایی

اگر Het einde van de workflow melden فعال شده باشد، در پایان هر مسیر ممکن باید یک callback نهایی وجود داشته باشد. در موفقیت از type: "completed" استفاده کنید، برای خطایی که خودتان مدیریت می‌کنید از type: "failed" و زمانی که کاربر workflow را رد می‌کند از 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": "گردش‌کار تکمیل شد"
  },
  "message": "گردش‌کار تکمیل شد.",
  "output": {
    "resultaat": "توضیح کوتاه یا پیوند به نتیجه"
  }
}

در هر اجرا برای هر callback یک eventId متفاوت استفاده کنید. همیشه یک step.label واضح هم به کار ببرید: این متن را کاربر در پنجره اجرا می‌بیند.

اختیاری: درخواست تأیید در app

تنظیم node از نوع Wait

در جایی که تأیید لازم است یک node از نوع Wait اضافه کنید.
در Resume گزینه On Webhook Call را انتخاب کنید.
HTTP Method را روی POST بگذارید.
در Authentication گزینه Header Auth را انتخاب کنید.
همان Header Auth credential node Start workflow را برگزینید.
قبل از node Wait یک کپی از node HTTP Request قبلی قرار دهید و نام آن را Vraag goedkeuring بگذارید.
در این node همان URL پویا و headerها را استفاده کنید. فقط بدنه 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": "بررسی سند"
  },
  "approval": {
    "question": "آیا گردش‌کار می‌تواند ادامه پیدا کند؟",
    "context": "ابتدا سند تولیدشده را بررسی کنید.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "تأیید" },
      { "value": "reject", "label": "رد کردن" }
    ]
  }
}

Vraag goedkeuring را به node Wait وصل کنید. سپس کاربر دکمه‌ها را در AI-School می‌بیند. resume-url محرمانه به مرورگر داده نمی‌شود؛ سرور انتخاب را به‌صورت امن به node Wait می‌فرستد.

پردازش انتخاب بعد از node Wait

بعد از node Wait یک node از نوع Switch اضافه کنید.
از این مقدار به‌عنوان مقدار بررسی‌شونده استفاده کنید:
```
{{ $json.body.decision }}
```
مثلاً یک مسیر برای approve و یک مسیر برای reject بسازید.
هر مسیر را با یک callback مناسب از نوع completed، rejected یا failed تمام کنید.

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

تنظیم callback-url تولید

callback-url تولید برای AI-School این است:

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

این URL را به‌صورت متن ثابت در هر callbacknode نچسبانید. در فیلد URL از node HTTP Request گزینه Expression را انتخاب کنید و از این استفاده کنید:

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

به این ترتیب AI-School در هر شروع، URL تولید درست را به‌طور خودکار می‌دهد. URL ثابت بالا فقط برای این است که هنگام تست بررسی کنید expression به AI-School اشاره می‌کند.

callables triggerCustomN8nWorkflow، triggerN8nWorkflow و resumeN8nWorkflow توسط خود app فراخوانی می‌شوند. لازم نیست این URLها را در n8n تنظیم کنید.

ارسال خطاهای غیرمنتظره

یک callback معمولی failed فقط وقتی کار می‌کند که workflow به آن HTTP Request node برسد. برای خطاهای غیرمنتظره node، علاوه بر آن از یک n8n Error Workflow مرکزی استفاده کنید.

ساختن Error Workflow مرکزی

در n8n یک workflow جداگانه با نام AI-School - fouten terugsturen بسازید.
یک node از نوع Error Trigger اضافه کنید.
سپس یک node از نوع HTTP Request اضافه کنید.
Method را روی POST بگذارید.

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

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

Authentication: None را انتخاب کنید.
Send Headers را روشن کنید و این را اضافه کنید:

Name Value
n8n-handihow-name مقدار پیش‌فرض محرمانه‌ای که از مدیر پلتفرم دریافت می‌کنید
Content-Type application/json
Send Body را روشن کنید، JSON را انتخاب کنید و این بدنه را بچسبانید:

Name	Value
`n8n-handihow-name`	مقدار پیش‌فرض محرمانه‌ای که از مدیر پلتفرم دریافت می‌کنید
`Content-Type`	`application/json`

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

Error Workflow را فعال کنید.
تنظیمات workflow معمولی را باز کنید و در Error Workflow این Error Workflow جدید را انتخاب کنید.

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

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

فقط webhook triggers پشتیبانی می‌شوند.
فقط production-webhook-urlها پشتیبانی می‌شوند.
test-webhook-urlها با /webhook-test/ رد می‌شوند.
فقط POST پشتیبانی می‌شود.
فقط generic header authentication پشتیبانی می‌شود.
مقدار header در برنامه به‌عنوان محرمانه در نظر گرفته می‌شود.
callback tokenها و resume-urlها فقط سمت سرور پردازش می‌شوند و مستقیماً برای کاربران در دسترس نیستند.
tenant سمت سرور و بر اساس کاربر واردشده تعیین می‌شود، نه بر اساس مقداری که مرورگر می‌فرستد.

عیب‌یابی

404 یا webhook ثبت نشده: workflow را در n8n فعال کنید و از production-url استفاده کنید.
خطای احراز هویت: بررسی کنید header name و value در هر دو سیستم دقیقاً یکسان باشند.
داده‌های ناقص: بررسی کنید نام فیلدها در برنامه با keyهایی که n8n انتظار دارد مطابقت داشته باشند.
هیچ درخواستی در n8n دیده نمی‌شود: بررسی کنید workflow با webhook trigger شروع شود و از POST استفاده کند.
پنجره اجرا همچنان در حال چرخش است: اگر Het einde van de workflow melden را فعال کرده‌اید، بررسی کنید n8n یک callback نهایی completed، failed یا rejected می‌فرستد. اگر انتظار هیچ بازخوردی ندارید، هر سه گزینه را هنگام ثبت خاموش کنید.
هیچ پیشرفتی دیده نمی‌شود: بررسی کنید Tussentijdse voortgang melden هنگام ثبت فعال باشد، شیء integration حفظ شده باشد و هر callback یک eventId یکتا داشته باشد.
دکمه‌های تأیید کار نمی‌کنند: node Wait، resumeUrl، header authentication و نویسه‌های مجاز در choices[].value را بررسی کنید.

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

این یکپارچه‌سازی چه می‌کند؟​

ساختن گردش‌کار n8n در AI-School​

فیلدها​

ساختن یک workflow سازگار در n8n​

نمونه بدنه JSON​

اختیاری: ارسال پیشرفت و اتمام​

تنظیم node از نوع HTTP Request​

تنظیم callback نهایی​

اختیاری: درخواست تأیید در app​

تنظیم node از نوع Wait​

پردازش انتخاب بعد از node Wait​

تنظیم callback-url تولید​

ارسال خطاهای غیرمنتظره​

ساختن Error Workflow مرکزی​

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

عیب‌یابی​